1IPSET(8)                                                              IPSET(8)
2
3
4

NAME

6       ipset — administration tool for IP sets
7

SYNOPSIS

9       ipset [ OPTIONS ] COMMAND [ COMMAND-OPTIONS ]
10
11       COMMANDS  :=  { create | add | del | test | destroy | list | save | re‐
12       store | flush | rename | swap | help | version | - }
13
14       OPTIONS := { -exist | -output { plain | save | xml } |  -quiet  |  -re‐
15       solve | -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

DESCRIPTION

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
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

OPTIONS

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  de‐
93              stroyed.
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 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
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 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
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 in‐
143              put.   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 al‐
152              ready 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  or  saving sets, the entries are
168              listed sorted.
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

INTRODUCTION

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 en‐
215       try cannot be added to the set.
216

GENERIC CREATE AND ADD OPTIONS

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
229              ipset create test hash:ip timeout 300
230
231              ipset add test 192.168.0.1 timeout 60
232
233              ipset -exist add test 192.168.0.1 timeout 600
234
235       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
241   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
250              ipset create foo hash:ip counters
251
252              ipset add foo 192.168.1.1 packets 42 bytes 1024
253
254   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
263              ipset add foo 1.1.1.1 comment "this comment is \"bad\""
264
265       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
273              ipset create foo hash:ip comment
274
275              ipset  add foo 192.168.1.1/24 comment "allow access to SMB share
276              on \\\\fileserv\\"
277
278              the above would appear as: "allow access to SMB share on \\file‐
279              serv\"
280
281   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
291              ipset create foo hash:ip skbinfo
292
293              ipset add foo 192.168.0.1 skbmark 0x1111/0xff00ffff skbprio 1:10
294              skbqueue 10
295
296   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
302              ipset create test hash:ip hashsize 1536
303
304   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
309              ipset create test hash:ip maxelem 2048
310
311   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
319              ipset create test hash:ip bucketsize 2
320
321   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
329       ipaddr := { ip | fromaddr-toaddr | ip/cidr }
330
331       netaddr := { fromaddr-toaddr | ip/cidr }
332
333       Example:
334
335              ipset create test hash:ip family inet6
336
337   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
344       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
348   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
353              ipset create foo hash:ip forceadd
354
355   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

SET TYPES

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
367       CREATE-OPTIONS  := range fromip-toip|ip/cidr [ netmask cidr ] [ timeout
368       value ] [ counters ] [ comment ] [ skbinfo ]
369
370       ADD-ENTRY := { ip | fromip-toip | ip/cidr }
371
372       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
373       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
374
375       DEL-ENTRY := { ip | fromip-toip | ip/cidr }
376
377       TEST-ENTRY := ip
378
379       Mandatory create options:
380
381       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
387       Optional create options:
388
389       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
396       The bitmap:ip type supports adding or deleting multiple entries in  one
397       command.
398
399       Examples:
400
401              ipset create foo bitmap:ip range 192.168.0.0/16
402
403              ipset add foo 192.168.1/24
404
405              ipset test foo 192.168.1.1
406
407   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
412       CREATE-OPTIONS  :=  range fromip-toip|ip/cidr [ timeout value ] [ coun‐
413       ters ] [ comment ] [ skbinfo ]
414
415       ADD-ENTRY := ip[,macaddr]
416
417       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
418       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
419
420       DEL-ENTRY := ip[,macaddr]
421
422       TEST-ENTRY := ip[,macaddr]
423
424       Mandatory options to use when creating a bitmap:ip,mac type of set:
425
426       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
431       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
442       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
446       Examples:
447
448              ipset create foo bitmap:ip,mac range 192.168.0.0/16
449
450              ipset add foo 192.168.1.1,12:34:56:78:9A:BC
451
452              ipset test foo 192.168.1.1
453
454   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
458       CREATE-OPTIONS  := range fromport-toport [ timeout value ] [ counters ]
459       [ comment ] [ skbinfo ]
460
461       ADD-ENTRY := { [proto:]port | [proto:]fromport-toport }
462
463       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
464       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
465
466       DEL-ENTRY := { [proto:]port | [proto:]fromport-toport }
467
468       TEST-ENTRY := [proto:]port
469
470       Mandatory options to use when creating a bitmap:port type of set:
471
472       range [proto:]fromport-toport
473              Create the set from the specified inclusive port range.
474
475       The  set  match  and  SET target netfilter kernel modules interpret the
476       stored numbers as TCP or UDP port numbers.
477
478       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
482       Examples:
483
484              ipset create foo bitmap:port range 0-1024
485
486              ipset add foo 80
487
488              ipset test foo 80
489
490              ipset del foo udp:[macon-udp]-[tn-tl-w2]
491
492   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
497       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
498       elem  value ] [ bucketsize value ] [ netmask cidr ] [ timeout value ] [
499       counters ] [ comment ] [ skbinfo ]
500
501       ADD-ENTRY := ipaddr
502
503       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
504       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
505
506       DEL-ENTRY := ipaddr
507
508       TEST-ENTRY := ipaddr
509
510       Optional create options:
511
512       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
520              ipset create foo hash:ip netmask 30
521
522              ipset add foo 192.168.1.0/24
523
524              ipset test foo 192.168.1.2
525
526   hash:mac
527       The hash:mac set type uses a hash to store MAC addresses.  Zero  valued
528       MAC  addresses  cannot be stored in a hash:mac type of set. For matches
529       on destination MAC addresses, see COMMENTS below.
530
531       CREATE-OPTIONS := [ hashsize value ] [ maxelem  value  ]  [  bucketsize
532       value ] [ timeout value ] [ counters ] [ comment ] [ skbinfo ]
533
534       ADD-ENTRY := macaddr
535
536       ADD-OPTIONS  :=  [  timeout value ] [ packets value ] [ bytes value ] [
537       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
538
539       DEL-ENTRY := macaddr
540
541       TEST-ENTRY := macaddr
542
543       Examples:
544
545              ipset create foo hash:mac
546
547              ipset add foo 01:02:03:04:05:06
548
549              ipset test foo 01:02:03:04:05:06
550
551
552   hash:ip,mac
553       The hash:ip,mac set type uses a hash to store  IP  and  a  MAC  address
554       pairs. Zero valued MAC addresses cannot be stored in a hash:ip,mac type
555       of set. For matches on destination MAC addresses, see COMMENTS below.
556
557       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
558       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
559       ment ] [ skbinfo ]
560
561       ADD-ENTRY := ipaddr,macaddr
562
563       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
564       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
565
566       DEL-ENTRY := ipaddr,macaddr
567
568       TEST-ENTRY := ipaddr,macaddr
569
570       Examples:
571
572              ipset create foo hash:ip,mac
573
574              ipset add foo 1.1.1.1,01:02:03:04:05:06
575
576              ipset test foo 1.1.1.1,01:02:03:04:05:06
577
578
579   hash:net
580       The  hash:net  set type uses a hash to store different sized IP network
581       addresses.  Network address with zero prefix size cannot be  stored  in
582       this type of sets.
583
584       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
585       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
586       ment ] [ skbinfo ]
587
588       ADD-ENTRY := netaddr
589
590       ADD-OPTIONS  := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
591       value ] [ comment string ] [ skbmark  value  ]  [  skbprio  value  ]  [
592       skbqueue value ]
593
594       DEL-ENTRY := netaddr
595
596       TEST-ENTRY := netaddr
597
598       where netaddr := ip[/cidr]
599
600       When  adding/deleting/testing  entries, if the cidr prefix parameter is
601       not  specified,  then  the  host  prefix   value   is   assumed.   When
602       adding/deleting  entries,  the exact element is added/deleted and over‐
603       lapping elements are not checked by the kernel.  When testing  entries,
604       if  a  host  address is tested, then the kernel tries to match the host
605       address in the networks added to the set and reports the result accord‐
606       ingly.
607
608       From  the  set  netfilter match point of view the searching for a match
609       always  starts  from  the smallest  size  of  netblock  (most  specific
610       prefix)  to  the  largest one (least specific prefix) added to the set.
611       When  adding/deleting IP addresses  to the set  by  the  SET  netfilter
612       target,  it   will   be added/deleted by the most specific prefix which
613       can be found in  the set, or by the host prefix value  if  the  set  is
614       empty.
615
616       The  lookup time grows linearly with the number of the different prefix
617       values added to the set.
618
619       Example:
620
621              ipset create foo hash:net
622
623              ipset add foo 192.168.0.0/24
624
625              ipset add foo 10.1.0.0/16
626
627              ipset add foo 192.168.0/24
628
629              ipset add foo 192.168.0/30 nomatch
630
631       When matching the elements in the set  above,  all  IP  addresses  will
632       match  from  the  networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24
633       except the ones from 192.168.0/30.
634
635   hash:net,net
636       The hash:net,net set type uses a hash to store pairs of different sized
637       IP  network  addresses.  Bear  in  mind  that  the  first parameter has
638       precedence over the second, so a nomatch entry could be potentially  be
639       ineffective  if a more specific first parameter existed with a suitable
640       second parameter.  Network address with  zero  prefix  size  cannot  be
641       stored in this type of set.
642
643       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
644       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
645       ment ] [ skbinfo ]
646
647       ADD-ENTRY := netaddr,netaddr
648
649       ADD-OPTIONS  := [ timeout value ] [ nomatch ] [ packets value ] [ bytes
650       value ] [ comment string ] [ skbmark  value  ]  [  skbprio  value  ]  [
651       skbqueue value ]
652
653       DEL-ENTRY := netaddr,netaddr
654
655       TEST-ENTRY := netaddr,netaddr
656
657       where netaddr := ip[/cidr]
658
659       When  adding/deleting/testing  entries, if the cidr prefix parameter is
660       not  specified,  then  the  host  prefix   value   is   assumed.   When
661       adding/deleting  entries,  the exact element is added/deleted and over‐
662       lapping elements are not checked by the kernel.  When testing  entries,
663       if  a  host  address is tested, then the kernel tries to match the host
664       address in the networks added to the set and reports the result accord‐
665       ingly.
666
667       From  the  set  netfilter match point of view the searching for a match
668       always  starts  from  the smallest  size  of  netblock  (most  specific
669       prefix) to the largest one (least specific prefix) with the first param
670       having precedence.  When  adding/deleting IP addresses  to the  set  by
671       the  SET  netfilter  target,  it  will  be  added/deleted  by  the most
672       specific prefix which can be found in the set, or by  the  host  prefix
673       value if the set is empty.
674
675       The  lookup time grows linearly with the number of the different prefix
676       values added to the first parameter of the set. The number of secondary
677       prefixes  further  increases  this as the list of secondary prefixes is
678       traversed per primary prefix.
679
680       Example:
681
682              ipset create foo hash:net,net
683
684              ipset add foo 192.168.0.0/24,10.0.1.0/24
685
686              ipset add foo 10.1.0.0/16,10.255.0.0/24
687
688              ipset add foo 192.168.0/24,192.168.54.0-192.168.54.255
689
690              ipset add foo 192.168.0/30,192.168.64/30 nomatch
691
692       When matching the elements in the set  above,  all  IP  addresses  will
693       match      from      the     networks     192.168.0.0/24<->10.0.1.0/24,
694       10.1.0.0/16<->10.255.0.0/24 and  192.168.0/24<->192.168.54.0/24  except
695       the ones from 192.168.0/30<->192.168.64/30.
696
697   hash:ip,port
698       The hash:ip,port set type uses a hash to store IP address and port num‐
699       ber pairs.  The port number is interpreted  together  with  a  protocol
700       (default TCP) and zero protocol number cannot be used.
701
702       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
703       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
704       ment ] [ skbinfo ]
705
706       ADD-ENTRY := ipaddr,[proto:]port
707
708       ADD-OPTIONS  :=  [  timeout value ] [ packets value ] [ bytes value ] [
709       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
710
711       DEL-ENTRY := ipaddr,[proto:]port
712
713       TEST-ENTRY := ipaddr,[proto:]port
714
715       The [proto:]port part of the elements may be expressed in the following
716       forms, where the range variations are valid when adding or deleting en‐
717       tries:
718
719       portname[-portname]
720              TCP port or range of ports expressed in TCP portname identifiers
721              from /etc/services
722
723       portnumber[-portnumber]
724              TCP port or range of ports expressed in TCP port numbers
725
726       tcp|sctp|udp|udplite:portname|portnumber[-portname|portnumber]
727              TCP,  SCTP,  UDP or UDPLITE port or port range expressed in port
728              name(s) or port number(s)
729
730       icmp:codename|type/code
731              ICMP codename or type/code. The supported ICMP codename  identi‐
732              fiers can always be listed by the help command.
733
734       icmpv6:codename|type/code
735              ICMPv6  codename  or  type/code.  The  supported ICMPv6 codename
736              identifiers can always be listed by the help command.
737
738       proto:0
739              All other protocols, as an  identifier  from  /etc/protocols  or
740              number. The pseudo port number must be zero.
741
742       The hash:ip,port type of sets require two src/dst parameters of the set
743       match and SET target kernel modules.
744
745       Examples:
746
747              ipset create foo hash:ip,port
748
749              ipset add foo 192.168.1.0/24,80-82
750
751              ipset add foo 192.168.1.1,udp:53
752
753              ipset add foo 192.168.1.1,vrrp:0
754
755              ipset test foo 192.168.1.1,80
756
757   hash:net,port
758       The hash:net,port set type uses a hash to store different sized IP net‐
759       work  address  and  port pairs. The port number is interpreted together
760       with a protocol (default TCP) and zero protocol number cannot be  used.
761       Network address with zero prefix size is not accepted either.
762
763       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
764       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
765       ment ] [ skbinfo ]
766
767       ADD-ENTRY := netaddr,[proto:]port
768
769       ADD-OPTIONS := [ timeout value ]  [ nomatch ] [ packets value ] [ bytes
770       value ] [ comment string ] [ skbmark  value  ]  [  skbprio  value  ]  [
771       skbqueue value ]
772
773       DEL-ENTRY := netaddr,[proto:]port
774
775       TEST-ENTRY := netaddr,[proto:]port
776
777       where netaddr := ip[/cidr]
778
779       For  the  netaddr  part  of  the  elements  see  the description at the
780       hash:net set type. For the [proto:]port part of the  elements  see  the
781       description at the hash:ip,port set type.
782
783       When  adding/deleting/testing  entries, if the cidr prefix parameter is
784       not  specified,  then  the  host  prefix   value   is   assumed.   When
785       adding/deleting  entries,  the exact element is added/deleted and over‐
786       lapping elements are not checked by the kernel.  When testing  entries,
787       if  a  host  address is tested, then the kernel tries to match the host
788       address in the networks added to the set and reports the result accord‐
789       ingly.
790
791       From  the  set netfilter match point of view the searching for a  match
792       always  starts  from  the smallest  size  of  netblock  (most  specific
793       prefix)  to  the  largest one (least specific prefix) added to the set.
794       When  adding/deleting IP addresses  to the set  by  the  SET  netfilter
795       target,  it   will   be added/deleted by the most specific prefix which
796       can be found in  the set, or by the host prefix value  if  the  set  is
797       empty.
798
799       The  lookup time grows linearly with the number of the different prefix
800       values added to the set.
801
802       Examples:
803
804              ipset create foo hash:net,port
805
806              ipset add foo 192.168.0/24,25
807
808              ipset add foo 10.1.0.0/16,80
809
810              ipset test foo 192.168.0/24,25
811
812   hash:ip,port,ip
813       The hash:ip,port,ip set type uses a hash to store IP address, port num‐
814       ber and a second IP address triples. The port number is interpreted to‐
815       gether with a protocol (default TCP) and zero protocol number cannot be
816       used.
817
818       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
819       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
820       ment ] [ skbinfo ]
821
822       ADD-ENTRY := ipaddr,[proto:]port,ip
823
824       ADD-OPTIONS  :=  [  timeout value ] [ packets value ] [ bytes value ] [
825       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
826
827       DEL-ENTRY := ipaddr,[proto:]port,ip
828
829       TEST-ENTRY := ipaddr,[proto:]port,ip
830
831       For the first ipaddr and [proto:]port parts of the elements see the de‐
832       scriptions at the hash:ip,port set type.
833
834       The  hash:ip,port,ip  type  of sets require three src/dst parameters of
835       the set match and SET target kernel modules.
836
837       Examples:
838
839              ipset create foo hash:ip,port,ip
840
841              ipset add foo 192.168.1.1,80,10.0.0.1
842
843              ipset test foo 192.168.1.1,udp:53,10.0.0.1
844
845   hash:ip,port,net
846       The hash:ip,port,net set type uses a hash to  store  IP  address,  port
847       number  and  IP network address triples. The port number is interpreted
848       together with a protocol (default TCP) and zero protocol number  cannot
849       be used. Network address with zero prefix size cannot be stored either.
850
851       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
852       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
853       ment ] [ skbinfo ]
854
855       ADD-ENTRY := ipaddr,[proto:]port,netaddr
856
857       ADD-OPTIONS := [ timeout value ]  [ nomatch ] [ packets value ] [ bytes
858       value ] [ comment string ] [ skbmark  value  ]  [  skbprio  value  ]  [
859       skbqueue value ]
860
861       DEL-ENTRY := ipaddr,[proto:]port,netaddr
862
863       TEST-ENTRY := ipaddr,[proto:]port,netaddr
864
865       where netaddr := ip[/cidr]
866
867       For  the ipaddr and [proto:]port parts of the elements see the descrip‐
868       tions at the hash:ip,port set type. For the netaddr part  of  the  ele‐
869       ments see the description at the hash:net set type.
870
871       From  the  set  netfilter match point of view the searching for a match
872       always  starts  from  the smallest  size  of  netblock  (most  specific
873       cidr)  to the largest one (least specific cidr) added to the set.  When
874       adding/deleting triples to the set by  the  SET  netfilter  target,  it
875       will   be added/deleted by the most specific cidr which can be found in
876       the set, or by the host cidr value if the set is empty.
877
878       The lookup time grows linearly with the number of  the  different  cidr
879       values added to the set.
880
881       The  hash:ip,port,net  type of sets require three src/dst parameters of
882       the set match and SET target kernel modules.
883
884       Examples:
885
886              ipset create foo hash:ip,port,net
887
888              ipset add foo 192.168.1,80,10.0.0/24
889
890              ipset add foo 192.168.2,25,10.1.0.0/16
891
892              ipset test foo 192.168.1,80.10.0.0/24
893
894   hash:ip,mark
895       The hash:ip,mark set type uses a hash to store IP  address  and  packet
896       mark pairs.
897
898       CREATE-OPTIONS  :=  [  family  {  inet | inet6 } ] [ markmask value ] [
899       hashsize value ] [ maxelem value ] [ bucketsize value ] [ timeout value
900       ] [ counters ] [ comment ] [ skbinfo ]
901
902       ADD-ENTRY := ipaddr,mark
903
904       ADD-OPTIONS  :=  [  timeout value ] [ packets value ] [ bytes value ] [
905       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
906
907       DEL-ENTRY := ipaddr,mark
908
909       TEST-ENTRY := ipaddr,mark
910
911       Optional create options:
912
913       markmask value
914              Allows you to set bits you are interested in  the  packet  mark.
915              This  values  is  then used to perform bitwise AND operation for
916              every mark added.  markmask can  be  any  value  between  1  and
917              4294967295, by default all 32 bits are set.
918
919       The mark can be any value between 0 and 4294967295.
920
921       The hash:ip,mark type of sets require two src/dst parameters of the set
922       match and SET target kernel modules.
923
924       Examples:
925
926              ipset create foo hash:ip,mark
927
928              ipset add foo 192.168.1.0/24,555
929
930              ipset add foo 192.168.1.1,0x63
931
932              ipset add foo 192.168.1.1,111236
933
934   hash:net,port,net
935       The hash:net,port,net set type behaves  similarly  to  hash:ip,port,net
936       but  accepts a cidr value for both the first and last parameter. Either
937       subnet is permitted to be a /0 should you wish to  match  port  between
938       all destinations.
939
940       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
941       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
942       ment ] [ skbinfo ]
943
944       ADD-ENTRY := netaddr,[proto:]port,netaddr
945
946       ADD-OPTIONS := [ timeout value ]  [ nomatch ] [ packets value ] [ bytes
947       value ] [ comment string ] [ skbmark  value  ]  [  skbprio  value  ]  [
948       skbqueue value ]
949
950       DEL-ENTRY := netaddr,[proto:]port,netaddr
951
952       TEST-ENTRY := netaddr,[proto:]port,netaddr
953
954       where netaddr := ip[/cidr]
955
956       For  the  [proto:]port  part of the elements see the description at the
957       hash:ip,port set type. For the netaddr part of the elements see the de‐
958       scription at the hash:net set type.
959
960       From  the  set  netfilter match point of view the searching for a match
961       always  starts  from  the smallest  size  of  netblock  (most  specific
962       cidr)  to the largest one (least specific cidr) added to the set.  When
963       adding/deleting triples to the set by  the  SET  netfilter  target,  it
964       will   be added/deleted by the most specific cidr which can be found in
965       the set, or by the host cidr value if the set is empty. The first  sub‐
966       net  has  precedence  when performing the most-specific lookup, just as
967       for hash:net,net
968
969       The lookup time grows linearly with the number of  the  different  cidr
970       values  added to the set and by the number of secondary cidr values per
971       primary.
972
973       The hash:net,port,net type of sets require three src/dst parameters  of
974       the set match and SET target kernel modules.
975
976       Examples:
977
978              ipset create foo hash:net,port,net
979
980              ipset add foo 192.168.1.0/24,0,10.0.0/24
981
982              ipset add foo 192.168.2.0/24,25,10.1.0.0/16
983
984              ipset test foo 192.168.1.1,80,10.0.0.1
985
986   hash:net,iface
987       The  hash:net,iface  set  type  uses a hash to store different sized IP
988       network address and interface name pairs.
989
990       CREATE-OPTIONS := [ family { inet | inet6 } ] [ hashsize value ] [ max‐
991       elem value ] [ bucketsize value ] [ timeout value ] [ counters ] [ com‐
992       ment ] [ skbinfo ]
993
994       ADD-ENTRY := netaddr,[physdev:]iface
995
996       ADD-OPTIONS := [ timeout value ]  [ nomatch ] [ packets value ] [ bytes
997       value  ]  [  comment  string  ]  [  skbmark value ] [ skbprio value ] [
998       skbqueue value ] [ wildcard ]
999
1000       DEL-ENTRY := netaddr,[physdev:]iface
1001
1002       TEST-ENTRY := netaddr,[physdev:]iface
1003
1004       where netaddr := ip[/cidr]
1005
1006       For the netaddr part  of  the  elements  see  the  description  at  the
1007       hash:net set type.
1008
1009       When  adding/deleting/testing  entries, if the cidr prefix parameter is
1010       not  specified,  then  the  host  prefix   value   is   assumed.   When
1011       adding/deleting  entries,  the exact element is added/deleted and over‐
1012       lapping elements are not checked by the kernel.  When testing  entries,
1013       if  a  host  address is tested, then the kernel tries to match the host
1014       address in the networks added to the set and reports the result accord‐
1015       ingly.
1016
1017       From  the  set netfilter match point of view the searching for a  match
1018       always  starts  from  the smallest  size  of  netblock  (most  specific
1019       prefix)  to  the  largest one (least specific prefix) added to the set.
1020       When  adding/deleting IP addresses  to the set  by  the  SET  netfilter
1021       target,  it   will   be added/deleted by the most specific prefix which
1022       can be found in  the set, or by the host prefix value  if  the  set  is
1023       empty.
1024
1025       The  second direction parameter of the set match and SET target modules
1026       corresponds to the incoming/outgoing interface: src to the incoming one
1027       (similar  to  the  -i  flag of iptables), while dst to the outgoing one
1028       (similar to the -o flag of iptables). When  the  interface  is  flagged
1029       with  physdev:,  the  interface is interpreted as the incoming/outgoing
1030       bridge port.
1031
1032       The lookup time grows linearly with the number of the different  prefix
1033       values added to the set.
1034
1035       The  internal  restriction  of  the hash:net,iface set type is that the
1036       same network prefix cannot be stored with more than 64 different inter‐
1037       faces in a single set.
1038
1039       Examples:
1040
1041              ipset create foo hash:net,iface
1042
1043              ipset add foo 192.168.0/24,eth0
1044
1045              ipset add foo 10.1.0.0/16,eth1
1046
1047              ipset test foo 192.168.0/24,eth0
1048
1049   list:set
1050       The list:set type uses a simple list in which you can store set names.
1051
1052       CREATE-OPTIONS  := [ size value ] [ timeout value ] [ counters ] [ com‐
1053       ment ] [ skbinfo ]
1054
1055       ADD-ENTRY := setname [ { before | after } setname ]
1056
1057       ADD-OPTIONS := [ timeout value ] [ packets value ] [ bytes  value  ]  [
1058       comment string ] [ skbmark value ] [ skbprio value ] [ skbqueue value ]
1059
1060       DEL-ENTRY := setname [ { before | after } setname ]
1061
1062       TEST-ENTRY := setname [ { before | after } setname ]
1063
1064       Optional create options:
1065
1066       size value
1067              The size of the list, the default is 8. The parameter is ignored
1068              since ipset version 6.24.
1069
1070       By the ipset command you  can add, delete  and  test  set  names  in  a
1071       list:set type of set.
1072
1073       By the set match or SET target of netfilter you can test, add or delete
1074       entries in the sets added to the list:set type of set. The  match  will
1075       try to find a matching entry in the sets and the target will try to add
1076       an entry to the first set to which it can be added.  The number of  di‐
1077       rection  options  of the match and target are important: sets which re‐
1078       quire more parameters than specified are skipped, while sets with equal
1079       or  less parameters are checked, elements added/deleted. For example if
1080       a and b are list:set type of sets then in the command
1081
1082              iptables -m set --match-set a src,dst -j SET --add-set b src,dst
1083
1084       the match and target will skip any set in a and  b  which  stores  data
1085       triples,  but will match all sets with single or double data storage in
1086       a set and stop matching at the first successful set, and add src to the
1087       first  single  or  src,dst to the first double data storage set in b to
1088       which the entry can be added. You can imagine a list:set type of set as
1089       an ordered union of the set elements.
1090
1091       Please note: by the ipset command you can add, delete and test the set‐
1092       names in a list:set type of set, and not the presence of a set's member
1093       (such as an IP address).
1094

