reduce the verbosity of the two examples sections, and provide some

indent;

ok henning

1 files changed, 106 insertions, 143 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 98b3a2da2b8..d52f4173e7e 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.435 2009/04/24 05:44:39 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.436 2009/04/24 15:40:02 jmc Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -2470,21 +2470,18 @@ characters around the anchor name.
 This example maps incoming requests on port 80 to port 8080, on
 which a daemon is running (because, for example, it is not run as root,
 and therefore lacks permission to bind to port 80).
-.Bd -literal
-# use a macro for the interface name, so it can be changed easily
-ext_if = \&"ne3\&"
-
-# map daemon on 8080 to appear to be on 80
-rdr on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 port 8080
+.Bd -literal -offset 4n
+rdr on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 \e
+    port 8080
 .Ed
 .Pp
 If the
 .Ar pass
 modifier is given, packets matching the translation rule are passed without
-inspecting the filter rules:
-.Bd -literal
+inspecting the filter rules.
+.Bd -literal -offset 4n
 rdr pass on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 \e
-      port 8080
+    port 8080
 .Ed
 .Pp
 In the example below, vlan12 is configured as 192.168.168.1;
@@ -2494,185 +2491,151 @@ This has the net effect of making traffic from the 192.168.168.0/24
 network appear as though it is the Internet routable 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
+Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.
+.Bd -literal -offset 4n
 nat on ! vlan12 from 192.168.168.0/24 to any -\*(Gt 204.92.77.111
 .Ed
 .Pp
-In the example below, the machine sits between a fake internal 144.19.74.*
-network, and a routable external IP of 204.92.77.100.
+In the example below, the machine sits between a fake internal
+144.19.74.* network, and a routable external IP of 204.92.77.100.
 The
 .Ar no nat
 rule excludes protocol AH from being translated.
-.Bd -literal
-# NO NAT
+.Bd -literal -offset 4n
 no nat on $ext_if proto ah from 144.19.74.0/24 to any
 nat on $ext_if from 144.19.74.0/24 to any -\*(Gt 204.92.77.100
 .Ed
 .Pp
 In the example below, 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
+.Bd -literal -offset 4n
 no rdr on $int_if proto { tcp, udp } from any to $server port 80
 no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80
-rdr on $int_if proto { tcp, udp } from any to any port 80 -\*(Gt 127.0.0.1 \e
-      port 80
-.Ed
-.Pp
-This longer example uses both a NAT and a redirection.
-The external interface has the address 157.161.48.183.
-On localhost, we are running
-.Xr ftp-proxy 8 ,
-waiting for FTP sessions to be redirected to it.
-The three mandatory anchors for
-.Xr ftp-proxy 8
-are omitted from this example; see the
-.Xr ftp-proxy 8
-manpage.
-.Bd -literal
-# NAT
-# Translate outgoing packets' source addresses (any protocol).
-# In this case, any address but the gateway's external address is mapped.
-nat on $ext_if inet from ! ($ext_if) to any -\*(Gt ($ext_if)
-
-# NAT PROXYING
-# Map outgoing packets' source port to an assigned proxy port instead of
-# an arbitrary port.
-# In this case, proxy outgoing isakmp with port 500 on the gateway.
-nat on $ext_if inet proto udp from any port = isakmp to any -\*(Gt ($ext_if) \e
-      port 500
-
-# BINAT
-# Translate outgoing packets' source address (any protocol).
-# Translate incoming packets' destination address to an internal machine
-# (bidirectional).
+rdr on $int_if proto { tcp, udp } from any to any port 80 \e
+    -\*(Gt 127.0.0.1 port 80
+.Ed
+.Pp
+This example maps outgoing packets' source port
+to an assigned proxy port instead of an arbitrary port.
+In this case, proxy outgoing isakmp with port 500 on the gateway.
+.Bd -literal -offset 4n
+nat on $ext_if inet proto udp from any port isakmp to any \e
+    -\*(Gt ($ext_if) port 500
+.Ed
+.Pp
+Two more examples.
+The first uses binat to translate source and destination addresses
+(bidirectional).
+The second uses rdr to redirect a TCP and UDP port to an internal machine.
+.Bd -literal -offset 4n
 binat on $ext_if from 10.1.2.150 to any -\*(Gt $ext_if
 
-# RDR
-# Translate incoming packets' destination addresses.
-# As an example, redirect a TCP and UDP port to an internal machine.
 rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
-      -\*(Gt 10.1.2.151 port 22
+    -\*(Gt 10.1.2.151 port 22
 rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
-      -\*(Gt 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 8021.
-rdr on $int_if proto tcp from any to any port 21 -\*(Gt 127.0.0.1 port 8021
+    -\*(Gt 10.1.2.151 port 53
 .Ed
 .Pp
 In this example, a NAT gateway is set up to translate internal addresses
-using a pool of public addresses (192.0.2.16/28) and to redirect
-incoming web server connections to a group of web servers on the internal
-network.
-.Bd -literal
-# NAT LOAD BALANCE
-# Translate outgoing packets' source addresses using an address pool.
-# A given source address is always translated to the same pool address by
-# using the source-hash keyword.
+using a pool of public addresses (192.0.2.16/28).
+A given source address is always translated to the same pool address by
+using the source-hash keyword.
+The gateway also translates incoming web server connections
+to a group of web servers on the internal network.
+.Bd -literal -offset 4n
 nat on $ext_if inet from any to any -\*(Gt 192.0.2.16/28 source-hash
-
-# RDR ROUND ROBIN
-# Translate incoming web server connections to a group of web servers on
-# the internal network.
 rdr on $ext_if proto tcp from any to any port 80 \e
-      -\*(Gt { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
+    -\*(Gt { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
 .Ed
 .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.
-
-# use a macro for the interface name, so it can be changed easily
+In this example,
+the external interface is kue0.
+We use a macro for the interface name, so it can be changed easily.
+All incoming traffic is "normalised",
+and everything is blocked and logged by default.
+.Bd -literal -offset 4n
 ext_if = \&"kue0\&"
-
-# normalise all incoming traffic
 match in all scrub (no-df max-mss 1440)
-
-# block and log everything by default
 block return log on $ext_if all
-
-# block anything coming from source we have no back routes for
+.Ed
+.Pp
+Here we specifically block packets we don't want:
+anything coming from source we have no back routes for;
+packets whose ingress interface does not match the one in
+the route back to their source address;
+anything that does not have our address (157.161.48.183) as source;
+broadcasts (cable modem noise);
+and anything from reserved address space or invalid addresses.
+.Bd -literal -offset 4n
 block in from no-route to any
-
-# block packets whose ingress interface does not match the one in
-# the route back to their source address
 block in from urpf-failed to any
-
-# block and log outgoing packets that do not have our address as source,
-# they are either spoofed or something is misconfigured (NAT disabled,
-# for instance), we want to be nice and do not send out garbage.
 block out log quick on $ext_if from ! 157.161.48.183 to any
-
-# silently drop broadcasts (cable modem noise)
 block in quick on $ext_if from any to 255.255.255.255
-
-# block and log incoming packets from reserved address space and invalid
-# addresses, they are either spoofed or misconfigured, we cannot reply to
-# them anyway (hence, no return-rst).
 block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e
-      192.168.0.0/16, 255.255.255.255/32 } to any
-
-# ICMP
-
-# pass out/in certain ICMP queries and keep state (ping)
-# state matching is done on host addresses and ICMP id (not type/code),
-# so replies (like 0/0 for 8/0) will match queries
-# ICMP error messages (which always refer to a TCP/UDP packet) are
-# handled by the TCP/UDP states
+    192.168.0.0/16, 255.255.255.255/32 } to any
+.Ed
+.Pp
+For ICMP,
+pass out/in ping queries.
+State matching is done on host addresses and ICMP ID (not type/code),
+so replies (like 0/0 for 8/0) will match queries.
+ICMP error messages (which always refer to a TCP/UDP packet)
+are handled by the TCP/UDP states.
+.Bd -literal -offset 4n
 pass on $ext_if inet proto icmp all icmp-type 8 code 0
-
-# UDP
-
-# pass out all UDP connections and keep state
+.Ed
+.Pp
+For UDP,
+pass out all UDP connections.
+DNS connections are passed in.
+.Bd -literal -offset 4n
 pass out on $ext_if proto udp all
-
-# pass in certain UDP connections and keep state (DNS)
 pass in on $ext_if proto udp from any to any port domain
-
-# TCP
-
-# pass out all TCP connections and modulate state
+.Ed
+.Pp
+For TCP,
+pass out all TCP connections and modulate state.
+SSH, SMTP, DNS, and IDENT connections are passed in.
+We do not allow Windows 9x SMTP connections since they are typically
+a viral worm.
+.Bd -literal -offset 4n
 pass out on $ext_if proto tcp all modulate state
-
-# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT)
-pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
-      auth }
-
-# Do not allow Windows 9x SMTP connections since they are typically
-# a viral worm. Alternately we could limit these OSes to 1 connection each.
-block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
-      to any port smtp
-
-# IPv6
-# pass in/out all IPv6 traffic: note that we have to enable this in two
-# different ways, on both our physical interface and our tunnel
+pass in on $ext_if proto tcp from any to any \e
+    port { ssh, smtp, domain, auth }
+block in on $ext_if proto tcp from any \e
+    os { "Windows 95", "Windows 98" } to any port smtp
+.Ed
+.Pp
+Here we pass in/out all IPv6 traffic:
+note that we have to enable this in two different ways,
+on both our physical interface and our tunnel.
+.Bd -literal -offset 4n
 pass quick on gif0 inet6
 pass quick on $ext_if proto ipv6
-
-# Packet Tagging
-
-# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is
-# being done on $ext_if for all outgoing packets. tag packets in on
-# $int_if and pass those tagged packets out on $ext_if.  all other
-# outgoing packets (i.e. packets from the wireless network) are only
-# permitted to access port 80.
-
+.Ed
+.Pp
+This example illustrates packet tagging.
+There are three interfaces: $int_if, $ext_if, and $wifi_if (wireless).
+NAT is being done on $ext_if for all outgoing packets.
+Packets in on $int_if are tagged and passed out on $ext_if.
+All other outgoing packets
+(i.e. packets from the wireless network)
+are only permitted to access port 80.
+.Bd -literal -offset 4n
 pass in on $int_if from any to any tag INTNET
 pass in on $wifi_if from any to any
 
 block out on $ext_if from any to any
 pass out quick on $ext_if tagged INTNET
 pass out on $ext_if proto tcp from any to any port 80
-
-# tag incoming packets as they are redirected to spamd(8). use the tag
-# to pass those packets through the packet filter.
-
+.Ed
+.Pp
+In this example,
+we tag incoming packets as they are redirected to spamd(8).
+The tag is used to pass those packets through the packet filter.
+.Bd -literal -offset 4n
 rdr on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e
-	tag SPAMD -\*(Gt 127.0.0.1 port spamd
+    tag SPAMD -\*(Gt 127.0.0.1 port spamd
 
 block in on $ext_if
 pass in on $ext_if inet proto tcp tagged SPAMD