Import of ipfilter 3.3.3 in anticipation of its revival.

More to come in the next days.

8 files changed, 240 insertions, 51 deletions

diff --git a/contrib/ipfilter/man/Makefile b/contrib/ipfilter/man/Makefile
index 972fbf5..5e029de 100644
--- a/contrib/ipfilter/man/Makefile
+++ b/contrib/ipfilter/man/Makefile
@@ -1,5 +1,5 @@
 #
-# Copyright (C) 1993-1997 by Darren Reed.
+# Copyright (C) 1993-1998 by Darren Reed.
 #
 # Redistribution and use in source and binary forms are permitted
 # provided that this notice is preserved and due credit is given
diff --git a/contrib/ipfilter/man/ipf.4 b/contrib/ipfilter/man/ipf.4
index 3519d52..eb836e7 100644
--- a/contrib/ipfilter/man/ipf.4
+++ b/contrib/ipfilter/man/ipf.4
@@ -25,7 +25,19 @@ However, the full complement is as follows:
 	ioctl(fd, SIOCRMIFR, struct frentry *)
 	ioctl(fd, SIOCINAFR, struct frentry *)
 	ioctl(fd, SIOCINIFR, struct frentry *)
+	ioctl(fd, SIOCSETFF, u_int *)
+	ioctl(fd, SIOGGETFF, u_int *)
+	ioctl(fd, SIOCGETFS, struct friostat *)
 	ioctl(fd, SIOCIPFFL, int *)
+	ioctl(fd, SIOCIPFFB, int *)
+	ioctl(fd, SIOCSWAPA, u_int *)
+	ioctl(fd, SIOCFRENB, u_int *)
+	ioctl(fd, SIOCFRSYN, u_int *)
+	ioctl(fd, SIOCFRZST, struct friostat *)
+	ioctl(fd, SIOCZRLST, struct frentry *)
+	ioctl(fd, SIOCAUTHW, struct fr_info *)
+	ioctl(fd, SIOCAUTHR, struct fr_info *)
+	ioctl(fd, SIOCATHST, struct fr_authstat *)
 .fi
 .PP
 The variations, SIOCADAFR vs. SIOCADIFR, allow operation on the two lists,
@@ -44,21 +56,24 @@ which it is inserted is stored in the "fr_hits" field, below.
 typedef struct  frentry {
         struct  frentry *fr_next;
         u_short fr_group;       /* group to which this rule belongs */
-        u_short fr_head;        /* group # which this rule starts */
+        u_short fr_grhead;      /* group # which this rule starts */
         struct  frentry *fr_grp;
         int     fr_ref;         /* reference count - for grouping */
-        struct  ifnet   *fr_ifa;
+        void    *fr_ifa;
+#if BSD >= 199306
+        void    *fr_oifa;
+#endif
         /*
          * These are only incremented when a packet  matches this rule and
          * it is the last match
          */
-        U_QUAD_T  fr_hits;
-        U_QUAD_T  fr_bytes;
+        U_QUAD_T        fr_hits;
+        U_QUAD_T        fr_bytes;
         /*
          * Fields after this may not change whilst in the kernel.
          */
         struct  fr_ip   fr_ip;
-        struct  fr_ip   fr_mip;
+        struct  fr_ip   fr_mip; /* mask structure */
 
         u_char  fr_tcpfm;       /* tcp flags mask */
         u_char  fr_tcpf;        /* tcp flags */
@@ -67,16 +82,20 @@ typedef struct  frentry {
         u_short fr_icmp;
 
         u_char  fr_scmp;        /* data for port comparisons */
-        u_char  fr_dcmp;
+        u_char  fr_dcmp; 
         u_short fr_dport;
         u_short fr_sport;
-        u_short fr_stop;        /* top port for <> and >< */
+        u_short fr_stop;        /* top port for <> and >< */ 
         u_short fr_dtop;        /* top port for <> and >< */
-        u_long  fr_flags;       /* per-rule flags && options (see below) */
-        int     fr_skip;        /* # of rules to skip */
-        int     (*fr_func)();   /* call this function */
+        u_32_t  fr_flags;       /* per-rule flags && options (see below) */
+        u_short fr_skip;        /* # of rules to skip */
+        u_short fr_loglevel;    /* syslog log facility + priority */
+        int     (*fr_func) __P((int, ip_t *, fr_info_t *));
         char    fr_icode;       /* return ICMP code */
         char    fr_ifname[IFNAMSIZ];
+#if BSD > 199306
+        char    fr_oifname[IFNAMSIZ];
+#endif  
         struct  frdest  fr_tif; /* "to" interface */
         struct  frdest  fr_dif; /* duplicate packet interfaces */
 } frentry_t;
@@ -101,7 +120,8 @@ Flags which are recognised in fr_pass:
      FR_LOGBODY      0x000020   /* log the body of packets too */
      FR_LOGFIRST     0x000040   /* log only the first packet to match */
      FR_RETRST       0x000080   /* return a TCP RST packet if blocked */
-     FR__RETICMP     0x000100   /* return an ICMP packet if blocked */
+     FR_RETICMP      0x000100   /* return an ICMP packet if blocked */
+     FR_FAKEICMP     0x00180    /* Return ICMP unreachable with fake source */
      FR_NOMATCH      0x000200   /* no match occured */
      FR_ACCOUNT      0x000400   /* count packet bytes */
      FR_KEEPFRAG     0x000800   /* keep fragment information */
@@ -137,9 +157,11 @@ comparisons) :
 The third ioctl, SIOCIPFFL, flushes either the input filter list, the
 output filter list or both and it returns the number of filters removed
 from the list(s).  The values which it will take and recognise are FR_INQUE