GENERAL RESTRICTIONS

1096       Zero valued set entries cannot be used with hash methods. Zero protocol
1097       value with ports cannot be used.
1098

COMMENTS

1100       If you want to store same size subnets from a given  network  (say  /24
1101       blocks  from a /8 network), use the bitmap:ip set type.  If you want to
1102       store random same size  networks  (say  random  /24  blocks),  use  the
1103       hash:ip  set  type.  If  you  have  got  random  size of netblocks, use
1104       hash:net.
1105
1106       Matching on destination MAC addresses using the dst  parameter  of  the
1107       set  match  netfilter  kernel modules will only work if the destination
1108       MAC address is available in the packet at the given  processing  stage,
1109       that  is, it only applies for incoming packets in the PREROUTING, INPUT
1110       and FORWARD chains, against the MAC address as originally found in  the
1111       received  packet  (typically,  one  of  the  MAC addresses of the local
1112       host). This is not the destination MAC address a destination IP address
1113       resolves  to,  after routing. If the MAC address is not available (e.g.
1114       in the OUTPUT chain), the packet will simply not match.
1115
1116       Backward compatibility is maintained and old ipset syntax is still sup‐
1117       ported.
1118
1119       The  iptree  and iptreemap set types are removed: if you refer to them,
1120       they are automatically replaced by hash:ip type of sets.
1121

DIAGNOSTICS

1123       Various error messages are printed to standard error.  The exit code is
1124       0 for correct functioning.
1125

BUGS

1127       Bugs? No, just funny features. :-) OK, just kidding...
1128

SEE ALSO

1130       iptables(8), ip6tables(8) iptables-extensions(8)
1131

AUTHORS

1133       Jozsef Kadlecsik wrote ipset, which is based on ippool by Joakim Axels‐
1134       son, Patrick Schaaf and Martin Josefsson.
1135       Sven Wegener wrote the iptreemap type.
1136

LAST REMARK

1138       I stand on the shoulders of giants.
1139
1140
1141
1142Jozsef Kadlecsik                 Jun 25, 2015                         IPSET(8)
Impressum