1 .TH IPSET 8 "Feb 05, 2004" "" ""
3 .\" Man page written by Jozsef Kadlecsik <kadlec@blackhole.kfki.hu>
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License as published by
7 .\" the Free Software Foundation; either version 2 of the License, or
8 .\" (at your option) any later version.
10 .\" This program is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 .\" GNU General Public License for more details.
15 .\" You should have received a copy of the GNU General Public License
16 .\" along with this program; if not, write to the Free Software
17 .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21 ipset \- administration tool for IP sets
23 .BR "ipset -N " "set type-specification [options]"
25 .BR "ipset -[XFLSHh] " "[set] [options]"
27 .BR "ipset -[EW] " "from-set to-set"
29 .BR "ipset -[ADU] " "set entry"
31 .BR "ipset -B " "set entry -b binding"
33 .BR "ipset -T " "set entry [-b binding]"
38 is used to set up, maintain and inspect so called IP sets in the Linux
39 kernel. Depending on the type, an IP set may store IP addresses, (TCP/UDP)
40 port numbers or additional informations besides IP addresses: the word IP
41 means a general term here. See the set type definitions below.
43 Any entry in a set can be bound to another set, which forms a relationship
44 between a set element and the set it is bound to. In order to define a
45 binding it is not required that the entry be already added to the set.
46 The sets may have a default binding, which is valid for every set element
47 for which there is no binding defined at all.
49 IP set bindings pointing to sets and iptables matches and targets
50 referring to sets creates references, which protects the given sets in
51 the kernel. A set cannot be removed (destroyed) while there is a single
52 reference pointing to it.
54 The options that are recognized by
56 can be divided into several different groups.
58 These options specify the specific action to perform. Only one of them
59 can be specified on the command line unless otherwise specified
60 below. For all the long versions of the command and option names, you
61 need to use only enough letters to ensure that
63 can differentiate it from all other options.
65 .BI "-N, --create " "\fIsetname\fP type type-specific-options"
66 Create a set identified with setname and specified type.
67 Type-specific options must be supplied.
69 .BI "-X, --destroy " "[\fIsetname\fP]"
70 Destroy the specified set, or all sets if none or the keyword
74 Before destroying the set, all bindings belonging to the
75 set elements and the default binding of the set are removed.
77 If the set has got references, nothing is done.
79 .BI "-F, --flush " "[\fIsetname\fP]"
80 Delete all entries from the specified set, or flush
81 all sets if none or the keyword
84 is given. Bindings are not affected by the flush operation.
86 .BI "-E, --rename " "\fIfrom-setname\fP \fIto-setname\fP"
87 Rename a set. Set identified by to-setname must not exist.
89 .BI "-W, --swap " "\fIfrom-setname\fP \fIto-setname\fP"
90 Swap two sets as they referenced in the Linux kernel.
96 bindings pointing to the content of from-setname will point to
97 the content of to-setname and vice versa. Both sets must exist.
99 .BI "-L, --list " "[\fIsetname\fP]"
100 List the entries and bindings for the specified set, or for
101 all sets if none or the keyword
106 option can be used to suppress name lookups and generate numeric
109 option is given, the entries are listed sorted (if the given set
110 type supports the operation).
112 .BI "-S, --save " "[\fIsetname\fP]"
113 Save the given set, or all sets if none or the keyword
116 is specified to stdout in a format that --restore can read.
119 Restore a saved session generated by --save. The saved session
120 can be fed from stdin.
122 When generating a session file please note that the supported commands
123 (create set, add element, bind) must appear in a strict order: first create
124 the set, then add all elements. Then create the next set, add all its elements
125 and so on. Finally you can list all binding commands. Also, it is a restore
126 operation, so the sets being restored must not exist.
128 .BI "-A, --add " "\fIsetname\fP \fIIP\fP"
131 .BI "-D, --del " "\fIsetname\fP \fIIP\fP"
132 Delete an IP from a set.
134 .BI "-T, --test " "\fIsetname\fP \fIIP
135 Test wether an IP is in a set or not. Exit status number is zero
136 if the tested IP is in the set and nonzero if it is missing from
139 .BI "-T, --test " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
140 Test wether the IP belonging to the set points to the specified binding.
141 Exit status number is zero if the binding points to the specified set,
142 otherwise it is nonzero. The keyword
145 can be used to test the default binding of the set.
147 .BI "-B, --bind " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
148 Bind the IP in setname to to-setname.
150 .BI "-U, --unbind " "\fIsetname\fP \fIIP\fP"
151 Delete the binding belonging to IP in set setname.
153 .BI "-H, --help " "[settype]"
154 Print help and settype specific help if settype specified.
162 commands you can use the token
165 to bind, unbind or test the default binding of a set instead
169 command you can use the token
172 to destroy the bindings of all elements of a set.
174 The following additional options can be specified:
176 .B "-b, --binding setname"
177 The option specifies the value of the binding for the
179 binding command, for which it is a mandatory option.
180 You can use it in the
182 test command as well to test bindings.
185 Sorted output. When listing sets, entries are listed sorted.
188 Numeric output. When listing sets, bindings, IP addresses and
189 port numbers will be printed in numeric format. By default the
190 program will try to display them as host names, network names
191 or services (whenever applicable), which can trigger
198 Suppress any output to stdout and stderr. ipset will still return
201 ipset supports the following set types:
203 The ipmap set type uses a memory range, where each bit represents
204 one IP address. An ipmap set can store up to 65536 (B-class network)
205 IP addresses. The ipmap set type is very fast and memory cheap, great
206 for use when one want to match certain IPs in a range. Using the
208 option with a CIDR netmask value between 0-32 when creating an ipmap
209 set, you will be able to store and match network addresses: i.e an
210 IP address will be in the set if the value resulted by masking the address
211 with the specified netmask can be found in the set.
213 Options to use when creating an ipmap set:
215 .BR "--from " from-IP
218 Create an ipmap set from the specified range.
220 .BR "--network " IP/mask
221 Create an ipmap set from the specified network.
223 .BR "--netmask " CIDR-netmask
226 parameter specified, network addresses will be
227 stored in the set instead of IP addresses, and the from-IP parameter
228 must be a network address.
230 The macipmap set type uses a memory range, where each 8 bytes
231 represents one IP and a MAC addresses. A macipmap set type can store
232 up to 65536 (B-class network) IP addresses with MAC.
233 When adding an entry to a macipmap set, you must specify the entry as
235 When deleting or testing macipmap entries, the
237 part is not mandatory.
239 Options to use when creating an macipmap set:
241 .BR "--from " from-IP
244 Create a macipmap set from the specified range.
246 .BR "--network " IP/mask
247 Create a macipmap set from the specified network.
252 parameter specified, IP addresses which could be stored
253 in the set but not set yet, will always match.
261 netfilter kernel modules
264 use the source MAC address from the packet to match, add or delete
265 entries from a macipmap type of set.
267 The portmap set type uses a memory range, where each bit represents
268 one port. A portmap set type can store up to 65536 ports.
269 The portmap set type is very fast and memory cheap.
271 Options to use when creating an portmap set:
273 .BR "--from " from-port
276 Create a portmap set from the specified range.
278 The iphash set type uses a hash to store IP addresses.
279 In order to avoid clashes in the hash double-hashing, and as a last
280 resort, dynamic growing of the hash performed. The iphash set type is
281 great to store random addresses. By supplyig the
283 option with a CIDR netmask value between 0-32 at creating the set,
284 you will be able to store and match network addresses instead: i.e
285 an IP address will be in the set if the value of the address
286 masked with the specified netmask can be found in the set.
288 Options to use when creating an iphash set:
290 .BR "--hashsize " hashsize
291 The initial hash size (default 1024)
293 .BR "--probes " probes
294 How many times try to resolve clashing at adding an IP to the hash
295 by double-hashing (default 8).
297 .BR "--resize " percent
298 Increase the hash size by this many percent (default 50) when adding
299 an IP to the hash could not be performed after
302 number of double-hashing.
304 .BR "--netmask " CIDR-netmask
307 parameter specified, network addresses will be
308 stored in the set instead of IP addresses.
310 Sets created by zero valued resize parameter won't be resized at all.
311 The lookup time in an iphash type of set approximately linearly grows with
315 parameter. At the same time higher
318 values result a better utilized hash while smaller values
319 produce a larger, sparse hash.
321 The nethash set type uses a hash to store different size of
322 network addresses. The
325 "address" used in the ipset commands must be in the form
328 where the CIDR block size must be in the inclusive range of 1-31.
329 In order to avoid clashes in the hash
330 double-hashing, and as a last resort, dynamic growing of the hash performed.
332 Options to use when creating an nethash set:
334 .BR "--hashsize " hashsize
335 The initial hash size (default 1024)
337 .BR "--probes " probes
338 How many times try to resolve clashing at adding an IP to the hash
339 by double-hashing (default 4).
341 .BR "--resize " percent
342 Increase the hash size by this many percent (default 50) when adding
343 an IP to the hash could not be performed after
345 An IP address will be in a nethash type of set if it is in any of the
346 netblocks added to the set and the matching always start from the smallest
347 size of netblock (most specific netmask) to the biggest ones (least
348 specific netmasks). When adding/deleting IP addresses
349 to a nethash set by the
352 netfilter kernel module, it will be added/deleted by the smallest
353 netblock size which can be found in the set.
355 The lookup time in a nethash type of set is approximately linearly
356 grows with the times of the
359 parameter and the number of different mask parameters in the hash.
360 Otherwise the same speed and memory efficiency comments applies here
361 as at the iphash type.
363 The ipporthash set type uses a hash to store IP address and port pairs.
364 In order to avoid clashes in the hash double-hashing, and as a last
365 resort, dynamic growing of the hash performed. An ipporthash set can
366 store up to 65536 (B-class network) IP addresses with all possible port
367 values. When adding, deleting and testing values in an ipporthash type of
368 set, the entries must be specified as
372 The ipporthash types of sets evaluates two src/dst parameters of the
380 Options to use when creating an ipporthash set:
382 .BR "--from " from-IP
385 Create an ipporthash set from the specified range.
387 .BR "--network " IP/mask
388 Create an ipporthash set from the specified network.
390 .BR "--hashsize " hashsize
391 The initial hash size (default 1024)
393 .BR "--probes " probes
394 How many times try to resolve clashing at adding an IP to the hash
395 by double-hashing (default 8).
397 .BR "--resize " percent
398 Increase the hash size by this many percent (default 50) when adding
399 an IP to the hash could not be performed after
402 number of double-hashing.
404 The same resizing, speed and memory efficiency comments applies here
405 as at the iphash type.
407 The iptree set type uses a tree to store IP addresses, optionally
410 Options to use when creating an iptree set:
412 .BR "--timeout " value
413 The timeout value for the entries in seconds (default 0)
415 If a set was created with a nonzero valued
417 parameter then one may add IP addresses to the set with a specific
418 timeout value using the syntax
420 .SH GENERAL RESTRICTIONS
421 Setnames starting with colon (:) cannot be defined. Zero valued set
422 entries cannot be used with hash type of sets.
424 If you want to store same size subnets from a given network
425 (say /24 blocks from a /8 network), use the ipmap set type.
426 If you want to store random same size networks (say random /24 blocks),
427 use the iphash set type. If you have got random size of netblocks,
430 Various error messages are printed to standard error. The exit code
431 is 0 for correct functioning. Errors which appear to be caused by
432 invalid or abused command line parameters cause an exit code of 2, and
433 other errors cause an exit code of 1.
435 Bugs? No, just funny features. :-)
440 Jozsef Kadlecsik wrote ipset, which is based on ippool by
441 Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
442 .\" .. and did I mention that we are incredibly cool people?
444 .\" .. witty, charming, powerful ..
445 .\" .. and most of all, modest ..