1IPSET(8) IPSET(8)
2
3
4
6 ipset — administration tool for IP sets
7
9 ipset [ OPTIONS ] COMMAND [ COMMAND-OPTIONS ]
10
11 COMMANDS := { create | add | del | test | destroy | list | save |
12 restore | flush | rename | swap | help | version | - }
13
14 OPTIONS := { -exist | -output { plain | save | xml } | -quiet |
15 -resolve | -sorted | -name | -terse | -file filename }
16
17 ipset create SETNAME TYPENAME [ CREATE-OPTIONS ]
18
19 ipset add SETNAME ADD-ENTRY [ ADD-OPTIONS ]
20
21 ipset del SETNAME DEL-ENTRY [ DEL-OPTIONS ]
22
23 ipset test SETNAME TEST-ENTRY [ TEST-OPTIONS ]
24
25 ipset destroy [ SETNAME ]
26
27 ipset list [ SETNAME ]
28
29 ipset save [ SETNAME ]
30
31 ipset restore
32
33 ipset flush [ SETNAME ]
34
35 ipset rename SETNAME-FROM SETNAME-TO
36
37 ipset swap SETNAME-FROM SETNAME-TO
38
39 ipset help [ TYPENAME ]
40
41 ipset version
42
43 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
52 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
60 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
68 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
75 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
79 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
84 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
89 x, destroy [ SETNAME ]
90 Destroy the specified set or all the sets if none is given.
91
92 If the set has got reference(s), nothing is done and no set
93 destroyed.
94
95 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 sorted (if the given set
100 type supports the operation). The option -output can be used to
101 control the format of the listing: plain, save or xml. (The
102 default is plain.) If the option -name is specified, just the
103 names of the existing sets are listed. If the option -terse is
104 specified, just the set names and headers are listed. The output
105 is printed to stdout, the option -file can be used to specify a
106 filename instead of stdout.
107
108 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
113 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
118 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
123 flush [ SETNAME ]
124 Flush all entries from the specified set or flush all sets if
125 none is given.
126
127 e, rename SETNAME-FROM SETNAME-TO
128 Rename a set. Set identified by SETNAME-TO must not exist.
129
130 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
135 help [ TYPENAME ]
136 Print help and set type specific help if TYPENAME is specified.
137
138 version
139 Print program version.
140
141 - 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
146 OTHER OPTIONS
147 The following additional options can be specified. The long option
148 names cannot be abbreviated.
149
150 -!, -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
154 -o, -output { plain | save | xml }
155 Select the output format to the list command.
156
157 -q, -quiet
158 Suppress any output to stdout and stderr. ipset will still exit
159 with error if it cannot continue.
160
161 -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
166 -s, -sorted
167 Sorted output. When listing sets entries are listed sorted. Not
168 supported yet.
169
170 -n, -name
171 List just the names of the existing sets, i.e. suppress listing
172 of set headers and members.
173
174 -t, -terse
175 List the set names and headers, i.e. suppress listing of set
176 members.
177
178 -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
187 TYPENAME := method:datatype[,datatype[,datatype]]
188
189 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
193 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
197 ipset add foo ipaddr,portnum,ipaddr
198
199 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
203 ipset add foo [test-hostname],[ftp-data]
204
205 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
209 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. Example:
227
228 ipset create test hash:ip timeout 300
229
230 ipset add test 192.168.0.1 timeout 60
231
232 ipset -exist add test 192.168.0.1 timeout 600
233
234 When listing the set, the number of entries printed in the header might
235 be larger than the listed number of entries for sets with the timeout
236 extensions: the number of entries in the set is updated when elements
237 added/deleted to the set and periodically when the garbage collector
238 evicts the timed out entries.
239
240 counters, packets, bytes
241 All set types support the optional counters option when creating a set.
242 If the option is specified then the set is created with packet and byte
243 counters per element support. The packet and byte counters are initial‐
244 ized to zero when the elements are (re-)added to the set, unless the
245 packet and byte counter values are explicitly specified by the packets
246 and bytes options. An example when an element is added to a set with
247 non-zero counter values:
248
249 ipset create foo hash:ip counters
250
251 ipset add foo 192.168.1.1 packets 42 bytes 1024
252
253 comment
254 All set types support the optional comment extension. Enabling this
255 extension on an ipset enables you to annotate an ipset entry with an
256 arbitrary string. This string is completely ignored by both the kernel
257 and ipset itself and is purely for providing a convenient means to doc‐
258 ument the reason for an entry's existence. Comments must not contain
259 any quotation marks and the usual escape character (\) has no meaning.
260 For example, the following shell command is illegal:
261
262 ipset add foo 1.1.1.1 comment "this comment is \"bad\""
263
264 In the above, your shell will of course escape the quotation marks and
265 ipset will see the quote marks in the argument for the comment, which
266 will result in a parse error. If you are writing your own system, you
267 should avoid creating comments containing a quotation mark if you do
268 not want to break "ipset save" and "ipset restore", nonetheless, the
269 kernel will not stop you from doing so. The following is perfectly
270 acceptable:
271
272 ipset create foo hash:ip comment
273
274 ipset add foo 192.168.1.1/24 comment "allow access to SMB share
275 on \\\\fileserv\\"
276
277 the above would appear as: "allow access to SMB share on \\file‐
278 serv\"
279
280 skbinfo, skbmark, skbprio, skbqueue
281 All set types support the optional skbinfo extension. This extension
282 allows you to store the metainfo (firewall mark, tc class and hardware
283 queue) with every entry and map it to packets by usage of SET netfilter
284 target with --map-set option. skbmark option format: MARK or
285 MARK/MASK, where MARK and MASK are 32bit hex numbers with 0x prefix. If
286 only mark is specified mask 0xffffffff are used. skbprio option has tc
287 class format: MAJOR:MINOR, where major and minor numbers are hex with‐
288 out 0x prefix. skbqueue option is just decimal number.
289
290 ipset create foo hash:ip skbinfo
291
292 ipset add foo skbmark 0x1111/0xff00ffff skbprio 1:10 skbqueue 10
293
294 hashsize
295 This parameter is valid for the create command of all hash type sets.
296 It defines the initial hash size for the set, default is 1024. The hash
297 size must be a power of two, the kernel automatically rounds up non
298 power of two hash sizes to the first correct value. Example:
299
300 ipset create test hash:ip hashsize 1536
301
302 maxelem
303 This parameter is valid for the create command of all hash type sets.
304 It does define the maximal number of elements which can be stored in
305 the set, default 65536. Example:
306
307 ipset create test hash:ip maxelem 2048.
308
309 family { inet | inet6 }
310 This parameter is valid for the create command of all hash type sets
311 except for hash:mac. It defines the protocol family of the IP
312 addresses to be stored in the set. The default is inet, i.e IPv4. For
313 the inet family one can add or delete multiple entries by specifying a
314 range or a network of IPv4 addresses in the IP address part of the
315 entry:
316
317 ipaddr := { ip | fromaddr-toaddr | ip/cidr }
318
319 netaddr := { fromaddr-toaddr | ip/cidr }
320
321 Example:
322
323 ipset create test hash:ip family inet6
324
325 nomatch
326 The hash set types which can store net type of data (i.e. hash:*net*)
327 support the optional nomatch option when adding entries. When matching
328 elements in the set, entries marked as nomatch are skipped as if those
329 were not added to the set, which makes possible to build up sets with
330 exceptions. See the example at hash type hash:net below.
331
332 When elements are tested by ipset, the nomatch flags are taken into
333 account. If one wants to test the existence of an element marked with
334 nomatch in a set, then the flag must be specified too.
335
336 forceadd
337 All hash set types support the optional forceadd parameter when creat‐
338 ing a set. When sets created with this option become full the next
339 addition to the set may succeed and evict a random entry from the set.
340
341 ipset create foo hash:ip forceadd
342
344 bitmap:ip
345 The bitmap:ip set type uses a memory range to store either IPv4 host
346 (default) or IPv4 network addresses. A bitmap:ip type of set can store
347 up to 65536 entries.
348
349 CREATE-OPTIONS := range fromip-toip|ip/cidr [ netmask cidr ] [ timeout
350 value ] [ counters ] [ comment ] [ skbinfo ]
351
352 ADD-ENTRY := { ip | fromip-toip | ip/cidr }
353
354 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
355 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
356
357 DEL-ENTRY := { ip | fromip-toip | ip/cidr }
358
359 TEST-ENTRY := ip
360
361 Mandatory create options:
362
363 range fromip-toip|ip/cidr
364 Create the set from the specified inclusive address range
365 expressed in an IPv4 address range or network. The size of the
366 range (in entries) cannot exceed the limit of maximum 65536 ele‐
367 ments.
368
369 Optional create options:
370
371 netmask cidr
372 When the optional netmask parameter specified, network addresses
373 will be stored in the set instead of IP host addresses. The cidr
374 prefix value must be between 1-32. An IP address will be in the
375 set if the network address, which is resulted by masking the
376 address with the specified netmask, can be found in the set.
377
378 The bitmap:ip type supports adding or deleting multiple entries in one
379 command.
380
381 Examples:
382
383 ipset create foo bitmap:ip range 192.168.0.0/16
384
385 ipset add foo 192.168.1/24
386
387 ipset test foo 192.168.1.1
388
389 bitmap:ip,mac
390 The bitmap:ip,mac set type uses a memory range to store IPv4 and a MAC
391 address pairs. A bitmap:ip,mac type of set can store up to 65536
392 entries.
393
394 CREATE-OPTIONS := range fromip-toip|ip/cidr [ timeout value ] [ coun‐
395 ters ] [ comment ] [ skbinfo ]
396
397 ADD-ENTRY := ip[,macaddr]
398
399 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
400 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
401
402 DEL-ENTRY := ip[,macaddr]
403
404 TEST-ENTRY := ip[,macaddr]
405
406 Mandatory options to use when creating a bitmap:ip,mac type of set:
407
408 range fromip-toip|ip/cidr
409 Create the set from the specified inclusive address range
410 expressed in an IPv4 address range or network. The size of the
411 range cannot exceed the limit of maximum 65536 entries.
412
413 The bitmap:ip,mac type is exceptional in the sense that the MAC part
414 can be left out when adding/deleting/testing entries in the set. If we
415 add an entry without the MAC address specified, then when the first
416 time the entry is matched by the kernel, it will automatically fill out
417 the missing MAC address with the source MAC address from the packet. If
418 the entry was specified with a timeout value, the timer starts off when
419 the IP and MAC address pair is complete.
420
421 The bitmap:ip,mac type of sets require two src/dst parameters of the
422 set match and SET target netfilter kernel modules and the second one
423 must be src to match, add or delete entries, because the set match and
424 SET target have access to the source MAC address only.
425
426 Examples:
427
428 ipset create foo bitmap:ip,mac range 192.168.0.0/16
429
430 ipset add foo 192.168.1.1,12:34:56:78:9A:BC
431
432 ipset test foo 192.168.1.1
433
434 bitmap:port
435 The bitmap:port set type uses a memory range to store port numbers and
436 such a set can store up to 65536 ports.
437
438 CREATE-OPTIONS := range fromport-toport [ timeout value ] [ counters ]
439 [ comment ] [ skbinfo ]
440
441 ADD-ENTRY := { [proto:]port | [proto:]fromport-toport }
442
443 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
444 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
445
446 DEL-ENTRY := { [proto:]port | [proto:]fromport-toport }
447
448 TEST-ENTRY := [proto:]port
449
450 Mandatory options to use when creating a bitmap:port type of set:
451
452 range [proto:]fromport-toport
453 Create the set from the specified inclusive port range.
454
455 The set match and SET target netfilter kernel modules interpret the
456 stored numbers as TCP or UDP port numbers.
457
458 proto only needs to be specified if a service name is used, and that
459 name does not exist as a TCP service.
460
461 Examples:
462
463 ipset create foo bitmap:port range 0-1024
464
465 ipset add foo 80
466
467 ipset test foo 80
468
469 ipset del foo udp:[macon-udp]-[tn-tl-w2]
470
471 hash:ip
472 The hash:ip set type uses a hash to store IP host addresses (default)
473 or network addresses. Zero valued IP address cannot be stored in a
474 hash:ip type of set.
475
476 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
477 maxelem value ] [ netmask cidr ] [ timeout value ] [ counters ] [ com‐
478 ment ] [ skbinfo ]
479
480 ADD-ENTRY := ipaddr
481
482 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
483 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
484
485 DEL-ENTRY := ipaddr
486
487 TEST-ENTRY := ipaddr
488
489 Optional create options:
490
491 netmask cidr
492 When the optional netmask parameter specified, network addresses
493 will be stored in the set instead of IP host addresses. The cidr
494 prefix value must be between 1-32 for IPv4 and between 1-128 for
495 IPv6. An IP address will be in the set if the network address,
496 which is resulted by masking the address with the netmask, can
497 be found in the set. Examples:
498
499 ipset create foo hash:ip netmask 30
500
501 ipset add foo 192.168.1.0/24
502
503 ipset test foo 192.168.1.2
504
505 hash:mac
506 The hash:mac set type uses a hash to store MAC addresses. Zero valued
507 MAC addresses cannot be stored in a hash:mac type of set.
508
509 CREATE-OPTIONS := [ hashsize value ] [ maxelem value ] [ timeout value
510 ] [ counters ] [ comment ] [ skbinfo ]
511
512 ADD-ENTRY := macaddr
513
514 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
515 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
516
517 DEL-ENTRY := macaddr
518
519 TEST-ENTRY := macaddr
520
521 Examples:
522
523 ipset create foo hash:mac
524
525 ipset add foo 01:02:03:04:05:06
526
527 ipset test foo 01:02:03:04:05:06
528
529
530 hash:ip,mac
531 The hash:ip,mac set type uses a hash to store IP and a MAC address
532 pairs. Zero valued MAC addresses cannot be stored in a hash:ip,mac type
533 of set.
534
535 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
536 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
537
538 ADD-ENTRY := ipaddr,macaddr
539
540 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
541 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
542
543 DEL-ENTRY := ipaddr,macaddr
544
545 TEST-ENTRY := ipaddr,macaddr
546
547 Examples:
548
549 ipset create foo hash:ip,mac
550
551 ipset add foo 1.1.1.1,01:02:03:04:05:06
552
553 ipset test foo 1.1.1.1,01:02:03:04:05:06
554
555
556 hash:net
557 The hash:net set type uses a hash to store different sized IP network
558 addresses. Network address with zero prefix size cannot be stored in
559 this type of sets.
560
561 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
562 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
563
564 ADD-ENTRY := netaddr
565
566 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
567 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
568 skbqueue value ]
569
570 DEL-ENTRY := netaddr
571
572 TEST-ENTRY := netaddr
573
574 where netaddr := ip[/cidr]
575
576 When adding/deleting/testing entries, if the cidr prefix parameter is
577 not specified, then the host prefix value is assumed. When
578 adding/deleting entries, the exact element is added/deleted and over‐
579 lapping elements are not checked by the kernel. When testing entries,
580 if a host address is tested, then the kernel tries to match the host
581 address in the networks added to the set and reports the result accord‐
582 ingly.
583
584 From the set netfilter match point of view the searching for a match
585 always starts from the smallest size of netblock (most specific
586 prefix) to the largest one (least specific prefix) added to the set.
587 When adding/deleting IP addresses to the set by the SET netfilter
588 target, it will be added/deleted by the most specific prefix which
589 can be found in the set, or by the host prefix value if the set is
590 empty.
591
592 The lookup time grows linearly with the number of the different prefix
593 values added to the set.
594
595 Example:
596
597 ipset create foo hash:net
598
599 ipset add foo 192.168.0.0/24
600
601 ipset add foo 10.1.0.0/16
602
603 ipset add foo 192.168.0/24
604
605 ipset add foo 192.168.0/30 nomatch
606
607 When matching the elements in the set above, all IP addresses will
608 match from the networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24
609 except the ones from 192.168.0/30.
610
611 hash:net,net
612 The hash:net,net set type uses a hash to store pairs of different sized
613 IP network addresses. Bear in mind that the first parameter has
614 precedence over the second, so a nomatch entry could be potentially be
615 ineffective if a more specific first parameter existed with a suitable
616 second parameter. Network address with zero prefix size cannot be
617 stored in this type of set.
618
619 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
620 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
621
622 ADD-ENTRY := netaddr,netaddr
623
624 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
625 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
626 skbqueue value ]
627
628 DEL-ENTRY := netaddr,netaddr
629
630 TEST-ENTRY := netaddr,netaddr
631
632 where netaddr := ip[/cidr]
633
634 When adding/deleting/testing entries, if the cidr prefix parameter is
635 not specified, then the host prefix value is assumed. When
636 adding/deleting entries, the exact element is added/deleted and over‐
637 lapping elements are not checked by the kernel. When testing entries,
638 if a host address is tested, then the kernel tries to match the host
639 address in the networks added to the set and reports the result accord‐
640 ingly.
641
642 From the set netfilter match point of view the searching for a match
643 always starts from the smallest size of netblock (most specific
644 prefix) to the largest one (least specific prefix) with the first param
645 having precedence. When adding/deleting IP addresses to the set by
646 the SET netfilter target, it will be added/deleted by the most
647 specific prefix which can be found in the set, or by the host prefix
648 value if the set is empty.
649
650 The lookup time grows linearly with the number of the different prefix
651 values added to the first parameter of the set. The number of secondary
652 prefixes further increases this as the list of secondary prefixes is
653 traversed per primary prefix.
654
655 Example:
656
657 ipset create foo hash:net,net
658
659 ipset add foo 192.168.0.0/24,10.0.1.0/24
660
661 ipset add foo 10.1.0.0/16,10.255.0.0/24
662
663 ipset add foo 192.168.0/24,192.168.54.0-192.168.54.255
664
665 ipset add foo 192.168.0/30,192.168.64/30 nomatch
666
667 When matching the elements in the set above, all IP addresses will
668 match from the networks 192.168.0.0/24<->10.0.1.0/24,
669 10.1.0.0/16<->10.255.0.0/24 and 192.168.0/24<->192.168.54.0/24 except
670 the ones from 192.168.0/30<->192.168.64/30.
671
672 hash:ip,port
673 The hash:ip,port set type uses a hash to store IP address and port num‐
674 ber pairs. The port number is interpreted together with a protocol
675 (default TCP) and zero protocol number cannot be used.
676
677 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
678 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
679
680 ADD-ENTRY := ipaddr,[proto:]port
681
682 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
683 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
684
685 DEL-ENTRY := ipaddr,[proto:]port
686
687 TEST-ENTRY := ipaddr,[proto:]port
688
689 The [proto:]port part of the elements may be expressed in the following
690 forms, where the range variations are valid when adding or deleting
691 entries:
692
693 portname[-portname]
694 TCP port or range of ports expressed in TCP portname identifiers
695 from /etc/services
696
697 portnumber[-portnumber]
698 TCP port or range of ports expressed in TCP port numbers
699
700 tcp|sctp|udp|udplite:portname|portnumber[-portname|portnumber]
701 TCP, SCTP, UDP or UDPLITE port or port range expressed in port
702 name(s) or port number(s)
703
704 icmp:codename|type/code
705 ICMP codename or type/code. The supported ICMP codename identi‐
706 fiers can always be listed by the help command.
707
708 icmpv6:codename|type/code
709 ICMPv6 codename or type/code. The supported ICMPv6 codename
710 identifiers can always be listed by the help command.
711
712 proto:0
713 All other protocols, as an identifier from /etc/protocols or
714 number. The pseudo port number must be zero.
715
716 The hash:ip,port type of sets require two src/dst parameters of the set
717 match and SET target kernel modules.
718
719 Examples:
720
721 ipset create foo hash:ip,port
722
723 ipset add foo 192.168.1.0/24,80-82
724
725 ipset add foo 192.168.1.1,udp:53
726
727 ipset add foo 192.168.1.1,vrrp:0
728
729 ipset test foo 192.168.1.1,80
730
731 hash:net,port
732 The hash:net,port set type uses a hash to store different sized IP net‐
733 work address and port pairs. The port number is interpreted together
734 with a protocol (default TCP) and zero protocol number cannot be used.
735 Network address with zero prefix size is not accepted either.
736
737 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
738 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
739
740 ADD-ENTRY := netaddr,[proto:]port
741
742 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
743 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
744 skbqueue value ]
745
746 DEL-ENTRY := netaddr,[proto:]port
747
748 TEST-ENTRY := netaddr,[proto:]port
749
750 where netaddr := ip[/cidr]
751
752 For the netaddr part of the elements see the description at the
753 hash:net set type. For the [proto:]port part of the elements see the
754 description at the hash:ip,port set type.
755
756 When adding/deleting/testing entries, if the cidr prefix parameter is
757 not specified, then the host prefix value is assumed. When
758 adding/deleting entries, the exact element is added/deleted and over‐
759 lapping elements are not checked by the kernel. When testing entries,
760 if a host address is tested, then the kernel tries to match the host
761 address in the networks added to the set and reports the result accord‐
762 ingly.
763
764 From the set netfilter match point of view the searching for a match
765 always starts from the smallest size of netblock (most specific
766 prefix) to the largest one (least specific prefix) added to the set.
767 When adding/deleting IP addresses to the set by the SET netfilter
768 target, it will be added/deleted by the most specific prefix which
769 can be found in the set, or by the host prefix value if the set is
770 empty.
771
772 The lookup time grows linearly with the number of the different prefix
773 values added to the set.
774
775 Examples:
776
777 ipset create foo hash:net,port
778
779 ipset add foo 192.168.0/24,25
780
781 ipset add foo 10.1.0.0/16,80
782
783 ipset test foo 192.168.0/24,25
784
785 hash:ip,port,ip
786 The hash:ip,port,ip set type uses a hash to store IP address, port num‐
787 ber and a second IP address triples. The port number is interpreted
788 together with a protocol (default TCP) and zero protocol number cannot
789 be used.
790
791 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
792 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
793
794 ADD-ENTRY := ipaddr,[proto:]port,ip
795
796 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
797 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
798
799 DEL-ENTRY := ipaddr,[proto:]port,ip
800
801 TEST-ENTRY := ipaddr,[proto:]port,ip
802
803 For the first ipaddr and [proto:]port parts of the elements see the
804 descriptions at the hash:ip,port set type.
805
806 The hash:ip,port,ip type of sets require three src/dst parameters of
807 the set match and SET target kernel modules.
808
809 Examples:
810
811 ipset create foo hash:ip,port,ip
812
813 ipset add foo 192.168.1.1,80,10.0.0.1
814
815 ipset test foo 192.168.1.1,udp:53,10.0.0.1
816
817 hash:ip,port,net
818 The hash:ip,port,net set type uses a hash to store IP address, port
819 number and IP network address triples. The port number is interpreted
820 together with a protocol (default TCP) and zero protocol number cannot
821 be used. Network address with zero prefix size cannot be stored either.
822
823 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
824 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
825
826 ADD-ENTRY := ipaddr,[proto:]port,netaddr
827
828 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
829 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
830 skbqueue value ]
831
832 DEL-ENTRY := ipaddr,[proto:]port,netaddr
833
834 TEST-ENTRY := ipaddr,[proto:]port,netaddr
835
836 where netaddr := ip[/cidr]
837
838 For the ipaddr and [proto:]port parts of the elements see the descrip‐
839 tions at the hash:ip,port set type. For the netaddr part of the ele‐
840 ments see the description at the hash:net set type.
841
842 From the set netfilter match point of view the searching for a match
843 always starts from the smallest size of netblock (most specific
844 cidr) to the largest one (least specific cidr) added to the set. When
845 adding/deleting triples to the set by the SET netfilter target, it
846 will be added/deleted by the most specific cidr which can be found in
847 the set, or by the host cidr value if the set is empty.
848
849 The lookup time grows linearly with the number of the different cidr
850 values added to the set.
851
852 The hash:ip,port,net type of sets require three src/dst parameters of
853 the set match and SET target kernel modules.
854
855 Examples:
856
857 ipset create foo hash:ip,port,net
858
859 ipset add foo 192.168.1,80,10.0.0/24
860
861 ipset add foo 192.168.2,25,10.1.0.0/16
862
863 ipset test foo 192.168.1,80.10.0.0/24
864
865 hash:ip,mark
866 The hash:ip,mark set type uses a hash to store IP address and packet
867 mark pairs.
868
869 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ markmask value ] [
870 hashsize value ] [ maxelem value ] [ timeout value ] [ counters ] [
871 comment ] [ skbinfo ]
872
873 ADD-ENTRY := ipaddr,mark
874
875 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
876 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
877
878 DEL-ENTRY := ipaddr,mark
879
880 TEST-ENTRY := ipaddr,mark
881
882 Optional create options:
883
884 markmask value
885 Allows you to set bits you are interested in the packet mark.
886 This values is then used to perform bitwise AND operation for
887 every mark added. markmask can be any value between 1 and
888 4294967295, by default all 32 bits are set.
889
890 The mark can be any value between 0 and 4294967295.
891
892 The hash:ip,mark type of sets require two src/dst parameters of the set
893 match and SET target kernel modules.
894
895 Examples:
896
897 ipset create foo hash:ip,mark
898
899 ipset add foo 192.168.1.0/24,555
900
901 ipset add foo 192.168.1.1,0x63
902
903 ipset add foo 192.168.1.1,111236
904
905 hash:net,port,net
906 The hash:net,port,net set type behaves similarly to hash:ip,port,net
907 but accepts a cidr value for both the first and last parameter. Either
908 subnet is permitted to be a /0 should you wish to match port between
909 all destinations.
910
911 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
912 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
913
914 ADD-ENTRY := netaddr,[proto:]port,netaddr
915
916 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
917 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
918 skbqueue value ]
919
920 DEL-ENTRY := netaddr,[proto:]port,netaddr
921
922 TEST-ENTRY := netaddr,[proto:]port,netaddr
923
924 where netaddr := ip[/cidr]
925
926 For the [proto:]port part of the elements see the description at the
927 hash:ip,port set type. For the netaddr part of the elements see the
928 description at the hash:net set type.
929
930 From the set netfilter match point of view the searching for a match
931 always starts from the smallest size of netblock (most specific
932 cidr) to the largest one (least specific cidr) added to the set. When
933 adding/deleting triples to the set by the SET netfilter target, it
934 will be added/deleted by the most specific cidr which can be found in
935 the set, or by the host cidr value if the set is empty. The first sub‐
936 net has precedence when performing the most-specific lookup, just as
937 for hash:net,net
938
939 The lookup time grows linearly with the number of the different cidr
940 values added to the set and by the number of secondary cidr values per
941 primary.
942
943 The hash:net,port,net type of sets require three src/dst parameters of
944 the set match and SET target kernel modules.
945
946 Examples:
947
948 ipset create foo hash:net,port,net
949
950 ipset add foo 192.168.1.0/24,0,10.0.0/24
951
952 ipset add foo 192.168.2.0/24,25,10.1.0.0/16
953
954 ipset test foo 192.168.1.1,80,10.0.0.1
955
956 hash:net,iface
957 The hash:net,iface set type uses a hash to store different sized IP
958 network address and interface name pairs.
959
960 CREATE-OPTIONS := [ family { inet | inet6 } ] | [ hashsize value ] [
961 maxelem value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
962
963 ADD-ENTRY := netaddr,[physdev:]iface
964
965 ADD-OPTIONS := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
966 value ] [ comment string ] [ skbmark value ] [ skbprio value ] [
967 skbqueue value ]
968
969 DEL-ENTRY := netaddr,[physdev:]iface
970
971 TEST-ENTRY := netaddr,[physdev:]iface
972
973 where netaddr := ip[/cidr]
974
975 For the netaddr part of the elements see the description at the
976 hash:net set type.
977
978 When adding/deleting/testing entries, if the cidr prefix parameter is
979 not specified, then the host prefix value is assumed. When
980 adding/deleting entries, the exact element is added/deleted and over‐
981 lapping elements are not checked by the kernel. When testing entries,
982 if a host address is tested, then the kernel tries to match the host
983 address in the networks added to the set and reports the result accord‐
984 ingly.
985
986 From the set netfilter match point of view the searching for a match
987 always starts from the smallest size of netblock (most specific
988 prefix) to the largest one (least specific prefix) added to the set.
989 When adding/deleting IP addresses to the set by the SET netfilter
990 target, it will be added/deleted by the most specific prefix which
991 can be found in the set, or by the host prefix value if the set is
992 empty.
993
994 The second direction parameter of the set match and SET target modules
995 corresponds to the incoming/outgoing interface: src to the incoming one
996 (similar to the -i flag of iptables), while dst to the outgoing one
997 (similar to the -o flag of iptables). When the interface is flagged
998 with physdev:, the interface is interpreted as the incoming/outgoing
999 bridge port.
1000
1001 The lookup time grows linearly with the number of the different prefix
1002 values added to the set.
1003
1004 The internal restriction of the hash:net,iface set type is that the
1005 same network prefix cannot be stored with more than 64 different inter‐
1006 faces in a single set.
1007
1008 Examples:
1009
1010 ipset create foo hash:net,iface
1011
1012 ipset add foo 192.168.0/24,eth0
1013
1014 ipset add foo 10.1.0.0/16,eth1
1015
1016 ipset test foo 192.168.0/24,eth0
1017
1018 list:set
1019 The list:set type uses a simple list in which you can store set names.
1020
1021 CREATE-OPTIONS := [ size value ] [ timeout value ] [ counters ] [ com‐
1022 ment ] [ skbinfo ]
1023
1024 ADD-ENTRY := setname [ { before | after } setname ]
1025
1026 ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes value ] [
1027 comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
1028
1029 DEL-ENTRY := setname [ { before | after } setname ]
1030
1031 TEST-ENTRY := setname [ { before | after } setname ]
1032
1033 Optional create options:
1034
1035 size value
1036 The size of the list, the default is 8. The parameter is ignored
1037 since ipset version 6.24.
1038
1039 By the ipset command you can add, delete and test set names in a
1040 list:set type of set.
1041
1042 By the set match or SET target of netfilter you can test, add or delete
1043 entries in the sets added to the list:set type of set. The match will
1044 try to find a matching entry in the sets and the target will try to add
1045 an entry to the first set to which it can be added. The number of
1046 direction options of the match and target are important: sets which
1047 require more parameters than specified are skipped, while sets with
1048 equal or less parameters are checked, elements added/deleted. For exam‐
1049 ple if a and b are list:set type of sets then in the command
1050
1051 iptables -m set --match-set a src,dst -j SET --add-set b src,dst
1052
1053 the match and target will skip any set in a and b which stores data
1054 triples, but will match all sets with single or double data storage in
1055 a set and stop matching at the first successful set, and add src to the
1056 first single or src,dst to the first double data storage set in b to
1057 which the entry can be added. You can imagine a list:set type of set as
1058 an ordered union of the set elements.
1059
1060 Please note: by the ipset command you can add, delete and test the set‐
1061 names in a list:set type of set, and not the presence of a set's member
1062 (such as an IP address).
1063
1065 Zero valued set entries cannot be used with hash methods. Zero protocol
1066 value with ports cannot be used.
1067
1069 If you want to store same size subnets from a given network (say /24
1070 blocks from a /8 network), use the bitmap:ip set type. If you want to
1071 store random same size networks (say random /24 blocks), use the
1072 hash:ip set type. If you have got random size of netblocks, use
1073 hash:net.
1074
1075 Backward compatibility is maintained and old ipset syntax is still sup‐
1076 ported.
1077
1078 The iptree and iptreemap set types are removed: if you refer to them,
1079 they are automatically replaced by hash:ip type of sets.
1080
1082 Various error messages are printed to standard error. The exit code is
1083 0 for correct functioning.
1084
1086 Bugs? No, just funny features. :-) OK, just kidding...
1087
1089 iptables(8), ip6tables(8) iptables-extensions(8)
1090
1092 Jozsef Kadlecsik wrote ipset, which is based on ippool by Joakim Axels‐
1093 son, Patrick Schaaf and Martin Josefsson.
1094 Sven Wegener wrote the iptreemap type.
1095
1097 I stand on the shoulders of giants.
1098
1099
1100
1101Jozsef Kadlecsik Jun 25, 2015 IPSET(8)