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)