Index: natd.8
===================================================================
RCS file: /home/ncvs/src/sbin/natd/natd.8,v
retrieving revision 1.65
diff -u -p -r1.65 natd.8
--- natd.8	14 Dec 2007 14:34:26 -0000	1.65
+++ natd.8	31 Jan 2008 09:19:23 -0000
@@ -28,6 +28,8 @@
 .Op Fl redirect_proto Ar linkspec
 .Op Fl redirect_address Ar linkspec
 .Op Fl config | f Ar configfile
+.Op Fl instance Ar instancename
+.Op Fl globalport Ar port
 .Op Fl log_denied
 .Op Fl log_facility Ar facility_name
 .Op Fl punch_fw Ar firewall_range
@@ -449,6 +451,32 @@ Trailing spaces and empty lines are igno
 A
 .Ql \&#
 sign will mark the rest of the line as a comment.
+.It Fl instance Ar instancename
+This option switches command line options processing to configure instance
+.Ar instancename
+(creating it if necessary) till the next
+.Fl instance
+option or end of command line.
+It is easier to set up multiple instances in the configuration file
+specified with the
+.Fl config
+option rather than on a command line.
+.It Fl globalport Ar port
+Read from and write to
+.Xr divert 4
+port
+.Ar port ,
+treating all packets as
+.Dq outgoing .
+This option is intended to be used with multiple instances:
+packets received on this port are checked against
+internal translation tables of every configured instance.
+If an entry is found, packet is aliased according to that entry.
+In no entry was found in any of the instances, packet is passed
+unchanged, and no new entry will be created.
+See
+.Sx MULTIPLE INSTANCES
+section for more details.
 .It Fl reverse
 This option makes
 .Nm
@@ -635,6 +663,135 @@ will stop at this point - blocking all a
 Running the script in the background should be enough to prevent this
 disaster.
 .El
+.Sh MULTIPLE INSTANCES
+It is not so uncommon to have a need of aliasing to several external IP
+addresses.
+While this traditionally was achieved by running several
+.Nm
+processes with independent configurations,
+.Nm
+can have multiple aliasing instances in a single process,
+also allowing them to be not so independent of each other.
+For example, let us see a common task of load balancing two
+channels to different providers on a machine with two external
+interfaces
+.Ql sis0
+(with IP 1.2.3.4) and
+.Ql sis2
+(with IP 2.3.4.5):
+.Bd -literal -offset indent
+          net 1.2.3.0/24
+1.2.3.1 ------------------ sis0
+(router)                (1.2.3.4)
+                                         net 10.0.0.0/24
+                                  sis1 ------------------- 10.0.0.2
+                               (10.0.0.1)
+          net 2.3.4.0/24
+2.3.4.1 ------------------ sis2
+(router)                (2.3.4.5)
+.Ed
+.Pp
+Default route is out via
+.Ql sis0 .
+.Pp
+Interior machine (10.0.0.2) is accessible on TCP port 122 through
+both exterior IPs, and outgoing connections choose a path randomly
+between
+.Ql sis0
+and
+.Ql sis2 .
+.Pp
+The way this works is that
+.Pa natd.conf
+builds two instances of the
+aliasing engine (one of them have to be named
+.Dq Li default
+right now or
+.Nm
+will refuse to start).
+.Pp
+In addition to these instances' private
+.Xr divert 4
+sockets, a third socket called the
+.Dq globalport
+is created; packets sent to
+.Nm
+via this one will be matched against all instances and translated
+if an existing entry is found, and unchanged if no entry is found.
+The following lines are placed into:
+.Pa /etc/natd.conf :
+.Bd -literal -offset indent
+log
+deny_incoming
+verbose
+
+instance default
+interface sis0
+port 1000
+redirect_port tcp 10.0.0.2:122 122
+
+instance sis2
+interface sis2
+port 2000
+redirect_port tcp 10.0.0.2:122 122
+
+globalport 3000
+.Ed
+.Pp
+And the following
+.Xr ipfw 8
+rules are used:
+.Bd -literal -offset indent
+ipfw -f flush
+
+ipfw add      allow ip from any to any via sis1
+
+ipfw add      skipto 1000 ip from any to any in via sis0
+ipfw add      skipto 2000 ip from any to any out via sis0
+ipfw add      skipto 3000 ip from any to any in via sis2
+ipfw add      skipto 4000 ip from any to any out via sis2
+
+ipfw add 1000 count ip from any to any
+
+ipfw add      divert 1000 ip from any to any
+ipfw add      allow ip from any to any
+
+ipfw add 2000 count ip from any to any
+
+ipfw add      divert 3000 ip from any to any
+
+ipfw add      allow ip from 1.2.3.4 to any
+ipfw add      skipto 5000 ip from 2.3.4.5 to any
+
+ipfw add      prob .5 skipto 4000 ip from any to any
+
+ipfw add      divert 1000 ip from any to any
+ipfw add      allow ip from any to any
+
+ipfw add 3000 count ip from any to any
+
+ipfw add      divert 2000 ip from any to any
+ipfw add      allow ip from any to any
+
+ipfw add 4000 count ip from any to any
+
+ipfw add      divert 2000 ip from any to any
+
+ipfw add 5000 fwd 2.3.4.1 ip from 2.3.4.5 to not 2.3.4.0/24
+ipfw add      allow ip from any to any
+.Ed
+.Pp
+Here all packets from internal network to Internet go out via
+.Ql sis0
+(rule number 2000) and get catched by
+.Fl globalport
+socket (3000).
+After that they are either found in translation table
+of one of two instances or go to one of two another
+.Xr divert 4
+ports (1000 or 2000) with equal probability.
+This ensures that load balancing is done on a per-flow basis
+(that is, packets from a single TCP connection are always sent to the
+same interface).
+Translated packets with source IP of a non-default interface are
+forwarded to appropriate router on that interface.
 .Sh SEE ALSO
 .Xr libalias 3 ,
 .Xr divert 4 ,
@@ -662,3 +819,5 @@ times:
 (glue)
 .An Ruslan Ermilov Aq ru@FreeBSD.org
 (natd, packet aliasing, glue)
+.An Poul-Henning Kamp Aq phk@FreeBSD.org
+(multiple instances)