contrib/ipfilter/man/ippool.5

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