FreeBSD Man Pages

IPNAT(5) FreeBSD File Formats Manual IPNAT(5)
NAME
ipnat, ipnat.conf - IPFilter NAT file format
DESCRIPTION
The ipnat.conf file is used to specify rules for the Network Address
Translation (NAT) component of IPFilter. To load rules specified in
the ipnat.conf file, the ipnat(8) program is used.
For standard NAT functionality, a rule should start with map 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.
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.
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.
VARIABLES
This configuration file, like all others used with IPFilter, supports
the use of variable substitution throughout the text.
nif="ppp0";
map $nif 0/0 -> 0/32
would become
map ppp0 0/0 -> 0/32
Variables can be used recursively, such as 'foo="$bar baz";', so long
as $bar exists when the parser reaches the assignment for foo.
See ipnat(8) for instructions on how to define variables to be used
from a shell environment.
OUTBOUND SOURCE TRANSLATION (map'ing)
Changing the source address of a packet is traditionally performed
using map rules. Both the source address and optionally port number
can be changed according to various controls.
To start out with, a common rule used is of the form:
map le0 0/0 -> 0/32
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:
map le0 0/0 -> 0/0
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:
map le0 10.1.1.0/24 -> 192.168.55.3/32
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:
map le0 10.0.0.0/8 -> 192.168.55.0/24
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.
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:
map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp auto
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 mire 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:
map le0 10.0.0.0/8 -> 192.168.55.0/24 portmap tcp/udp 5000:65000
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.
If the new addresses to be used are in a consecutive range, rather than
a complete subnet, we can express this as:
map le0 10.0.0.0/8 -> range 192.168.55.10-192.168.55.249
portmap tcp/udp 5000:65000
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.
If there were several ranges of addresses for use, we can use each one
in a round-robin fashion as followed:
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
To specify translation rules that impact a specific IP protocol, the
protocol name or number is appended to the rule like this:
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
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 acheived using
the mssclamp option with TCP map rules like this:
map pppoe0 0/0 -> 0/32 mssclamp 1400 tcp
For ICMP packets, we can map the ICMP id space in query packets:
map le0 10.0.0.0/8 -> 192.168.55.1/32 icmpidmap icmp 1000:20000
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
ipf.conf(5) :
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
NOTE: negation matching with source addresses is NOT possible with map
/ map-block rules.
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:
map le0 0/0 -> 0/32 gre age 30
or setting a different timeout for the reply:
map le0 from any to any port = 53 -> 0/32 age 60/10 udp
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:
map le0 0/0 -> 0/32 proxy port 21 ftp/tcp
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.
See below for a list of proxies and their relative staus.
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 map rules, we
can match tags set by filter rules like this:
map le0 0/0 -> 0/32 proxy portmap 5000:5999 tag lan1 tcp
This would be used with "pass out" rules that includes a stanza such as
"set-tag (nat = lan1)".
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:
map hme0,le0 0/0 -> 0/32
Although this might seem counterintuitive, the interfaces when listed
in rules for ipnat.conf are always in the inbound , 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:
map *,le0 0/0 -> 0/32
A special variant of map rules exists, called 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:
map-block ppp0 172.192.0.0/16 -> 209.1.2.0/24 ports auto
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 map, 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 map-block but would just moveon to the
next IP address with the map command.
Extendedmatching
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 ipf.conf(5).
What follows applies equally to the map rules discussed above and rdr
rules discussed below. A simple example is as follows:
map bge0 from 10.1.0.0/16 to 192.168.1.0/24 -> 172.12.1.4
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:
rdr bge0 from 10.1.0.0/16 to any port = 25 -> 127.0.0.1 port 2501 tcp
Where only TCP packets from 10.1.0.0/16 to port 25 will be redirected
to port 2501.
As with ipf.conf(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
ippool(8) in ippool.conf(5) and then refer to it in an ipnat rule like
this:
map bge0 from pool/100 to any port = 25 -> 127.0.0.1 port 2501 tcp
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, evenif the defined pool only has /24's or /32's.
Pools may also be used wherever the from-to syntax in
ipnat.conf(5) is allowed.
INBOUND DESTINATION TRANSLATION (redirection)
Redirection of packets is used to change the destination fields in a
packet and is supported for packets that are moving in on a network
interface. While the same general syntax for map rules is supported,
there are differences and limitations.
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:
rdr le0 0/0 -> 192.168.1.0
Will not spread packets across all 256 IP addresses in that class C
network. If you were to try a rule like this:
rdr le0 0/0 -> 192.168.1.0/24
then you will receive a parsing error.
The from-to source-destination matching used with map rules can be used
with rdr rules, along with negation, however the restriction moves -
only a source address match can be negated:
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
If there is a consective 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:
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
If there are only two addresses to split the packets across, the
recommended method is to use a comma (",") like this:
rdr le0 0/0 -> 192.168.1.1,192.168.1.2
If there is a large group of destination addresses that are somewhat
disjoint in nature, we can cycle through them using a round-robin
technique like this:
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
If there are a large number of redirect rules and hosts being targetted
then it may be desirable to have all those from a single source address
be targetted at the same destination address. To achieve this, the
word sticky is appended to the rule like this:
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
The sticky feature can only be combined with round-robin and the use of
comma.
For TCP and UDP packets, it is possible to both match on the
destiantion port number and to modify it. For example, to change the
destination port from 80 to 3128, we would use a rule like this:
rdr de0 0/0 port 80 -> 127.0.0.1 port 3128 tcp
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:
rdr le0 0/0 port 80-88 -> 127.0.0.1 port 3128 tcp
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:
rdr le0 0/0 port 80-88 -> 127.0.0.1 port = 3128 tcp
In this case, port 80 goes to 3128, port 81 to 3128, etc.
As with map rules, it is possible to manually set a timeout using the
age option, like this:
rdr le0 0/0 port 53 -> 127.0.0.1 port 10053 udp age 5/5
The use of proxies is not restricted to map rules and outbound
sessions. Proxies can also be used with redirect rules, although the
syntax is slightly different:
rdr ge0 0/0 port 21 -> 127.0.0.1 port 21 tcp proxy ftp
For rdr rules, the interfaces supplied are in the same order as 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.
rdr le0,* 0/0 -> 192.168.1.0
A single rule, with as many options set as possible would look
something like this:
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
REWRITING SOURCE AND DESTINATION
Whilst the above two commands provide a lot of flexibility in changing
addressing fields in packets, often it can be of benefit to translate
both source and 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 rewrite NAT rules.
A rewrite rule requires the same level of packet matching as before,
protocol and source/destination information but in addition allows
either in or out to be specified like this:
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;
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
ipnat.conf, there are shortcuts syntaxes available to use the original
address information (0/0) and the address associated with the network
interface (0/32.) 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 (X-Y) or a single port number (=X) as
follows:
rewrite in on le0 proto tcp from any to any port = 80 ->
src 0/0,2000-20000 dst 127.0.0.1,port = 3128;
There are four fields that are stepped through in enumerating the
number space available for creating a new destination:
source address
source port
destination address
destination port
If one of these happens to be a static then it will be skipped and the
next one incremented. As an example:
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;
The translated packets would be:
1st src=1.0.0.1,5000 dst=2.0.0.1,6000
2nd src=1.0.0.2,5000 dst=2.0.0.1,6000
3rd src=1.0.0.2,5001 dst=2.0.0.1,6000
4th src=1.0.0.2,5001 dst=2.0.0.2,6000
5th src=1.0.0.2,5001 dst=2.0.0.2,6001
6th src=1.0.0.3,5001 dst=2.0.0.2,6001
and so on.
As with map rules, it is possible to specify a range of addresses by
including the word range before the addresses:
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;
DIVERTING PACKETS
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 divert rule.
Divert rules can be be used with both inbound and outbound packet
matching however the rule 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:
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;
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.
As this feature is intended to be used with targetting packets at
sockets and not IPFilter running on other systems, there is no rule
provided to undivert packets.
NOTE: Diverted packets may 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.
PathMTUDiscovery 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.
COMMON OPTIONS
This section deals with options that are available with all rules.
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.
RULE ORDERINGNOTE: Rules in ipnat.conf are read in sequentially as listed and loaded
into the kernel in this fashion BUT packet matching is done on netmask,
going from 32 down to 0. If a rule uses pool or hash to reference a
set of addresses or networks, the netmask value for these fields is
considered to be "0". So if your ipnat.conf has the following rules:
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
then the rule with 192.2.2.1 will match first, 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:
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
where the first line is actually a /32.
If your ipnat.conf file has entries with matching target fields (source
address for map rules and destination address for rdr rules), then the
ordering in the ipnat.conf file does matter. So if you had the
following:
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
Then no packets will match the 2nd rule, they'll all match the first.
IPv6
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.
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.
KERNEL PROXIES
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:
Aging - protocol is roughly understood from the time at which the proxy
was written but it is not well tested or maintained;
Developmental - basic functionality exists, works most of the time but
may be problematic in extended real use;
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.
Mature - well tested, protocol is properly understood by the proxy;
The currently compiled in proxy list is as follows:
FTP - Mature
(map ... proxy port ftp ftp/tcp)
IRC - Experimental
(proxy port 6667 irc/tcp)
rpcbind - Experimental
PPTP - Experimental
H.323 - Experimental
(map ... proxy port 1720 h323/tcp)
Real Audio (PNA) - Aging
DNS - Developmental
(map ... proxy port 53 dns/udp { block .cnn.com; })
IPsec - Developmental
(map ... proxy port 500 ipsec/tcp)
netbios - Experimental
R-command - Mature
(map ... proxy port shell rcmd/tcp)
KERNEL PROXIESFILES
/dev/ipnat
/etc/protocols
/etc/services
/etc/hosts
SEE ALSOipnat(4), hosts(5), ipf(5), services(5), ipf(8), ipnat(8)IPNAT(5)