dist/html/IPV6_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix IPv6 Support</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix
IPv6 Support</h1>

<hr>

<h2>Introduction</h2>

<p> Postfix 2.2 introduces support for the IPv6 (IP version 6)
protocol. IPv6 support for older Postfix versions was available as
an add-on patch. The section "<a href="#compat">Compatibility with
Postfix &lt;2.2 IPv6 support</a>" below discusses the differences
between these implementations. </p>

<p> The main feature of interest is that IPv6 uses 128-bit IP
addresses instead of the 32-bit addresses used by IPv4. It can
therefore accommodate a much larger number of hosts and networks
without ugly kluges such as NAT. A side benefit of the much larger
address space is that it makes random network scanning impractical.
</p>

<p> Postfix uses the same SMTP protocol over IPv6 as it already
uses over the older IPv4 network, and does AAAA record lookups in
the DNS in addition to the older A records.  Information about IPv6
can be found at <a href="http://www.ipv6.org/">http://www.ipv6.org/</a>. </p>

<p> This document provides information on the following topics:
</p>

<ul>

<li><a href="#platforms">Supported platforms</a>

<li><a href="#configuration">Configuration</a>

<li><a href="#limitations">Known limitations</a>

<li><a href="#compat">Compatibility with Postfix &lt;2.2 IPv6 support</a>

<li><a href="#porting">IPv6 Support for unsupported platforms</a>

<li><a href="#credits">Credits</a>

</ul>

<h2><a name="platforms">Supported Platforms</a></h2>

<p> Postfix version 2.2 supports IPv4 and IPv6 on the following
platforms:  </p>

<ul>

<li> AIX 5.1+
<li> Darwin 7.3+
<li> FreeBSD 4+
<li> Linux 2.4+
<li> NetBSD 1.5+
<li> OpenBSD 2+
<li> Solaris 8+
<li> Tru64Unix V5.1+

</ul>

<p> On other platforms Postfix will simply use IPv4 as it has always
done. </p>

<p> See "<a href="#porting">IPv6 Support for unsupported platforms</a>"
for tips to port Postfix IPv6 support to other environments.  </p>

<h2><a name="configuration">Configuration</a></h2>

<p> Postfix IPv6 support introduces two new <a href="postconf.5.html">main.cf</a> configuration
parameters, and introduces an important change in address syntax
notation in match lists such as <a href="postconf.5.html#mynetworks">mynetworks</a> or
<a href="postconf.5.html#debug_peer_list">debug_peer_list</a>. </p>

<p> Postfix IPv6 address syntax is a little tricky, because there
are a few places where you must enclose an IPv6 address inside
"<tt>[]</tt>" characters, and a few places where you must not. It is
a good idea to use "<tt>[]</tt>" only in the few places where you
have to. Check out the <a href="postconf.5.html">postconf(5)</a> manual whenever you do IPv6
related configuration work with Postfix.  </p>

<ul>

<li> <p> Instead of hard-coding 127.0.0.1 and ::1 loopback addresses
in <a href="master.5.html">master.cf</a>, specify "<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = loopback-only" in <a href="postconf.5.html">main.cf</a>.
This way you can use the same <a href="master.5.html">master.cf</a> file regardless of whether
or not Postfix will run on an IPv6-enabled system. </p>

<li> <p> The first new parameter is called <a href="postconf.5.html#inet_protocols">inet_protocols</a>.  This
specifies what protocols Postfix will use when it makes or accepts
network connections, and also controls what DNS lookups Postfix
will use when it makes network connections.  </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    # You must stop/start Postfix after changing this parameter.
    <a href="postconf.5.html#inet_protocols">inet_protocols</a> = all        (enable IPv4, and IPv6 if supported)
    <a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv4       (enable IPv4 only)
    <a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv4, ipv6 (enable both IPv4 and IPv6)
    <a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv6       (enable IPv6 only)
</pre>
</blockquote>

<p> The default is compile-time dependent: "all" when Postfix is built
on a software distribution with IPv6 support, "ipv4" otherwise. </p>

<p> Note 1: you must stop and start Postfix after changing the
<a href="postconf.5.html#inet_protocols">inet_protocols</a> configuration parameter. </p>

<p> Note 2: on older Linux and Solaris systems, the setting
"<a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv6" will not prevent Postfix from
accepting IPv4 connections. </p>

<p> For an unsupported test option to build Postfix without IPv6
support, see the NO_IPV6 option in the <a href="INSTALL.html">INSTALL</a> document. </p>

