document af-to (aka nat64)

the patch was started by todd about a year ago and have been
finally finished by phessler and myself today; discussed with
and tweaks from jmc, ok sthen, henning

1 files changed, 70 insertions, 2 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 294236b167c..509eee79b80 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.conf.5,v 1.511 2012/01/16 01:18:31 bluhm Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.512 2012/01/30 21:56:48 mikeb Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 16 2012 $
+.Dd $Mdocdate: January 30 2012 $
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -525,6 +525,7 @@ if one flushes the state table.
 However, states created from such intermediate packets may be missing
 connection details such as the TCP window scaling factor.
 States which modify the packet flow, such as those affected by
+.Ar af-to,
 .Ar modulate ,
 .Ar nat-to ,
 .Ar rdr-to ,
@@ -798,6 +799,56 @@ and correctly direct return traffic for that connection.
 .Pp
 Different types of translation are possible with pf:
 .Bl -tag -width xxxxxxxx
+.It Ar af-to
+Translation between different address families (NAT64) is handled
+using
+.Ar af-to
+rules.
+Because address family translation overrides the routing table, it's
+only possible to use
+.Ar af-to
+on inbound rules, and a source address of the resulting translation
+must always be specified.
+.Pp
+The optional second argument is the host or subnet the original
+addresses are translated into for the destination.
+The lowest bits of the original destination address form the host
+part of the new destination address according to the specified subnet.
+It is possible to embed a complete IPv4 address into an IPv6 address
+using a network prefix of /96 or smaller.
+.Pp
+When a destination address is not specified it is assumed that the host
+part is 32-bit long.
+For IPv6 to IPv4 translation this would mean using only the lower 32
+bits of the original IPv6 destination address.
+For IPv4 to IPv6 translation the destination subnet defaults to the
+subnet of the new IPv6 source address with a prefix length of /96.
+See RFC 6052 Section 2.2 for details on how the prefix determines the
+destination address encoding.
+.Pp
+For example, the following rules are identical:
+.Bd -literal -offset indent
+pass in inet af-to inet6 from 2001:db8::1 to 2001:db8::/96
+pass in inet af-to inet6 from 2001:db8::1
+.Ed
+.Pp
+In the above example the matching IPv4 packets will be modified to
+have a source address of 2001:db8::1 and a destination address will
+get prefixed with 2001:db8::/96, e.g. 198.51.100.100 will be
+translated to 2001:db8::c633:6464.
+.Pp
+In the reverse case the following rules are identical:
+.Bd -literal -offset indent
+pass in inet6 af-to inet from 198.51.100.1 to 0.0.0.0/0
+pass in inet6 af-to inet from 198.51.100.1
+.Ed
+.Pp
+The destination IPv4 address is assumed to be embedded inside the
+original IPv6 destination address, e.g. 64:ff9b::c633:6464 will be
+translated to 198.51.100.100.
+.Pp
+The current implementation will only extract IPv4 addresses from the
+IPv6 addresses with a prefix length of /96 and greater.
 .It Ar binat-to
 A
 .Ar binat-to
@@ -896,6 +947,7 @@ connections only to daemons bound to this address or not bound to
 any address.
 .Pp
 For
+.Ar af-to ,
 .Ar nat-to
 and
 .Ar rdr-to
@@ -2679,6 +2731,20 @@ pass out on $ext_if inet from 10.1.2.120 to any \e
       nat-to 192.0.2.17 static-port
 pass in on $ext_if inet from any to 192.0.2.17 rdr-to 10.1.2.120
 .Ed
+.Pp
+In the example below, a router handling both address families
+translates an internal IPv4 subnet to IPv6 using the well-known
+64:ff9b::/96 prefix:
+.Bd -literal -offset 4n
+pass in on $v4_if inet af-to inet6 from ($v6_if) to 64:ff9b::/96
+.Ed
+.Pp
+Paired with the example above, the example below can be used on
+another router handling both address families to translate back
+to IPv4:
+.Bd -literal -offset 4n
+pass in on $v6_if inet6 to 64:ff9b::/96 af-to inet from ($v4_if)
+.Ed
 .Sh GRAMMAR
 Syntax for
 .Nm
@@ -2723,6 +2789,8 @@ filteropt      = user | group | flags | icmp-type | icmp6-type |
                  "prio" ( number | "(" number [ [ "," ] number ] ")" ) |
                  "queue" ( string | "(" string [ [ "," ] string ] ")" ) |
                  "rtable" number | "probability" number"%" |
+		 "af-to" af "from" ( redirhost | "{" redirhost-list "}" )
+		 [ "to" ( redirhost | "{" redirhost-list "}" ) ] |
 		 "binat-to" ( redirhost | "{" redirhost-list "}" )
 		 [ portspec ] [ pooltype ] |
 		 "rdr-to" ( redirhost | "{" redirhost-list "}" )