.\"      $OpenBSD: ipnat.5,v 1.12 2000/01/24 07:27:02 kjell Exp $
.Dd June 5, 1999
.Dt IPNAT 5
.Os
.Sh NAME
.Nm ipnat
.Nd IP NAT file format
.Sh DESCRIPTION
Files processed by
.Xr ipnat 8
are normal text files containing either a valid NAT rule or a comment on each
non-blank line. Comment lines begin with a
.Ql #
and are ignored, as are blank lines. Valid NAT rules
are described by the following grammar:
.Bd -literal -offset indent
natrule     ::= maprule | rdrrule | bimaprule

maprule     ::= "map" ifname source "->" destination [mapoption]
rdrrule     ::= "rdr" ifname destination port "->" target
bimaprule   ::= "bimap" ifname source "->" destination

source      ::= destination
destination ::= host "/" mask
target      ::= host "port" port porttype

portrange   ::= port ":" port
portmap     ::= "portmap" porttype portrange
proxy       ::= "proxy port" port [ "/" protocol ]
mapoption   ::= proxy | portmap

porttype    ::= "tcp" | "udp" | "tcpudp" | "tcp/udp"

protocol    ::= <name from /etc/protocols> | <# from /etc/protocols>
port        ::= <unsigned 16 bit value> | <name from /etc/services>
host        ::= 'any' | <IP addr> | <interface name> | <host name>
mask        ::= <non-numeric> | <IP addr> | <hex value> | <bit count>
ifname      ::= <interface name>
.Ed
.Pp
Elements in a rule are usually separated by whitespace (blanks or tabs).
In the case of the
.Ql \&/
in
.Fa host
rule or the
.Ql \&:
in the
.Fa portrange
rule, there must be no whitespace before or after it. In the case
of the
.Ql \&/
in the
.Fa proxy
rule there must be whitespace before but no whitespace after.
.Pp
In the
.Fa host
and
.Fa mask
rules, the alternatives are evaluated in the order given.
.Pp
For the
.Fa mask
rule, if the element begins with a non-digit the mask is taken to be all zeros.
A
.Ql \&.
in the element causes the element to be interpreted as a numeric IP
address of the form 1.2.3.4. An
.Ql x
in the element causes the element to be interpreted as a 32 bit hex value. If all
else fails the element is interpreted as the number of sequential 1's to place
as the most significant bits in the 32 bit network mask.
Whatever the interpretation method, a result network mask of all 1's, indicating a
hostname, is valid.  A network mask of 31 1's (255.255.255.254)
is considered invalid as there is no space for allocating host
.Tn IP Ns #\&'s
after consideration for broadcast and network addresses.
.Sh EXAMPLES
To change
.Tn IP
numbers 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:
.Bd -literal -offset indent
map ppp0 10.0.0.0/8 -> 209.1.2.0/24
.Ed
.Pp
The obvious problem here is we're trying to squeeze over 16,000,000
.Tn IP
addresses into a 254 address space. To increase the scope, remapping for
.Tn TCP
and/or
.Tn UDP ,
port remapping can be used:
.Bd -literal -offset indent
map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
.Ed
.Pp
which falls only 527,566
.Sq addresses
short of the space available in network
10.  If we were to combine these rules, they would need to be specified as
follows:
.Bd -literal -offset indent
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
.Ed
.Pp
so that all
.Tn TCP Ns / Tn UDP
packets were port mapped and other protocols, such as
.Tn ICMP ,
have only their
.Tn IP Ns #
changed.
.Pp
Further examples can be found in the file
.Pa \&/use\&/share\&/ipf\&/nat\&.1
.Sh FILES
.Bl -tag -width "/usr/share/ipf/nat.1" -compact
.It Pa /dev/ipnat
.It Pa /etc/services
.It Pa /etc/protocols
.It Pa /etc/hosts
.It Pa /usr/share/ipf/nat.1
example rules
.It Pa /usr/share/ipf/nat.2
system requirements for use of NAT
.It Pa /etc/ipnat.rules
actual rule list
.El
.Sh SEE ALSO
.Xr ipf 8 ,
.Xr ipftest 1 ,
.Xr ipf 4 ,
.Xr ipl 4 ,
.Xr ipnat 4 ,
.Xr hosts 5 ,
.Xr ipf 5 ,
.Xr services 5
.Xr protocols 5
.Xr ipfstat 8 ,
.Xr ipmon 8 ,
.Xr ipnat 8
.Pp
http://coombs.anu.edu.au/~avalon