<li> <p> The other new parameter is <a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a>.
This sets the local interface address for outgoing IPv6 SMTP
connections, just like the <a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> parameter
does for IPv4: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#smtp_bind_address6">smtp_bind_address6</a> = 2001:240:587:0:250:56ff:fe89:1
</pre>
</blockquote>

<li> <p> If you left the value of the <a href="postconf.5.html#mynetworks">mynetworks</a> parameter at its
default (i.e. no <a href="postconf.5.html#mynetworks">mynetworks</a> setting in <a href="postconf.5.html">main.cf</a>) Postfix will figure
out by itself what its network addresses are. This is what a typical
setting looks like: </p>

<blockquote>
<pre>
% postconf <a href="postconf.5.html#mynetworks">mynetworks</a>
<a href="postconf.5.html#mynetworks">mynetworks</a> = 127.0.0.0/8 168.100.189.0/28 [::1]/128 [fe80::]/10 [2001:240:587::]/64
</pre>
</blockquote>

<p> If you did specify the <a href="postconf.5.html#mynetworks">mynetworks</a> parameter value in
<a href="postconf.5.html">main.cf</a>, you need to update the <a href="postconf.5.html#mynetworks">mynetworks</a> value to include
the IPv6 networks the system is in. Be sure to specify IPv6 address
information inside "<tt>[]</tt>", like this: </p>

<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
    <a href="postconf.5.html#mynetworks">mynetworks</a> = ...<i>IPv4 networks</i>... [::1]/128 [2001:240:587::]/64 ...
</pre>
</blockquote>

</ul>

<p> <b> NOTE: when configuring Postfix match lists such as
<a href="postconf.5.html#mynetworks">mynetworks</a> or <a href="postconf.5.html#debug_peer_list">debug_peer_list</a>, you must specify
IPv6 address information inside "<tt>[]</tt>" in the <a href="postconf.5.html">main.cf</a> parameter
value and in files specified with a "<i>/file/name</i>" pattern.
IPv6 addresses contain the ":" character, and would otherwise be
confused with a "<i><a href="DATABASE_README.html">type:table</a></i>" pattern. </b>  </p>

<h2><a name="limitations">Known Limitations</a></h2>

<ul>

<li> <p> Postfix SMTP clients before version 2.8 try to connect
over IPv6 before trying IPv4.  With more recent Postfix versions,
the order of IPv6 versus IPv4 outgoing connection attempts is
configurable with the <a href="postconf.5.html#smtp_address_preference">smtp_address_preference</a> parameter.  </p>

<li> <p> Postfix versions before 2.6 do not support DNSBL (DNS
blocklist) lookups for IPv6 client IP addresses. </p>

<li> <p> IPv6 does not have class A, B, C, etc. networks. With IPv6
networks, the setting "<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = class" has the
same effect as the setting "<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = subnet".
</p>

<li> <p> On Tru64Unix and AIX, Postfix can't figure out the local
subnet mask
and always assumes a /128 network. This is a problem only with
"<a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = subnet" and no explicit <a href="postconf.5.html#mynetworks">mynetworks</a>
setting in <a href="postconf.5.html">main.cf</a>. </p>

</ul>

<h2> <a name="compat">Compatibility with Postfix &lt;2.2 IPv6 support</a>
</h2>

<p> Postfix version 2.2 IPv6 support is based on the Postfix/IPv6 patch
by Dean Strik and others, but differs in a few minor ways. </p>

<ul>

<li> <p> <a href="postconf.5.html">main.cf</a>: The <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> parameter does not support
the notation  "ipv6:all" or "ipv4:all". Use the
<a href="postconf.5.html#inet_protocols">inet_protocols</a> parameter instead. </p>

<li> <p> <a href="postconf.5.html">main.cf</a>: Specify "<a href="postconf.5.html#inet_protocols">inet_protocols</a> = all" or
"<a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv4, ipv6" in order to enable both IPv4
and IPv6 support. </p>

<li> <p> <a href="postconf.5.html">main.cf</a>: The <a href="postconf.5.html#inet_protocols">inet_protocols</a> parameter also controls
what DNS lookups Postfix will attempt to make when delivering or
receiving mail. </p>

<li> <p> <a href="postconf.5.html">main.cf</a>: Specify "<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = loopback-only"
to listen on loopback network interfaces only. </p>

<li> <p> The <a href="postconf.5.html#lmtp_bind_address">lmtp_bind_address</a> and <a href="postconf.5.html#lmtp_bind_address6">lmtp_bind_address6</a>
features were omitted. Postfix version 2.3 merged the LMTP client
into the SMTP client, so there was no reason to keep adding features
to the LMTP client. </p>

