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 |
12 restore | flush | rename | swap | help | version | - }
13 OPTIONS := { -exist | -output { plain | save | xml } | -quiet |
15 -resolve | -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
50 below.
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
93 destroyed.
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
99 option is given, the entries are listed/saved sorted (which may
100 be slow). The option -output can be used to control the format
101 of 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
119 restore unless specified so in the restore file. All commands
120 are allowed in restore mode except list, help, version, interac‐
121 tive 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
143 input. 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
152 already 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
215 entry 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
222 entries. If a set is created with timeout support, then the same time‐
223 out option can be used to specify non-default timeout values when
224 adding entries. Zero timeout value means the entry is added permanent
225 to the set. The timeout value of already added elements can be changed
226 by re-adding the element using the -exist option. The largest possible
227 timeout 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
271 acceptable:
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 skbmark 0x1111/0xff00ffff skbprio 1:10 skbqueue 10
294 hashsize
296 This parameter is valid for the create command of all hash type sets.
297 It defines the initial hash size for the set, default is 1024. The hash
298 size must be a power of two, the kernel automatically rounds up non
299 power of two hash sizes to the first correct value. Example:
300 ipset create test hash:ip hashsize 1536
302 maxelem
304 This parameter is valid for the create command of all hash type sets.
305 It does define the maximal number of elements which can be stored in
306 the set, default 65536. Example:
307 ipset create test hash:ip maxelem 2048.
309 family { inet | inet6 }
311 This parameter is valid for the create command of all hash type sets
312 except for hash:mac. It defines the protocol family of the IP
313 addresses to be stored in the set. The default is inet, i.e IPv4. For
314 the inet family one can add or delete multiple entries by specifying a
315 range or a network of IPv4 addresses in the IP address part of the
316 entry:
317 ipaddr := { ip | fromaddr-toaddr | ip/cidr }
319 netaddr := { fromaddr-toaddr | ip/cidr }
321 Example:
323 ipset create test hash:ip family inet6
325 nomatch
327 The hash set types which can store net type of data (i.e. hash:*net*)
328 support the optional nomatch option when adding entries. When matching
329 elements in the set, entries marked as nomatch are skipped as if those
330 were not added to the set, which makes possible to build up sets with
331 exceptions. See the example at hash type hash:net below.
332 When elements are tested by ipset, the nomatch flags are taken into
334 account. If one wants to test the existence of an element marked with
335 nomatch in a set, then the flag must be specified too.
336 forceadd
338 All hash set types support the optional forceadd parameter when creat‐
339 ing a set. When sets created with this option become full the next
340 addition to the set may succeed and evict a random entry from the set.
341 ipset create foo hash:ip forceadd
343 wildcard
345 This flag is valid when adding elements to a hash:net,iface set. If the
346 flag is set, then prefix matching is used when comparing with this ele‐
347 ment. For example, an element containing the interface name "eth" will
348 match any name with that prefix.
349
351 bitmap:ip
352 The bitmap:ip set type uses a memory range to store either IPv4 host
353 (default) or IPv4 network addresses. A bitmap:ip type of set can store
354 up to 65536 entries.
355 CREATE-OPTIONS := range fromip-toip|ip/cidr [ netmask cidr ] [ timeout
357 value ] [ counters ] [ comment ] [ skbinfo ]
358 ADD-ENTRY := { ip | fromip-toip | ip/cidr }
360 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
362 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
363 DEL-ENTRY := { ip | fromip-toip | ip/cidr }
365 TEST-ENTRY := ip
367 Mandatory create options:
369 range fromip-toip|ip/cidr
371 Create the set from the specified inclusive address range
372 expressed in an IPv4 address range or network. The size of the
373 range (in entries) cannot exceed the limit of maximum 65536 ele‐
374 ments.
375 Optional create options:
377 netmask cidr
379 When the optional netmask parameter specified, network addresses
380 will be stored in the set instead of IP host addresses. The cidr
381 prefix value must be between 1-32. An IP address will be in the
382 set if the network address, which is resulted by masking the
383 address with the specified netmask, can be found in the set.
384 The bitmap:ip type supports adding or deleting multiple entries in one
386 command.
387 Examples:
389 ipset create foo bitmap:ip range 192.168.0.0/16
391 ipset add foo 192.168.1/24
393 ipset test foo 192.168.1.1
395 bitmap:ip,mac
397 The bitmap:ip,mac set type uses a memory range to store IPv4 and a MAC
398 address pairs. A bitmap:ip,mac type of set can store up to 65536
399 entries.
400 CREATE-OPTIONS := range fromip-toip|ip/cidr [ timeout value ] [ coun‐
402 ters ] [ comment ] [ skbinfo ]
403 ADD-ENTRY := ip[,macaddr]
405 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
407 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
408 DEL-ENTRY := ip[,macaddr]
410 TEST-ENTRY := ip[,macaddr]
412 Mandatory options to use when creating a bitmap:ip,mac type of set:
414 range fromip-toip|ip/cidr
416 Create the set from the specified inclusive address range
417 expressed in an IPv4 address range or network. The size of the
418 range cannot exceed the limit of maximum 65536 entries.
419 The bitmap:ip,mac type is exceptional in the sense that the MAC part
421 can be left out when adding/deleting/testing entries in the set. If we
422 add an entry without the MAC address specified, then when the first
423 time the entry is matched by the kernel, it will automatically fill out
424 the missing MAC address with the MAC address from the packet. The
425 source MAC address is used if the entry matched due to a src parameter
426 of the set match, and the destination MAC address is used if available
427 and the entry matched due to a dst parameter. If the entry was speci‐
428 fied with a timeout value, the timer starts off when the IP and MAC
429 address pair is complete.
430 The bitmap:ip,mac type of sets require two src/dst parameters of the
432 set match and SET target netfilter kernel modules. For matches on des‐
433 tination MAC addresses, see COMMENTS below.
434 Examples:
436 ipset create foo bitmap:ip,mac range 192.168.0.0/16
438 ipset add foo 192.168.1.1,12:34:56:78:9A:BC
440 ipset test foo 192.168.1.1
442 bitmap:port
444 The bitmap:port set type uses a memory range to store port numbers and
445 such a set can store up to 65536 ports.
446 CREATE-OPTIONS := range fromport-toport [ timeout value ] [ counters ]
448 [ comment ] [ skbinfo ]
449 ADD-ENTRY := { [proto:]port | [proto:]fromport-toport }
451 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
453 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
454 DEL-ENTRY := { [proto:]port | [proto:]fromport-toport }
456 TEST-ENTRY := [proto:]port
458 Mandatory options to use when creating a bitmap:port type of set:
460 range [proto:]fromport-toport
462 Create the set from the specified inclusive port range.
463 The set match and SET target netfilter kernel modules interpret the
465 stored numbers as TCP or UDP port numbers.
466 proto only needs to be specified if a service name is used and that
468 name does not exist as a TCP service. The protocol is never stored in
469 the set, just the port number of the service.
470 Examples:
472 ipset create foo bitmap:port range 0-1024
474 ipset add foo 80
476 ipset test foo 80
478 ipset del foo udp:[macon-udp]-[tn-tl-w2]
480 hash:ip
482 The hash:ip set type uses a hash to store IP host addresses (default)
483 or network addresses. Zero valued IP address cannot be stored in a
484 hash:ip type of set.
485 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
487 maxelem value ] [ netmask cidr ] [ timeout value ] [ counters ] [ com‐
488 ment ] [ skbinfo ]
489 ADD-ENTRY := ipaddr
491 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
493 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
494 DEL-ENTRY := ipaddr
496 TEST-ENTRY := ipaddr
498 Optional create options:
500 netmask cidr
502 When the optional netmask parameter specified, network addresses
503 will be stored in the set instead of IP host addresses. The cidr
504 prefix value must be between 1-32 for IPv4 and between 1-128 for
505 IPv6. An IP address will be in the set if the network address,
506 which is resulted by masking the address with the netmask, can
507 be found in the set. Examples:
508 ipset create foo hash:ip netmask 30
510 ipset add foo 192.168.1.0/24
512 ipset test foo 192.168.1.2
514 hash:mac
516 The hash:mac set type uses a hash to store MAC addresses. Zero valued
517 MAC addresses cannot be stored in a hash:mac type of set. For matches
518 on destination MAC addresses, see COMMENTS below.
519 CREATE-OPTIONS := [ hashsize value ] [ maxelem value ] [ timeout value
521 ] [ counters ] [ comment ] [ skbinfo ]
522 ADD-ENTRY := macaddr
524 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
526 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
527 DEL-ENTRY := macaddr
529 TEST-ENTRY := macaddr
531 Examples:
533 ipset create foo hash:mac
535 ipset add foo 01:02:03:04:05:06
537 ipset test foo 01:02:03:04:05:06
539 hash:ip,mac
542 The hash:ip,mac set type uses a hash to store IP and a MAC address
543 pairs. Zero valued MAC addresses cannot be stored in a hash:ip,mac type
544 of set. For matches on destination MAC addresses, see COMMENTS below.
545 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
547 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
548 ADD-ENTRY := ipaddr,macaddr
550 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
552 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
553 DEL-ENTRY := ipaddr,macaddr
555 TEST-ENTRY := ipaddr,macaddr
557 Examples:
559 ipset create foo hash:ip,mac
561 ipset add foo 1.1.1.1,01:02:03:04:05:06
563 ipset test foo 1.1.1.1,01:02:03:04:05:06
565 hash:net
568 The hash:net set type uses a hash to store different sized IP network
569 addresses. Network address with zero prefix size cannot be stored in
570 this type of sets.
571 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
573 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
574 ADD-ENTRY := netaddr
576 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
578 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
579 skbqueue value ]
580 DEL-ENTRY := netaddr
582 TEST-ENTRY := netaddr
584 where netaddr := ip[/cidr]
586 When adding/deleting/testing entries, if the cidr prefix parameter is
588 not specified, then the host prefix value is assumed. When
589 adding/deleting entries, the exact element is added/deleted and over‐
590 lapping elements are not checked by the kernel. When testing entries,
591 if a host address is tested, then the kernel tries to match the host
592 address in the networks added to the set and reports the result accord‐
593 ingly.
594 From the set netfilter match point of view the searching for a match
596 always starts from the smallest size of netblock (most specific
597 prefix) to the largest one (least specific prefix) added to the set.
598 When adding/deleting IP addresses to the set by the SET netfilter
599 target, it will be added/deleted by the most specific prefix which
600 can be found in the set, or by the host prefix value if the set is
601 empty.
602 The lookup time grows linearly with the number of the different prefix
604 values added to the set.
605 Example:
607 ipset create foo hash:net
609 ipset add foo 192.168.0.0/24
611 ipset add foo 10.1.0.0/16
613 ipset add foo 192.168.0/24
615 ipset add foo 192.168.0/30 nomatch
617 When matching the elements in the set above, all IP addresses will
619 match from the networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24
620 except the ones from 192.168.0/30.
621 hash:net,net
623 The hash:net,net set type uses a hash to store pairs of different sized
624 IP network addresses. Bear in mind that the first parameter has
625 precedence over the second, so a nomatch entry could be potentially be
626 ineffective if a more specific first parameter existed with a suitable
627 second parameter. Network address with zero prefix size cannot be
628 stored in this type of set.
629 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
631 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
632 ADD-ENTRY := netaddr,netaddr
634 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
636 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
637 skbqueue value ]
638 DEL-ENTRY := netaddr,netaddr
640 TEST-ENTRY := netaddr,netaddr
642 where netaddr := ip[/cidr]
644 When adding/deleting/testing entries, if the cidr prefix parameter is
646 not specified, then the host prefix value is assumed. When
647 adding/deleting entries, the exact element is added/deleted and over‐
648 lapping elements are not checked by the kernel. When testing entries,
649 if a host address is tested, then the kernel tries to match the host
650 address in the networks added to the set and reports the result accord‐
651 ingly.
652 From the set netfilter match point of view the searching for a match
654 always starts from the smallest size of netblock (most specific
655 prefix) to the largest one (least specific prefix) with the first param
656 having precedence. When adding/deleting IP addresses to the set by
657 the SET netfilter target, it will be added/deleted by the most
658 specific prefix which can be found in the set, or by the host prefix
659 value if the set is empty.
660 The lookup time grows linearly with the number of the different prefix
662 values added to the first parameter of the set. The number of secondary
663 prefixes further increases this as the list of secondary prefixes is
664 traversed per primary prefix.
665 Example:
667 ipset create foo hash:net,net
669 ipset add foo 192.168.0.0/24,10.0.1.0/24
671 ipset add foo 10.1.0.0/16,10.255.0.0/24
673 ipset add foo 192.168.0/24,192.168.54.0-192.168.54.255
675 ipset add foo 192.168.0/30,192.168.64/30 nomatch
677 When matching the elements in the set above, all IP addresses will
679 match from the networks 192.168.0.0/24<->10.0.1.0/24,
680 10.1.0.0/16<->10.255.0.0/24 and 192.168.0/24<->192.168.54.0/24 except
681 the ones from 192.168.0/30<->192.168.64/30.
682 hash:ip,port
684 The hash:ip,port set type uses a hash to store IP address and port num‐
685 ber pairs. The port number is interpreted together with a protocol
686 (default TCP) and zero protocol number cannot be used.
687 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
689 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
690 ADD-ENTRY := ipaddr,[proto:]port
692 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
694 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
695 DEL-ENTRY := ipaddr,[proto:]port
697 TEST-ENTRY := ipaddr,[proto:]port
699 The [proto:]port part of the elements may be expressed in the following
701 forms, where the range variations are valid when adding or deleting
702 entries:
703 portname[-portname]
705 TCP port or range of ports expressed in TCP portname identifiers
706 from /etc/services
707 portnumber[-portnumber]
709 TCP port or range of ports expressed in TCP port numbers
710 tcp|sctp|udp|udplite:portname|portnumber[-portname|portnumber]
712 TCP, SCTP, UDP or UDPLITE port or port range expressed in port
713 name(s) or port number(s)
714 icmp:codename|type/code
716 ICMP codename or type/code. The supported ICMP codename identi‐
717 fiers can always be listed by the help command.
718 icmpv6:codename|type/code
720 ICMPv6 codename or type/code. The supported ICMPv6 codename
721 identifiers can always be listed by the help command.
722 proto:0
724 All other protocols, as an identifier from /etc/protocols or
725 number. The pseudo port number must be zero.
726 The hash:ip,port type of sets require two src/dst parameters of the set
728 match and SET target kernel modules.
729 Examples:
731 ipset create foo hash:ip,port
733 ipset add foo 192.168.1.0/24,80-82
735 ipset add foo 192.168.1.1,udp:53
737 ipset add foo 192.168.1.1,vrrp:0
739 ipset test foo 192.168.1.1,80
741 hash:net,port
743 The hash:net,port set type uses a hash to store different sized IP net‐
744 work address and port pairs. The port number is interpreted together
745 with a protocol (default TCP) and zero protocol number cannot be used.
746 Network address with zero prefix size is not accepted either.
747 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
749 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
750 ADD-ENTRY := netaddr,[proto:]port
752 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
754 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
755 skbqueue value ]
756 DEL-ENTRY := netaddr,[proto:]port
758 TEST-ENTRY := netaddr,[proto:]port
760 where netaddr := ip[/cidr]
762 For the netaddr part of the elements see the description at the
764 hash:net set type. For the [proto:]port part of the elements see the
765 description at the hash:ip,port set type.
766 When adding/deleting/testing entries, if the cidr prefix parameter is
768 not specified, then the host prefix value is assumed. When
769 adding/deleting entries, the exact element is added/deleted and over‐
770 lapping elements are not checked by the kernel. When testing entries,
771 if a host address is tested, then the kernel tries to match the host
772 address in the networks added to the set and reports the result accord‐
773 ingly.
774 From the set netfilter match point of view the searching for a match
776 always starts from the smallest size of netblock (most specific
777 prefix) to the largest one (least specific prefix) added to the set.
778 When adding/deleting IP addresses to the set by the SET netfilter
779 target, it will be added/deleted by the most specific prefix which
780 can be found in the set, or by the host prefix value if the set is
781 empty.
782 The lookup time grows linearly with the number of the different prefix
784 values added to the set.
785 Examples:
787 ipset create foo hash:net,port
789 ipset add foo 192.168.0/24,25
791 ipset add foo 10.1.0.0/16,80
793 ipset test foo 192.168.0/24,25
795 hash:ip,port,ip
797 The hash:ip,port,ip set type uses a hash to store IP address, port num‐
798 ber and a second IP address triples. The port number is interpreted
799 together with a protocol (default TCP) and zero protocol number cannot
800 be used.
801 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
803 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
804 ADD-ENTRY := ipaddr,[proto:]port,ip
806 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
808 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
809 DEL-ENTRY := ipaddr,[proto:]port,ip
811 TEST-ENTRY := ipaddr,[proto:]port,ip
813 For the first ipaddr and [proto:]port parts of the elements see the
815 descriptions at the hash:ip,port set type.
816 The hash:ip,port,ip type of sets require three src/dst parameters of
818 the set match and SET target kernel modules.
819 Examples:
821 ipset create foo hash:ip,port,ip
823 ipset add foo 192.168.1.1,80,10.0.0.1
825 ipset test foo 192.168.1.1,udp:53,10.0.0.1
827 hash:ip,port,net
829 The hash:ip,port,net set type uses a hash to store IP address, port
830 number and IP network address triples. The port number is interpreted
831 together with a protocol (default TCP) and zero protocol number cannot
832 be used. Network address with zero prefix size cannot be stored either.
833 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
835 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
836 ADD-ENTRY := ipaddr,[proto:]port,netaddr
838 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
840 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
841 skbqueue value ]
842 DEL-ENTRY := ipaddr,[proto:]port,netaddr
844 TEST-ENTRY := ipaddr,[proto:]port,netaddr
846 where netaddr := ip[/cidr]
848 For the ipaddr and [proto:]port parts of the elements see the descrip‐
850 tions at the hash:ip,port set type. For the netaddr part of the ele‐
851 ments see the description at the hash:net set type.
852 From the set netfilter match point of view the searching for a match
854 always starts from the smallest size of netblock (most specific
855 cidr) to the largest one (least specific cidr) added to the set. When
856 adding/deleting triples to the set by the SET netfilter target, it
857 will be added/deleted by the most specific cidr which can be found in
858 the set, or by the host cidr value if the set is empty.
859 The lookup time grows linearly with the number of the different cidr
861 values added to the set.
862 The hash:ip,port,net type of sets require three src/dst parameters of
864 the set match and SET target kernel modules.
865 Examples:
867 ipset create foo hash:ip,port,net
869 ipset add foo 192.168.1,80,10.0.0/24
871 ipset add foo 192.168.2,25,10.1.0.0/16
873 ipset test foo 192.168.1,80.10.0.0/24
875 hash:ip,mark
877 The hash:ip,mark set type uses a hash to store IP address and packet
878 mark pairs.
879 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ markmask value ] [
881 hashsize value ] [ maxelem value ] [ timeout value ] [ counters ] [
882 comment ] [ skbinfo ]
883 ADD-ENTRY := ipaddr,mark
885 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
887 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
888 DEL-ENTRY := ipaddr,mark
890 TEST-ENTRY := ipaddr,mark
892 Optional create options:
894 markmask value
896 Allows you to set bits you are interested in the packet mark.
897 This values is then used to perform bitwise AND operation for
898 every mark added. markmask can be any value between 1 and
899 4294967295, by default all 32 bits are set.
900 The mark can be any value between 0 and 4294967295.
902 The hash:ip,mark type of sets require two src/dst parameters of the set
904 match and SET target kernel modules.
905 Examples:
907 ipset create foo hash:ip,mark
909 ipset add foo 192.168.1.0/24,555
911 ipset add foo 192.168.1.1,0x63
913 ipset add foo 192.168.1.1,111236
915 hash:net,port,net
917 The hash:net,port,net set type behaves similarly to hash:ip,port,net
918 but accepts a cidr value for both the first and last parameter. Either
919 subnet is permitted to be a /0 should you wish to match port between
920 all destinations.
921 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
923 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
924 ADD-ENTRY := netaddr,[proto:]port,netaddr
926 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
928 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
929 skbqueue value ]
930 DEL-ENTRY := netaddr,[proto:]port,netaddr
932 TEST-ENTRY := netaddr,[proto:]port,netaddr
934 where netaddr := ip[/cidr]
936 For the [proto:]port part of the elements see the description at the
938 hash:ip,port set type. For the netaddr part of the elements see the
939 description at the hash:net set type.
940 From the set netfilter match point of view the searching for a match
942 always starts from the smallest size of netblock (most specific
943 cidr) to the largest one (least specific cidr) added to the set. When
944 adding/deleting triples to the set by the SET netfilter target, it
945 will be added/deleted by the most specific cidr which can be found in
946 the set, or by the host cidr value if the set is empty. The first sub‐
947 net has precedence when performing the most-specific lookup, just as
948 for hash:net,net
949 The lookup time grows linearly with the number of the different cidr
951 values added to the set and by the number of secondary cidr values per
952 primary.
953 The hash:net,port,net type of sets require three src/dst parameters of
955 the set match and SET target kernel modules.
956 Examples:
958 ipset create foo hash:net,port,net
960 ipset add foo 192.168.1.0/24,0,10.0.0/24
962 ipset add foo 192.168.2.0/24,25,10.1.0.0/16
964 ipset test foo 192.168.1.1,80,10.0.0.1
966 hash:net,iface
968 The hash:net,iface set type uses a hash to store different sized IP
969 network address and interface name pairs.
970 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
972 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
973 ADD-ENTRY := netaddr,[physdev:]iface
975 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
977 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
978 skbqueue value ] [ wildcard ]
979 DEL-ENTRY := netaddr,[physdev:]iface
981 TEST-ENTRY := netaddr,[physdev:]iface
983 where netaddr := ip[/cidr]
985 For the netaddr part of the elements see the description at the
987 hash:net set type.
988 When adding/deleting/testing entries, if the cidr prefix parameter is
990 not specified, then the host prefix value is assumed. When
991 adding/deleting entries, the exact element is added/deleted and over‐
992 lapping elements are not checked by the kernel. When testing entries,
993 if a host address is tested, then the kernel tries to match the host
994 address in the networks added to the set and reports the result accord‐
995 ingly.
996 From the set netfilter match point of view the searching for a match
998 always starts from the smallest size of netblock (most specific
999 prefix) to the largest one (least specific prefix) added to the set.
1000 When adding/deleting IP addresses to the set by the SET netfilter
1001 target, it will be added/deleted by the most specific prefix which
1002 can be found in the set, or by the host prefix value if the set is
1003 empty.
1004 The second direction parameter of the set match and SET target modules
1006 corresponds to the incoming/outgoing interface: src to the incoming one
1007 (similar to the -i flag of iptables), while dst to the outgoing one
1008 (similar to the -o flag of iptables). When the interface is flagged
1009 with physdev:, the interface is interpreted as the incoming/outgoing
1010 bridge port.
1011 The lookup time grows linearly with the number of the different prefix
1013 values added to the set.
1014 The internal restriction of the hash:net,iface set type is that the
1016 same network prefix cannot be stored with more than 64 different inter‐
1017 faces in a single set.
1018 Examples:
1020 ipset create foo hash:net,iface
1022 ipset add foo 192.168.0/24,eth0
1024 ipset add foo 10.1.0.0/16,eth1
1026 ipset test foo 192.168.0/24,eth0
1028 list:set
1030 The list:set type uses a simple list in which you can store set names.
1031 CREATE-OPTIONS := [ size value ] [ timeout value ] [ counters ] [ com‐
1033 ment ] [ skbinfo ]
1034 ADD-ENTRY := setname [ { before | after } setname ]
1036 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
1038 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
1039 DEL-ENTRY := setname [ { before | after } setname ]
1041 TEST-ENTRY := setname [ { before | after } setname ]
1043 Optional create options:
1045 size value
1047 The size of the list, the default is 8. The parameter is ignored
1048 since ipset version 6.24.
1049 By the ipset command you can add, delete and test set names in a
1051 list:set type of set.
1052 By the set match or SET target of netfilter you can test, add or delete
1054 entries in the sets added to the list:set type of set. The match will
1055 try to find a matching entry in the sets and the target will try to add
1056 an entry to the first set to which it can be added. The number of
1057 direction options of the match and target are important: sets which
1058 require more parameters than specified are skipped, while sets with
1059 equal or less parameters are checked, elements added/deleted. For exam‐
1060 ple if a and b are list:set type of sets then in the command
1061 iptables -m set --match-set a src,dst -j SET --add-set b src,dst
1063 the match and target will skip any set in a and b which stores data
1065 triples, but will match all sets with single or double data storage in
1066 a set and stop matching at the first successful set, and add src to the
1067 first single or src,dst to the first double data storage set in b to
1068 which the entry can be added. You can imagine a list:set type of set as
1069 an ordered union of the set elements.
1070 Please note: by the ipset command you can add, delete and test the set‐
1072 names in a list:set type of set, and not the presence of a set's member
1073 (such as an IP address).
1074
1076 Zero valued set entries cannot be used with hash methods. Zero protocol
1077 value with ports cannot be used.
1078
1080 If you want to store same size subnets from a given network (say /24
1081 blocks from a /8 network), use the bitmap:ip set type. If you want to
1082 store random same size networks (say random /24 blocks), use the
1083 hash:ip set type. If you have got random size of netblocks, use
1084 hash:net.
1085 Matching on destination MAC addresses using the dst parameter of the
1087 set match netfilter kernel modules will only work if the destination
1088 MAC address is available in the packet at the given processing stage,
1089 that is, it only applies for incoming packets in the PREROUTING, INPUT
1090 and FORWARD chains, against the MAC address as originally found in the
1091 received packet (typically, one of the MAC addresses of the local
1092 host). This is not the destination MAC address a destination IP address
1093 resolves to, after routing. If the MAC address is not available (e.g.
1094 in the OUTPUT chain), the packet will simply not match.
1095 Backward compatibility is maintained and old ipset syntax is still sup‐
1097 ported.
1098 The iptree and iptreemap set types are removed: if you refer to them,
1100 they are automatically replaced by hash:ip type of sets.
1101
1103 Various error messages are printed to standard error. The exit code is
1104 0 for correct functioning.
1105
1107 Bugs? No, just funny features. :-) OK, just kidding...
1108
1110 iptables(8), ip6tables(8) iptables-extensions(8)
1111
1113 Jozsef Kadlecsik wrote ipset, which is based on ippool by Joakim Axels‐
1114 son, Patrick Schaaf and Martin Josefsson.
1115 Sven Wegener wrote the iptreemap type.
1116
1118 I stand on the shoulders of giants.
1119Jozsef Kadlecsik Jun 25, 2015 IPSET(8)