mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-12-03 14:48:57 +00:00
e413da1358
The full mandoc warnings were:
skipping paragraph macro: PP after SS
skipping paragraph macro: PP after SH
The rendered output (in ascii and html) is not affected by this commit.
Fixes made by script in https://github.com/Tarsnap/freebsd-doc-scripts
Signed-off-by: Graham Percival <gperciva@tarsnap.com>
Reviewed by: jlduran, mhorne
MFC after: 1 week
Sponsored by: Tarsnap Backup Inc.
Pull Request: https://github.com/freebsd/freebsd-src/pull/1524
314 lines
12 KiB
Groff
314 lines
12 KiB
Groff
.\"
|
|
.TH IPPOOL 5
|
|
.SH NAME
|
|
ippool, ippool.conf \- IP Pool file format
|
|
.SH DESCRIPTION
|
|
The file ippool.conf is used with ippool(8) to configure address pools for
|
|
use with ipnat(8) and ipf(8).
|
|
.PP
|
|
There are four different types of address pools that can be configured
|
|
through ippool.conf. The various types are presented below with a brief
|
|
description of how they are used:
|
|
.HP
|
|
dstlist
|
|
.IP
|
|
destination list - is a collection of IP addresses with an optional
|
|
network interface name that can be used with either redirect (rdr) rules
|
|
in ipnat.conf(5) or as the destination in ipf.conf(5) for policy based
|
|
routing.
|
|
.HP
|
|
group-map
|
|
.IP
|
|
group maps - support the srcgrpmap and dstgrpmap call functions in
|
|
ipf.conf(5) by providing a list of addresses or networks rule group
|
|
numbers to start processing them with.
|
|
.HP
|
|
hash
|
|
.IP
|
|
hash tables - provide the means for performing a very efficient
|
|
lookup address or network when there is expected to be only one
|
|
exact match. These are best used with more static sets of addresses
|
|
so they can be sized optimally.
|
|
.HP
|
|
pool
|
|
.IP
|
|
address pools - are an alternative to hash tables that can perform just
|
|
as well in most circumstances. In addition, the address pools allow for
|
|
heirarchical matching, so it is possible to define a subnet as matching
|
|
but then exclude specific addresses from it.
|
|
.SS
|
|
Evolving Configuration
|
|
Over time the configuration syntax used by ippool.conf(5) has evolved.
|
|
Originally the syntax used was more verbose about what a particular
|
|
value was being used for, for example:
|
|
.PP
|
|
.nf
|
|
table role = ipf type = tree number = 100
|
|
{ 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
|
|
.fi
|
|
.PP
|
|
This is rather long winded. The evolution of the configuration syntax
|
|
has also replaced the use of numbers with names, although numbers can
|
|
still be used as can be seen here:
|
|
.PP
|
|
.nf
|
|
pool ipf/tree (name "100";)
|
|
{ 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
|
|
.fi
|
|
.PP
|
|
Both of the above examples produce the same configuration in the kernel
|
|
for use with ipf.conf(5).
|
|
.PP
|
|
Newer options for use in ippool.conf(5) will only be offered in the new
|
|
configuration syntax and all output using "ippool -l" will also be in the
|
|
new configuration syntax.
|
|
.SS
|
|
IPFilter devices and pools
|
|
To cater to different administration styles, ipool.conf(5) allows you to
|
|
tie a pool to a specific role in IPFilter. The recognised role names are:
|
|
.HP
|
|
ipf
|
|
.IP
|
|
pools defined for role "ipf" are available for use with all rules that are
|
|
found in ipf.conf(5) except for auth rules.
|
|
.HP
|
|
nat
|
|
.IP
|
|
pools defined for role "nat" are available for use with all rules that are
|
|
found in ipnat.conf(5).
|
|
.HP
|
|
auth
|
|
.IP
|
|
pools defined for role "auth" are available only for use with "auth" rules
|
|
that are found in ipf.conf(5)
|
|
.HP
|
|
all
|
|
.IP
|
|
pools that are defined for the "all" role are available to all types of
|
|
rules, be they NAT rules in ipnat.conf(5) or firewall rules in ipf.conf(5).
|
|
.SH Address Pools
|
|
An address pool can be used in ipf.conf(5) and ipnat.conf(5) for matching
|
|
the source or destination address of packets. They can be referred to either
|
|
by name or number and can hold an arbitrary number of address patterns to
|
|
match.
|
|
.PP
|
|
An address pool is considered to be a "tree type". In the older configuration
|
|
style, it was necessary to have "type=tree" in ippool.conf(5). In the new
|
|
style configuration, it follows the IPFilter device with which the pool
|
|
is being configured.
|
|
Now it is the default if left out.
|
|
.PP
|
|
For convenience, both IPv4 and IPv6 addresses can be stored in the same
|
|
address pool. It should go without saying that either type of packet can
|
|
only ever match an entry in a pool that is of the same address family.
|
|
.PP
|
|
The address pool searches the list of addresses configured for the best
|
|
match. The "best match" is considered to be the match that has the highest
|
|
number of bits set in the mask. Thus if both 2.2.0.0/16 and 2.2.2.0/24 are
|
|
present in an address pool, the address 2.2.2.1 will match 2.2.2.0/24 and
|
|
2.2.1.1 will match 2.2.0.0/16. The reason for this is to allow exceptions
|
|
to be added through the use of negative matching. In the following example,
|
|
the pool contains "2.2.0.0/16" and "!2.2.2.0/24", meaning that all packets
|
|
that match 2.2.0.0/16, except those that match 2.2.2.0/24, will be considered
|
|
as a match for this pool.
|
|
.PP
|
|
table role = ipf type = tree number = 100
|
|
{ 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24; ef00::5/128; };
|
|
.PP
|
|
For the sake of clarity and to aid in managing large numbers of addresses
|
|
inside address pools, it is possible to specify a location to load the
|
|
addresses from. To do this simply use a "file://" URL where you would
|
|
specify an actual IP address.
|
|
.PP
|
|
.nf
|
|
pool ipf/tree (name rfc1918;) { file:///etc/ipf/rfc1918; };
|
|
.fi
|
|
.PP
|
|
The contents of the file might look something like this:
|
|
.PP
|
|
.nf
|
|
# RFC 1918 networks
|
|
10.0.0.0/8
|
|
!127.0.0.0/8
|
|
172.16.0.0/12
|
|
192.168.0.0/24
|
|
.fi
|
|
.PP
|
|
In this example, the inclusion of the line "!127.0.0.0/8" is, strictly
|
|
speaking not correct and serves only as an example to show that negative
|
|
matching is also supported in this file.
|
|
.PP
|
|
Another format that ippool(8) recognises for input from a file is that
|
|
from whois servers. In the following example, output from a query to a
|
|
WHOIS server for information about which networks are associated with
|
|
the name "microsoft" has been saved in a file named "ms-networks".
|
|
There is no need to modify the output from the whois server, so using
|
|
either the whois command or dumping data directly from it over a TCP
|
|
connection works perfectly file as input.
|
|
.PP
|
|
.nf
|
|
pool ipf/tree (name microsoft;) { whois file "/etc/ipf/ms-networks"; };
|
|
.fi
|
|
.PP
|
|
And to then block all packets to/from networks defined in that file,
|
|
a rule like this might be used:
|
|
.PP
|
|
.nf
|
|
block in from pool/microsoft to any
|
|
.fi
|
|
.PP
|
|
Note that there are limitations on the output returned by whois servers
|
|
so be aware that their output may not be 100% perfect for your goal.
|
|
.SH Destination Lists
|
|
Destination lists are provided for use primarily with NAT redirect rules
|
|
(rdr). Their purpose is to allow more sophisticated methods of selecting
|
|
which host to send traffic to next than the simple round-robin technique
|
|
that is present with with "round-robin" rules in ipnat.conf(5).
|
|
.PP
|
|
When building a list of hosts to use as a redirection list, it is
|
|
necessary to list each host to be used explicitly. Expressing a
|
|
collection of hosts as a range or a subnet is not supported. With each
|
|
address it is also possible to specify a network interface name. The
|
|
network interface name is ignored by NAT when using destination lists.
|
|
The network itnerface name is currently only used with policy based
|
|
routing (use of "to"/"dup-to" in ipf.conf(5)).
|
|
.PP
|
|
Unlike the other directives that can be expressed in this file, destination
|
|
lists must be written using the new configuration syntax. Each destination
|
|
list must have a name associated with it and a next hop selection policy.
|
|
Some policies have further options. The currently available selection
|
|
policies are:
|
|
.HP
|
|
round-robin
|
|
.IP
|
|
steps through the list of hosts configured with the destination list
|
|
one by one
|
|
.HP
|
|
random
|
|
.IP
|
|
the next hop is chosen by random selection from the list available
|
|
.HP
|
|
src-hash
|
|
.IP
|
|
a hash is made of the source address components of the packet
|
|
(address and port number) and this is used to select which
|
|
next hop address is used
|
|
.HP
|
|
dst-hash
|
|
.IP
|
|
a hash is made of the destination address components of the packet
|
|
(address and port number) and this is used to select which
|
|
next hop address is used
|
|
.HP
|
|
hash
|
|
.IP
|
|
a hash is made of all the address components in the packet
|
|
(addresses and port numbers) and this is used to select which
|
|
next hop address is used
|
|
.HP
|
|
weighted
|
|
.IP
|
|
selecting a weighted policy for destination selection needs further
|
|
clarification as to what type of weighted selection will be used.
|
|
The sub-options to a weighted policy are:
|
|
.RS
|
|
.HP
|
|
connection
|
|
.IP
|
|
the host that has received the least number of connections is selected
|
|
to be the next hop. When all hosts have the same connection count,
|
|
the last one used will be the next address selected.
|
|
.RE
|
|
.PP
|
|
The first example here shows 4 destinations that are used with a
|
|
round-robin selection policy.
|
|
.PP
|
|
.nf
|
|
pool nat/dstlist (name servers; policy round-robin;)
|
|
{ 1.1.1.2; 1.1.1.4; 1.1.1.5; 1.1.1.9; };
|
|
.fi
|
|
.PP
|
|
In the following example, the destination is chosen by whichever has
|
|
had the least number of connections. By placing the interface name
|
|
with each address and saying "all/dstlist", the destination list can
|
|
be used with both ipnat.conf(5) and ipf.conf(5).
|
|
.PP
|
|
.nf
|
|
pool all/dstlist (name servers; policy weighted connection;)
|
|
{ bge0:1.1.1.2; bge0:1.1.1.4; bge1:1.1.1.5; bge1:1.1.1.9; };
|
|
.fi
|
|
.SH Group maps
|
|
Group maps are provided to allow more efficient processing of packets
|
|
where there are a larger number of subnets and groups of rules for those
|
|
subnets. Group maps are used with "call" rules in ipf.conf(5) that
|
|
use the "srcgrpmap" and "dstgrpmap" functions.
|
|
.PP
|
|
A group map declaration must mention which group is the default group
|
|
for all matching addresses to be applied to. Then inside the list of
|
|
addresses and networks for the group, each one may optionally have
|
|
a group number associated with it. A simple example like this, where
|
|
the first two entries would map to group 2020 but 5.0.0.0/8 sends
|
|
rule processing to group 2040.
|
|
.PP
|
|
.nf
|
|
group-map out role = ipf number = 2010 group = 2020
|
|
{ 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; };
|
|
.fi
|
|
.PP
|
|
An example that outlines the real purpose of group maps is below,
|
|
where each one of the 12 subnets is mapped to a different group
|
|
number. This might be because each subnet has its own policy and
|
|
rather than write a list of twelve rules in ipf.conf(5) that match
|
|
the subnet and branch off with a head statement, a single rule can
|
|
be used with this group map to achieve the same result.
|
|
.PP
|
|
.nf
|
|
group-map ( name "2010"; in; )
|
|
{ 192.168.1.0/24, group = 10010; 192.168.2.0/24, group = 10020;
|
|
192.168.3.0/24, group = 10030; 192.168.4.0/24, group = 10040;
|
|
192.168.5.0/24, group = 10050; 192.168.6.0/24, group = 10060;
|
|
192.168.7.0/24, group = 10070; 192.168.8.0/24, group = 10080;
|
|
192.168.9.0/24, group = 10090; 192.168.10.0/24, group = 10100;
|
|
192.168.11.0/24, group = 10110; 192.168.12.0/24, group = 10120;
|
|
};
|
|
.fi
|
|
.PP
|
|
The limitation with group maps is that only the source address or the
|
|
destination address can be used to map the packet to the starting group,
|
|
not both, in your ipf.conf(5) file.
|
|
.SH Hash Tables
|
|
The hash table is operationally similar to the address pool. It is
|
|
used as a store for a collection of address to match on, saving the
|
|
need to write a lengthy list of rules. As with address pools, searching
|
|
will attempt to find the best match - an address specification with the
|
|
largest contiguous netmask.
|
|
.PP
|
|
Hash tables are best used where the list of addresses, subnets and
|
|
networks is relatively static, which is something of a contrast to
|
|
the address pool that can work with either static or changing
|
|
address list sizes.
|
|
.PP
|
|
Further work is still needed to have IPFilter correctly size and tune
|
|
the hash table to optimise searching. The goal is to allow for small to
|
|
medium sized tables to achieve close to O(1) for either a positive or
|
|
negative match, in contrast to the address pool, which is O(logn).
|
|
.PP
|
|
The following two examples build the same table in the kernel, using
|
|
the old configuration format (first) and the new one (second).
|
|
.PP
|
|
.nf
|
|
table role=all type=hash name=servers size=5
|
|
{ 1.1.1.2/32; 1.1.1.3/32; 11.23.44.66/32; };
|
|
|
|
pool all/hash (name servers; size 5;)
|
|
{ 1.1.1.2; 1.1.1.3; 11.23.44.66; };
|
|
.fi
|
|
.SH FILES
|
|
/dev/iplookup
|
|
.br
|
|
/etc/ippool.conf
|
|
.br
|
|
/etc/hosts
|
|
.SH SEE ALSO
|
|
ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)
|