usr/src/man/man4/ippool.4

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