1IPSET(8) IPSET(8)
2
6 ipset — administration tool for IP sets
7
9 ipset [ OPTIONS ] COMMAND [ COMMAND-OPTIONS ]
10 COMMANDS := { create | add | del | test | destroy | list | save | re‐
12 store | flush | rename | swap | help | version | - }
13 OPTIONS := { -exist | -output { plain | save | xml } | -quiet | -re‐
15 solve | -sorted | -name | -terse | -file filename }
16 ipset create SETNAME TYPENAME [ CREATE-OPTIONS ]
18 ipset add SETNAME ADD-ENTRY [ ADD-OPTIONS ]
20 ipset del SETNAME DEL-ENTRY [ DEL-OPTIONS ]
22 ipset test SETNAME TEST-ENTRY [ TEST-OPTIONS ]
24 ipset destroy [ SETNAME ]
26 ipset list [ SETNAME ]
28 ipset save [ SETNAME ]
30 ipset restore
32 ipset flush [ SETNAME ]
34 ipset rename SETNAME-FROM SETNAME-TO
36 ipset swap SETNAME-FROM SETNAME-TO
38 ipset help [ TYPENAME ]
40 ipset version
42 ipset -
44
46 ipset is used to set up, maintain and inspect so called IP sets in the
47 Linux kernel. Depending on the type of the set, an IP set may store
48 IP(v4/v6) addresses, (TCP/UDP) port numbers, IP and MAC address pairs,
49 IP address and port number pairs, etc. See the set type definitions be‐
50 low.
51 Iptables matches and targets referring to sets create references, which
53 protect the given sets in the kernel. A set cannot be destroyed while
54 there is a single reference pointing to it.
55
57 The options that are recognized by ipset can be divided into several
58 different groups.
59 COMMANDS
61 These options specify the desired action to perform. Only one of them
62 can be specified on the command line unless otherwise specified below.
63 For all the long versions of the command names, you need to use only
64 enough letters to ensure that ipset can differentiate it from all other
65 commands. The ipset parser follows the order here when looking for the
66 shortest match in the long command names.
67 n, create SETNAME TYPENAME [ CREATE-OPTIONS ]
69 Create a set identified with setname and specified type. The
70 type may require type specific options. If the -exist option is
71 specified, ipset ignores the error otherwise raised when the
72 same set (setname and create parameters are identical) already
73 exists.
74 add SETNAME ADD-ENTRY [ ADD-OPTIONS ]
76 Add a given entry to the set. If the -exist option is specified,
77 ipset ignores if the entry already added to the set.
78 del SETNAME DEL-ENTRY [ DEL-OPTIONS ]
80 Delete an entry from a set. If the -exist option is specified
81 and the entry is not in the set (maybe already expired), then
82 the command is ignored.
83 test SETNAME TEST-ENTRY [ TEST-OPTIONS ]
85 Test whether an entry is in a set or not. Exit status number is
86 zero if the tested entry is in the set and nonzero if it is
87 missing from the set.
88 x, destroy [ SETNAME ]
90 Destroy the specified set or all the sets if none is given.
91 If the set has got reference(s), nothing is done and no set de‐
93 stroyed.
94 list [ SETNAME ] [ OPTIONS ]
96 List the header data and the entries for the specified set, or
97 for all sets if none is given. The -resolve option can be used
98 to force name lookups (which may be slow). When the -sorted op‐
99 tion is given, the entries are listed/saved sorted (which may be
100 slow). The option -output can be used to control the format of
101 the listing: plain, save or xml. (The default is plain.) If
102 the option -name is specified, just the names of the existing
103 sets are listed. If the option -terse is specified, just the set
104 names and headers are listed. The output is printed to stdout,
105 the option -file can be used to specify a filename instead of
106 stdout.
107 save [ SETNAME ]
109 Save the given set, or all sets if none is given to stdout in a
110 format that restore can read. The option -file can be used to
111 specify a filename instead of stdout.
112 restore
114 Restore a saved session generated by save. The saved session
115 can be fed from stdin or the option -file can be used to specify
116 a filename instead of stdin.
117 Please note, existing sets and elements are not erased by re‐
119 store unless specified so in the restore file. All commands are
120 allowed in restore mode except list, help, version, interactive
121 mode and restore itself.
122 flush [ SETNAME ]
124 Flush all entries from the specified set or flush all sets if
125 none is given.
126 e, rename SETNAME-FROM SETNAME-TO
128 Rename a set. Set identified by SETNAME-TO must not exist.
129 w, swap SETNAME-FROM SETNAME-TO
131 Swap the content of two sets, or in another words, exchange the
132 name of two sets. The referred sets must exist and compatible
133 type of sets can be swapped only.
134 help [ TYPENAME ]
136 Print help and set type specific help if TYPENAME is specified.
137 version
139 Print program version.
140 - If a dash is specified as command, then ipset enters a simple
142 interactive mode and the commands are read from the standard in‐
143 put. The interactive mode can be finished by entering the
144 pseudo-command quit.
145 OTHER OPTIONS
147 The following additional options can be specified. The long option
148 names cannot be abbreviated.
149 -!, -exist
151 Ignore errors when exactly the same set is to be created or al‐
152 ready added entry is added or missing entry is deleted.
153 -o, -output { plain | save | xml }
155 Select the output format to the list command.
156 -q, -quiet
158 Suppress any output to stdout and stderr. ipset will still exit
159 with error if it cannot continue.
160 -r, -resolve
162 When listing sets, enforce name lookup. The program will try to
163 display the IP entries resolved to host names which requires
164 slow DNS lookups.
165 -s, -sorted
167 Sorted output. When listing or saving sets, the entries are
168 listed sorted.
169 -n, -name
171 List just the names of the existing sets, i.e. suppress listing
172 of set headers and members.
173 -t, -terse
175 List the set names and headers, i.e. suppress listing of set
176 members.
177 -f, -file filename
179 Specify a filename to print into instead of stdout (list or save
180 commands) or read from instead of stdin (restore command).
181
183 A set type comprises of the storage method by which the data is stored
184 and the data type(s) which are stored in the set. Therefore the TYPE‐
185 NAME parameter of the create command follows the syntax
186 TYPENAME := method:datatype[,datatype[,datatype]]
188 where the current list of the methods are bitmap, hash, and list and
190 the possible data types are ip, net, mac, port and iface. The dimen‐
191 sion of a set is equal to the number of data types in its type name.
192 When adding, deleting or testing entries in a set, the same comma sepa‐
194 rated data syntax must be used for the entry parameter of the commands,
195 i.e
196 ipset add foo ipaddr,portnum,ipaddr
198 If host names or service names with dash in the name are used instead
200 of IP addresses or service numbers, then the host name or service name
201 must be enclosed in square brackets. Example:
202 ipset add foo [test-hostname],[ftp-data]
204 In the case of host names the DNS resolver is called internally by
206 ipset but if it returns multiple IP addresses, only the first one is
207 used.
208 The bitmap and list types use a fixed sized storage. The hash types use
210 a hash to store the elements. In order to avoid clashes in the hash, a
211 limited number of chaining, and if that is exhausted, the doubling of
212 the hash size is performed when adding entries by the ipset command.
213 When entries added by the SET target of iptables/ip6tables, then the
214 hash size is fixed and the set won't be duplicated, even if the new en‐
215 try cannot be added to the set.
216
218 timeout
219 All set types supports the optional timeout parameter when creating a
220 set and adding entries. The value of the timeout parameter for the cre‐
221 ate command means the default timeout value (in seconds) for new en‐
222 tries. If a set is created with timeout support, then the same timeout
223 option can be used to specify non-default timeout values when adding
224 entries. Zero timeout value means the entry is added permanent to the
225 set. The timeout value of already added elements can be changed by re-
226 adding the element using the -exist option. The largest possible time‐
227 out value is 2147483 (in seconds). Example:
228 ipset create test hash:ip timeout 300
230 ipset add test 192.168.0.1 timeout 60
232 ipset -exist add test 192.168.0.1 timeout 600
234 When listing the set, the number of entries printed in the header might
236 be larger than the listed number of entries for sets with the timeout
237 extensions: the number of entries in the set is updated when elements
238 added/deleted to the set and periodically when the garbage collector
239 evicts the timed out entries.
240 counters, packets, bytes
242 All set types support the optional counters option when creating a set.
243 If the option is specified then the set is created with packet and byte
244 counters per element support. The packet and byte counters are initial‐
245 ized to zero when the elements are (re-)added to the set, unless the
246 packet and byte counter values are explicitly specified by the packets
247 and bytes options. An example when an element is added to a set with
248 non-zero counter values:
249 ipset create foo hash:ip counters
251 ipset add foo 192.168.1.1 packets 42 bytes 1024
253 comment
255 All set types support the optional comment extension. Enabling this
256 extension on an ipset enables you to annotate an ipset entry with an
257 arbitrary string. This string is completely ignored by both the kernel
258 and ipset itself and is purely for providing a convenient means to doc‐
259 ument the reason for an entry's existence. Comments must not contain
260 any quotation marks and the usual escape character (\) has no meaning.
261 For example, the following shell command is illegal:
262 ipset add foo 1.1.1.1 comment "this comment is \"bad\""
264 In the above, your shell will of course escape the quotation marks and
266 ipset will see the quote marks in the argument for the comment, which
267 will result in a parse error. If you are writing your own system, you
268 should avoid creating comments containing a quotation mark if you do
269 not want to break "ipset save" and "ipset restore", nonetheless, the
270 kernel will not stop you from doing so. The following is perfectly ac‐
271 ceptable:
272 ipset create foo hash:ip comment
274 ipset add foo 192.168.1.1/24 comment "allow access to SMB share
276 on \\\\fileserv\\"
277 the above would appear as: "allow access to SMB share on \\file‐
279 serv\"
280 skbinfo, skbmark, skbprio, skbqueue
282 All set types support the optional skbinfo extension. This extension
283 allows you to store the metainfo (firewall mark, tc class and hardware
284 queue) with every entry and map it to packets by usage of SET netfilter
285 target with --map-set option. skbmark option format: MARK or
286 MARK/MASK, where MARK and MASK are 32bit hex numbers with 0x prefix. If
287 only mark is specified mask 0xffffffff are used. skbprio option has tc
288 class format: MAJOR:MINOR, where major and minor numbers are hex with‐
289 out 0x prefix. skbqueue option is just decimal number.
290 ipset create foo hash:ip skbinfo
292 ipset add foo 192.168.0.1 skbmark 0x1111/0xff00ffff skbprio 1:10
294 skbqueue 10
295 hashsize
297 This parameter is valid for the create command of all hash type sets.
298 It defines the initial hash size for the set, default is 1024. The hash
299 size must be a power of two, the kernel automatically rounds up non
300 power of two hash sizes to the first correct value. Example:
301 ipset create test hash:ip hashsize 1536
303 maxelem
305 This parameter is valid for the create command of all hash type sets.
306 It defines the maximal number of elements which can be stored in the
307 set, default 65536. Example:
308 ipset create test hash:ip maxelem 2048
310 bucketsize
312 This parameter is valid for the create command of all hash type sets.
313 It specifies the maximal number of elements which can be stored in a
314 hash bucket. Possible values are any even number between 2-14 and the
315 default is 14. Setting the value lower forces ipset to create larger
316 hashes which consumes more memory but gives more speed at matching in
317 the set. Example:
318 ipset create test hash:ip bucketsize 2
320 family { inet | inet6 }
322 This parameter is valid for the create command of all hash type sets
323 except for hash:mac. It defines the protocol family of the IP ad‐
324 dresses to be stored in the set. The default is inet, i.e IPv4. For
325 the inet family one can add or delete multiple entries by specifying a
326 range or a network of IPv4 addresses in the IP address part of the en‐
327 try:
328 ipaddr := { ip | fromaddr-toaddr | ip/cidr }
330 netaddr := { fromaddr-toaddr | ip/cidr }
332 Example:
334 ipset create test hash:ip family inet6
336 nomatch
338 The hash set types which can store net type of data (i.e. hash:*net*)
339 support the optional nomatch option when adding entries. When matching
340 elements in the set, entries marked as nomatch are skipped as if those
341 were not added to the set, which makes possible to build up sets with
342 exceptions. See the example at hash type hash:net below.
343 When elements are tested by ipset, the nomatch flags are taken into ac‐
345 count. If one wants to test the existence of an element marked with no‐
346 match in a set, then the flag must be specified too.
347 forceadd
349 All hash set types support the optional forceadd parameter when creat‐
350 ing a set. When sets created with this option become full the next ad‐
351 dition to the set may succeed and evict a random entry from the set.
352 ipset create foo hash:ip forceadd
354 wildcard
356 This flag is valid when adding elements to a hash:net,iface set. If the
357 flag is set, then prefix matching is used when comparing with this ele‐
358 ment. For example, an element containing the interface name "eth" will
359 match any name with that prefix.
360
362 bitmap:ip
363 The bitmap:ip set type uses a memory range to store either IPv4 host
364 (default) or IPv4 network addresses. A bitmap:ip type of set can store
365 up to 65536 entries.
366 CREATE-OPTIONS := range fromip-toip|ip/cidr [ netmask cidr ] [ timeout
368 value ] [ counters ] [ comment ] [ skbinfo ]
369 ADD-ENTRY := { ip | fromip-toip | ip/cidr }
371 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
373 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
374 DEL-ENTRY := { ip | fromip-toip | ip/cidr }
376 TEST-ENTRY := ip
378 Mandatory create options:
380 range fromip-toip|ip/cidr
382 Create the set from the specified inclusive address range ex‐
383 pressed in an IPv4 address range or network. The size of the
384 range (in entries) cannot exceed the limit of maximum 65536 ele‐
385 ments.
386 Optional create options:
388 netmask cidr
390 When the optional netmask parameter specified, network addresses
391 will be stored in the set instead of IP host addresses. The cidr
392 prefix value must be between 1-32. An IP address will be in the
393 set if the network address, which is resulted by masking the ad‐
394 dress with the specified netmask, can be found in the set.
395 The bitmap:ip type supports adding or deleting multiple entries in one
397 command.
398 Examples:
400 ipset create foo bitmap:ip range 192.168.0.0/16
402 ipset add foo 192.168.1/24
404 ipset test foo 192.168.1.1
406 bitmap:ip,mac
408 The bitmap:ip,mac set type uses a memory range to store IPv4 and a MAC
409 address pairs. A bitmap:ip,mac type of set can store up to 65536 en‐
410 tries.
411 CREATE-OPTIONS := range fromip-toip|ip/cidr [ timeout value ] [ coun‐
413 ters ] [ comment ] [ skbinfo ]
414 ADD-ENTRY := ip[,macaddr]
416 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
418 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
419 DEL-ENTRY := ip[,macaddr]
421 TEST-ENTRY := ip[,macaddr]
423 Mandatory options to use when creating a bitmap:ip,mac type of set:
425 range fromip-toip|ip/cidr
427 Create the set from the specified inclusive address range ex‐
428 pressed in an IPv4 address range or network. The size of the
429 range cannot exceed the limit of maximum 65536 entries.
430 The bitmap:ip,mac type is exceptional in the sense that the MAC part
432 can be left out when adding/deleting/testing entries in the set. If we
433 add an entry without the MAC address specified, then when the first
434 time the entry is matched by the kernel, it will automatically fill out
435 the missing MAC address with the MAC address from the packet. The
436 source MAC address is used if the entry matched due to a src parameter
437 of the set match, and the destination MAC address is used if available
438 and the entry matched due to a dst parameter. If the entry was speci‐
439 fied with a timeout value, the timer starts off when the IP and MAC ad‐
440 dress pair is complete.
441 The bitmap:ip,mac type of sets require two src/dst parameters of the
443 set match and SET target netfilter kernel modules. For matches on des‐
444 tination MAC addresses, see COMMENTS below.
445 Examples:
447 ipset create foo bitmap:ip,mac range 192.168.0.0/16
449 ipset add foo 192.168.1.1,12:34:56:78:9A:BC
451 ipset test foo 192.168.1.1
453 bitmap:port
455 The bitmap:port set type uses a memory range to store port numbers and
456 such a set can store up to 65536 ports.
457 CREATE-OPTIONS := range fromport-toport [ timeout value ] [ counters ]
459 [ comment ] [ skbinfo ]
460 ADD-ENTRY := { [proto:]port | [proto:]fromport-toport }
462 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
464 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
465 DEL-ENTRY := { [proto:]port | [proto:]fromport-toport }
467 TEST-ENTRY := [proto:]port
469 Mandatory options to use when creating a bitmap:port type of set:
471 range [proto:]fromport-toport
473 Create the set from the specified inclusive port range.
474 The set match and SET target netfilter kernel modules interpret the
476 stored numbers as TCP or UDP port numbers.
477 proto only needs to be specified if a service name is used and that
479 name does not exist as a TCP service. The protocol is never stored in
480 the set, just the port number of the service.
481 Examples:
483 ipset create foo bitmap:port range 0-1024
485 ipset add foo 80
487 ipset test foo 80
489 ipset del foo udp:[macon-udp]-[tn-tl-w2]
491 hash:ip
493 The hash:ip set type uses a hash to store IP host addresses (default)
494 or network addresses. Zero valued IP address cannot be stored in a
495 hash:ip type of set.
496 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
498 elem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [
499 timeout value ] [ counters ] [ comment ] [ skbinfo ]
500 ADD-ENTRY := ipaddr
502 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
504 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
505 DEL-ENTRY := ipaddr
507 TEST-ENTRY := ipaddr
509 Optional create options:
511 netmask cidr
513 When the optional netmask parameter specified, network addresses
514 will be stored in the set instead of IP host addresses. The cidr
515 prefix value must be between 1-32 for IPv4 and between 1-128 for
516 IPv6. An IP address will be in the set if the network address,
517 which is resulted by masking the address with the netmask, can
518 be found in the set. Examples:
519 ipset create foo hash:ip netmask 30
521 ipset add foo 192.168.1.0/24
523 ipset test foo 192.168.1.2
525 bitmask mask
527 This works similar to netmask but it will accept any valid
528 IPv4/v6 address. It does not have to be a valid netmask.
529 hash:mac
531 The hash:mac set type uses a hash to store MAC addresses. Zero valued
532 MAC addresses cannot be stored in a hash:mac type of set. For matches
533 on destination MAC addresses, see COMMENTS below.
534 CREATE-OPTIONS := [ hashsize value ] [ maxelem value ] [ bucketsize
536 value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
537 ADD-ENTRY := macaddr
539 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
541 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
542 DEL-ENTRY := macaddr
544 TEST-ENTRY := macaddr
546 Examples:
548 ipset create foo hash:mac
550 ipset add foo 01:02:03:04:05:06
552 ipset test foo 01:02:03:04:05:06
554 hash:ip,mac
557 The hash:ip,mac set type uses a hash to store IP and a MAC address
558 pairs. Zero valued MAC addresses cannot be stored in a hash:ip,mac type
559 of set. For matches on destination MAC addresses, see COMMENTS below.
560 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
562 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
563 ment ] [ skbinfo ]
564 ADD-ENTRY := ipaddr,macaddr
566 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
568 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
569 DEL-ENTRY := ipaddr,macaddr
571 TEST-ENTRY := ipaddr,macaddr
573 Examples:
575 ipset create foo hash:ip,mac
577 ipset add foo 1.1.1.1,01:02:03:04:05:06
579 ipset test foo 1.1.1.1,01:02:03:04:05:06
581 hash:net
584 The hash:net set type uses a hash to store different sized IP network
585 addresses. Network address with zero prefix size cannot be stored in
586 this type of sets.
587 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
589 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
590 ment ] [ skbinfo ]
591 ADD-ENTRY := netaddr
593 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
595 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
596 skbqueue value ]
597 DEL-ENTRY := netaddr
599 TEST-ENTRY := netaddr
601 where netaddr := ip[/cidr]
603 When adding/deleting/testing entries, if the cidr prefix parameter is
605 not specified, then the host prefix value is assumed. When
606 adding/deleting entries, the exact element is added/deleted and over‐
607 lapping elements are not checked by the kernel. When testing entries,
608 if a host address is tested, then the kernel tries to match the host
609 address in the networks added to the set and reports the result accord‐
610 ingly.
611 From the set netfilter match point of view the searching for a match
613 always starts from the smallest size of netblock (most specific
614 prefix) to the largest one (least specific prefix) added to the set.
615 When adding/deleting IP addresses to the set by the SET netfilter
616 target, it will be added/deleted by the most specific prefix which
617 can be found in the set, or by the host prefix value if the set is
618 empty.
619 The lookup time grows linearly with the number of the different prefix
621 values added to the set.
622 Example:
624 ipset create foo hash:net
626 ipset add foo 192.168.0.0/24
628 ipset add foo 10.1.0.0/16
630 ipset add foo 192.168.0/24
632 ipset add foo 192.168.0/30 nomatch
634 When matching the elements in the set above, all IP addresses will
636 match from the networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24
637 except the ones from 192.168.0/30.
638 hash:net,net
640 The hash:net,net set type uses a hash to store pairs of different sized
641 IP network addresses. Bear in mind that the first parameter has
642 precedence over the second, so a nomatch entry could be potentially be
643 ineffective if a more specific first parameter existed with a suitable
644 second parameter. Network address with zero prefix size cannot be
645 stored in this type of set.
646 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
648 elem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [
649 timeout value ] [ counters ] [ comment ] [ skbinfo ]
650 ADD-ENTRY := netaddr,netaddr
652 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
654 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
655 skbqueue value ]
656 DEL-ENTRY := netaddr,netaddr
658 TEST-ENTRY := netaddr,netaddr
660 where netaddr := ip[/cidr]
662 When adding/deleting/testing entries, if the cidr prefix parameter is
664 not specified, then the host prefix value is assumed. When
665 adding/deleting entries, the exact element is added/deleted and over‐
666 lapping elements are not checked by the kernel. When testing entries,
667 if a host address is tested, then the kernel tries to match the host
668 address in the networks added to the set and reports the result accord‐
669 ingly.
670 From the set netfilter match point of view the searching for a match
672 always starts from the smallest size of netblock (most specific
673 prefix) to the largest one (least specific prefix) with the first param
674 having precedence. When adding/deleting IP addresses to the set by
675 the SET netfilter target, it will be added/deleted by the most
676 specific prefix which can be found in the set, or by the host prefix
677 value if the set is empty.
678 The lookup time grows linearly with the number of the different prefix
680 values added to the first parameter of the set. The number of secondary
681 prefixes further increases this as the list of secondary prefixes is
682 traversed per primary prefix.
683 Optional create options:
685 netmask cidr
687 When the optional netmask parameter specified, network addresses
688 will be stored in the set instead of IP host addresses. The cidr
689 prefix value must be between 1-32 for IPv4 and between 1-128 for
690 IPv6. An IP address will be in the set if the network address,
691 which is resulted by masking the address with the netmask, can
692 be found in the set.
693 bitmask mask
695 This works similar to netmask but it will accept any valid
696 IPv4/v6 address. It does not have to be a valid netmask.
697 Example:
699 ipset create foo hash:net,net
701 ipset add foo 192.168.0.0/24,10.0.1.0/24
703 ipset add foo 10.1.0.0/16,10.255.0.0/24
705 ipset add foo 192.168.0/24,192.168.54.0-192.168.54.255
707 ipset add foo 192.168.0/30,192.168.64/30 nomatch
709 When matching the elements in the set above, all IP addresses will
711 match from the networks 192.168.0.0/24<->10.0.1.0/24,
712 10.1.0.0/16<->10.255.0.0/24 and 192.168.0/24<->192.168.54.0/24 except
713 the ones from 192.168.0/30<->192.168.64/30.
714 hash:ip,port
716 The hash:ip,port set type uses a hash to store IP address and port num‐
717 ber pairs. The port number is interpreted together with a protocol
718 (default TCP) and zero protocol number cannot be used.
719 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
721 elem value ] [ bucketsize value ] [ netmask cidr ] [ bitmask mask ] [
722 timeout value ] [ counters ] [ comment ] [ skbinfo ]
723 ADD-ENTRY := ipaddr,[proto:]port
725 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
727 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
728 DEL-ENTRY := ipaddr,[proto:]port
730 TEST-ENTRY := ipaddr,[proto:]port
732 The [proto:]port part of the elements may be expressed in the following
734 forms, where the range variations are valid when adding or deleting en‐
735 tries:
736 portname[-portname]
738 TCP port or range of ports expressed in TCP portname identifiers
739 from /etc/services
740 portnumber[-portnumber]
742 TCP port or range of ports expressed in TCP port numbers
743 tcp|sctp|udp|udplite:portname|portnumber[-portname|portnumber]
745 TCP, SCTP, UDP or UDPLITE port or port range expressed in port
746 name(s) or port number(s)
747 icmp:codename|type/code
749 ICMP codename or type/code. The supported ICMP codename identi‐
750 fiers can always be listed by the help command.
751 icmpv6:codename|type/code
753 ICMPv6 codename or type/code. The supported ICMPv6 codename
754 identifiers can always be listed by the help command.
755 proto:0
757 All other protocols, as an identifier from /etc/protocols or
758 number. The pseudo port number must be zero.
759 The hash:ip,port type of sets require two src/dst parameters of the set
761 match and SET target kernel modules.
762 Optional create options:
764 netmask cidr
766 When the optional netmask parameter specified, network addresses
767 will be stored in the set instead of IP host addresses. The cidr
768 prefix value must be between 1-32 for IPv4 and between 1-128 for
769 IPv6. An IP address will be in the set if the network address,
770 which is resulted by masking the address with the netmask, can
771 be found in the set.
772 bitmask mask
774 This works similar to netmask but it will accept any valid
775 IPv4/v6 address. It does not have to be a valid netmask.
776 Examples:
778 ipset create foo hash:ip,port
780 ipset add foo 192.168.1.0/24,80-82
782 ipset add foo 192.168.1.1,udp:53
784 ipset add foo 192.168.1.1,vrrp:0
786 ipset test foo 192.168.1.1,80
788 hash:net,port
790 The hash:net,port set type uses a hash to store different sized IP net‐
791 work address and port pairs. The port number is interpreted together
792 with a protocol (default TCP) and zero protocol number cannot be used.
793 Network address with zero prefix size is not accepted either.
794 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
796 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
797 ment ] [ skbinfo ]
798 ADD-ENTRY := netaddr,[proto:]port
800 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
802 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
803 skbqueue value ]
804 DEL-ENTRY := netaddr,[proto:]port
806 TEST-ENTRY := netaddr,[proto:]port
808 where netaddr := ip[/cidr]
810 For the netaddr part of the elements see the description at the
812 hash:net set type. For the [proto:]port part of the elements see the
813 description at the hash:ip,port set type.
814 When adding/deleting/testing entries, if the cidr prefix parameter is
816 not specified, then the host prefix value is assumed. When
817 adding/deleting entries, the exact element is added/deleted and over‐
818 lapping elements are not checked by the kernel. When testing entries,
819 if a host address is tested, then the kernel tries to match the host
820 address in the networks added to the set and reports the result accord‐
821 ingly.
822 From the set netfilter match point of view the searching for a match
824 always starts from the smallest size of netblock (most specific
825 prefix) to the largest one (least specific prefix) added to the set.
826 When adding/deleting IP addresses to the set by the SET netfilter
827 target, it will be added/deleted by the most specific prefix which
828 can be found in the set, or by the host prefix value if the set is
829 empty.
830 The lookup time grows linearly with the number of the different prefix
832 values added to the set.
833 Examples:
835 ipset create foo hash:net,port
837 ipset add foo 192.168.0/24,25
839 ipset add foo 10.1.0.0/16,80
841 ipset test foo 192.168.0/24,25
843 hash:ip,port,ip
845 The hash:ip,port,ip set type uses a hash to store IP address, port num‐
846 ber and a second IP address triples. The port number is interpreted to‐
847 gether with a protocol (default TCP) and zero protocol number cannot be
848 used.
849 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
851 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
852 ment ] [ skbinfo ]
853 ADD-ENTRY := ipaddr,[proto:]port,ip
855 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
857 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
858 DEL-ENTRY := ipaddr,[proto:]port,ip
860 TEST-ENTRY := ipaddr,[proto:]port,ip
862 For the first ipaddr and [proto:]port parts of the elements see the de‐
864 scriptions at the hash:ip,port set type.
865 The hash:ip,port,ip type of sets require three src/dst parameters of
867 the set match and SET target kernel modules.
868 Examples:
870 ipset create foo hash:ip,port,ip
872 ipset add foo 192.168.1.1,80,10.0.0.1
874 ipset test foo 192.168.1.1,udp:53,10.0.0.1
876 hash:ip,port,net
878 The hash:ip,port,net set type uses a hash to store IP address, port
879 number and IP network address triples. The port number is interpreted
880 together with a protocol (default TCP) and zero protocol number cannot
881 be used. Network address with zero prefix size cannot be stored either.
882 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
884 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
885 ment ] [ skbinfo ]
886 ADD-ENTRY := ipaddr,[proto:]port,netaddr
888 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
890 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
891 skbqueue value ]
892 DEL-ENTRY := ipaddr,[proto:]port,netaddr
894 TEST-ENTRY := ipaddr,[proto:]port,netaddr
896 where netaddr := ip[/cidr]
898 For the ipaddr and [proto:]port parts of the elements see the descrip‐
900 tions at the hash:ip,port set type. For the netaddr part of the ele‐
901 ments see the description at the hash:net set type.
902 From the set netfilter match point of view the searching for a match
904 always starts from the smallest size of netblock (most specific
905 cidr) to the largest one (least specific cidr) added to the set. When
906 adding/deleting triples to the set by the SET netfilter target, it
907 will be added/deleted by the most specific cidr which can be found in
908 the set, or by the host cidr value if the set is empty.
909 The lookup time grows linearly with the number of the different cidr
911 values added to the set.
912 The hash:ip,port,net type of sets require three src/dst parameters of
914 the set match and SET target kernel modules.
915 Examples:
917 ipset create foo hash:ip,port,net
919 ipset add foo 192.168.1,80,10.0.0/24
921 ipset add foo 192.168.2,25,10.1.0.0/16
923 ipset test foo 192.168.1,80.10.0.0/24
925 hash:ip,mark
927 The hash:ip,mark set type uses a hash to store IP address and packet
928 mark pairs.
929 CREATE-OPTIONS := [ family { inet | inet6 } ] [ markmask value ] [
931 hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value
932 ] [ counters ] [ comment ] [ skbinfo ]
933 ADD-ENTRY := ipaddr,mark
935 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
937 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
938 DEL-ENTRY := ipaddr,mark
940 TEST-ENTRY := ipaddr,mark
942 Optional create options:
944 markmask value
946 Allows you to set bits you are interested in the packet mark.
947 This values is then used to perform bitwise AND operation for
948 every mark added. markmask can be any value between 1 and
949 4294967295, by default all 32 bits are set.
950 The mark can be any value between 0 and 4294967295.
952 The hash:ip,mark type of sets require two src/dst parameters of the set
954 match and SET target kernel modules.
955 Examples:
957 ipset create foo hash:ip,mark
959 ipset add foo 192.168.1.0/24,555
961 ipset add foo 192.168.1.1,0x63
963 ipset add foo 192.168.1.1,111236
965 hash:net,port,net
967 The hash:net,port,net set type behaves similarly to hash:ip,port,net
968 but accepts a cidr value for both the first and last parameter. Either
969 subnet is permitted to be a /0 should you wish to match port between
970 all destinations.
971 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
973 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
974 ment ] [ skbinfo ]
975 ADD-ENTRY := netaddr,[proto:]port,netaddr
977 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
979 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
980 skbqueue value ]
981 DEL-ENTRY := netaddr,[proto:]port,netaddr
983 TEST-ENTRY := netaddr,[proto:]port,netaddr
985 where netaddr := ip[/cidr]
987 For the [proto:]port part of the elements see the description at the
989 hash:ip,port set type. For the netaddr part of the elements see the de‐
990 scription at the hash:net set type.
991 From the set netfilter match point of view the searching for a match
993 always starts from the smallest size of netblock (most specific
994 cidr) to the largest one (least specific cidr) added to the set. When
995 adding/deleting triples to the set by the SET netfilter target, it
996 will be added/deleted by the most specific cidr which can be found in
997 the set, or by the host cidr value if the set is empty. The first sub‐
998 net has precedence when performing the most-specific lookup, just as
999 for hash:net,net
1000 The lookup time grows linearly with the number of the different cidr
1002 values added to the set and by the number of secondary cidr values per
1003 primary.
1004 The hash:net,port,net type of sets require three src/dst parameters of
1006 the set match and SET target kernel modules.
1007 Examples:
1009 ipset create foo hash:net,port,net
1011 ipset add foo 192.168.1.0/24,0,10.0.0/24
1013 ipset add foo 192.168.2.0/24,25,10.1.0.0/16
1015 ipset test foo 192.168.1.1,80,10.0.0.1
1017 hash:net,iface
1019 The hash:net,iface set type uses a hash to store different sized IP
1020 network address and interface name pairs.
1021 CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
1023 elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
1024 ment ] [ skbinfo ]
1025 ADD-ENTRY := netaddr,[physdev:]iface
1027 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
1029 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
1030 skbqueue value ] [ wildcard ]
1031 DEL-ENTRY := netaddr,[physdev:]iface
1033 TEST-ENTRY := netaddr,[physdev:]iface
1035 where netaddr := ip[/cidr]
1037 For the netaddr part of the elements see the description at the
1039 hash:net set type.
1040 When adding/deleting/testing entries, if the cidr prefix parameter is
1042 not specified, then the host prefix value is assumed. When
1043 adding/deleting entries, the exact element is added/deleted and over‐
1044 lapping elements are not checked by the kernel. When testing entries,
1045 if a host address is tested, then the kernel tries to match the host
1046 address in the networks added to the set and reports the result accord‐
1047 ingly.
1048 From the set netfilter match point of view the searching for a match
1050 always starts from the smallest size of netblock (most specific
1051 prefix) to the largest one (least specific prefix) added to the set.
1052 When adding/deleting IP addresses to the set by the SET netfilter
1053 target, it will be added/deleted by the most specific prefix which
1054 can be found in the set, or by the host prefix value if the set is
1055 empty.
1056 The second direction parameter of the set match and SET target modules
1058 corresponds to the incoming/outgoing interface: src to the incoming one
1059 (similar to the -i flag of iptables), while dst to the outgoing one
1060 (similar to the -o flag of iptables). When the interface is flagged
1061 with physdev:, the interface is interpreted as the incoming/outgoing
1062 bridge port.
1063 The lookup time grows linearly with the number of the different prefix
1065 values added to the set.
1066 The internal restriction of the hash:net,iface set type is that the
1068 same network prefix cannot be stored with more than 64 different inter‐
1069 faces in a single set.
1070 Examples:
1072 ipset create foo hash:net,iface
1074 ipset add foo 192.168.0/24,eth0
1076 ipset add foo 10.1.0.0/16,eth1
1078 ipset test foo 192.168.0/24,eth0
1080 list:set
1082 The list:set type uses a simple list in which you can store set names.
1083 CREATE-OPTIONS := [ size value ] [ timeout value ] [ counters ] [ com‐
1085 ment ] [ skbinfo ]
1086 ADD-ENTRY := setname [ { before | after } setname ]
1088 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
1090 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
1091 DEL-ENTRY := setname [ { before | after } setname ]
1093 TEST-ENTRY := setname [ { before | after } setname ]
1095 Optional create options:
1097 size value
1099 The size of the list, the default is 8. The parameter is ignored
1100 since ipset version 6.24.
1101 By the ipset command you can add, delete and test set names in a
1103 list:set type of set.
1104 By the set match or SET target of netfilter you can test, add or delete
1106 entries in the sets added to the list:set type of set. The match will
1107 try to find a matching entry in the sets and the target will try to add
1108 an entry to the first set to which it can be added. The number of di‐
1109 rection options of the match and target are important: sets which re‐
1110 quire more parameters than specified are skipped, while sets with equal
1111 or less parameters are checked, elements added/deleted. For example if
1112 a and b are list:set type of sets then in the command
1113 iptables -m set --match-set a src,dst -j SET --add-set b src,dst
1115 the match and target will skip any set in a and b which stores data
1117 triples, but will match all sets with single or double data storage in
1118 a set and stop matching at the first successful set, and add src to the
1119 first single or src,dst to the first double data storage set in b to
1120 which the entry can be added. You can imagine a list:set type of set as
1121 an ordered union of the set elements.
1122 Please note: by the ipset command you can add, delete and test the set‐
1124 names in a list:set type of set, and not the presence of a set's member
1125 (such as an IP address).
1126
1128 Zero valued set entries cannot be used with hash methods. Zero protocol
1129 value with ports cannot be used.
1130
1132 If you want to store same size subnets from a given network (say /24
1133 blocks from a /8 network), use the bitmap:ip set type. If you want to
1134 store random same size networks (say random /24 blocks), use the
1135 hash:ip set type. If you have got random size of netblocks, use
1136 hash:net.
1137 Matching on destination MAC addresses using the dst parameter of the
1139 set match netfilter kernel modules will only work if the destination
1140 MAC address is available in the packet at the given processing stage,
1141 that is, it only applies for incoming packets in the PREROUTING, INPUT
1142 and FORWARD chains, against the MAC address as originally found in the
1143 received packet (typically, one of the MAC addresses of the local
1144 host). This is not the destination MAC address a destination IP address
1145 resolves to, after routing. If the MAC address is not available (e.g.
1146 in the OUTPUT chain), the packet will simply not match.
1147 Backward compatibility is maintained and old ipset syntax is still sup‐
1149 ported.
1150 The iptree and iptreemap set types are removed: if you refer to them,
1152 they are automatically replaced by hash:ip type of sets.
1153
1155 Various error messages are printed to standard error. The exit code is
1156 0 for correct functioning.
1157
1159 Bugs? No, just funny features. :-) OK, just kidding...
1160
1162 iptables(8), ip6tables(8) iptables-extensions(8)
1163
1165 Jozsef Kadlecsik wrote ipset, which is based on ippool by Joakim Axels‐
1166 son, Patrick Schaaf and Martin Josefsson.
1167 Sven Wegener wrote the iptreemap type.
1168
1170 I stand on the shoulders of giants.
1171Jozsef Kadlecsik Jun 25, 2015 IPSET(8)