diff options
Diffstat (limited to 'static/freebsd/man5/ippool.5')
| -rw-r--r-- | static/freebsd/man5/ippool.5 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/static/freebsd/man5/ippool.5 b/static/freebsd/man5/ippool.5 new file mode 100644 index 00000000..1ab8681b --- /dev/null +++ b/static/freebsd/man5/ippool.5 @@ -0,0 +1,313 @@ +.\" +.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) |