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

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

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

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

SET TYPES

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

GENERAL RESTRICTIONS

1065       Zero valued set entries cannot be used with hash methods. Zero protocol
1066       value with ports cannot be used.
1067

COMMENTS

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

DIAGNOSTICS

1082       Various error messages are printed to standard error.  The exit code is
1083       0 for correct functioning.
1084

BUGS

1086       Bugs? No, just funny features. :-) OK, just kidding...
1087

SEE ALSO

1089       iptables(8), ip6tables(8) iptables-extensions(8)
1090

AUTHORS

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

LAST REMARK

1097       I stand on the shoulders of giants.
1098
1099
1100
1101Jozsef Kadlecsik                 Jun 25, 2015                         IPSET(8)
Impressum