<li> <p> The SMTP server now requires that IPv6 addresses in SMTP
commands are specified as [ipv6:<i>ipv6address</i>], as
described in <a href="https://tools.ietf.org/html/rfc2821">RFC 2821</a>. </p>

<li> <p> The IPv6 network address matching code was rewritten from
the ground up, and is expected to be closer to the specification.
The result may be incompatible with the Postfix/IPv6 patch.
</p>

</ul>

<h2><a name="porting">IPv6 Support for unsupported platforms</a></h2>

<p> Getting Postfix IPv6 working on other platforms involves the
following steps: </p>

<ul>

<li> <p> Specify how Postfix should find the local network interfaces.
Postfix needs this information to avoid mailer loops and to find out
if mail for <i>user@[ipaddress]</i> is a local or remote destination. </p>

<p> If your system has the getifaddrs() routine then add
the following to your platform-specific section in
src/util/sys_defs.h:  </p>

<blockquote>
<pre>
#ifndef NO_IPV6
# define HAS_IPV6
# define HAVE_GETIFADDRS
#endif
</pre>
</blockquote>

<p> Otherwise, if your system has the SIOCGLIF ioctl()
command in /usr/include/*/*.h, add the following to your
platform-specific section in src/util/sys_defs.h: </p>

<blockquote>
<pre>
#ifndef NO_IPV6
# define HAS_IPV6
# define HAS_SIOCGLIF
#endif
</pre>
</blockquote>

<p> Otherwise, Postfix will have to use the old SIOCGIF commands
and get along with reduced IPv6 functionality (it won't be able to
figure out your IPv6 netmasks, which are needed for "<a href="postconf.5.html#mynetworks_style">mynetworks_style</a>
= subnet". Add this to your platform-specific section in
src/util/sys_defs.h: </p>

<blockquote>
<pre>
#ifndef NO_IPV6
# define HAS_IPV6
#endif
</pre>
</blockquote>

<li> <p> Test if Postfix can figure out its interface information. </p>

<p> After compiling Postfix in the usual manner, step into the
src/util directory and type "<b>make inet_addr_local</b>".
Running this file by hand should produce all the interface addresses
and network masks, for example: </p>

<blockquote>
<pre>
% make
% cd src/util
% make inet_addr_local
[... some messages ...]
% ./inet_addr_local
[... some messages ...]
./inet_addr_local: inet_addr_local: configured 2 IPv4 addresses
./inet_addr_local: inet_addr_local: configured 4 IPv6 addresses
168.100.189.2/255.255.255.224
127.0.0.1/255.0.0.0
fe80:1::2d0:b7ff:fe88:2ca7/ffff:ffff:ffff:ffff::
2001:240:587:0:2d0:b7ff:fe88:2ca7/ffff:ffff:ffff:ffff::
fe80:5::1/ffff:ffff:ffff:ffff::
::1/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
</pre>
</blockquote>

<p> The above is for an old FreeBSD machine. Other systems produce
slightly different results, but you get the idea. </p>

</ul>

<p> If none of all this produces a usable result, send email to the
postfix-users (a] postfix.org mailing list and we'll try to help you
through this. </p>

<h2><a name="credits">Credits</a></h2>

<p> The following information is in part based on information that
was compiled by Dean Strik. </p>

<ul>

<li> <p> Mark Huizer wrote the original Postfix IPv6 patch. </p>

<li> <p> Jun-ichiro 'itojun' Hagino of the KAME project made
substantial improvements. Since then, we speak of the KAME patch.
</p>

<li> <p> The PLD Linux Distribution ported the code to other stacks
(notably USAGI).  We speak of the PLD patch. A very important
feature of the PLD patch was that it can work with Lutz Jaenicke's
TLS patch for Postfix.  </p>

<li> <p> Dean Strik extended IPv6 support to platforms other than
KAME and USAGI, updated the patch to keep up with Postfix development,
and provided a combined IPv6 + TLS patch.  Information about his
effort can be found on Dean Strik's Postfix website at
<a href="http://www.ipnet6.org/postfix/">http://www.ipnet6.org/postfix/</a>. </p>

<li> <p> Wietse Venema took Dean Strik's IPv6 patch, merged it into
Postfix 2.2, and took the opportunity to eliminate all IPv4-specific
code from Postfix that could be removed.  For systems without IPv6
support in the kernel and system libraries, Postfix has a simple
compatibility layer, so that it will use IPv4 as before.  </p>

</ul>

</body>

</html>