dist/ipf/man/ippool.5

   1 .\"     $NetBSD: ippool.5,v 1.2 2006/04/20 08:37:33 pavel Exp $
   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 .SH OVERVIEW
  61 .PP
  62 The IP pool configuration file provides for defining two different mechanisms
  63 for improving speed in matching IP addresses with rules.
  64 The first,
  65 .B table
  66 , defines a lookup
  67 .I table
  68 to provide a single reference in a
  69 filter rule to multiple targets and the second,
  70 .B group-map
  71 , provides a mechanism to target multiple groups from a single filter line.
  72 .PP
  73 The
  74 .B group-map
  75 command can only be used with filter rules that use the
  76 .B call
  77 command to invoke either
  78 .B fr_srcgrpmap
  79 or
  80 .B fr_dstgrpmap
  81 , to use the source or destination address,
  82 respectively, for determining which filter group to jump to next for
  83 continuation of filter packet processing.
  84 .SH POOL TYPES
  85 .PP
  86 Two storage formats are provided: hash tables and tree structure.  The hash
  87 table is intended for use with objects all containing the same netmask or a
  88 few different sized netmasks of non-overlapping address space and the tree
  89 is designed for being able to support exceptions to a covering mask, in
  90 addition to normal searching as you would do with a table.  It is not possible
  91 to use the tree data storage type with
  92 .B group-map
  93 configuration entries.
  94 .SH POOL ROLES
  95 .PP
  96 When a pool is defined in the configuration file, it must have an associated
  97 role.  At present the only supported role is
  98 .B ipf.
  99 Future development will see futher expansion of their use by other sections
 100 of IPFilter code.
 101 .SH EXAMPLES
 102 The following examples show how the pool configuration file is used with
 103 the ipf configuration file to enhance the ability for the ipf configuration
 104 file to be succinct in meaning.
 105 .TP
 106 1
 107 The first example shows how a filter rule makes reference to a specific
 108 pool for matching of the source address.
 109 .nf
 110 pass in from pool/100 to any
 111 .fi
 112 .PP
 113 The pool configuration, which matches IP addresses 1.1.1.1 and any
 114 in 2.2.0.0/16, except for those in 2.2.2.0/24.
 115 .PP
 116 .nf
 117 table role = ipf type = tree number = 100
 118         { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24 };
 119 .fi
 120 .TP
 121 2
 122 The following ipf.conf extract uses the
 123 fr_srcgrpmap/fr_dstgrpmap lookups to use the
 124 .B group-map
 125 facility to lookup the next group to use for filter processing, providing
 126 the
 127 .B call
 128 filter rule is matched.
 129 .nf
 130 call now fr_srcgrpmap/1010 in all
 131 call now fr_dstgrpmap/2010 out all
 132 pass in all group 1020
 133 block in all group 1030
 134 pass out all group 2020
 135 block out all group 2040
 136 .fi
 137 .PP
 138 A ippool configuration to work with the above ipf.conf file might
 139 look like this:
 140 .PP
 141 .nf
 142 group-map in role = ipf number = 1010
 143         { 1.1.1.1/32, group = 1020; 3.3.0.0/16, group = 1030; };
 144 group-map out role = ipf number = 2010 group = 2020
 145         { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; };
 146 .fi
 147 .SH FILES
 148 /dev/iplookup
 149 .br
 150 /etc/ippool.conf
 151 .br
 152 /etc/hosts
 153 .SH SEE ALSO
 154 ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)