merge nat.conf.5

most work by Chris Kuethe, some changes by me.
ok dhartmei@, pb@

1 files changed, 199 insertions, 18 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 9b8a1f3367e..ea878e6458b 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.57 2002/06/14 21:34:58 todd Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.58 2002/06/16 17:54:30 henning Exp $
 .\"
 .\" Copyright (c) 2001, Daniel Hartmeier
 .\" All rights reserved.
@@ -27,20 +27,29 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 8, 2001
+.Dd June 14, 2002
 .Dt PF.CONF 5
 .Os
 .Sh NAME
 .Nm pf.conf
-.Nd filter rule configuration file for packet filtering
+.Nd filtering and translation (NAT) rules file for the packet filter
 .Sh DESCRIPTION
 The
 .Xr pf 4
 packet filter drops, passes and modifies packets according to the
 rules defined in this file.
+Filter rules are used to selectively pass traffic while translation
+rules specify which addresses are to be mapped and which are to be
+redirected.
 For each packet inspected by the filter, the set of rules is evaluated
 from top to bottom, and the last matching rule decides what action is
 performed.
+For each packet inspected by the translator, the set of rules is evaluated
+from top to bottom, and the first matching rule decides what action is
+performed.
+In short: filters are last match, nat is first match.
+Rules must be in order: scrub, nat, filter.
+
 .Sh GRAMMAR
 Syntax for filter rules in BNF:
 .Bd -literal
@@ -103,20 +112,70 @@ icmp-list      = icmp-type-code [ "," icmp-list ] .
 
 state-opts     = state-opt [ "," state-opts ] .
 state-opt      = ( "max" number ) | ( timeout number ) .
+.Ed
+.Pp
+Syntax for translation rules in BNF:
+.Bd -literal
+rule      = [ "no" ] ( nat_rule | binat_rule | rdr_rule ) .
+
+nat_rule  = "nat" "on" [ "!" ] ifname [ protospec ] hosts
+            [ "->" address [ portspec ] ] .
+
+binat_rule = "binat" "on" ifname [ protospec ] "from" address
+             "to" ipspec [ "->" address ] .
+
+rdr_rule  = "rdr" "on" [ "!" ] ifname [ protospec ] "from" ipspec
+            "to" ipspec [ portspec ] [ "->" address [ portspec ] ] .
+
+protospec = "proto" ( number | "tcp" | "udp" | "icmp" ) .
+
+ipspec    = "any" | host | "{" host-list "}" .
+
+portspec  = "port" ( number | name ) [ ":" ( "*" | number | name ) ] .
+
+hosts     = "all" |
+            "from" ( "any" | host | "{" host-list "}" ) [ port ]
+            "to"   ( "any" | host | "{" host-list "}" ) [ port ] .
+
+host      = [ "!" ] address [ "/" mask-bits ] .
+address   = ( interface-name | "(" interface-name ")" | host-name |
+              ipv4-dotted-quad | ipv6-coloned-hex ) .
+host-list = host [ "," host-list ] .
 
+port      = "port" ( unary-op | binary-op | "{" op-list "}" ) .
+unary-op  = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ]
+            ( name | number ) .
+binary-op = number ( "<>" | "><" ) number .
+op-list   = ( unary-op | binary-op ) [ "," op-list ] .
 .Ed
 .Sh FILTER RULES
-Filter rules are typically manipulated using
-.Xr pfctl 8 .
-Filter rules are loaded from a text file into the kernel using
+While filter rules are typically manipulated using
+.Xr pfctl 8
+other utilities may be written using the
+.Xr ioctl 2
+interface described in
+.Xr pf 4 .
+Filter and NAT rules are loaded from a text file into the kernel using
 .Pp
-.Cm # pfctl -R file
+.Cm # pfctl -f file
 .Pp
 which replaces the active rule set with the new one.
-The active rule set can be displayed using
+To load only the filter rules from a file, one would use the command
+.Pp
+.Cm # pfctl -R -f file
+.Pp
+To load only the NAT rules from a file, one would use the command
+.Pp
+.Cm # pfctl -N -f file
+.Pp
+The active filter rule set can be displayed using
 .Pp
 .Cm # pfctl -s r
 .Pp
