man/ippool.5

   1 .TH IPPOOL 5
   2 .SH NAME
   3 ippool, ippool.conf \- IP Pool file format
   4 .SH DESCRIPTION
   5 The format for files accepted by ippool is described by the following grammar:
   6 .LP
   7 .nf
   8 line ::= table | groupmap .
   9 table ::= "table" role tabletype .
  10 groupmap ::= "group-map" inout role number ipfgroup
  11 tabletype ::= ipftree | ipfhash .
  12
  13 role ::= "role" "=" "ipf" .
  14 inout ::= "in" | "out" .
  15
  16 ipftree ::= "type" "=" "tree" number "{" addrlist "}" .
  17 ipfhash ::= "type" "=" "hash" number hashopts "{" hashlist "}" .
  18
  19 ipfgroup ::= setgroup hashopts "{" grouplist "}" |
  20              hashopts "{" setgrouplist "}" .
  21 setgroup ::= "group" "=" groupname .
  22
  23 hashopts ::= size [ seed ] | seed .
  24
  25 size ::= "size" number .
  26 seed ::= "seed" number .
  27
  28 addrlist ::= [ "!" ] addrmask ";" [ addrlist ] .
  29 grouplist ::= groupentry ";" [ grouplist ] | addrmask ";" [ grouplist ] .
  30
  31 setgrouplist ::= groupentry ";" [ setgrouplist ] .
  32
  33 groupentry ::= addrmask "," setgroup .
  34
  35 hashlist ::= hashentry ";" [ hashlist ] .
  36 hashentry ::= addrmask .
  37
  38 addrmask ::= ipaddr | ipaddr "/" mask .
  39
  40 mask ::= number | ipaddr .
  41
  42 groupname ::= number | name .
  43
  44 number ::= digit { digit } .
  45
  46 ipaddr  = host-num "." host-num "." host-num "." host-num .
  47 host-num = digit [ digit [ digit ] ] .
  48
  49 digit ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" .
  50 name ::= letter { letter | digit } .
  51 .fi
  52 .PP
  53 The IP pool configuration file is used for defining a single object that
  54 contains a reference to multiple IP address/netmask pairs.  A pool may consist
  55 of a mixture of netmask sizes, from 0 to 32.
  56 .PP
  57 At this point in time, only IPv4 addressing is supported.
  58 .TP
  59 .SH OVERVIEW
  60 .PP
  61 The IP pool configuration file provides for defining two different mechanisms
  62 for improving speed in matching IP addresses with rules.
  63 The first,
  64 .B table
  65 , defines a lookup
  66 .I table
  67 to provide a single reference in a
  68 filter rule to multiple targets and the second,
  69 .B group-map
  70 , provides a mechanism to target multiple groups from a single filter line.
  71 .PP
  72 The
  73 .B group-map
  74 command can only be used with filter rules that use the
  75 .B call
  76 command to invoke either
  77 .B fr_srcgrpmap
  78 or
  79 .B fr_dstgrpmap
  80 , to use the source or destination address,
  81 respectively, for determining which filter group to jump to next for
  82 continuation of filter packet processing.
  83 .SH POOL TYPES
  84 .PP
  85 Two storage formats are provided: hash tables and tree structure.  The hash
  86 table is intended for use with objects all containing the same netmask or a
  87 few different sized netmasks of non-overlapping address space and the tree
  88 is designed for being able to support exceptions to a covering mask, in
  89 addition to normal searching as you would do with a table.  It is not possible
  90 to use the tree data storage type with
  91 .B group-map
  92 configuration entries.
  93 .SH POOL ROLES
  94 .PP
  95 When a pool is defined in the configuration file, it must have an associated
  96 role.  At present the only supported role is
  97 .B ipf.
  98 Future development will see futher expansion of their use by other sections
  99 of IPFilter code.
 100 .SH EXAMPLES
 101 The following examples show how the pool configuration file is used with
 102 the ipf configuration file to enhance the ability for the ipf configuration
 103 file to be succinct in meaning.
 104 .TP
 105 1
 106 The first example shows how a filter rule makes reference to a specific
 107 pool for matching of the source address.
 108 .nf
 109 pass in from pool/100 to any
 110 .fi
 111 .PP
 112 The pool configuration, which matches IP addresses 1.1.1.1 and any
 113 in 2.2.0.0/16, except for those in 2.2.2.0/24.
 114 .PP
 115 .nf
 116 table role = ipf type = tree number = 100
 117         { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24 };
 118 .fi
 119 .TP
 120 2
 121 The following ipf.conf extract uses the
 122 fr_srcgrpmap/fr_dstgrpmap lookups to use the
 123 .B group-map
 124 facility to lookup the next group to use for filter processing, providing
 125 the
 126 .B call
 127 filter rule is matched.
 128 .nf
 129 call now fr_srcgrpmap/1010 in all
 130 call now fr_dstgrpmap/2010 out all
 131 pass in all group 1020
 132 block in all group 1030
 133 pass out all group 2020
 134 block out all group 2040
 135 .fi
 136 .PP
 137 A ippool configuration to work with the above ipf.conf file might
 138 look like this:
 139 .PP
 140 .nf
 141 group-map in role = ipf number = 1010
 142         { 1.1.1.1/32, group = 1020; 3.3.0.0/16, group = 1030; };
 143 group-map out role = ipf number = 2010 group = 2020
 144         { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; };
 145 .fi
 146 .SH FILES
 147 /dev/iplookup
 148 .br
 149 /etc/ippool.conf
 150 .br
 151 /etc/hosts
 152 .SH SEE ALSO
 153 ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)