5 ipnat, ipnat.conf \- IPFilter NAT file format
10 file is used to specify rules for the Network Address Translation (NAT)
11 component of IPFilter. To load rules specified in the
17 For standard NAT functionality, a rule should start with \fBmap\fP and then
18 proceeds to specify the interface for which outgoing packets will have their
19 source address rewritten. Following this it is expected that the old source
20 address, and optionally port number, will be specified.
22 In general, all NAT rules conform to the following layout:
23 the first word indicates what type of NAT rule is present, this is followed
24 by some stanzas to match a packet, followed by a "->" and this is then
25 followed by several more stanzas describing the new data to be put in the
28 In this text and in others,
29 use of the term "left hand side" (LHS) when talking about a NAT rule refers
30 to text that appears before the "->" and the "right hand side" (RHS) for text
31 that appears after it. In essence, the LHS is the packet matching and the
32 RHS is the new data to be used.
35 This configuration file, like all others used with IPFilter, supports the
36 use of variable substitution throughout the text.
49 Variables can be used recursively, such as 'foo="$bar baz";', so long as
50 $bar exists when the parser reaches the assignment for foo.
54 for instructions on how to define variables to be used from a shell
56 .SH OUTBOUND SOURCE TRANSLATION (map'ing)
57 Changing the source address of a packet is traditionally performed using
59 rules. Both the source address and optionally port number can be changed
60 according to various controls.
62 To start out with, a common rule used is of the form:
68 Here we're saying change the source address of all packets going out of
69 le0 (the address/mask pair of 0/0 matching all packets) to that of the
70 interface le0 (0/32 is a synonym for the interface's own address at
71 the current point in time.) If we wanted to pass the packet through
72 with no change in address, we would write it as:
78 If we only want to change a portion of our internal network and to a
79 different address that is routed back through this host, we might do:
82 map le0 10.1.1.0/24 -> 192.168.55.3/32
85 In some instances, we may have an entire subnet to map internal addresses
86 out onto, in which case we can express the translation as this:
89 map le0 10.0.0.0/8 -> 192.168.55.0/24
92 IPFilter will cycle through each of the 256 addresses in the 192.168.55.0/24
93 address space to ensure that they all get used.
95 Of course this poses a problem for TCP and UDP, with many connections made,
96 each with its own port number pair. If we're unlucky, translations can be
97 dropped because the new address/port pair mapping already exists. To
98 mitigate this problem, we add in port translation or port mapping:
101 map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp auto
104 In this instance, the word "auto" tells IPFilter to calculate a private
105 range of port numbers for each address on the LHS to use without fear
106 of them being trampled by others. This can lead to problems if there are
107 connections being generated mire quickly than IPFilter can expire them.
108 In this instance, and if we want to get away from a private range of
109 port numbers, we can say:
112 map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp 5000:65000
115 And now each connection through le0 will add to the enumeration of
116 the port number space 5000-65000 as well as the IP address subnet
119 If the new addresses to be used are in a consecutive range, rather
120 than a complete subnet, we can express this as:
123 map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.249
124 portmap tcp/udp 5000:65000
127 This tells IPFilter that it has a range of 240 IP address to use, from
128 192.168.55.10 to 192.168.55.249, inclusive.
130 If there were several ranges of addresses for use, we can use each one
131 in a round-robin fashion as followed:
134 map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.29
135 portmap tcp/udp 5000:65000 round-robin
136 map le0 10.0.0.0/8 -> range 192.168.55.40-192.168.55.49
137 portmap tcp/udp 5000:65000 round-robin
140 To specify translation rules that impact a specific IP protocol,
141 the protocol name or number is appended to the rule like this:
144 map le0 10.0.0.0/8 -> 192.168.55.0/24 tcp/udp
145 map le0 10.0.0.0/8 -> 192.168.55.1/32 icmp
146 map le0 10.0.0.0/8 -> 192.168.55.2/32 gre
149 For TCP connections exiting a connection such as PPPoE where the MTU is
150 slightly smaller than normal ethernet, it can be useful to reduce the
151 Maximum Segment Size (MSS) offered by the internal machines to match,
152 reducing the liklihood that the either end will attempt to send packets
153 that are too big and result in fragmentation. This is acheived using the
160 map pppoe0 0/0 -> 0/32 mssclamp 1400 tcp
163 For ICMP packets, we can map the ICMP id space in query packets:
166 map le0 10.0.0.0/8 -> 192.168.55.1/32 icmpidmap icmp 1000:20000
169 If we wish to be more specific about our initial matching criteria on the
170 LHS, we can expand to using a syntax more similar to that in
175 map le0 from 10.0.0.0/8 to 26.0.0.0/8 ->
177 map le0 from 10.0.0.0/8 port > 1024 to 26.0.0.0/8 ->
178 192.168.55.2 portmap 5000:9999 tcp/udp
179 map le0 from 10.0.0.0/8 ! to 26.0.0.0/8 ->
180 192.168.55.3 portmap 5000:9999 tcp/udp
184 negation matching with source addresses is
192 The NAT code has builtin default timeouts for TCP, UDP, ICMP and another
193 for all other protocols. In general, the timeout for an entry to be
194 deleted shrinks once a reply packet has been seen (excluding TCP.)
195 If you wish to specify your own timeouts, this can be achieved either
196 by setting one timeout for both directions:
199 map le0 0/0 -> 0/32 gre age 30
202 or setting a different timeout for the reply:
205 map le0 from any to any port = 53 -> 0/32 age 60/10 udp
208 A pressing problem that many people encounter when using NAT is that the
209 address protocol can be embedded inside an application's communication.
210 To address this problem, IPFilter provides a number of built-in proxies
211 for the more common trouble makers, such as FTP. These proxies can be
215 map le0 0/0 -> 0/32 proxy port 21 ftp/tcp
218 In this rule, the word "proxy" tells us that we want to connect up this
219 translation with an internal proxy. The "port 21" is an extra restriction
220 that requires the destination port number to be 21 if this rule is to be
221 activated. The word "ftp" is the proxy identifier that the kernel will
222 try and resolve internally, "tcp" the protocol that packets must match.
224 See below for a list of proxies and their relative staus.
226 To associate NAT rules with filtering rules, it is possible to set and
227 match tags during either inbound or outbound processing. At present the
228 tags for forwarded packets are not preserved by forwarding, so once the
229 packet leaves IPFilter, the tag is forgotten. For
231 rules, we can match tags set by filter rules like this:
234 map le0 0/0 -> 0/32 proxy portmap 5000:5999 tag lan1 tcp
237 This would be used with "pass out" rules that includes a stanza such
238 as "set-tag (nat = lan1)".
240 If the interface in which packets are received is different from the
241 interface on which packets are sent out, then the translation rule needs
242 to be written to take this into account:
245 map hme0,le0 0/0 -> 0/32
248 Although this might seem counterintuitive, the interfaces when listed
255 order. In this case, hme0 would be the return interface and le0 would be
256 the outgoing interface. If you wish to allow return packets on any
257 interface, the correct syntax to use would be:
260 map *,le0 0/0 -> 0/32
267 This command is intended for use when there is a large network to be mapped
268 onto a smaller network, where the difference in netmasks is upto 14 bits
269 difference in size. This is achieved by dividing the address space and
270 port space up to ensure that each source address has its own private range
271 of ports to use. For example, this rule:
274 map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto
277 would result in 172.192.0.0/24 being mapped to 209.1.2.0/32
278 with each address, from 172.192.0.0 to 172.192.0.255 having 252 ports of its
279 own. As opposed to the above use of \fBmap\fP, if for some reason the user
280 of (say) 172.192.0.2 wanted 260 simultaneous connections going out, they would
281 be limited to 252 with \fBmap-block\fP but would just \fImove on\fP to the next
282 IP address with the \fBmap\fP command.
283 .SS Extended matching
285 If it is desirable to match on both the source and destination of a packet
286 before applying an address translation to it, this can be achieved by using
287 the same from-to syntax as is used in \fBipf.conf\fP(5). What follows
288 applies equally to the
290 rules discussed above and
292 rules discussed below. A simple example is as follows:
295 map bge0 from 10.1.0.0/16 to 192.168.1.0/24 -> 172.12.1.4
298 This would only match packets that are coming from hosts that have a source
299 address matching 10.1.0.0/16 and a destination matching 192.168.1.0/24.
300 This can be expanded upon with ports for TCP like this:
303 rdr bge0 from 10.1.0.0/16 to any port = 25 -> 127.0.0.1 port 2501 tcp
306 Where only TCP packets from 10.1.0.0/16 to port 25 will be redirected to
309 As with \fBipf.conf\fR(5), if we have a large set of networks or addresses
310 that we would like to match up with then we can define a pool using
311 \fBippool\fR(8) in \fBippool.conf\fR(5) and then refer to it in an
312 \fBipnat\fR rule like this:
315 map bge0 from pool/100 to any port = 25 -> 127.0.0.1 port 2501 tcp
319 In this situation, the rule is considered to have a netmask of "0" and
320 thus is looked at last, after any rules with /16's or /24's in them,
322 the defined pool only has /24's or /32's. Pools may also be used
324 the from-to syntax in \fBipnat.conf\fR(5) is allowed.
325 .SH INBOUND DESTINATION TRANSLATION (redirection)
327 Redirection of packets is used to change the destination fields in a packet
328 and is supported for packets that are moving \fIin\fP on a network interface.
329 While the same general syntax for
331 rules is supported, there are differences and limitations.
333 Firstly, by default all redirection rules target a single IP address, not
334 a network or range of network addresses, so a rule written like this:
337 rdr le0 0/0 -> 192.168.1.0
340 Will not spread packets across all 256 IP addresses in that class C network.
341 If you were to try a rule like this:
344 rdr le0 0/0 -> 192.168.1.0/24
347 then you will receive a parsing error.
349 The from-to source-destination matching used with
351 rules can be used with rdr rules, along with negation, however the
352 restriction moves - only a source address match can be negated:
355 rdr le0 from 1.1.0.0/16 to any -> 192.168.1.3
356 rdr le0 ! from 1.1.0.0/16 to any -> 192.168.1.4
359 If there is a consective set of addresses you wish to spread the packets
360 over, then this can be done in one of two ways, the word "range" optional
364 rdr le0 0/0 -> 192.168.1.1 - 192.168.1.5
365 rdr le0 0/0 -> range 192.168.1.1 - 192.168.1.5
368 If there are only two addresses to split the packets across, the
369 recommended method is to use a comma (",") like this:
372 rdr le0 0/0 -> 192.168.1.1,192.168.1.2
375 If there is a large group of destination addresses that are somewhat
376 disjoint in nature, we can cycle through them using a
381 rdr le0 0/0 -> 192.168.1.1,192.168.1.2 round-robin
382 rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin
383 rdr le0 0/0 -> 192.168.1.9 round-robin
386 If there are a large number of redirect rules and hosts being targetted
387 then it may be desirable to have all those from a single source address
388 be targetted at the same destination address. To achieve this, the
391 is appended to the rule like this:
394 rdr le0 0/0 -> 192.168.1.1,192.168.1.2 sticky
395 rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin sticky
396 rdr le0 0/0 -> 192.168.1.9 round-robin sticky
401 feature can only be combined with
403 and the use of comma.
405 For TCP and UDP packets, it is possible to both match on the destiantion
406 port number and to modify it. For example, to change the destination port
407 from 80 to 3128, we would use a rule like this:
410 rdr de0 0/0 port 80 -> 127.0.0.1 port 3128 tcp
413 If a range of ports is given on the LHS and a single port is given on the
414 RHS, the entire range of ports is moved. For example, if we had this:
417 rdr le0 0/0 port 80-88 -> 127.0.0.1 port 3128 tcp
420 then port 80 would become 3128, port 81 would become 3129, etc. If we
421 want to redirect a number of different pots to just a single port, an
422 equals sign ("=") is placed before the port number on the RHS like this:
425 rdr le0 0/0 port 80-88 -> 127.0.0.1 port = 3128 tcp
428 In this case, port 80 goes to 3128, port 81 to 3128, etc.
432 rules, it is possible to manually set a timeout using the
437 rdr le0 0/0 port 53 -> 127.0.0.1 port 10053 udp age 5/5
440 The use of proxies is not restricted to
442 rules and outbound sessions. Proxies can also be used with redirect
443 rules, although the syntax is slightly different:
446 rdr ge0 0/0 port 21 -> 127.0.0.1 port 21 tcp proxy ftp
451 rules, the interfaces supplied are in the same order as
453 rules - input first, then output. In situations where the outgoing interface
454 is not certain, it is also possible to use a wildcard ("*") to effect a match
458 rdr le0,* 0/0 -> 192.168.1.0
461 A single rule, with as many options set as possible would look something like
465 rdr le0,ppp0 9.8.7.6/32 port 80 -> 1.1.1.1,1.1.1.2 port 80 tcp
466 round-robin frag age 40/40 sticky mssclamp 1000 tag tagged
468 .SH REWRITING SOURCE AND DESTINATION
470 Whilst the above two commands provide a lot of flexibility in changing
471 addressing fields in packets, often it can be of benefit to translate
472 \fIboth\fP source \fBand\fR destination at the same time or to change
473 the source address on input or the destination address on output.
474 Doing all of these things can be accomplished using
480 rule requires the same level of packet matching as before, protocol and
481 source/destination information but in addition allows either
485 to be specified like this:
488 rewrite in on ppp0 proto tcp from any to any port = 80 ->
489 src 0/0 dst 127.0.0.1,3128;
490 rewrite out on ppp0 from any to any ->
491 src 0/32 dst 10.1.1.0/24;
494 On the RHS we can specify both new source and destination information to place
495 into the packet being sent out. As with other rules used in
496 \fBipnat.conf\fR, there are shortcuts syntaxes available to use the original
497 address information (\fB0/0\fR) and the address associated with the network
498 interface (\fB0/32\fR.) For TCP and UDP, both address and port information
499 can be changed. At present it is only possible to specify either a range of
500 port numbers to be used (\fBX-Y\fR) or a single port number (\fB= X\fR) as
504 rewrite in on le0 proto tcp from any to any port = 80 ->
505 src 0/0,2000-20000 dst 127.0.0.1,port = 3128;
508 There are four fields that are stepped through in enumerating the number
509 space available for creating a new destination:
519 If one of these happens to be a static then it will be skipped and the next
520 one incremented. As an example:
523 rewrite out on le0 proto tcp from any to any port = 80 ->
524 src 1.0.0.0/8,5000-5999 dst 2.0.0.0/24,6000-6999;
527 The translated packets would be:
529 1st src=1.0.0.1,5000 dst=2.0.0.1,6000
531 2nd src=1.0.0.2,5000 dst=2.0.0.1,6000
533 3rd src=1.0.0.2,5001 dst=2.0.0.1,6000
535 4th src=1.0.0.2,5001 dst=2.0.0.2,6000
537 5th src=1.0.0.2,5001 dst=2.0.0.2,6001
539 6th src=1.0.0.3,5001 dst=2.0.0.2,6001
545 rules, it is possible to specify a range of addresses by including the word
546 \fIrange\fR before the addresses:
549 rewrite from any to any port = 80 ->
550 src 1.1.2.3 - 1.1.2.6 dst 2.2.3.4 - 2.2.3.6;
552 .SH DIVERTING PACKETS
554 If you'd like to send packets to a UDP socket rather than just another
555 computer to be decapsulated, this can be achieved using a
559 Divert rules can be be used with both inbound and outbound packet
560 matching however the rule
562 specify host addresses for the outer packet, not ranges of addresses
563 or netmasks, just single addresses.
564 Additionally the syntax must supply required information for UDP.
565 An example of what a divert rule looks ike is as follows:
568 divert in on le0 proto udp from any to any port = 53 ->
569 src 192.1.1.1,54 dst 192.168.1.22.1,5300;
572 On the LHS is a normal set of matching capabilities but on the RHS it is
573 a requirement to specify both the source and destination addresses and
576 As this feature is intended to be used with targetting packets at sockets
577 and not IPFilter running on other systems, there is no rule provided to
578 \fIundivert\fR packets.
581 Diverted packets \fImay\fP be fragmented if the addition of the
582 encapsulating IP header plus UDP header causes the packet to exceed
583 the size allowed by the outbound network interface. At present it is
584 not possible to cause Path MTU discovery to happen as this feature
585 is intended to be transparent to both endpoints.
586 .B Path MTU Discovery
587 If Path MTU discovery is being used and the "do not fragment" flag
588 is set in packets to be encapsulated, an ICMP error message will
589 be sent back to the sender if the new packet would need to be
592 This section deals with options that are available with all rules.
595 When the purge keyword is added to the end of a NAT rule, it will
596 cause all of the active NAT sessions to be removed when the rule
597 is removed as an individual operation. If all of the NAT rules
598 are flushed out, it is expected that the operator will similarly
599 flush the NAT table and thus NAT sessions are not removed when the
600 NAT rules are flushed out.
606 are read in sequentially as listed and loaded into the kernel in this
609 packet matching is done on \fBnetmask\fR, going from 32 down to 0.
614 to reference a set of addresses or networks, the netmask value for
615 these fields is considered to be "0".
618 has the following rules:
621 rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp
622 rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp
623 rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp
624 rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp
625 rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp
628 then the rule with 192.2.2.1 will match \fBfirst\fR, regardless of where
629 it appears in the ordering of the above rules. In fact, the order in
630 which they would be used to match a packet is:
633 rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp
634 rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp
635 rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp
636 rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp
637 rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp
640 where the first line is actually a /32.
644 file has entries with matching target fields (source address for
646 rules and destination address for
648 rules), then the ordering in the
650 file does matter. So if you had the following:
653 rdr le0 from 1.1.0.0/16 to 192.2.2.1 port 80 -> 127.0.0.1 3129 tcp
654 rdr le0 from 1.1.1.0/24 to 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp
657 Then no packets will match the 2nd rule, they'll all match the first.
660 In all of the examples above, where an IPv4 address is present, an IPv6
661 address can also be used. All rules must use either IPv4 addresses with
662 both halves of the NAT rule or IPv6 addresses for both halves. Mixing
663 IPv6 addresses with IPv4 addresses, in a single rule, will result in an
666 For shorthand notations such as "0/32", the equivalent for IPv6 is
667 "0/128". IPFilter will treat any netmask greater than 32 as an
668 implicit direction that the address should be IPv6, not IPv4.
669 To be unambiguous with 0/0, for IPv6 use ::0/0.
672 IP Filter comes with a few, simple, proxies built into the code that is loaded
673 into the kernel to allow secondary channels to be opened without forcing the
674 packets through a user program. The current state of the proxies is listed
675 below, as one of three states:
677 Aging - protocol is roughly understood from
678 the time at which the proxy was written but it is not well tested or
681 Developmental - basic functionality exists, works most of the time but
682 may be problematic in extended real use;
684 Experimental - rough support for the protocol at best, may or may not
685 work as testing has been at best sporadic, possible large scale changes
686 to the code in order to properly support the protocol.
688 Mature - well tested, protocol is properly
689 understood by the proxy;
691 The currently compiled in proxy list is as follows:
694 (map ... proxy port ftp ftp/tcp)
697 (proxy port 6667 irc/tcp)
699 rpcbind - Experimental
704 (map ... proxy port 1720 h323/tcp)
706 Real Audio (PNA) - Aging
709 (map ... proxy port 53 dns/udp { block .cnn.com; })
711 IPsec - Developmental
712 (map ... proxy port 500 ipsec/tcp)
714 netbios - Experimental
717 (map ... proxy port shell rcmd/tcp)
728 ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)
projects / FreeBSD / releng / 10.0.git / blob