.\"	$NetBSD: ipnat.5,v 1.14 2003/07/02 13:26:26 wiz Exp $
.\"
.TH IPNAT 5
.SH NAME
ipnat, ipnat.conf \- IP NAT file format
.SH DESCRIPTION
The format for files accepted by ipnat is described by the following grammar:
.LP
.nf
ipmap :: = mapblock | redir | map .

map ::= mapit ifname ipmask "->" dstipmask [ mapport ] [ clamp ] .
map ::= mapit ifname fromto "->" dstipmask [ mapport ] [ clamp ] .
mapblock ::= "map-block" ifname ipmask "->" ipmask [ ports ] [ clamp ] .
redir ::= "rdr" ifname ipmask dport "->" ip [ "," ip ] rdrport options .

dport ::= "port" portnum [ "-" portnum ] .
ports ::= "ports" numports | "auto" .
rdrport ::= "port" portnum .
mapit ::= "map" | "bimap" .
fromto ::= "from" object "to" object .
ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask .
dstipmask ::= ipmask | "range" ip "-" ip .
mapport ::= "portmap" tcpudp portspec .
clamp ::= "mssclamp" number .
options ::= [ tcpudp ] [ rr ] .

object  :: = addr [ port-comp | port-range ] .
addr    :: = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] .
port-comp :: = "port" compare port-num .
port-range :: = "port" port-num range port-num .

rr ::= "round-robin" .
nummask = host-name [ "/" decnumber ] .
tcpudp ::= "tcp" | "udp" | "tcp/udp" .
portspec ::= "auto" | portnumber ":" portnumber .
portnumber ::= number { numbers } .
ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers .

numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' .
.fi
.PP
In addition to this, # is used to mark the start of a comment and may
appear at the end of a line with a NAT rule (as described above) or on its
own lines.  Blank lines are ignored.
.PP
For standard NAT functionality, a rule should start with \fBmap\fP and then
proceeds to specify the interface for which outgoing packets will have their
source address rewritten.
.PP
Packets which will be rewritten can only be selected by matching the original
source address.  A netmask must be specified with the IP address.
.PP
The address selected for replacing the original is chosen from an IP#/netmask
pair.  A netmask of all 1's indicating a hostname is valid.  A netmask of
31 1's (255.255.255.254) is considered invalid as there is no space for
allocating host IP#'s after consideration for broadcast and network
addresses.
.PP
When remapping TCP and UDP packets, it is also possible to change the source
port number.  Either TCP or UDP or both can be selected by each rule, with a
range of port numbers to remap into given as \fBport-number:port-number\fP.
.SH COMMANDS
There are four commands recognised by IP Filter's NAT code:
.TP
.B map
that is used for mapping one address or network to another in an unregulated
round robin fashion;
.TP
.B rdr
that is used for redirecting packets to one IP address and port pair to
another;
.TP
.B bimap
for setting up bidirectional NAT between an external IP address and an internal
IP address and
.TP
.B map-block
which sets up static IP address based translation, based on a algorithm to
squeeze the addresses to be translated into the destination range.
.SH MATCHING
.PP
For basic NAT and redirection of packets, the address subject to change is used
along with its protocol to check if a packet should be altered.  The packet
\fImatching\fP part of the rule is to the left of the "->" in each rule.
.PP
Matching of packets has now been extended to allow more complex compares.
In place of the address which is to be translated, an IP address and port
number comparison can be made using the same expressions available with
\fBipf\fP.  A simple NAT rule could be written as:
.LP
.nf
map de0 10.1.0.0/16 -> 201.2.3.4/32
.fi
.LP
or as
.LP
.nf
map de0 from 10.1.0.0/16 to any -> 201.2.3.4/32
.fi
.LP
For even greater control, one may negate either of the "from" or "to" clauses
with a preceding exclamation mark ("!").  Please note that one may not use a
negated "from" within a \fBmap\fP rule or a negated "to" within a \fBrdr\fP
rule.  Such a rule might look like the following:
.LP
.nf
+map de0 from 10.1.0.0/16 ! to 10.1.0.0/16 -> 201.2.3.4/32
.fi
.PP
Only IP address and port numbers can be compared against.  This is available
with all NAT rules.
.SH TRANSLATION
.PP
To the right of the "->" is the address and port specification which will be
written into the packet providing it has already successfully matched the
prior constraints.  The case of redirections (\fBrdr\fP) is the simplest:
the new destination address is that specified in the rule.  For \fBmap\fP
rules, the destination address will be one for which the tuple combining
the new source and destination is known to be unique.  If the packet is
either a TCP or UDP packet, the destination and source ports come into the
equation too.  If the tuple already exists, IP Filter will increment the
port number first, within the available range specified with \fBportmap\fP
and if there exists no unique tuple, the source address will be incremented
within the specified netmask.  If a unique tuple cannot be determined, then
the packet will not be translated.  The \fBmap-block\fP is more limited in
how it searches for a new, free and unique tuple, in that it will used an
algorithm to determine what the new source address should be, along with the
range of available ports - the IP address is never changed and nor does the
port number ever exceed its allotted range.
.SH KERNEL PROXIES
.PP
IP Filter comes with a few, simple, proxies built into the code that is loaded
into the kernel to allow secondary channels to be opened without forcing the
packets through a user program.
.SH TRANSPARENT PROXIES
.PP
True transparent proxying should be performed using the redirect (\fBrdr\fP)
rules directing ports to localhost (127.0.0.1) with the proxy program doing
a lookup through \fB/dev/ipnat\fP to determine the real source and address
of the connection.
.SH LOAD-BALANCING
.PP
Two options for use with \fBrdr\fP are available to support primitive,
\fIround-robin\fP based load balancing.  The first option allows for a
\fBrdr\fP to specify a second destination, as follows:
.LP
.nf
rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp
.fi
.LP
This would send alternate connections to either 203.1.2.3 or 203.1.2.4.
In scenarios where the load is being spread amongst a larger set of
servers, you can use:
.LP
.nf
rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp round-robin
rdr le0 203.1.2.3/32 port 80 -> 203.1.2.5 port 80 tcp round-robin
.fi
.LP
In this case, a connection will be redirected to 203.1.2.3, then 203.1.2.4
and then 203.1.2.5 before going back to 203.1.2.3.  In accomplishing this,
the rule is removed from the top of the list and added to the end,
automatically, as required.  This will not effect the display of rules
using "ipnat -l", only the internal application order.
.SH EXAMPLES
.PP
This section deals with the \fBmap\fP command and its variations.
.PP
To change IP#'s used internally from network 10 into an ISP provided 8 bit
subnet at 209.1.2.0 through the ppp0 interface, the following would be used:
.LP
.nf
map ppp0 10.0.0.0/8 -> 209.1.2.0/24
.fi
.PP
The obvious problem here is we're trying to squeeze over 16,000,000 IP
addresses into a 254 address space.  To increase the scope, remapping for TCP
and/or UDP, port remapping can be used;
.LP
.nf
map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
.fi
.PP
which falls only 527,566 `addresses' short of the space available in network
10.  If we were to combine these rules, they would need to be specified as
follows:
.LP
.nf
map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
map ppp0 10.0.0.0/8 -> 209.1.2.0/24
.fi
.PP
so that all TCP/UDP packets were port mapped and only other protocols, such as
ICMP, only have their IP# changed.  In some instances, it is more appropriate
to use the keyword \fBauto\fP in place of an actual range of port numbers if
you want to guarantee simultaneous access to all within the given range.
However, in the above case, it would default to 1 port per IP address, since
we need to squeeze 24 bits of address space into 8.  A good example of how
this is used might be:
.LP
.nf
map ppp0 172.192.0.0/16 -> 209.1.2.0/24 portmap tcp/udp auto
.fi
.PP
which would result in each IP address being given a small range of ports to
use (252).  The problem here is that the \fBmap\fP directive tells the NAT
code to use the next address/port pair available for an outgoing connection,
resulting in no easily discernible relation between external addresses/ports
and internal ones.  This is overcome by using \fBmap-block\fP as follows:
.LP
.nf
map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto
.fi
.PP
For example, this would result in 172.192.0.0/24 being mapped to 209.1.2.0/32
with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its
own.  As opposed to the above use of \fBmap\fP, if for some reason the user
of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would
be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next
IP address with the \fBmap\fP command.
.LP
.nf
map pppoe0 10.0.0.0/8 -> 209.1.2.0/24 mssclamp 1452
.fi
.PP
The mssclamp clause tells the NAT processor to scan for TCP packets in the
three-way handshake and limit their negotiated MSS value to the number
given in the rule. This is useful to make hosts behind a connection with
low MTU (like PPPoE or tunnels) communicate without any outside proxies
with broken sites that use a misconfigured firewall. Unfortunately such
sites are not rare.
.PP
The value for the clamping clause is calculated as interface-MTU less
40 bytes (size of IP header plus maximal IP options size), so for a
PPPoE interface it is 1492 - 40 = 1452. Some sites seem to require clamping
to even smaller values, but there is no rationale for this behaviour.
.SH FILES
/dev/ipnat
.br
/etc/services
.br
/etc/hosts
.br
/usr/share/examples/ipf  Directory with examples.
.SH SEE ALSO
ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)