diff options
Diffstat (limited to 'sbin/ipf/ipnat/ipnat.5')
| -rw-r--r-- | sbin/ipf/ipnat/ipnat.5 | 727 |
1 files changed, 727 insertions, 0 deletions
diff --git a/sbin/ipf/ipnat/ipnat.5 b/sbin/ipf/ipnat/ipnat.5 new file mode 100644 index 000000000000..b01892f9749d --- /dev/null +++ b/sbin/ipf/ipnat/ipnat.5 @@ -0,0 +1,727 @@ +.\" +.TH IPNAT 5 +.SH NAME +ipnat, ipnat.conf \- IPFilter NAT file format +.SH DESCRIPTION +.PP +The +.B ipnat.conf +file is used to specify rules for the Network Address Translation (NAT) +component of IPFilter. To load rules specified in the +.B ipnat.conf +file, the +.B ipnat(8) +program is used. +.PP +For standard NAT functionality, a rule should start with \fBmap\fP and then +proceeds to specify the interface for which outgoing packets will have their +source address rewritten. Following this it is expected that the old source +address, and optionally port number, will be specified. +.PP +In general, all NAT rules conform to the following layout: +the first word indicates what type of NAT rule is present, this is followed +by some stanzas to match a packet, followed by a "->" and this is then +followed by several more stanzas describing the new data to be put in the +packet. +.PP +In this text and in others, +use of the term "left hand side" (LHS) when talking about a NAT rule refers +to text that appears before the "->" and the "right hand side" (RHS) for text +that appears after it. In essence, the LHS is the packet matching and the +RHS is the new data to be used. +.SH VARIABLES +.PP +This configuration file, like all others used with IPFilter, supports the +use of variable substitution throughout the text. +.nf + +nif="ppp0"; +map $nif 0/0 -> 0/32 +.fi +.PP +would become +.nf + +map ppp0 0/0 -> 0/32 +.fi +.PP +Variables can be used recursively, such as 'foo="$bar baz";', so long as +$bar exists when the parser reaches the assignment for foo. +.PP +See +.B ipnat(8) +for instructions on how to define variables to be used from a shell +environment. +.SH OUTBOUND SOURCE TRANSLATION (map'ing) +Changing the source address of a packet is traditionally performed using +.B map +rules. Both the source address and optionally port number can be changed +according to various controls. +.PP +To start out with, a common rule used is of the form: +.nf + +map le0 0/0 -> 0/32 +.fi +.PP +Here we're saying change the source address of all packets going out of +le0 (the address/mask pair of 0/0 matching all packets) to that of the +interface le0 (0/32 is a synonym for the interface's own address at +the current point in time.) If we wanted to pass the packet through +with no change in address, we would write it as: +.nf + +map le0 0/0 -> 0/0 +.fi +.PP +If we only want to change a portion of our internal network and to a +different address that is routed back through this host, we might do: +.nf + +map le0 10.1.1.0/24 -> 192.168.55.3/32 +.fi +.PP +In some instances, we may have an entire subnet to map internal addresses +out onto, in which case we can express the translation as this: +.nf + +map le0 10.0.0.0/8 -> 192.168.55.0/24 +.fi +.PP +IPFilter will cycle through each of the 256 addresses in the 192.168.55.0/24 +address space to ensure that they all get used. +.PP +Of course this poses a problem for TCP and UDP, with many connections made, +each with its own port number pair. If we're unlucky, translations can be +dropped because the new address/port pair mapping already exists. To +mitigate this problem, we add in port translation or port mapping: +.nf + +map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp auto +.fi +.PP +In this instance, the word "auto" tells IPFilter to calculate a private +range of port numbers for each address on the LHS to use without fear +of them being trampled by others. This can lead to problems if there are +connections being generated more quickly than IPFilter can expire them. +In this instance, and if we want to get away from a private range of +port numbers, we can say: +.nf + +map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp 5000:65000 +.fi +.PP +And now each connection through le0 will add to the enumeration of +the port number space 5000-65000 as well as the IP address subnet +of 192.168.55.0/24. +.PP +If the new addresses to be used are in a consecutive range, rather +than a complete subnet, we can express this as: +.nf + +map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.249 + portmap tcp/udp 5000:65000 +.fi +.PP +This tells IPFilter that it has a range of 240 IP address to use, from +192.168.55.10 to 192.168.55.249, inclusive. +.PP +If there were several ranges of addresses for use, we can use each one +in a round-robin fashion as followed: +.nf + +map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.29 + portmap tcp/udp 5000:65000 round-robin +map le0 10.0.0.0/8 -> range 192.168.55.40-192.168.55.49 + portmap tcp/udp 5000:65000 round-robin +.fi +.PP +To specify translation rules that impact a specific IP protocol, +the protocol name or number is appended to the rule like this: +.nf + +map le0 10.0.0.0/8 -> 192.168.55.0/24 tcp/udp +map le0 10.0.0.0/8 -> 192.168.55.1/32 icmp +map le0 10.0.0.0/8 -> 192.168.55.2/32 gre +.fi +.PP +For TCP connections exiting a connection such as PPPoE where the MTU is +slightly smaller than normal ethernet, it can be useful to reduce the +Maximum Segment Size (MSS) offered by the internal machines to match, +reducing the liklihood that the either end will attempt to send packets +that are too big and result in fragmentation. This is achieved using the +.B mssclamp +option with TCP +.B map +rules like this: +.nf + +map pppoe0 0/0 -> 0/32 mssclamp 1400 tcp +.fi +.PP +For ICMP packets, we can map the ICMP id space in query packets: +.nf + +map le0 10.0.0.0/8 -> 192.168.55.1/32 icmpidmap icmp 1000:20000 +.fi +.PP +If we wish to be more specific about our initial matching criteria on the +LHS, we can expand to using a syntax more similar to that in +.B ipf.conf(5) +: +.nf + +map le0 from 10.0.0.0/8 to 26.0.0.0/8 -> + 192.168.55.1 +map le0 from 10.0.0.0/8 port > 1024 to 26.0.0.0/8 -> + 192.168.55.2 portmap 5000:9999 tcp/udp +map le0 from 10.0.0.0/8 ! to 26.0.0.0/8 -> + 192.168.55.3 portmap 5000:9999 tcp/udp +.fi +.TP +.B NOTE: +negation matching with source addresses is +.B NOT +possible with +.B map +/ +.B map-block +rules. +.PP +The NAT code has builtin default timeouts for TCP, UDP, ICMP and another +for all other protocols. In general, the timeout for an entry to be +deleted shrinks once a reply packet has been seen (excluding TCP.) +If you wish to specify your own timeouts, this can be achieved either +by setting one timeout for both directions: +.nf + +map le0 0/0 -> 0/32 gre age 30 +.fi +.PP +or setting a different timeout for the reply: +.nf + +map le0 from any to any port = 53 -> 0/32 age 60/10 udp +.fi +.PP +A pressing problem that many people encounter when using NAT is that the +address protocol can be embedded inside an application's communication. +To address this problem, IPFilter provides a number of built-in proxies +for the more common trouble makers, such as FTP. These proxies can be +used as follows: +.nf + +map le0 0/0 -> 0/32 proxy port 21 ftp/tcp +.fi +.PP +In this rule, the word "proxy" tells us that we want to connect up this +translation with an internal proxy. The "port 21" is an extra restriction +that requires the destination port number to be 21 if this rule is to be +activated. The word "ftp" is the proxy identifier that the kernel will +try and resolve internally, "tcp" the protocol that packets must match. +.PP +See below for a list of proxies and their relative status. +.PP +To associate NAT rules with filtering rules, it is possible to set and +match tags during either inbound or outbound processing. At present the +tags for forwarded packets are not preserved by forwarding, so once the +packet leaves IPFilter, the tag is forgotten. For +.B map +rules, we can match tags set by filter rules like this: +.nf + +map le0 0/0 -> 0/32 proxy portmap 5000:5999 tag lan1 tcp +.fi +.PP +This would be used with "pass out" rules that includes a stanza such +as "set-tag (nat = lan1)". +.PP +If the interface in which packets are received is different from the +interface on which packets are sent out, then the translation rule needs +to be written to take this into account: +.nf + +map hme0,le0 0/0 -> 0/32 +.fi +.PP +Although this might seem counterintuitive, the interfaces when listed +in rules for +.B ipnat.conf +are always in the +.I inbound +, +.I outbound +order. In this case, hme0 would be the return interface and le0 would be +the outgoing interface. If you wish to allow return packets on any +interface, the correct syntax to use would be: +.nf + +map *,le0 0/0 -> 0/32 +.fi +.LP +A special variant of +.B map +rules exists, called +.B map-block. +This command is intended for use when there is a large network to be mapped +onto a smaller network, where the difference in netmasks is upto 14 bits +difference in size. This is achieved by dividing the address space and +port space up to ensure that each source address has its own private range +of ports to use. For example, this rule: +.nf + +map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto +.fi +.PP +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. +.SS Extended matching +.PP +If it is desirable to match on both the source and destination of a packet +before applying an address translation to it, this can be achieved by using +the same from-to syntax as is used in \fBipf.conf\fP(5). What follows +applies equally to the +.B map +rules discussed above and +.B rdr +rules discussed below. A simple example is as follows: +.nf + +map bge0 from 10.1.0.0/16 to 192.168.1.0/24 -> 172.12.1.4 +.fi +.PP +This would only match packets that are coming from hosts that have a source +address matching 10.1.0.0/16 and a destination matching 192.168.1.0/24. +This can be expanded upon with ports for TCP like this: +.nf + +rdr bge0 from 10.1.0.0/16 to any port = 25 -> 127.0.0.1 port 2501 tcp +.fi +.PP +Where only TCP packets from 10.1.0.0/16 to port 25 will be redirected to +port 2501. +.PP +As with \fBipf.conf\fR(5), if we have a large set of networks or addresses +that we would like to match up with then we can define a pool using +\fBippool\fR(8) in \fBippool.conf\fR(5) and then refer to it in an +\fBipnat\fR rule like this: +.nf + +map bge0 from pool/100 to any port = 25 -> 127.0.0.1 port 2501 tcp +.fi +.TP +.B NOTE: +In this situation, the rule is considered to have a netmask of "0" and +thus is looked at last, after any rules with /16's or /24's in them, +.I even if +the defined pool only has /24's or /32's. Pools may also be used +.I wherever +the from-to syntax in \fBipnat.conf\fR(5) is allowed. +.SH INBOUND DESTINATION TRANSLATION (redirection) +.PP +Redirection of packets is used to change the destination fields in a packet +and is supported for packets that are moving \fIin\fP on a network interface. +While the same general syntax for +.B map +rules is supported, there are differences and limitations. +.PP +Firstly, by default all redirection rules target a single IP address, not +a network or range of network addresses, so a rule written like this: +.nf + +rdr le0 0/0 -> 192.168.1.0 +.fi +.PP +Will not spread packets across all 256 IP addresses in that class C network. +If you were to try a rule like this: +.nf + +rdr le0 0/0 -> 192.168.1.0/24 +.fi +.PP +then you will receive a parsing error. +.PP +The from-to source-destination matching used with +.B map +rules can be used with rdr rules, along with negation, however the +restriction moves - only a source address match can be negated: +.nf + +rdr le0 from 1.1.0.0/16 to any -> 192.168.1.3 +rdr le0 ! from 1.1.0.0/16 to any -> 192.168.1.4 +.fi +.PP +If there is a consecutive set of addresses you wish to spread the packets +over, then this can be done in one of two ways, the word "range" optional +to preserve: +.nf + +rdr le0 0/0 -> 192.168.1.1 - 192.168.1.5 +rdr le0 0/0 -> range 192.168.1.1 - 192.168.1.5 +.fi +.PP +If there are only two addresses to split the packets across, the +recommended method is to use a comma (",") like this: +.nf + +rdr le0 0/0 -> 192.168.1.1,192.168.1.2 +.fi +.PP +If there is a large group of destination addresses that are somewhat +disjoint in nature, we can cycle through them using a +.B round-robin +technique like this: +.nf + +rdr le0 0/0 -> 192.168.1.1,192.168.1.2 round-robin +rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin +rdr le0 0/0 -> 192.168.1.9 round-robin +.fi +.PP +If there are a large number of redirect rules and hosts being targeted +then it may be desirable to have all those from a single source address +be targeted at the same destination address. To achieve this, the +word +.B sticky +is appended to the rule like this: +.nf + +rdr le0 0/0 -> 192.168.1.1,192.168.1.2 sticky +rdr le0 0/0 -> 192.168.1.5,192.168.1.7 round-robin sticky +rdr le0 0/0 -> 192.168.1.9 round-robin sticky +.fi +.PP +The +.B sticky +feature can only be combined with +.B round-robin +and the use of a comma. +.PP +For TCP and UDP packets, it is possible to both match on the destination +port number and to modify it. For example, to change the destination port +from 80 to 3128, we would use a rule like this: +.nf + +rdr de0 0/0 port 80 -> 127.0.0.1 port 3128 tcp +.fi +.PP +If a range of ports is given on the LHS and a single port is given on the +RHS, the entire range of ports is moved. For example, if we had this: +.nf + +rdr le0 0/0 port 80-88 -> 127.0.0.1 port 3128 tcp +.fi +.PP +then port 80 would become 3128, port 81 would become 3129, etc. If we +want to redirect a number of different pots to just a single port, an +equals sign ("=") is placed before the port number on the RHS like this: +.nf + +rdr le0 0/0 port 80-88 -> 127.0.0.1 port = 3128 tcp +.fi +.PP +In this case, port 80 goes to 3128, port 81 to 3128, etc. +.PP +As with +.B map +rules, it is possible to manually set a timeout using the +.B age +option, like this: +.nf + +rdr le0 0/0 port 53 -> 127.0.0.1 port 10053 udp age 5/5 +.fi +.PP +The use of proxies is not restricted to +.B map +rules and outbound sessions. Proxies can also be used with redirect +rules, although the syntax is slightly different: +.nf + +rdr ge0 0/0 port 21 -> 127.0.0.1 port 21 tcp proxy ftp +.fi +.PP +For +.B rdr +rules, the interfaces supplied are in the same order as +.B map +rules - input first, then output. In situations where the outgoing interface +is not certain, it is also possible to use a wildcard ("*") to effect a match +on any interface. +.nf + +rdr le0,* 0/0 -> 192.168.1.0 +.fi +.PP +A single rule, with as many options set as possible would look something like +this: +.nf + +rdr le0,ppp0 9.8.7.6/32 port 80 -> 1.1.1.1,1.1.1.2 port 80 tcp + round-robin frag age 40/40 sticky mssclamp 1000 tag tagged +.fi +.SH REWRITING SOURCE AND DESTINATION +.PP +Whilst the above two commands provide a lot of flexibility in changing +addressing fields in packets, often it can be of benefit to translate +\fIboth\fP source \fBand\fR destination at the same time or to change +the source address on input or the destination address on output. +Doing all of these things can be accomplished using +.B rewrite +NAT rules. +.PP +A +.B rewrite +rule requires the same level of packet matching as before, protocol and +source/destination information but in addition allows either +.B in +or +.B out +to be specified like this: +.nf + +rewrite in on ppp0 proto tcp from any to any port = 80 -> + src 0/0 dst 127.0.0.1,3128; +rewrite out on ppp0 from any to any -> + src 0/32 dst 10.1.1.0/24; +.fi +.PP +On the RHS we can specify both new source and destination information to place +into the packet being sent out. As with other rules used in +\fBipnat.conf\fR, there are shortcuts syntaxes available to use the original +address information (\fB0/0\fR) and the address associated with the network +interface (\fB0/32\fR.) For TCP and UDP, both address and port information +can be changed. At present it is only possible to specify either a range of +port numbers to be used (\fBX-Y\fR) or a single port number (\fB= X\fR) as +follows: +.nf + +rewrite in on le0 proto tcp from any to any port = 80 -> + src 0/0,2000-20000 dst 127.0.0.1,port = 3128; +.fi +.PP +There are four fields that are stepped through in enumerating the number +space available for creating a new destination: +.LP +source address +.LP +source port +.LP +destination address +.LP +destination port +.PP +If one of these happens to be a static then it will be skipped and the next +one incremented. As an example: +.nf + +rewrite out on le0 proto tcp from any to any port = 80 -> + src 1.0.0.0/8,5000-5999 dst 2.0.0.0/24,6000-6999; +.fi +.PP +The translated packets would be: +.LP +1st src=1.0.0.1,5000 dst=2.0.0.1,6000 +.LP +2nd src=1.0.0.2,5000 dst=2.0.0.1,6000 +.LP +3rd src=1.0.0.2,5001 dst=2.0.0.1,6000 +.LP +4th src=1.0.0.2,5001 dst=2.0.0.2,6000 +.LP +5th src=1.0.0.2,5001 dst=2.0.0.2,6001 +.LP +6th src=1.0.0.3,5001 dst=2.0.0.2,6001 +.PP +and so on. +.PP +As with +.B map +rules, it is possible to specify a range of addresses by including the word +\fIrange\fR before the addresses: +.nf + +rewrite from any to any port = 80 -> + src 1.1.2.3 - 1.1.2.6 dst 2.2.3.4 - 2.2.3.6; +.fi +.SH DIVERTING PACKETS +.PP +If you'd like to send packets to a UDP socket rather than just another +computer to be decapsulated, this can be achieved using a +.B divert +rule. +.PP +Divert rules can be used with both inbound and outbound packet +matching however the rule +.B must +specify host addresses for the outer packet, not ranges of addresses +or netmasks, just single addresses. +Additionally the syntax must supply required information for UDP. +An example of what a divert rule looks ike is as follows: +.nf + +divert in on le0 proto udp from any to any port = 53 -> + src 192.1.1.1,54 dst 192.168.1.22.1,5300; +.fi +.PP +On the LHS is a normal set of matching capabilities but on the RHS it is +a requirement to specify both the source and destination addresses and +ports. +.PP +As this feature is intended to be used with targeting packets at sockets +and not IPFilter running on other systems, there is no rule provided to +\fIundivert\fR packets. +.TP +.B NOTE: +Diverted packets \fImay\fP be fragmented if the addition of the +encapsulating IP header plus UDP header causes the packet to exceed +the size allowed by the outbound network interface. At present it is +not possible to cause Path MTU discovery to happen as this feature +is intended to be transparent to both endpoints. +.B Path MTU Discovery +If Path MTU discovery is being used and the "do not fragment" flag +is set in packets to be encapsulated, an ICMP error message will +be sent back to the sender if the new packet would need to be +fragmented. +.SH COMMON OPTIONS +This section deals with options that are available with all rules. +.TP +.B purge +When the purge keyword is added to the end of a NAT rule, it will +cause all of the active NAT sessions to be removed when the rule +is removed as an individual operation. If all of the NAT rules +are flushed out, it is expected that the operator will similarly +flush the NAT table and thus NAT sessions are not removed when the +NAT rules are flushed out. +.SH RULE ORDERING +.PP +.B NOTE: +Rules in +.B ipnat.conf +are read in sequentially as listed and loaded into the kernel in this +fashion +.B BUT +packet matching is done on \fBnetmask\fR, going from 32 down to 0. +If a rule uses +.B pool +or +.B hash +to reference a set of addresses or networks, the netmask value for +these fields is considered to be "0". +So if your +.B ipnat.conf +has the following rules: +.nf + +rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp +rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp +rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp +rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp +rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp +.fi +.PP +then the rule with 192.2.2.1 will match \fBfirst\fR, regardless of where +it appears in the ordering of the above rules. In fact, the order in +which they would be used to match a packet is: +.nf + +rdr le0 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp +rdr le0 192.2.2.0/24 port 80 -> 127.0.0.1 3129 tcp +rdr le0 192.2.0.0/16 port 80 -> 127.0.0.1 3131 tcp +rdr le0 192.0.0.0/8 port 80 -> 127.0.0.1 3132 tcp +rdr le0 from any to pool/100 port 80 -> 127.0.0.1 port 3130 tcp +.fi +.PP +where the first line is actually a /32. +.PP +If your +.B ipnat.conf +file has entries with matching target fields (source address for +.B map +rules and destination address for +.B rdr +rules), then the ordering in the +.B ipnat.conf +file does matter. So if you had the following: +.nf + +rdr le0 from 1.1.0.0/16 to 192.2.2.1 port 80 -> 127.0.0.1 3129 tcp +rdr le0 from 1.1.1.0/24 to 192.2.2.1 port 80 -> 127.0.0.1 3128 tcp +.fi +.PP +Then no packets will match the 2nd rule, they'll all match the first. +.SH IPv6 +.PP +In all of the examples above, where an IPv4 address is present, an IPv6 +address can also be used. All rules must use either IPv4 addresses with +both halves of the NAT rule or IPv6 addresses for both halves. Mixing +IPv6 addresses with IPv4 addresses, in a single rule, will result in an +error. +.PP +For shorthand notations such as "0/32", the equivalent for IPv6 is +"0/128". IPFilter will treat any netmask greater than 32 as an +implicit direction that the address should be IPv6, not IPv4. +To be unambiguous with 0/0, for IPv6 use ::0/0. +.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. The current state of the proxies is listed +below, as one of three states: +.HP +Aging - protocol is roughly understood from +the time at which the proxy was written but it is not well tested or +maintained; +.HP +Developmental - basic functionality exists, works most of the time but +may be problematic in extended real use; +.HP +Experimental - rough support for the protocol at best, may or may not +work as testing has been at best sporadic, possible large scale changes +to the code in order to properly support the protocol. +.HP +Mature - well tested, protocol is properly +understood by the proxy; +.PP +The currently compiled in proxy list is as follows: +.TP +FTP - Mature +(map ... proxy port ftp ftp/tcp) +.TP +IRC - Experimental +(proxy port 6667 irc/tcp) +.TP +rpcbind - Experimental +.TP +PPTP - Experimental +.TP +H.323 - Experimental +(map ... proxy port 1720 h323/tcp) +.TP +Real Audio (PNA) - Aging +.TP +DNS - Developmental +(map ... proxy port 53 dns/udp { block .cnn.com; }) +.TP +IPsec - Developmental +(map ... proxy port 500 ipsec/tcp) +.TP +netbios - Experimental +.TP +R-command - Mature +(map ... proxy port shell rcmd/tcp) +.SH KERNEL PROXIES +.SH FILES +/dev/ipnat +.br +/etc/protocols +.br +/etc/services +.br +/etc/hosts +.SH SEE ALSO +ipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8) |