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. (The old "%" separation token instead of ":", i.e
238 IP%MAC is accepted as well.)
240 Options to use when creating an macipmap set:
242 .BR "--from " from-IP
245 Create a macipmap set from the specified range.
247 .BR "--network " IP/mask
248 Create a macipmap set from the specified network.
253 parameter specified, IP addresses which could be stored
254 in the set but not set yet, will always match.
262 netfilter kernel modules
265 use the source MAC address from the packet to match, add or delete
266 entries from a macipmap type of set.
268 The portmap set type uses a memory range, where each bit represents
269 one port. A portmap set type can store up to 65536 ports.
270 The portmap set type is very fast and memory cheap.
272 Options to use when creating an portmap set:
274 .BR "--from " from-port
277 Create a portmap set from the specified range.
279 The iphash set type uses a hash to store IP addresses.
280 In order to avoid clashes in the hash double-hashing, and as a last
281 resort, dynamic growing of the hash performed. The iphash set type is
282 great to store random addresses. By supplyig the
284 option with a CIDR netmask value between 0-32 at creating the set,
285 you will be able to store and match network addresses instead: i.e
286 an IP address will be in the set if the value of the address
287 masked with the specified netmask can be found in the set.
289 Options to use when creating an iphash set:
291 .BR "--hashsize " hashsize
292 The initial hash size (default 1024)
294 .BR "--probes " probes
295 How many times try to resolve clashing at adding an IP to the hash
296 by double-hashing (default 8).
298 .BR "--resize " percent
299 Increase the hash size by this many percent (default 50) when adding
300 an IP to the hash could not be performed after
303 number of double-hashing.
305 .BR "--netmask " CIDR-netmask
308 parameter specified, network addresses will be
309 stored in the set instead of IP addresses.
311 The iphash type of sets can store up to 65535 entries. If a set is full,
312 no new entries can be added to it.
314 Sets created by zero valued resize parameter won't be resized at all.
315 The lookup time in an iphash type of set approximately linearly grows with
319 parameter. At the same time higher
322 values result a better utilized hash while smaller values
323 produce a larger, sparse hash.
325 The nethash set type uses a hash to store different size of
326 network addresses. The
329 "address" used in the ipset commands must be in the form
332 where the CIDR block size must be in the inclusive range of 1-31.
333 In order to avoid clashes in the hash
334 double-hashing, and as a last resort, dynamic growing of the hash performed.
336 Options to use when creating an nethash set:
338 .BR "--hashsize " hashsize
339 The initial hash size (default 1024)
341 .BR "--probes " probes
342 How many times try to resolve clashing at adding an IP to the hash
343 by double-hashing (default 4).
345 .BR "--resize " percent
346 Increase the hash size by this many percent (default 50) when adding
347 an IP to the hash could not be performed after
349 The nethash type of sets can store up to 65535 entries. If a set is full,
350 no new entries can be added to it.
352 An IP address will be in a nethash type of set if it is in any of the
353 netblocks added to the set and the matching always start from the smallest
354 size of netblock (most specific netmask) to the biggest ones (least
355 specific netmasks). When adding/deleting IP addresses
356 to a nethash set by the
359 netfilter kernel module, it will be added/deleted by the smallest
360 netblock size which can be found in the set.
362 The lookup time in a nethash type of set is approximately linearly
363 grows with the times of the
366 parameter and the number of different mask parameters in the hash.
367 Otherwise the same speed and memory efficiency comments applies here
368 as at the iphash type.
370 The ipporthash set type uses a hash to store IP address and port pairs.
371 In order to avoid clashes in the hash double-hashing, and as a last
372 resort, dynamic growing of the hash performed. An ipporthash set can
373 store up to 65536 (B-class network) IP addresses with all possible port
374 values. When adding, deleting and testing values in an ipporthash type of
375 set, the entries must be specified as
378 (Old "IP%port" format accepted as well.)
380 The ipporthash types of sets evaluates two src/dst parameters of the
388 Options to use when creating an ipporthash set:
390 .BR "--from " from-IP
393 Create an ipporthash set from the specified range.
395 .BR "--network " IP/mask
396 Create an ipporthash set from the specified network.
398 .BR "--hashsize " hashsize
399 The initial hash size (default 1024)
401 .BR "--probes " probes
402 How many times try to resolve clashing at adding an IP to the hash
403 by double-hashing (default 8).
405 .BR "--resize " percent
406 Increase the hash size by this many percent (default 50) when adding
407 an IP to the hash could not be performed after
410 number of double-hashing.
412 The same resizing, speed and memory efficiency comments applies here
413 as at the iphash type.
415 The iptree set type uses a tree to store IP addresses, optionally
418 Options to use when creating an iptree set:
420 .BR "--timeout " value
421 The timeout value for the entries in seconds (default 0)
423 If a set was created with a nonzero valued
425 parameter then one may add IP addresses to the set with a specific
426 timeout value using the syntax
428 Similarly to the hash types, the iptree type of sets can store up to 65535
431 The iptreemap set type uses a tree to store IP addresses or networks,
432 where the last octet of an IP address are stored in a bitmap.
433 As input entry, you can add IP addresses, CIDR blocks or network ranges
434 to the set. Network ranges can be specified in the format
437 Options to use when creating an iptreemap set:
440 How often the garbage collection should be called, in seconds (default 300)
441 .SH GENERAL RESTRICTIONS
442 Setnames starting with colon (:) cannot be defined. Zero valued set
443 entries cannot be used with hash type of sets.
445 If you want to store same size subnets from a given network
446 (say /24 blocks from a /8 network), use the ipmap set type.
447 If you want to store random same size networks (say random /24 blocks),
448 use the iphash set type. If you have got random size of netblocks,
451 Various error messages are printed to standard error. The exit code
452 is 0 for correct functioning. Errors which appear to be caused by
453 invalid or abused command line parameters cause an exit code of 2, and
454 other errors cause an exit code of 1.
456 Bugs? No, just funny features. :-)
461 Jozsef Kadlecsik wrote ipset, which is based on ippool by
462 Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
464 Sven Wegener wrote the iptreemap type.
465 .\" .. and did I mention that we are incredibly cool people?
467 .\" .. witty, charming, powerful ..
468 .\" .. and most of all, modest ..