5 ippool, ippool.conf \- IP Pool file format
7 The file ippool.conf is used with ippool(8) to configure address pools for
8 use with ipnat(8) and ipf(8).
10 There are four different types of address pools that can be configured
11 through ippool.conf. The various types are presented below with a brief
12 description of how they are used:
16 destination list - is a collection of IP addresses with an optional
17 network interface name that can be used with either redirect (rdr) rules
18 in ipnat.conf(5) or as the destination in ipf.conf(5) for policy based
23 group maps - support the srcgrpmap and dstgrpmap call functions in
24 ipf.conf(5) by providing a list of addresses or networks rule group
25 numbers to start processing them with.
29 hash tables - provide the means for performing a very efficient
30 lookup address or network when there is expected to be only one
31 exact match. These are best used with more static sets of addresses
32 so they can be sized optimally.
36 address pools - are an alternative to hash tables that can perform just
37 as well in most circumstances. In addition, the address pools allow for
38 heirarchical matching, so it is possible to define a subnet as matching
39 but then exclude specific addresses from it.
41 Evolving Configuration
43 Over time the configuration syntax used by ippool.conf(5) has evolved.
44 Originally the syntax used was more verbose about what a particular
45 value was being used for, for example:
48 table role = ipf type = tree number = 100
49 { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
52 This is rather long winded. The evolution of the configuration syntax
53 has also replaced the use of numbers with names, although numbers can
54 still be used as can be seen here:
57 pool ipf/tree (name "100";)
58 { 1.1.1.1/32; !2.2.0.0/16; 2.2.2.0/24; ef00::5/128; };
61 Both of the above examples produce the same configuration in the kernel
62 for use with ipf.conf(5).
64 Newer options for use in ippool.conf(5) will only be offered in the new
65 configuration syntax and all output using "ippool -l" will also be in the
66 new configuration syntax.
68 IPFilter devices and pools
70 To cater to different administration styles, ipool.conf(5) allows you to
71 tie a pool to a specific role in IPFilter. The recognised role names are:
75 pools defined for role "ipf" are available for use with all rules that are
76 found in ipf.conf(5) except for auth rules.
80 pools defined for role "nat" are available for use with all rules that are
81 found in ipnat.conf(5).
85 pools defined for role "auth" are available only for use with "auth" rules
86 that are found in ipf.conf(5)
90 pools that are defined for the "all" role are available to all types of
91 rules, be they NAT rules in ipnat.conf(5) or firewall rules in ipf.conf(5).
94 An address pool can be used in ipf.conf(5) and ipnat.conf(5) for matching
95 the source or destination address of packets. They can be referred to either
96 by name or number and can hold an arbitrary number of address patterns to
99 An address pool is considered to be a "tree type". In the older configuration
100 style, it was necessary to have "type=tree" in ippool.conf(5). In the new
101 style configuration, it follows the IPFilter device with which the pool
103 Now it is the default if left out.
105 For convenience, both IPv4 and IPv6 addresses can be stored in the same
106 address pool. It should go without saying that either type of packet can
107 only ever match an entry in a pool that is of the same address family.
109 The address pool searches the list of addresses configured for the best
110 match. The "best match" is considered to be the match that has the highest
111 number of bits set in the mask. Thus if both 2.2.0.0/16 and 2.2.2.0/24 are
112 present in an address pool, the addres 2.2.2.1 will match 2.2.2.0/24 and
113 2.2.1.1 will match 2.2.0.0/16. The reason for this is to allow exceptions
114 to be added through the use of negative matching. In the following example,
115 the pool contains "2.2.0.0/16" and "!2.2.2.0/24", meaning that all packets
116 that match 2.2.0.0/16, except those that match 2.2.2.0/24, will be considered
117 as a match for this pool.
119 table role = ipf type = tree number = 100
120 { 1.1.1.1/32; 2.2.0.0/16; !2.2.2.0/24; ef00::5/128; };
122 For the sake of clarity and to aid in managing large numbers of addresses
123 inside address pools, it is possible to specify a location to load the
124 addresses from. To do this simply use a "file://" URL where you would
125 specify an actual IP address.
128 pool ipf/tree (name rfc1918;) { file:///etc/ipf/rfc1918; };
131 The contents of the file might look something like this:
141 In this example, the inclusion of the line "!127.0.0.0/8" is, strictly
142 speaking not correct and serves only as an example to show that negative
143 matching is also supported in this file.
145 Another format that ippool(8) recognises for input from a file is that
146 from whois servers. In the following example, output from a query to a
147 WHOIS server for information about which networks are associated with
148 the name "microsoft" has been saved in a file named "ms-networks".
149 There is no need to modify the output from the whois server, so using
150 either the whois command or dumping data directly from it over a TCP
151 connection works perfectly file as input.
154 pool ipf/tree (name microsoft;) { whois file "/etc/ipf/ms-networks"; };
157 And to then block all packets to/from networks defined in that file,
158 a rule like this might be used:
161 block in from pool/microsoft to any
164 Note that there are limitations on the output returned by whois servers
165 so be aware that their output may not be 100% perfect for your goal.
166 .SH Destination Lists
168 Destination lists are provided for use primarily with NAT redirect rules
169 (rdr). Their purpose is to allow more sophisticated methods of selecting
170 which host to send traffic to next than the simple round-robin technique
171 that is present with with "round-robin" rules in ipnat.conf(5).
173 When building a list of hosts to use as a redirection list, it is
174 necessary to list each host to be used explicitly. Expressing a
175 collection of hosts as a range or a subnet is not supported. With each
176 address it is also possible to specify a network interface name. The
177 network interface name is ignored by NAT when using destination lists.
178 The network itnerface name is currently only used with policy based
179 routing (use of "to"/"dup-to" in ipf.conf(5)).
181 Unlike the other directives that can be expressed in this file, destination
182 lists must be written using the new configuration syntax. Each destination
183 list must have a name associated with it and a next hop selection policy.
184 Some policies have further options. The currently available selection
189 steps through the list of hosts configured with the destination list
194 the next hop is chosen by random selection from the list available
198 a hash is made of the source address components of the packet
199 (address and port number) and this is used to select which
200 next hop address is used
204 a hash is made of the destination address components of the packet
205 (address and port number) and this is used to select which
206 next hop address is used
210 a hash is made of all the address components in the packet
211 (addresses and port numbers) and this is used to select which
212 next hop address is used
216 selecting a weighted policy for destination selection needs further
217 clarification as to what type of weighted selection will be used.
218 The sub-options to a weighted policy are:
223 the host that has received the least number of connections is selected
224 to be the next hop. When all hosts have the same connection count,
225 the last one used will be the next address selected.
228 The first example here shows 4 destinations that are used with a
229 round-robin selection policy.
232 pool nat/dstlist (name servers; policy round-robin;)
233 { 1.1.1.2; 1.1.1.4; 1.1.1.5; 1.1.1.9; };
236 In the following example, the destination is chosen by whichever has
237 had the least number of connections. By placing the interface name
238 with each address and saying "all/dstlist", the destination list can
239 be used with both ipnat.conf(5) and ipf.conf(5).
242 pool all/dstlist (name servers; policy weighted connection;)
243 { bge0:1.1.1.2; bge0:1.1.1.4; bge1:1.1.1.5; bge1:1.1.1.9; };
247 Group maps are provided to allow more efficient processing of packets
248 where there are a larger number of subnets and groups of rules for those
249 subnets. Group maps are used with "call" rules in ipf.conf(5) that
250 use the "srcgrpmap" and "dstgrpmap" functions.
252 A group map declaration must mention which group is the default group
253 for all matching addresses to be applied to. Then inside the list of
254 addresses and networks for the group, each one may optionally have
255 a group number associated with it. A simple example like this, where
256 the first two entries would map to group 2020 but 5.0.0.0/8 sends
257 rule processing to group 2040.
260 group-map out role = ipf number = 2010 group = 2020
261 { 2.2.2.2/32; 4.4.0.0/16; 5.0.0.0/8, group = 2040; };
264 An example that outlines the real purpose of group maps is below,
265 where each one of the 12 subnets is mapped to a different group
266 number. This might be because each subnet has its own policy and
267 rather than write a list of twelve rules in ipf.conf(5) that match
268 the subnet and branch off with a head statement, a single rule can
269 be used with this group map to achieve the same result.
272 group-map ( name "2010"; in; )
273 { 192.168.1.0/24, group = 10010; 192.168.2.0/24, group = 10020;
274 192.168.3.0/24, group = 10030; 192.168.4.0/24, group = 10040;
275 192.168.5.0/24, group = 10050; 192.168.6.0/24, group = 10060;
276 192.168.7.0/24, group = 10070; 192.168.8.0/24, group = 10080;
277 192.168.9.0/24, group = 10090; 192.168.10.0/24, group = 10100;
278 192.168.11.0/24, group = 10110; 192.168.12.0/24, group = 10120;
282 The limitation with group maps is that only the source address or the
283 destination address can be used to map the packet to the starting group,
284 not both, in your ipf.conf(5) file.
287 The hash table is operationally similar to the address pool. It is
288 used as a store for a collection of address to match on, saving the
289 need to write a lengthy list of rules. As with address pools, searching
290 will attempt to find the best match - an address specification with the
291 largest contiguous netmask.
293 Hash tables are best used where the list of addresses, subnets and
294 networks is relatively static, which is something of a contrast to
295 the address pool that can work with either static or changing
298 Further work is still needed to have IPFilter correctly size and tune
299 the hash table to optimise searching. The goal is to allow for small to
300 medium sized tables to achieve close to O(1) for either a positive or
301 negative match, in contrast to the address pool, which is O(logn).
303 The following two examples build the same table in the kernel, using
304 the old configuration format (first) and the new one (second).
307 table role=all type=hash name=servers size=5
308 { 1.1.1.2/32; 1.1.1.3/32; 11.23.44.66/32; };
310 pool all/hash (name servers; size 5;)
311 { 1.1.1.2; 1.1.1.3; 11.23.44.66; };
320 ippool(8), hosts(5), ipf(5), ipf(8), ipnat(8)
projects / FreeBSD / releng / 10.2.git / blob