+The active translation rule set can be displayed using
+.Pp
+.Cm # pfctl -s n
+.Pp
 For each packet processed by the packet filter, the filter rules are
 evaluated in sequential order, from first to last.
 Each rule either matches the packet or doesn't.
@@ -133,19 +192,69 @@ that match explicit rules, one uses
 .Ed
 .Pp
 as the first two rules.
+.Pp
+For each packet processed by the translator, the translation rules are
+evaluated in sequential order, from first to last.
+Each rule either matches the packet or doesn't.
+The first matching rule decides what action is taken.
+.Pp
+If no rule matches the packet, the default action is to pass the packet
+up to the filter unmodified.
+It should be noted that that all translations of packets occur before
+the filters are applied.
+Hence, rules for redirected packets should specify the address and port
+after translation.
+Note that all translation rules apply only to packets that pass through
+the specified interface.
+For instance, redirecting port 80 on an external interface to an internal
+web server will only work for connections originating from the outside.
+Connections to the address of the external interface from local hosts will
+not be redirected, since such packets do not actually pass through the
+external interface.
+Redirections can't reflect packets back through the interface they arrive
+on, they can only be redirected to hosts connected to different interfaces
+or to the firewall itself.
 .Sh ACTIONS
 .Bl -tag -width Fl
-.It Em pass
-The packet is passed.
 .It Em block
 The packet is blocked.
 Optionally, the filter can return a TCP RST or ICMP UNREACHABLE packet
 to the sender, where applicable. Returning ICMP packets can have
 an ICMP code set by number or name, TCP RST can have a TTL set.
+.It Em pass
+The packet is passed.
 .It Em scrub
 The packet is run through normalization/defragmentation.
 Scrub rules are not considered last matching rules.
 IPv6 packets are not defragmented.
+.It Em binat
+A
+.Em binat
+rule specifies a bidirectional mapping between an external IP address and an internal IP address.
+.It Em nat
+A
+.Em nat
+rule specifies that IP addresses are to be changed as the packet
+traverses the given interface. This technique allows a single IP address
+on the translating host to support network traffic for a larger range of
+machines on an "inside" network.
+Although in theory any IP address can be used on the inside, it is strongly
+recommended that one of the address ranges defined by RFC 1918 be used.
+These netblocks are:
+.Bd -literal
+10.0.0.0    - 10.255.255.255 (all of net 10, i.e., 10/8)
+172.16.0.0  - 172.31.255.255 (i.e., 172.16/12)
+192.168.0.0 - 192.168.255.255 (i.e., 192.168/16)
+.Ed
+.It Em rdr
+The packet is redirected to a another destination and possibly a
+different port.
+.Em rdr
+rules can optionally specify port ranges instead of single ports.
+\'rdr ... port 2000:2999 -> ... port 4000\' redirects ports 2000 to 2999
+(including port 2000 and 2999) to the same port 4000.
+\'rdr ... port 2000:2999 -> ... port 4000:*\' redirects port 2000 to 4000,
+2001 to 4001, ..., 2999 to 4999.
 .El
 .Sh LOGGING
 .Bl -tag -width Fl
@@ -181,6 +290,13 @@ If a packet matches a rule which has the
 option set, this rule
 is considered the last matching rule, and evaluation of subsequent rules
 is skipped.
+.Sh NO
+The
+.Sq no
+option is to a NAT rule what the
+.Sq quick
+option is to a filter rule. This option causes matching packets
+to remain untranslated.
 .Sh ROUTING
 If a packet matches a rule with a route option set, the packet filter will
 route the packet according to the type of route option.
@@ -487,12 +603,7 @@ lets echo requests
 .Pq pings
 out, creates state, and matches incoming echo replies correctly to states.
 .Pp
-Note: nat/rdr rules
-.Po
-see
-.Xr nat.conf 5
-.Pc
-implicitly create state for connections.
+Note: nat/rdr rules implicitly create state for connections.
 .Sh STATE MODULATION
 Much of the security derived from TCP is attributable to how well the
 initial sequence numbers (ISNs) are chosen.
