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 \(em administration tool for IP sets
24 \fBipset \-N\fP \fIset\fP \fItype-specification\fP [\fIoptions\fP...]
26 \fBipset\fP {\fB\-F\fP|\fB\-H\fP|\fB\-L\fP|\fB\-S\fP|\fB\-X\fP} [\fIset\fP]
29 \fBipset\fP {\fB\-E\fP|\fB\-W\fP} \fIfrom-set\fP \fIto-set\fP
31 \fBipset\fP {\fB\-A\fP|\fB\-D\fP|\fB\-T\fP} \fIset\fP \fIentry\fP
35 \fBipset\fP {\fB-V\fP|\fB\-v\fP}
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 Iptables matches and targets referring to sets creates references, which
44 protects the given sets in the kernel. A set cannot be removed (destroyed)
45 while there is a single reference pointing to it.
47 The options that are recognized by
49 can be divided into several different groups.
51 These options specify the specific action to perform. Only one of them
52 can be specified on the command line unless otherwise specified
53 below. For all the long versions of the command and option names, you
54 need to use only enough letters to ensure that
56 can differentiate it from all other options.
58 \fB\-N\fP, \fB\-\-create\fP \fIsetname\fP \fItype\fP \fItype-specific-options\fP
59 Create a set identified with setname and specified type.
60 Type-specific options must be supplied.
62 \fB\-X\fP, \fB\-\-destroy\fP [\fIsetname\fP]
63 Destroy the specified set or all the sets if none is given.
65 If the set has got references, nothing is done.
67 \fB\-F\fP, \fB\-\-flush\fP [\fIsetname\fP]
68 Delete all entries from the specified set or flush
69 all sets if none is given.
71 \fB\-E\fP, \fB\-\-rename\fP \fIfrom-setname\fP \fIto-setname\fP
72 Rename a set. Set identified by to-setname must not exist.
74 \fB\-W\fP, \fB\-\-swap\fP \fIfrom-setname\fP \fIto-setname\fP
75 Swap the content of two sets, or in another words,
76 exchange the name of two sets. The referred sets must exist and
77 identical type of sets can be swapped only.
79 \fB\-L\fP, \fB\-\-list\fP [\fIsetname\fP]
80 List the entries for the specified set, or for
81 all sets if none is given. The
82 \fB\-r\fP/\fB\-\-resolve\fP
83 option can be used to force name lookups (which may be slow). When the
84 \fB\-s\fP/\fB\-\-sorted\fP
85 option is given, the entries are listed sorted (if the given set
86 type supports the operation).
88 \fB\-S\fP, \fB\-\-save\fP [\fIsetname\fP]
89 Save the given set, or all sets if none is given
90 to stdout in a format that \fB\-\-restore\fP can read.
92 \fB\-R\fP, \fB\-\-restore\fP
93 Restore a saved session generated by \fB\-\-save\fP. The saved session
94 can be fed from stdin.
96 When generating a session file please note that the supported commands
97 (create set and add element) must appear in a strict order: first create
98 the set, then add all elements. Then create the next set, add all its elements
99 and so on. Also, it is a restore operation, so the sets being restored must
102 \fB\-A\fP, \fB\-\-add\fP \fIsetname\fP \fIentry\fP
103 Add an entry to a set.
105 \fB\-D\fP, \fB\-\-del\fP \fIsetname\fP \fIentry\fP
106 Delete an entry from a set.
108 \fB-T\fP, \fB\-\-test\fP \fIsetname\fP \fIentry\fP
109 Test wether an entry is in a set or not. Exit status number is zero
110 if the tested entry is in the set and nonzero if it is missing from
113 \fB\-H\fP, \fB\-\-help\fP [\fIsettype\fP]
114 Print help and settype specific help if settype specified.
116 \fB\-V\fP, \fB\-v\fP, \fB\-\-version\fP
117 Print program version and protocol version.
120 The following additional options can be specified:
122 \fB\-r\fP, \fB\-\-resolve\fP
123 When listing sets, enforce name lookup. The
124 program will try to display the IP entries resolved to
125 host names or services (whenever applicable), which can trigger
131 \fB\-s\fP, \fB\-\-sorted\fP
132 Sorted output. When listing sets, entries are listed sorted.
134 \fB\-n\fP, \fB\-\-numeric\fP
135 Numeric output. When listing sets, IP addresses and
136 port numbers will be printed in numeric format. This is the default.
138 \fB\-q\fP, \fB\-\-quiet\fP
139 Suppress any output to stdout and stderr. ipset will still return
142 ipset supports the following set types:
144 The ipmap set type uses a memory range, where each bit represents
145 one IP address. An ipmap set can store up to 65536 (B-class network)
146 IP addresses. The ipmap set type is very fast and memory cheap, great
147 for use when one want to match certain IPs in a range. If the optional
149 parameter is specified with a CIDR netmask value between 1-31 then
150 network addresses are stored in the given set: i.e an
151 IP address will be in the set if the network address, which is resulted
152 by masking the address with the specified netmask, can be found in the set.
154 Options to use when creating an ipmap set:
156 \fB\-\-from\fP \fIfrom-addr\fP
158 \fB\-\-to\fP \fIto-addr\fP
159 Create an ipmap set from the specified address range.
161 \fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
162 Create an ipmap set from the specified network.
164 \fB\-\-netmask\fP \fIprefixlen\fP
167 parameter specified, network addresses will be
168 stored in the set instead of IP addresses, and the \fIfrom-addr\fP parameter
169 must be a network address. The \fIprefixlen\fP value must be between 1-31.
173 ipset \-N test ipmap \-\-network 192.168.0.0/16
175 The macipmap set type uses a memory range, where each 8 bytes
176 represents one IP and a MAC addresses. A macipmap set type can store
177 up to 65536 (B-class network) IP addresses with MAC.
178 When adding an entry to a macipmap set, you must specify the entry as
179 "\fIaddress\fP\fB,\fP\fImac\fP".
180 When deleting or testing macipmap entries, the
182 part is not mandatory.
184 Options to use when creating an macipmap set:
186 \fB\-\-from\fP \fIfrom-addr\fP
188 \fB\-\-to\fP \fIto-addr\fP
189 Create a macipmap set from the specified address range.
191 \fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
192 Create a macipmap set from the specified network.
197 parameter specified, IP addresses which could be stored
198 in the set but not set yet, will always match.
204 netfilter kernel modules
207 use the source MAC address from the packet to match, add or delete
208 entries from a macipmap type of set.
210 The portmap set type uses a memory range, where each bit represents
211 one port. A portmap set type can store up to 65536 ports.
212 The portmap set type is very fast and memory cheap.
214 Options to use when creating an portmap set:
216 \fB\-\-from\fP \fIfrom-port\fP
218 \fB\-\-to\fP \fIto-port\fP
219 Create a portmap set from the specified port range.
221 The iphash set type uses a hash to store IP addresses.
222 In order to avoid clashes in the hash double-hashing, and as a last
223 resort, dynamic growing of the hash performed. The iphash set type is
224 great to store random addresses. If the optional
226 parameter is specified with a CIDR prefix length value between 1-31 then
227 network addresses are stored in the given set: i.e an
228 IP address will be in the set if the network address, which is resulted
229 by masking the address with the specified netmask, can be found in the set.
231 Options to use when creating an iphash set:
233 \fB\-\-hashsize\fP \fIhashsize\fP
234 The initial hash size (default 1024)
236 \fB\-\-probes\fP \fIprobes\fP
237 How many times try to resolve clashing at adding an IP to the hash
238 by double-hashing (default 8).
240 \fB\-\-resize\fP \fIpercent\fP
241 Increase the hash size by this many percent (default 50) when adding
242 an IP to the hash could not be performed after
244 number of double-hashing.
246 \fB\-\-netmask\fP \fIprefixlen\fP
249 parameter specified, network addresses will be
250 stored in the set instead of IP addresses. The \fIprefixlen\fP value must
253 The iphash type of sets can store up to 65536 entries. If a set is full,
254 no new entries can be added to it.
256 Sets created by zero valued resize parameter won't be resized at all.
257 The lookup time in an iphash type of set grows approximately linearly with
260 parameter. In general higher
262 value results better utilized hash while smaller value
263 produces larger, sparser hash.
267 ipset \-N test iphash \-\-probes 2
269 The nethash set type uses a hash to store different size of
270 network addresses. The
273 used in the ipset commands must be in the form
274 "\fIaddress\fP\fB/\fP\fIprefixlen\fP"
275 where prefixlen must be in the inclusive range of 1-31.
276 In order to avoid clashes in the hash
277 double-hashing, and as a last resort, dynamic growing of the hash performed.
279 Options to use when creating an nethash set:
281 \fB\-\-hashsize\fP \fIhashsize\fP
282 The initial hash size (default 1024)
284 \fB\-\-probes\fP \fIprobes\fP
285 How many times try to resolve clashing at adding an IP to the hash
286 by double-hashing (default 4).
288 \fB\-\-resize\fP \fIpercent\fP
289 Increase the hash size by this many percent (default 50) when adding
290 an IP to the hash could not be performed after
292 The nethash type of sets can store up to 65536 entries. If a set is full,
293 no new entries can be added to it.
295 An IP address will be in a nethash type of set if it belongs to any of the
296 netblocks added to the set. The matching always start from the smallest
297 size of netblock (most specific netmask) to the largest ones (least
298 specific netmasks). When adding/deleting IP addresses
299 to a nethash set by the
301 netfilter kernel module, it will be added/deleted by the smallest
302 netblock size which can be found in the set, or by /31 if the set is empty.
304 The lookup time in a nethash type of set grows approximately linearly
305 with the times of the
307 parameter and the number of different mask parameters in the hash.
308 Otherwise the same speed and memory efficiency comments applies here
309 as at the iphash type.
311 The ipporthash set type uses a hash to store IP address and port pairs.
312 In order to avoid clashes in the hash double-hashing, and as a last
313 resort, dynamic growing of the hash performed. An ipporthash set can
314 store up to 65536 (B-class network) IP addresses with all possible port
315 values. When adding, deleting and testing values in an ipporthash type of
316 set, the entries must be specified as
317 "\fIaddress\fP\fB,\fP\fIport\fP".
319 The ipporthash types of sets evaluates two src/dst parameters of the
325 Options to use when creating an ipporthash set:
327 \fB\-\-from\fP \fIfrom-addr\fP
329 \fB\-\-to\fP \fIto-addr\fP
330 Create an ipporthash set from the specified address range.
332 \fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
333 Create an ipporthash set from the specified network.
335 \fB\-\-hashsize\fP \fIhashsize\fP
336 The initial hash size (default 1024)
338 \fB\-\-probes\fP \fIprobes\fP
339 How many times try to resolve clashing at adding an IP to the hash
340 by double-hashing (default 8).
342 \fB\-\-resize\fP \fIpercent\fP
343 Increase the hash size by this many percent (default 50) when adding
344 an IP to the hash could not be performed after
346 number of double-hashing.
348 The same resizing, speed and memory efficiency comments applies here
349 as at the iphash type.
351 The ipportiphash set type uses a hash to store IP address,port and IP
352 address triples. The first IP address must come form a maximum /16
353 sized network or range while the port number and the second IP address
354 parameters are arbitrary. When adding, deleting and testing values in an
355 ipportiphash type of set, the entries must be specified as
356 "\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP".
358 The ipportiphash types of sets evaluates three src/dst parameters of the
364 Options to use when creating an ipportiphash set:
366 \fB\-\-from\fP \fIfrom-addr\fP
368 \fB\-\-to\fP \fIto-addr\fP
369 Create an ipportiphash set from the specified address range.
371 \fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
372 Create an ipportiphash set from the specified network.
374 \fB\-\-hashsize\fP \fIhashsize\fP
375 The initial hash size (default 1024)
377 \fB\-\-probes\fP \fIprobes\fP
378 How many times try to resolve clashing at adding an IP to the hash
379 by double-hashing (default 8).
381 \fB\-\-resize\fP \fIpercent\fP
382 Increase the hash size by this many percent (default 50) when adding
383 an IP to the hash could not be performed after
385 number of double-hashing.
387 The same resizing, speed and memory efficiency comments applies here
388 as at the iphash type.
390 The ipportnethash set type uses a hash to store IP address, port, and
391 network address triples. The IP address must come form a maximum /16
392 sized network or range while the port number and the network address
393 parameters are arbitrary, but the size of the network address must be
394 between /1-/31. When adding, deleting
395 and testing values in an ipportnethash type of set, the entries must be
397 "\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP\fB/\fP\fIprefixlen\fP".
399 The ipportnethash types of sets evaluates three src/dst parameters of the
405 Options to use when creating an ipportnethash set:
407 \fB\-\-from\fP \fIfrom-address\fP
409 \fB\-\-to\fP \fIto-address\fP
410 Create an ipporthash set from the specified range.
412 \fB\-\-network\fP \fIaddress\fP\fB/\fP\fImask\fP
413 Create an ipporthash set from the specified network.
415 \fB\-\-hashsize\fP \fIhashsize\fP
416 The initial hash size (default 1024)
418 \fB\-\-probes\fP \fIprobes\fP
419 How many times try to resolve clashing at adding an IP to the hash
420 by double-hashing (default 8).
422 \fB\-\-resize\fP \fIpercent\fP
423 Increase the hash size by this many percent (default 50) when adding
424 an IP to the hash could not be performed after
426 number of double-hashing.
428 The same resizing, speed and memory efficiency comments applies here
429 as at the iphash type.
431 The iptree set type uses a tree to store IP addresses, optionally
434 Options to use when creating an iptree set:
436 \fB\-\-timeout\fP \fIvalue\fP
437 The timeout value for the entries in seconds (default 0)
439 If a set was created with a nonzero valued
441 parameter then one may add IP addresses to the set with a specific
442 timeout value using the syntax
443 "\fIaddress\fP\fB,\fP\fItimeout-value\fP".
444 Similarly to the hash types, the iptree type of sets can store up to 65536
447 The iptreemap set type uses a tree to store IP addresses or networks,
448 where the last octet of an IP address are stored in a bitmap.
449 As input entry, you can add IP addresses, CIDR blocks or network ranges
450 to the set. Network ranges can be specified in the format
451 "\fIaddress1\fP\fB-\fP\fIaddress2\fP".
453 Options to use when creating an iptreemap set:
455 \fB\-\-gc\fP \fIvalue\fP
456 How often the garbage collection should be called, in seconds (default 300)
458 The setlist type uses a simple list in which you can store sets. By the
460 command you can add, delete and test sets in a setlist type of set.
461 You can specify the sets as
462 "\fIsetname\fP[\fB,\fP{\fBafter\fP|\fBbefore\fP},\fIsetname\fP]".
463 By default new sets are added after (appended to) the existing
464 elements. Setlist type of sets cannot be added to a setlist type of set.
466 Options to use when creating a setlist type of set:
468 \fB\-\-size\fP \fIsize\fP
469 Create a setlist type of set with the given size (default 8).
477 you can test, add or delete entries in the sets. The match
478 will try to find a matching IP address/port in the sets and
479 the target will try to add the IP address/port to the first set
480 to which it can be added. The number of src,dst options of
481 the match and target are important: sets which eats more src,dst
482 parameters than specified are skipped, while sets with equal
483 or less parameters are checked, elements added. For example
490 are setlist type of sets then in the command
492 iptables \-m set \-\-match\-set a src,dst \-j SET \-\-add-set b src,dst
494 the match and target will skip any set in
499 data triples, but will check all sets with single or double
502 set and add src to the first single or src,dst to the first double
506 You can imagine a setlist type of set as an ordered union of
508 .SH GENERAL RESTRICTIONS
509 Setnames starting with colon (:) cannot be defined. Zero valued set
510 entries cannot be used with hash type of sets.
512 If you want to store same size subnets from a given network
513 (say /24 blocks from a /8 network), use the ipmap set type.
514 If you want to store random same size networks (say random /24 blocks),
515 use the iphash set type. If you have got random size of netblocks,
518 Old separator tokens (':' and '%") are still accepted.
520 Binding support is removed.
522 Various error messages are printed to standard error. The exit code
523 is 0 for correct functioning. Errors which appear to be caused by
524 invalid or abused command line parameters cause an exit code of 2, and
525 other errors cause an exit code of 1.
527 Bugs? No, just funny features. :-)
532 Jozsef Kadlecsik wrote ipset, which is based on ippool by
533 Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
535 Sven Wegener wrote the iptreemap type.
537 .BR "I stand on the shoulders of giants."