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 "May 16, 2020"
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 The IP pool configuration file provides for defining two different mechanisms
66 for improving speed in matching IP addresses with rules.
67 The first,
68 .B table
69 , defines a lookup
70 .I table
71 to provide a single reference in a
72 filter rule to multiple targets and the second,
73 .B group-map
74 , provides a mechanism to target multiple groups from a single filter line.
75 .PP
76 The
77 .B group-map
78 command can only be used with filter rules that use the
79 .B call
80 command to invoke either
81 .B fr_srcgrpmap
82 or
83 .B fr_dstgrpmap
84 , to use the source or destination address,
85 respectively, for determining which filter group to jump to next for
86 continuation of filter packet processing.
87 .SH POOL TYPES
88 Two storage formats are provided: hash tables and tree structure. The hash
89 table is intended for use with objects all containing the same netmask or a
90 few different sized netmasks of non-overlapping address space and the tree
91 is designed for being able to support exceptions to a covering mask, in
92 addition to normal searching as you would do with a table. It is not possible
93 to use the tree data storage type with
94 .B group-map
95 configuration entries.
96 .SH POOL ROLES
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 further 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 \fBippool\fR(1M), \fBhosts\fR(4), \fBipf\fR(4), \fBipf\fR(1M), \fBipnat\fR(1M),
156 \fBipfilter\fR(5)