@@ -641,7 +752,7 @@ also be adjusted.
 .Pp
 Currently, only IPv4 fragments are supported and IPv6 fragments
 are blocked unconditionally.
-.Sh EXAMPLES
+.Sh FILTER EXAMPLES
 .Bd -literal
 # The external interface is kue0 (157.161.48.183, the only routable address)
 # and the private network is 10.0.0.0/8, for which we are doing NAT.
@@ -710,6 +821,77 @@ pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 41952 \\
 	keep state
 
 .Ed
+.SH NAT EXAMPLES
+This example maps incoming requests on port 80 to port 8080, on
+which Apache Tomcat is running (say Tomcat is not run as root,
+therefore lacks permission to bind to port 80).
+.Bd -literal
+# map tomcat on 8080 to appear to be on 80
+rdr on ne3 proto tcp from any to any port 80 -> 127.0.0.1 port 8080
+.Ed
+.Pp
+In the example below, vlan12 is configured for the 192.168.168.1;
+the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
+when they are going out any interface except vlan12.
+This has the net effect of making traffic from the 192.168.168.0/24
+network appear as though it is the Internet routeable address
+204.92.77.111 to nodes behind any interface on the router except
+for the nodes on vlan12.
+(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.)
+.Bd -literal
+nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111
+.Ed
+.Pp
+In the example below, fxp1 is the outside interface; the machine sits between a
+fake internal 144.19.74.* network, and a routable external IP of 204.92.77.100.
+The "no nat" rule excludes protocol AH from being translated.
+.Bd -literal
+#NO NAT
+no nat on fxp1 proto ah from 144.19.74.0/24 to any
+nat on fxp1 from 144.19.74.0/24 to any -> 204.92.77.100
+.Ed
+.Pp
+In the example below, fxp0 is the internal interface. Packets bound
+for one specific server, as well as those generated by the sysadmins
+are not proxied, all other connections are.
+.Bd -literal
+# NO RDR
+no rdr on fxp0 from any        to $server port 80
+no rdr on fxp0 from $sysadmins to any     port 80
+   rdr on fxp0 from any        to any     port 80 -> 127.0.0.1 80
+.Ed
+.Pp
+This longer example uses both a NAT and a redirection.
+Interface kue0 is the outside interface, and its external address is
+157.161.48.183.
+Interface fxp0 is the inside interface, and we are running
+.Xr ftp-proxy 8
+listening for outbound ftp sessions captured to port 8081.
+.Bd -literal
+# NAT
+# translate outgoing packets' source addresses (any protocol)
+# in my case, any address but the gateway's external address is mapped
+nat on kue0 from ! (kue0) to any -> (kue0)
+
+# BINAT
+# translate outgoing packets' source address (any protocol)
+# translate incoming packets' destination address to an internal machine
+# (bidirectional)
+binat on kue0 from 10.1.2.150 to any -> (kue0)
+
+# RDR
+# translate incoming packets' destination addresses
+# as an example, redirect a TCP and UDP port to an internal machine
+rdr on kue0 proto tcp from any to (kue0) port 8080 -> 10.1.2.151 port 22
+rdr on kue0 proto udp from any to (kue0) port 8080 -> 10.1.2.151 port 53
+
+# RDR
+# translate outgoing ftp control connections to send them to localhost
+# for proxying with ftp-proxy(8) running on port 8081
+rdr on fxp0 proto tcp from any to any port 21 -> 127.0.0.1 port 8081
+
+
+.Ed
 .Sh FILES
 .Bl -tag -width "/etc/pf.conf" -compact
 .It Pa /etc/hosts
@@ -720,7 +902,6 @@ pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 41952 \\
 .Sh SEE ALSO
 .Xr pf 4 ,
 .Xr hosts 5 ,
-.Xr nat.conf 5 ,
 .Xr protocols 5 ,
 .Xr services 5 ,
 .Xr ftp-proxy 8 ,