contrib/ipfilter/man/ipnat.5

   1 .TH IPNAT 5
   2 .SH NAME
   3 ipnat, ipnat.conf \- IP NAT file format
   4 .SH DESCRIPTION
   5 The format for files accepted by ipnat is described by the following grammar:
   6 .LP
   7 .nf
   8 ipmap :: = mapblock | redir | map .
   9
  10 map ::= mapit ifname ipmask "->" dstipmask [ mapport ] .
  11 map ::= mapit ifname fromto "->" dstipmask [ mapport ] .
  12 mapblock ::= "map-block" ifname ipmask "->" ipmask [ ports ] .
  13 redir ::= "rdr" ifname ipmask dport "->" ip [ "," ip ] rdrport options .
  14
  15 dport ::= "port" portnum [ "-" portnum ] .
  16 ports ::= "ports" numports | "auto" .
  17 rdrport ::= "port" portnum .
  18 mapit ::= "map" | "bimap" .
  19 fromto ::= "from" object "to" object .
  20 ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask .
  21 dstipmask ::= ipmask | "range" ip "-" ip .
  22 mapport ::= "portmap" tcpudp portspec .
  23 options ::= [ tcpudp ] [ rr ] .
  24
  25 object  :: = addr [ port-comp | port-range ] .
  26 addr    :: = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] .
  27 port-comp :: = "port" compare port-num .
  28 port-range :: = "port" port-num range port-num .
  29
  30 rr ::= "round-robin" .
  31 nummask = host-name [ "/" decnumber ] .
  32 tcpudp ::= "tcp" | "udp" | "tcp/udp" .
  33 portspec ::= "auto" | portnumber ":" portnumber .
  34 portnumber ::= number { numbers } .
  35 ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers .
  36
  37 numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' .
  38 .fi
  39 .PP
  40 In addition to this, # is used to mark the start of a comment and may
  41 appear at the end of a line with a NAT rule (as described above) or on its
  42 own lines.  Blank lines are ignored.
  43 .PP
  44 For standard NAT functionality, a rule should start with \fBmap\fP and then
  45 proceeds to specify the interface for which outgoing packets will have their
  46 source address rewritten.
  47 .PP
  48 Packets which will be rewritten can only be selected by matching the original
  49 source address.  A netmask must be specified with the IP address.
  50 .PP
  51 The address selected for replacing the original is chosen from an IP#/netmask
  52 pair.  A netmask of all 1's indicating a hostname is valid.  A netmask of
  53 31 1's (255.255.255.254) is considered invalid as there is no space for
  54 allocating host IP#'s after consideration for broadcast and network
  55 addresses.
  56 .PP
  57 When remapping TCP and UDP packets, it is also possible to change the source
  58 port number.  Either TCP or UDP or both can be selected by each rule, with a
  59 range of port numbers to remap into given as \fBport-number:port-number\fP.
  60 .SH COMMANDS
  61 There are four commands recognised by IP Filter's NAT code:
  62 .TP
  63 .B map
  64 that is used for mapping one address or network to another in an unregulated
  65 round robin fashion;
  66 .TP
  67 .B rdr
  68 that is used for redirecting packets to one IP address and port pair to
  69 another;
  70 .TP
  71 .B bimap
  72 for setting up bidirectional NAT between an external IP address and an internal
  73 IP address and
  74 .TP
  75 .B map-block
  76 which sets up static IP address based translation, based on a algorithm to
  77 squeeze the addresses to be translated into the destination range.
  78 .SH MATCHING
  79 .PP
  80 For basic NAT and redirection of packets, the address subject to change is used
  81 along with its protocol to check if a packet should be altered.  The packet
  82 \fImatching\fP part of the rule is to the left of the "->" in each rule.
  83 .PP
  84 Matching of packets has now been extended to allow more complex compares.
  85 In place of the address which is to be translated, an IP address and port
  86 number comparison can be made using the same expressions available with
  87 \fBipf\fP.  A simple NAT rule could be written as:
  88 .LP
  89 .nf
  90 map de0 10.1.0.0/16 -> 201.2.3.4/32
  91 .fi
  92 .LP
  93 or as
  94 .LP
  95 .nf
  96 map de0 from 10.1.0.0/16 to any -> 201.2.3.4/32
  97 .fi
  98 .LP
  99 For even greater control, one may negate either of the "from" or "to" clauses
 100 with a preceding exclamation mark ("!").  Please note that one may not use a
 101 negated "from" within a \fBmap\fP rule or a negated "to" within a \fBrdr\fP
 102 rule.  Such a rule might look like the following:
 103 .LP
 104 .nf
 105 +map de0 from 10.1.0.0/16 ! to 10.1.0.0/16 -> 201.2.3.4/32
 106 .fi
 107 .PP
 108 Only IP address and port numbers can be compared against.  This is available
 109 with all NAT rules.
 110 .SH TRANSLATION
 111 .PP
 112 To the right of the "->" is the address and port specificaton which will be
 113 written into the packet providing it has already successful matched the
 114 prior constraints.  The case of redirections (\fBrdr\fP) is the simpliest:
 115 the new destination address is that specified in the rule.  For \fBmap\fP
 116 rules, the destination address will be one for which the tuple combining
 117 the new source and destination is known to be unique.  If the packet is
 118 either a TCP or UDP packet, the destination and source ports come into the
 119 equation too.  If the tuple already exists, IP Filter will increment the
 120 port number first, within the available range specified with \fBportmap\fP
 121 and if there exists no unique tuple, the source address will be incremented
 122 within the specified netmask.  If a unique tuple cannot be determined, then
 123 the packet will not be translated.  The \fBmap-block\fP is more limited in
 124 how it searches for a new, free and unique tuple, in that it will used an
 125 algorithm to determine what the new source address should be, along with the
 126 range of available ports - the IP address is never changed and nor does the
 127 port number ever exceed its alloted range.
 128 .SH KERNEL PROXIES
 129 .PP
 130 IP Filter comes with a few, simple, proxies built into the code that is loaded
 131 into the kernel to allow secondary channels to be opened without forcing the
 132 packets through a user program.
 133 .SH TRNSPARENT PROXIES
 134 .PP
 135 True transparent proxying should be performed using the redirect (\fBrdr\fP)
 136 rules directing ports to localhost (127.0.0.1) with the proxy program doing
 137 a lookup through \fB/dev/ipnat\fP to determine the real source and address
 138 of the connection.
 139 .SH LOAD-BALANCING
 140 .PP
 141 Two options for use with \fBrdr\fP are available to support primitive,
 142 \fIround-robin\fP based load balancing.  The first option allows for a
 143 \fBrdr\fP to specify a second destination, as follows:
 144 .LP
 145 .nf
 146 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp
 147 .fi
 148 .LP
 149 This would send alternate connections to either 203.1.2.3 or 203.1.2.4.
 150 In scenarios where the load is being spread amongst a larger set of
 151 servers, you can use:
 152 .LP
 153 .nf
 154 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp round-robin
 155 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.5 port 80 tcp round-robin
 156 .fi
 157 .LP
 158 In this case, a connection will be redirected to 203.1.2.3, then 203.1.2.4
 159 and then 203.1.2.5 before going back to 203.1.2.3.  In accomplishing this,
 160 the rule is removed from the top of the list and added to the end,
 161 automatically, as required.  This will not effect the display of rules
 162 using "ipnat -l", only the internal application order.
 163 .SH EXAMPLES
 164 .PP
 165 This section deals with the \fBmap\fP command and it's variations.
 166 .PP
 167 To change IP#'s used internally from network 10 into an ISP provided 8 bit
 168 subnet at 209.1.2.0 through the ppp0 interface, the following would be used:
 169 .LP
 170 .nf
 171 map ppp0 10.0.0.0/8 -> 209.1.2.0/24
 172 .fi
 173 .PP
 174 The obvious problem here is we're trying to squeeze over 16,000,000 IP
 175 addresses into a 254 address space.  To increase the scope, remapping for TCP
 176 and/or UDP, port remapping can be used;
 177 .LP
 178 .nf
 179 map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
 180 .fi
 181 .PP
 182 which falls only 527,566 `addresses' short of the space available in network
 183 10.  If we were to combine these rules, they would need to be specified as
 184 follows:
 185 .LP
 186 .nf
 187 map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
 188 map ppp0 10.0.0.0/8 -> 209.1.2.0/24
 189 .fi
 190 .PP
 191 so that all TCP/UDP packets were port mapped and only other protocols, such as
 192 ICMP, only have their IP# changed.  In some instaces, it is more appropriate
 193 to use the keyword \fBauto\fP in place of an actual range of port numbers if
 194 you want to guarantee simultaneous access to all within the given range.
 195 However, in the above case, it would default to 1 port per IP address, since
 196 we need to squeeze 24 bits of address space into 8.  A good example of how
 197 this is used might be:
 198 .LP
 199 .nf
 200 map ppp0 172.192.0.0/16 -> 209.1.2.0/24 portmap tcp/udp auto
 201 .fi
 202 .PP
 203 which would result in each IP address being given a small range of ports to
 204 use (252).  The problem here is that the \fBmap\fP directive tells the NAT
 205 code to use the next address/port pair available for an outgoing connection,
 206 resulting in no easily discernable relation between external addresses/ports
 207 and internal ones.  This is overcome by using \fBmap-block\fP as follows:
 208 .LP
 209 .nf
 210 map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto
 211 .fi
 212 .PP
 213 For example, this would result in 172.192.0.0/24 being mapped to 209.1.2.0/32
 214 with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its
 215 own.  As opposed to the above use of \fBmap\fP, if for some reason the user
 216 of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would
 217 be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next
 218 IP address with the \fBmap\fP command.
 219 .SH FILES
 220 /dev/ipnat
 221 .br
 222 /etc/services
 223 .br
 224 /etc/hosts
 225 .SH SEE ALSO
 226 ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)