-and FR_OUTQUE (see above).
+and FR_OUTQUE (see above).  This ioctl is also implemented for
+\fB/dev/ipstate\fP and will flush all state tables entries if passed 0
+or just all those which are not established if passed 1.
 
-\fBGeneral Logging Flags\fP
+.IP "\fBGeneral Logging Flags\fP" 0
 There are two flags which can be set to log packets independantly of the
 rules used.  These allow for packets which are either passed or blocked
 to be logged.  To set (and clear)/get these flags, two ioctls are
@@ -157,8 +179,7 @@ those provided (clearing/setting all in one).
 .IP SIOCGETFF 16
 Takes a pointer to an unsigned integer as the parameter.  A copy of the
 flags currently in used is copied to user space.
-.LP
-\fBFilter statistics\fP
+.IP "\fBFilter statistics\fP" 0
 Statistics on the various operations performed by this package on packets
 is kept inside the kernel.  These statistics apply to packets traversing
 through the kernel.  To retrieve this structure, use this ioctl:
@@ -173,7 +194,12 @@ struct  friostat        {
         struct  frentry         *f_acctin[2];
         struct  frentry         *f_acctout[2];
         struct  frentry         *f_auth;
-        int     f_active;
+        u_long  f_froute[2];
+        int     f_active;       /* 1 or 0 - active rule set */
+        int     f_defpass;      /* default pass - from fr_pass */
+        int     f_running;      /* 1 if running, else 0 */
+        int     f_logging;      /* 1 if enabled, else 0 */
+        char    f_version[32];  /* version string */
 };
 
 struct	filterstats {
@@ -195,12 +221,28 @@ struct	filterstats {
         u_long  fr_chit;        /* cached hit */
         u_long  fr_pull[2];     /* good and bad pullup attempts */
 #if SOLARIS
+        u_long  fr_notdata;     /* PROTO/PCPROTO that have no data */
+        u_long  fr_nodata;      /* mblks that have no data */
         u_long  fr_bad;         /* bad IP packets to the filter */
         u_long  fr_notip;       /* packets passed through no on ip queue */
         u_long  fr_drop;        /* packets dropped - no info for them! */
 #endif
 };
 .fi
+If we wanted to retrieve all the statistics and reset the counters back to
+0, then the ioctl() call would be made to SIOCFRZST rather than SIOCGETFS.
+In addition to the statistics above, each rule keeps a hit count, counting
+both number of packets and bytes.  To reset these counters for a rule,
+load the various rule information into a frentry structure and call
+SIOCZRLST.
+.IP "Swapping Active lists" 0
+IP Filter supports two lists of rules for filtering and accounting: an
+active list and an inactive list.  This allows for large scale rule base
+changes to be put in place atomically with otherwise minimal interruption.
+Which of the two is active can be changed using the SIOCSWAPA ioctl.  It
+is important to note that no passed argument is recognised and that the
+value returned is that of the list which is now inactive.
+.br
 .SH FILES
 /dev/ipauth
 .br
diff --git a/contrib/ipfilter/man/ipf.5 b/contrib/ipfilter/man/ipf.5
index 79ab393..efc9b63 100644
--- a/contrib/ipfilter/man/ipf.5
+++ b/contrib/ipfilter/man/ipf.5
@@ -31,17 +31,18 @@ proto	= "proto" protocol .
 ip	= srcdst [ flags ] [ with withopt ] [ icmp ] [ keep ] .
 group	= [ "head" decnumber ] [ "group" decnumber ] .
 
-block	= "block" [ "return-icmp"[return-code] | "return-rst" ] .
+block	= "block" [ icmp[return-code] | "return-rst" ] .
 auth    = "auth" | "preauth" .
-log	= "log" [ "body" ] [ "first" ] [ "or-block" ] .
+log	= "log" [ "body" ] [ "first" ] [ "or-block" ] [ "level" loglevel ] .
 call	= "call" [ "now" ] function-name .
 skip	= "skip" decnumber .
 dup	= "dup-to" interface-name[":"ipaddr] .
 froute	= "fastroute" | "to" interface-name .
 protocol = "tcp/udp" | "udp" | "tcp" | "icmp" | decnumber .
 srcdst	= "all" | fromto .
-fromto	= "from" object "to" object .
+fromto	= "from" [ "!" ] object "to" [ "!" ] object .
 
+icmp	= "return-icmp" | "return-icmp-as-dest" .
 object	= addr [ port-comp | port-range ] .
 addr	= "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] .
 port-comp = "port" compare port-num .
@@ -51,6 +52,7 @@ with	= "with" | "and" .
 icmp	= "icmp-type" icmp-type [ "code" decnumber ] .
 return-code = "("icmp-code")" .
 keep	= "keep" "state" | "keep" "frags" .
+loglevel = facility"."priority | priority .
 
 nummask	= host-name [ "/" decnumber ] .
 host-name = ipaddr | hostname | "any" .
@@ -74,6 +76,12 @@ icmp-code = decumber | "net-unr" | "host-unr" | "proto-unr" | "port-unr" |
 optlist	= "nop" | "rr" | "zsu" | "mtup" | "mtur" | "encode" | "ts" |
 	  "tr" | "sec" | "lsrr" | "e-sec" | "cipso" | "satid" | "ssrr" |
 	  "addext" | "visa" | "imitd" | "eip" | "finn" .
+facility = "kern" | "user" | "mail" | "daemon" | "auth" | "syslog" |
+	   "lpr" | "news" | "uucp" | "cron" | "ftp" | "authpriv" |
+	   "audit" | "logalert" | "local0" | "local1" | "local2" |
+	   "local3" | "local4" | "local5" | "local6" | "local7" .
+priority = "emerg" | "alert" | "crit" | "err" | "warn" | "notice" |
+	   "info" | "debug" . 
 
 hexnumber = "0" "x" hexstring .
 hexstring = hexdigit [ hexstring ] .
@@ -118,11 +126,23 @@ actions are recognised:
 .B block
 indicates that the packet should be flagged to be dropped. In response
 to blocking a packet, the filter may be instructed to send a reply
-packet, either an ICMP packet (\fBreturn-icmp\fP) or a TCP "reset"
-(\fBreturn-rst\fP).  An ICMP packet may be generated in response to
-any IP packet, and its type may optionally be specified, but a TCP
-reset may only be used with a rule which is being applied to TCP
-packets.
+packet, either an ICMP packet (\fBreturn-icmp\fP), an ICMP packet
+masquerading as being from the original packet's destination
+(\fBreturn-icmp-as-dest\fP), or a TCP "reset" (\fBreturn-rst\fP).  An
+ICMP packet may be generated in response to any IP packet, and its
+type may optionally be specified, but a TCP reset may only be used
+with a rule which is being applied to TCP packets.  When using
+\fBreturn-icmp\fP or \fBreturn-icmp-as-dest\fP, it is possible to specify
+the actual unreachable `type'.  That is, whether it is a network
+unreachable, port unreachable or even administratively
+prohibitied. This is done by enclosing the ICMP code associated with
+it in parenthesis directly following \fBreturn-icmp\fP or
+\fBreturn-icmp-as-dest\fP as follows:
+.nf
+        block return-icmp(11) ...
+.fi
+.PP
+Would return a Type-Of-Service (TOS) ICMP unreachable error.
 .TP
 .B pass
 will flag the packet to be let through the filter.  
@@ -145,10 +165,27 @@ feature is for use by knowledgeable hackers, and is not currently
 documented.
 .TP
 .B "skip <n>"
+causes the filter to skip over the next \fIn\fP filter rules.  If a rule is
+inserted or deleted inside the region being skipped over, then the value of
+\fIn\fP is adjusted appropriately.
 .TP
 .B auth
+this allows authentication to be performed by a user-space program running
+and waiting for packet information to validate.  The packet is held for a
+period of time in an internal buffer whilst it waits for the program to return
+to the kernel the \fIreal\fP flags for whether it should be allowed through
+or not.  Such a program might look at the source address and request some sort
+of authentication from the user (such as a password) before allowing the
+packet through or telling the kernel to drop it if from an unrecognised source.
 .TP
 .B preauth
+tells the filter that for packets of this class, it should look in the
+pre-authenticated list for further clarification.  If no further matching
+rule is found, the packet will be dropped (the FR_PREAUTH is not the same
+as FR_PASS).  If a further matching rule is found, the result from that is
+used in its instead.  This might be used in a situation where a person
+\fIlogs in\fP to the firewall and it sets up some temporary rules defining
+the access for that person.
 .PP
 The next word must be either \fBin\fP or \fBout\fP.  Each packet
 moving through the kernel is either inbound (just been received on an
@@ -195,7 +232,10 @@ which the specified source address would be expected, others may be
 logged and/or dropped.
 .TP
 .B dup-to
-causes the packet to be copied, and the duplicate packet to be sent outbound on the specified interface, optionally with the destination IP address changed to that specified. This is useful for off-host logging, using a network sniffer.
+causes the packet to be copied, and the duplicate packet to be sent
+outbound on the specified interface, optionally with the destination
+IP address changed to that specified. This is useful for off-host
+logging, using a network sniffer.
 .TP
 .B to
 causes the packet to be moved to the outbound queue on the
@@ -351,7 +391,7 @@ with which they are associated can be used.  The most important from
 a security point of view is the ICMP redirect.
 .SH KEEP HISTORY
 .PP
-The second last parameter which can be set for a filter rule is whether on not
+The second last parameter which can be set for a filter rule is whether or not
 to record historical information for that packet, and what sort to keep. The
 following information can be kept:
 .TP
@@ -394,10 +434,19 @@ indicates that the first 128 bytes of the packet contents will be
 logged after the headers. 
 .TP
 .B first
-??
+If log is being used in conjunction with a "keep" option, it is recommended
+that this option is also applied so that only the triggering packet is logged
+and not every packet which thereafter matches state information.
 .TP
 .B or-block
-indicates that, if for some reason the filter is unable to log the packet (such as the log reader being too slow) then the rule should be interpreted as if the action was \fBblock\fP for this packet.
+indicates that, if for some reason the filter is unable to log the
+packet (such as the log reader being too slow) then the rule should be
+interpreted as if the action was \fBblock\fP for this packet.
+.TP
+.B "level <loglevel>"
+indicates what logging facility and priority, or just priority with
+the default facility being used, will be used to log information about 
+this packet using ipmon's -s option.
 .PP
 See ipl(4) for the format of records written
 to this device. The ipmon(8) program can be used to read and format
@@ -419,7 +468,7 @@ The "fall-through" rule parsing allows for effects such as this:
 .nf
         block in from any to any port < 6000
         pass in from any to any port >= 6000
-        block in from any to port > 6003
+        block in from any to any port > 6003
 .fi
 .PP
 which sets up the range 6000-6003 as being permitted and all others being
@@ -446,9 +495,9 @@ all inbound packets, we would do something like:
 .LP
 .nf
        block in all
-       block in on le0 quick all head 100
-       block in on le1 quick all head 200
-       block in on lo0 quick all head 300
+       block in quick on le0 all head 100
+       block in quick on le1 all head 200
+       block in quick on lo0 all head 300
 .fi
 .PP
 
diff --git a/contrib/ipfilter/man/ipf.8 b/contrib/ipfilter/man/ipf.8
index 06d2723..65734ce 100644
--- a/contrib/ipfilter/man/ipf.8
+++ b/contrib/ipfilter/man/ipf.8
@@ -4,7 +4,7 @@ ipf \- alters packet filtering lists for IP packet input and output
 .SH SYNOPSIS
 .B ipf
 [
-.B \-AdDEInorsUvyzZ
+.B \-AdDEInoPrsUvVyzZ
 ] [
 .B \-l
 <block|pass|nomatch>
@@ -81,6 +81,9 @@ calls or doing anything which would alter the currently running kernel.
 Force rules by default to be added/deleted to/from the output list, rather
 than the (default) input list.
 .TP
+.B \-P
+Add rules as temporary entries in the authentication rule table.
+.TP
 .B \-r
 Remove matching filter rules rather than add them to the internal lists
 .TP
@@ -94,6 +97,13 @@ recognised as IP packets.  They will be printed out on the console.
 .B \-v
 Turn verbose mode on.  Displays information relating to rule processing.
 .TP
+.B \-V
+Show version information.  This will display the version information compiled
+into the ipf binary and retrieve it from the kernel code (if running/present).
+If it is present in the kernel, information about its current state will be
+displayed (whether logging is active, default filtering, etc).
+.TP
+.TP
 .B \-y
 Manually resync the in-kernel interface list maintained by IP Filter with
 the current interface status list.
diff --git a/contrib/ipfilter/man/ipfilter.5 b/contrib/ipfilter/man/ipfilter.5
index 2826359..95116e2 100644
--- a/contrib/ipfilter/man/ipfilter.5
+++ b/contrib/ipfilter/man/ipfilter.5
@@ -3,5 +3,8 @@
 IP FIlter
 .SH DESCRIPTION
 .PP
+IP Filter is a package providing packet filtering capabilities for a variety
+of operating systems.  On a properly setup system, it can be used to build a
+firewall.
 .SH SEE ALSO
 ipf(8), ipf(1), ipf(5), ipnat(1), ipnat(5), mkfilters(1)
diff --git a/contrib/ipfilter/man/ipmon.8 b/contrib/ipfilter/man/ipmon.8
index 3fba05f..11c1263 100644
--- a/contrib/ipfilter/man/ipmon.8
+++ b/contrib/ipfilter/man/ipmon.8
@@ -42,9 +42,6 @@ for normal IP Filter log records.
 Flush the current packet log buffer.  The number of bytes flushed is displayed,
 even should the result be zero.
 .TP
-.B "\-N <device>"
-Set the logfile to be opened for reading NAT log records from to <device>.
-.TP
 .B \-n
 IP addresses and port numbers will be mapped, where possible, back into
 hostnames and service names.
@@ -64,7 +61,8 @@ as for \fB-o\fP.
 .TP
 .B \-s
 Packet information read in will be sent through syslogd rather than
-saved to a file.  The following levels are used:
+saved to a file.  The default facility when compiled and installed is
+\fBlocal0\fP.  The following levels are used:
 .TP
 .B "\-S <device>"
 Set the logfile to be opened for reading state log records from to <device>.
@@ -84,12 +82,12 @@ than pass or block.
 \- packets which have been logged and which can be considered
 "short".
 .TP
-.B \-S
-Treat the logfile as being composed of state log records.
-.TP
 .B \-t
 read the input file/device in a manner akin to tail(1).
 .TP
+.B \-v
+show tcp window, ack and sequence fields.
+.TP
 .B \-x
 show the packet data in hex.
 .TP
diff --git a/contrib/ipfilter/man/ipnat.1 b/contrib/ipfilter/man/ipnat.1
index 01b5100..f241415 100644
--- a/contrib/ipfilter/man/ipnat.1
+++ b/contrib/ipfilter/man/ipnat.1
@@ -19,11 +19,11 @@ which they appear when given to \fBipnat\fP.
 .SH OPTIONS
 .TP
 .B \-C
-delete all entries in the current NAT listing (NAT rules)
+delete all entries in the current NAT rule listing (NAT rules)
 .TP
 .B \-F
-delete all active entries in the current NAT table (currently active
-NAT mappings)
+delete all active entries in the current NAT translation table (currently
+active NAT mappings)
 .TP
 .B \-l
 Show the list of current NAT table entry mappings.
@@ -39,7 +39,8 @@ Retrieve and display NAT statistics
 Remove matching NAT rules rather than add them to the internal lists
 .TP
 .B \-v
-Turn verbose mode on.  Displays information relating to rule processing.
+Turn verbose mode on.  Displays information relating to rule processing
+and active rules/table entries.
 .DT
 .SH FILES
 /dev/ipnat
diff --git a/contrib/ipfilter/man/ipnat.5 b/contrib/ipfilter/man/ipnat.5
index 576e9c2..e15fa0d 100644
--- a/contrib/ipfilter/man/ipnat.5
+++ b/contrib/ipfilter/man/ipnat.5
@@ -5,14 +5,19 @@ ipnat, ipnat.conf \- IP NAT file format
 The format for files accepted by ipnat is described by the following grammar:
 .LP
 .nf
-ipmap :: = mapit ifname ipmask "->" ipmask [ mapport ] .
+ipmap :: = mapblock | redir | map .
 
-mapit ::= "map" | "rdr" .
+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 .
 
+fromspec ::= "from" ip "/" ipmask .
 tcpudp ::= "tcp" | "udp" | "tcp/udp" .
-portnumber ::= number { numbers } .
+portnumber ::= number { numbers } | "auto" .
 ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers .
 
 numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' .
@@ -34,7 +39,63 @@ addresses.
 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 Examples
+.SH COMMANDS
+There are found 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:
@@ -61,8 +122,33 @@ 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.
-.SH FILES
+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