IPPOOL(5)                                                            IPPOOL(5)



NAME
       ippool, ippool.conf - IP Pool file format

DESCRIPTION
       The  file ippool.conf is used with ippool(8) to configure address pools
       for use with ipnat(8) and ipf(8).

       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:

       dstlist

              destination list - is a  collection  of  IP  addresses  with  an
              optional network interface name that can be used with either re-
              direct (rdr) rules in ipnat.conf(5) or  as  the  destination  in
              ipf.conf(5) for policy based routing.

       group-map

              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.

       hash

              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.

       pool

              address pools - are an alternative to hash tables that can  per-
              form  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.

   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:

       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; };

       The IP pool configuration file is used for  defining  a  single  object
       that contains a reference to multiple IP address/netmask pairs.  A pool
       may consist of a mixture of netmask sizes, from 0 to 32.

       At this point in time, only IPv4 addressing is supported.

OVERVIEW
       The IP pool configuration file  provides  for  defining  two  different
       mechanisms  for  improving  speed  in matching IP addresses with rules.
       The first, table , defines a lookup table to provide a single reference
       in  a  filter rule to multiple targets and the second, group-map , pro-
       vides a mechanism to target multiple groups from a single filter  line.

       The  group-map  command can only be used with filter rules that use the
       call command to invoke either fr_srcgrpmap or fr_dstgrpmap , to use the
       source or destination address, respectively, for determining which fil-
       ter group to jump to next for continuation of filter packet processing.

POOL TYPES
       Two  storage formats are provided: hash tables and tree structure.  The
       hash table is intended for use with objects  all  containing  the  same
       netmask  or  a  few different sized netmasks of non-overlapping address
       space and the tree is designed for being able to support exceptions  to
       a covering mask, in addition to normal searching as you would do with a
       table.  It is not possible to use  the  tree  data  storage  type  with
       group-map configuration entries.

POOL ROLES
       When a pool is defined in the configuration file, it must have an asso-
       ciated role.  At present the only supported role is ipf.  Future devel-
       opment  will  see  futher  expansion  of their use by other sections of
       IPFilter code.

EXAMPLES
       The following examples show how the pool  configuration  file  is  used
       with the ipf configuration file to enhance the ability for the ipf con-
       figuration file to be succinct in meaning.

       1      The first example shows how a filter rule makes reference  to  a
              specific pool for matching of the source address.
              pool ipf/tree (name "100";)
                   { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };

       Both of the above examples produce the same configuration in the kernel
       for use with ipf.conf(5).

       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.

   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:

       ipf

              pools defined for role "ipf" are  available  for  use  with  all
              rules that are found in ipf.conf(5) except for auth rules.

       nat

              pools  defined  for  role  "nat"  are available for use with all
              rules that are found in ipnat.conf(5).

       auth

              pools defined for role "auth" are available only  for  use  with
              "auth" rules that are found in ipf.conf(5)

       all

              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).

Address Pools
       An address pool can be used in ipf.conf(5) and ipnat.conf(5) for match-
       ing 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.

       An address pool is considered to be a "tree type". In the older config-
       uration  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.

       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 fam-
       ily.

       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  addres  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  match-
       ing.  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.

       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; };

       The prior example is  the  older  file  format.  The  declaration  that
       defines  the  pool  itself has been updated and can now be expressed as
       below:

       pool ipf/tree (name "100";)
            { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };

       If the role and table type are left out, such as in the exmaple  below,
       the  default  is to make the table available to all aspects of IPFilter
       and for the storage type to be "tree".

       pool (name "100";)
            { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };

       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.

       pool ipf/tree (name rfc1918;) { file:///etc/ipf/rfc1918; };

       The contents of the file might look something like this:

       # RFC 1918 networks
       10.0.0.0/8
       !127.0.0.0/8
       172.16.0.0/12
       192.168.0.0/24

       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  nega-
       tive matching is also supported in this file.

       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.

       pool ipf/tree (name microsoft;) { whois file "/etc/ipf/ms-networks"; };

       And  to then block all packets to/from networks defined in that file, a
       rule like this might be used:

       block in from pool/microsoft to any

       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.

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).

       When  building a list of hosts to use as a redirection list, it is nec-
       essary 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)).

       Unlike  the other directives that can be expressed in this file, desti-
       nation 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:

       round-robin

              steps  through the list of hosts configured with the destination
              list one by one

       random

              the next hop is chosen by random selection from the list  avail-
              able

       src-hash

              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

       dst-hash

              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

       hash

              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

       weighted

              selecting a weighted policy for destination selection needs fur-
              ther clarification as to what type of weighted selection will be
              used.  The sub-options to a weighted policy are:

              connection

                     the  host  that  has received the least number of connec-
                     tions 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.

       The first example here shows 4 destinations that are used with a round-
       robin selection policy.

       pool nat/dstlist (name servers; policy round-robin;)
               { 1.1.1.2; 1.1.1.4; 1.1.1.5; 1.1.1.9; };

       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).

       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; };

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.

       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 pro-
       cessing to group 2040.

       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; };

       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.

       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;
           };

       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.

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.

       Hash tables are best used where the list of addresses, subnets and net-
       works is relatively static, which is something of  a  contrast  to  the
       address  pool that can work with either static or changing address list
       sizes.

       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).

       The  following  two  examples build the same table in the kernel, using
       the old configuration format (first) and the new one (second).

       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; };

FILES
       /dev/iplookup
       /etc/ippool.conf
       /etc/hosts

SEE ALSO
       ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)



                                                                     IPPOOL(5)

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen