5 ipnat, ipnat.conf \- IP NAT file format
7 The format for files accepted by ipnat is described by the following grammar:
10 ipmap :: = mapblock | redir | map .
12 map ::= mapit ifname lhs "->" dstipmask [ mapicmp | mapport | mapproxy ]
14 mapblock ::= "map-block" ifname lhs "->" ipmask [ ports ] mapoptions .
15 redir ::= "rdr" ifname rlhs "->" ip [ "," ip ] rdrport rdroptions .
17 lhs ::= ipmask | fromto .
18 rlhs ::= ipmask dport | fromto .
19 dport ::= "port" portnum [ "-" portnum ] .
20 ports ::= "ports" numports | "auto" .
21 rdrport ::= "port" portnum .
22 mapit ::= "map" | "bimap" .
23 fromto ::= "from" object "to" object .
24 ipmask ::= ip "/" bits | ip "/" mask | ip "netmask" mask .
25 dstipmask ::= ipmask | "range" ip "-" ip .
26 mapicmp ::= "icmpidmap" "icmp" number ":" number .
27 mapport ::= "portmap" tcpudp portspec .
28 mapoptions ::= [ tcpudp ] [ "frag" ] [ age ] [ clamp ] .
29 rdroptions ::= rdrproto [ rr ] [ "frag" ] [ age ] [ clamp ] [ rdrproxy ] .
31 object :: = addr [ port-comp | port-range ] .
32 addr :: = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] .
33 port-comp :: = "port" compare port-num .
34 port-range :: = "port" port-num range port-num .
35 rdrproto ::= tcpudp | protocol .
37 rr ::= "round-robin" .
38 age ::= "age" decnumber [ "/" decnumber ] .
39 clamp ::= "mssclamp" decnumber .
40 tcpudp ::= "tcp/udp" | protocol .
41 mapproxy ::= "proxy" "port" port proxy-name '/' protocol
42 rdrproxy ::= "proxy" proxy-name .
44 protocol ::= protocol-name | decnumber .
45 nummask ::= host-name [ "/" decnumber ] .
46 portspec ::= "auto" | portnumber ":" portnumber .
47 port ::= portnumber | port-name .
48 portnumber ::= number { numbers } .
49 ifname ::= 'A' - 'Z' { 'A' - 'Z' } numbers .
51 numbers ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' .
54 For standard NAT functionality, a rule should start with \fBmap\fP and then
55 proceeds to specify the interface for which outgoing packets will have their
56 source address rewritten.
58 Packets which will be rewritten can only be selected by matching the original
59 source address. A netmask must be specified with the IP address.
61 The address selected for replacing the original is chosen from an IP#/netmask
62 pair. A netmask of all 1's indicating a hostname is valid. A netmask of
63 31 1's (255.255.255.254) is considered invalid as there is no space for
64 allocating host IP#'s after consideration for broadcast and network
67 When remapping TCP and UDP packets, it is also possible to change the source
68 port number. Either TCP or UDP or both can be selected by each rule, with a
69 range of port numbers to remap into given as \fBport-number:port-number\fP.
71 There are four commands recognised by IP Filter's NAT code:
74 that is used for mapping one address or network to another in an unregulated
78 that is used for redirecting packets to one IP address and port pair to
82 for setting up bidirectional NAT between an external IP address and an internal
86 which sets up static IP address based translation, based on a algorithm to
87 squeeze the addresses to be translated into the destination range.
90 For basic NAT and redirection of packets, the address subject to change is used
91 along with its protocol to check if a packet should be altered. The packet
92 \fImatching\fP part of the rule is to the left of the "->" in each rule.
94 Matching of packets has now been extended to allow more complex compares.
95 In place of the address which is to be translated, an IP address and port
96 number comparison can be made using the same expressions available with
97 \fBipf\fP. A simple NAT rule could be written as:
100 map de0 10.1.0.0/16 -> 201.2.3.4/32
106 map de0 from 10.1.0.0/16 to any -> 201.2.3.4/32
109 Only IP address and port numbers can be compared against. This is available
113 To the right of the "->" is the address and port specification which will be
114 written into the packet providing it has already successfully matched the
115 prior constraints. The case of redirections (\fBrdr\fP) is the simplest:
116 the new destination address is that specified in the rule. For \fBmap\fP
117 rules, the destination address will be one for which the tuple combining
118 the new source and destination is known to be unique. If the packet is
119 either a TCP or UDP packet, the destination and source ports come into the
120 equation too. If the tuple already exists, IP Filter will increment the
121 port number first, within the available range specified with \fBportmap\fP
122 and if there exists no unique tuple, the source address will be incremented
123 within the specified netmask. If a unique tuple cannot be determined, then
124 the packet will not be translated. The \fBmap-block\fP is more limited in
125 how it searches for a new, free and unique tuple, in that it will used an
126 algorithm to determine what the new source address should be, along with the
127 range of available ports - the IP address is never changed and nor does the
128 port number ever exceed its allotted range.
131 ICMP messages can be divided into two groups: "errors" and "queries". ICMP
132 errors are generated as a response of another IP packet. IP Filter will take
133 care that ICMP errors that are the response of a NAT-ed IP packet are
136 For 4 types of ICMP queries (echo request, timestamp request, information
137 request and address mask request) IP Filter supports an additional mapping
138 called "ICMP id mapping". All these 4 types of ICMP queries use a unique
139 identifier called the ICMP id. This id is set by the process sending the
140 ICMP query and it is usually equal to the process id. The receiver of the
141 ICMP query will use the same id in its response, thus enabling the
142 sender to recognize that the incoming ICMP reply is intended for him and is
143 an answer to a query that he made. The "ICMP id mapping" feature modifies
144 these ICMP id in a way identical to \fBportmap\fP for TCP or UDP.
146 The reason that you might want this, is that using this feature you don't
147 need an IP address per host behind the NAT box, that wants to do ICMP queries.
148 The two numbers behind the \fBicmpidmap\fP keyword are the first and the
149 last icmp id number that can be used. There is one important caveat: if you
150 map to an IP address that belongs to the NAT box itself (notably if you have
151 only a single public IP address), then you must ensure that the NAT box does
152 not use the \fBicmpidmap\fP range that you specified in the \fBmap\fP rule.
153 Since the ICMP id is usually the process id, it is wise to restrict the
154 largest permittable process id (PID) on your operating system to e.g. 63999 and
155 use the range 64000:65535 for ICMP id mapping. Changing the maximal PID is
156 system dependent. For most BSD derived systems can be done by changing
157 PID_MAX in /usr/include/sys/proc.h and then rebuild the system.
160 IP Filter comes with a few, simple, proxies built into the code that is loaded
161 into the kernel to allow secondary channels to be opened without forcing the
162 packets through a user program. The current state of the proxies is listed
163 below, as one of three states:
165 Aging - protocol is roughly understood from
166 the time at which the proxy was written but it is not well tested or
169 Developmental - basic functionality exists, works most of the time but
170 may be problematic in extended real use;
172 Experimental - rough support for the protocol at best, may or may not
173 work as testing has been at best sporadic, possible large scale changes
174 to the code in order to properly support the protocol.
176 Mature - well tested, protocol is properly
177 understood by the proxy;
179 The currently compiled in proxy list is as follows:
185 rpcbind - Experimental
189 Real Audio (PNA) - Aging
191 IPsec - Developmental
193 netbios - Experimental
197 .SH TRANSPARENT PROXIES
199 True transparent proxying should be performed using the redirect (\fBrdr\fP)
200 rules directing ports to localhost (127.0.0.1) with the proxy program doing
201 a lookup through \fB/dev/ipnat\fP to determine the real source and address
205 Two options for use with \fBrdr\fP are available to support primitive,
206 \fIround-robin\fP based load balancing. The first option allows for a
207 \fBrdr\fP to specify a second destination, as follows:
210 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp
213 This would send alternate connections to either 203.1.2.3 or 203.1.2.4.
214 In scenarios where the load is being spread amongst a larger set of
215 servers, you can use:
218 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.3,203.1.2.4 port 80 tcp round-robin
219 rdr le0 203.1.2.3/32 port 80 -> 203.1.2.5 port 80 tcp round-robin
222 In this case, a connection will be redirected to 203.1.2.3, then 203.1.2.4
223 and then 203.1.2.5 before going back to 203.1.2.3. In accomplishing this,
224 the rule is removed from the top of the list and added to the end,
225 automatically, as required. This will not effect the display of rules
226 using "ipnat -l", only the internal application order.
229 This section deals with the \fBmap\fP command and its variations.
231 To change IP#'s used internally from network 10 into an ISP provided 8 bit
232 subnet at 209.1.2.0 through the ppp0 interface, the following would be used:
235 map ppp0 10.0.0.0/8 -> 209.1.2.0/24
238 The obvious problem here is we're trying to squeeze over 16,000,000 IP
239 addresses into a 254 address space. To increase the scope, remapping for TCP
240 and/or UDP, port remapping can be used;
243 map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
246 which falls only 527,566 `addresses' short of the space available in network
247 10. If we were to combine these rules, they would need to be specified as
251 map ppp0 10.0.0.0/8 -> 209.1.2.0/24 portmap tcp/udp 1025:65000
252 map ppp0 10.0.0.0/8 -> 209.1.2.0/24
255 so that all TCP/UDP packets were port mapped and only other protocols, such as
256 ICMP, only have their IP# changed. In some instances, it is more appropriate
257 to use the keyword \fBauto\fP in place of an actual range of port numbers if
258 you want to guarantee simultaneous access to all within the given range.
259 However, in the above case, it would default to 1 port per IP address, since
260 we need to squeeze 24 bits of address space into 8. A good example of how
261 this is used might be:
264 map ppp0 172.192.0.0/16 -> 209.1.2.0/24 portmap tcp/udp auto
267 which would result in each IP address being given a small range of ports to
268 use (252). In all cases, the new port number that is used is deterministic.
269 That is, port X will always map to port Y.
270 WARNING: It is not advisable to use the \fBauto\fP feature if you are map'ing
271 to a /32 (i.e. 0/32) because the NAT code will try to map multiple hosts to
272 the same port number, outgoing and ultimately this will only succeed for one
274 The problem here is that the \fBmap\fP directive tells the NAT
275 code to use the next address/port pair available for an outgoing connection,
276 resulting in no easily discernible relation between external addresses/ports
277 and internal ones. This is overcome by using \fBmap-block\fP as follows:
280 map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto
283 For example, this would result in 172.192.0.0/24 being mapped to 209.1.2.0/32
284 with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its
285 own. As opposed to the above use of \fBmap\fP, if for some reason the user
286 of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would
287 be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next
288 IP address with the \fBmap\fP command.
295 ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)
projects / FreeBSD / releng / 9.2.git / blob