Long overdue documentation update for IPFilter. These

are taken directly from the ipf distribution, and are
not mandoc'ed. ipf(8), ipfstat(8), and ipnat(8) are yet
to go and must be done manually. (sigh)

1 files changed, 152 insertions, 145 deletions

diff --git a/sbin/ipnat/ipnat.5 b/sbin/ipnat/ipnat.5
index 61e2878d280..48cd0da1993 100644
--- a/sbin/ipnat/ipnat.5
+++ b/sbin/ipnat/ipnat.5
@@ -1,153 +1,160 @@
-.\"      $OpenBSD: ipnat.5,v 1.13 2000/03/18 22:55:59 aaron 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
+.\"	$OpenBSD: ipnat.5,v 1.14 2000/04/13 19:59:39 kjell 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 .
 
-maprule     ::= "map" ifname source "->" destination [mapoption]
-rdrrule     ::= "rdr" ifname destination port "->" target
-bimaprule   ::= "bimap" ifname source "->" destination
+map ::= mapit ifname ipmask "->" ipmask [ mapport ] .
+mapblock ::= "map-block" ifname ipmask "->" ipmask [ ports ] .
+redir ::= "rdr" ifname [ fromspec ] ipmask "->" ip [ ports ] [ tcpudp ] .
+ports ::= "ports" numports | "auto" .
+mapit ::= "map" | "bimap" .
+ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask .
+mapport ::= "portmap" tcpudp portnumber ":" portnumber .
 
-source      ::= destination
-destination ::= host "/" mask
-target      ::= host "port" port porttype
+fromspec ::= "from" ip "/" ipmask .
+tcpudp ::= "tcp" | "udp" | "tcp/udp" .
+portnumber ::= number { numbers } | "auto" .
+ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers .
 
-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
+numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' .
+.fi
+.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.  In the case
+of redirects, it is also possible to select packets on a source address basis
+using the \fBfrom\fP keyword, as well as the manditory destination port.  The
+packet \fImatching\fP part of the rule is to the left of the "->" in each rule.
+.SH TRANSLATION
+.PP
+To the right of the "->" is the address and port specificaton which will be
+written into the packet providing it has already successful matched the
+prior constraints.  The case of redirections (\fBrdr\fP) is the simpliest:
+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 alloted 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 TRNSPARENT 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 EXAMPLES
+.PP
+This section deals with the \fBmap\fP command and it's 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
-.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
+.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
-.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
+.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:
-.Bd -literal -offset indent
+.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
-.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
-
+.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 instaces, 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 discernable 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.
+/dev/ipnat
+.br
+/etc/services
+.br
+/etc/hosts
+.SH SEE ALSO
+ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)