1
.TH IPSET 8 "Feb 05, 2004" "" ""
3
.\" Man page written by Jozsef Kadlecsik <kadlec@blackhole.kfki.hu>
5
.\" This program is free software; you can redistribute it and/or modify
6
.\" it under the terms of the GNU General Public License as published by
7
.\" the Free Software Foundation; either version 2 of the License, or
8
.\" (at your option) any later version.
10
.\" This program is distributed in the hope that it will be useful,
11
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
.\" GNU General Public License for more details.
15
.\" You should have received a copy of the GNU General Public License
16
.\" along with this program; if not, write to the Free Software
17
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21
ipset \(em administration tool for IP sets
24
\fBipset \-N\fP \fIset\fP \fItype-specification\fP [\fIoptions\fP...]
26
\fBipset\fP {\fB\-F\fP|\fB\-H\fP|\fB\-L\fP|\fB\-S\fP|\fB\-X\fP} [\fIset\fP]
29
\fBipset\fP {\fB\-E\fP|\fB\-W\fP} \fIfrom-set\fP \fIto-set\fP
31
\fBipset\fP {\fB\-A\fP|\fB\-D\fP|\fB\-T\fP} \fIset\fP \fIentry\fP
35
\fBipset\fP {\fB-V\fP|\fB\-v\fP}
38
is used to set up, maintain and inspect so called IP sets in the Linux
39
kernel. Depending on the type, an IP set may store IP addresses, (TCP/UDP)
40
port numbers or additional informations besides IP addresses: the word IP
41
means a general term here. See the set type definitions below.
43
Iptables matches and targets referring to sets creates references, which
44
protects the given sets in the kernel. A set cannot be removed (destroyed)
45
while there is a single reference pointing to it.
47
The options that are recognized by
49
can be divided into several different groups.
51
These options specify the specific action to perform. Only one of them
52
can be specified on the command line unless otherwise specified
53
below. For all the long versions of the command and option names, you
54
need to use only enough letters to ensure that
56
can differentiate it from all other options.
58
\fB\-N\fP, \fB\-\-create\fP \fIsetname\fP \fItype\fP \fItype-specific-options\fP
59
Create a set identified with setname and specified type.
60
Type-specific options must be supplied.
62
\fB\-X\fP, \fB\-\-destroy\fP [\fIsetname\fP]
63
Destroy the specified set or all the sets if none is given.
65
If the set has got references, nothing is done.
67
\fB\-F\fP, \fB\-\-flush\fP [\fIsetname\fP]
68
Delete all entries from the specified set or flush
69
all sets if none is given.
71
\fB\-E\fP, \fB\-\-rename\fP \fIfrom-setname\fP \fIto-setname\fP
72
Rename a set. Set identified by to-setname must not exist.
74
\fB\-W\fP, \fB\-\-swap\fP \fIfrom-setname\fP \fIto-setname\fP
75
Swap the content of two sets, or in another words,
76
exchange the name of two sets. The referred sets must exist and
77
identical type of sets can be swapped only.
79
\fB\-L\fP, \fB\-\-list\fP [\fIsetname\fP]
80
List the entries for the specified set, or for
81
all sets if none is given. The
82
\fB\-r\fP/\fB\-\-resolve\fP
83
option can be used to force name lookups (which may be slow). When the
84
\fB\-s\fP/\fB\-\-sorted\fP
85
option is given, the entries are listed sorted (if the given set
86
type supports the operation).
88
\fB\-S\fP, \fB\-\-save\fP [\fIsetname\fP]
89
Save the given set, or all sets if none is given
90
to stdout in a format that \fB\-\-restore\fP can read.
92
\fB\-R\fP, \fB\-\-restore\fP
93
Restore a saved session generated by \fB\-\-save\fP. The saved session
94
can be fed from stdin.
96
When generating a session file please note that the supported commands
97
(create set and add element) must appear in a strict order: first create
98
the set, then add all elements. Then create the next set, add all its elements
99
and so on. Also, it is a restore operation, so the sets being restored must
102
\fB\-A\fP, \fB\-\-add\fP \fIsetname\fP \fIentry\fP
103
Add an entry to a set.
105
\fB\-D\fP, \fB\-\-del\fP \fIsetname\fP \fIentry\fP
106
Delete an entry from a set.
108
\fB-T\fP, \fB\-\-test\fP \fIsetname\fP \fIentry\fP
109
Test wether an entry is in a set or not. Exit status number is zero
110
if the tested entry is in the set and nonzero if it is missing from
113
\fB\-H\fP, \fB\-\-help\fP [\fIsettype\fP]
114
Print help and settype specific help if settype specified.
116
\fB\-V\fP, \fB\-v\fP, \fB\-\-version\fP
117
Print program version and protocol version.
120
The following additional options can be specified:
122
\fB\-r\fP, \fB\-\-resolve\fP
123
When listing sets, enforce name lookup. The
124
program will try to display the IP entries resolved to
125
host names or services (whenever applicable), which can trigger
131
\fB\-s\fP, \fB\-\-sorted\fP
132
Sorted output. When listing sets, entries are listed sorted.
134
\fB\-n\fP, \fB\-\-numeric\fP
135
Numeric output. When listing sets, IP addresses and
136
port numbers will be printed in numeric format. This is the default.
138
\fB\-q\fP, \fB\-\-quiet\fP
139
Suppress any output to stdout and stderr. ipset will still return
142
ipset supports the following set types:
144
The ipmap set type uses a memory range, where each bit represents
145
one IP address. An ipmap set can store up to 65536 (B-class network)
146
IP addresses. The ipmap set type is very fast and memory cheap, great
147
for use when one want to match certain IPs in a range. If the optional
149
parameter is specified with a CIDR netmask value between 1-31 then
150
network addresses are stored in the given set: i.e an
151
IP address will be in the set if the network address, which is resulted
152
by masking the address with the specified netmask, can be found in the set.
154
Options to use when creating an ipmap set:
156
\fB\-\-from\fP \fIfrom-addr\fP
158
\fB\-\-to\fP \fIto-addr\fP
159
Create an ipmap set from the specified address range.
161
\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
162
Create an ipmap set from the specified network.
164
\fB\-\-netmask\fP \fIprefixlen\fP
167
parameter specified, network addresses will be
168
stored in the set instead of IP addresses, and the \fIfrom-addr\fP parameter
169
must be a network address. The \fIprefixlen\fP value must be between 1-31.
173
ipset \-N test ipmap \-\-network 192.168.0.0/16
175
The macipmap set type uses a memory range, where each 8 bytes
176
represents one IP and a MAC addresses. A macipmap set type can store
177
up to 65536 (B-class network) IP addresses with MAC.
178
When adding an entry to a macipmap set, you must specify the entry as
179
"\fIaddress\fP\fB,\fP\fImac\fP".
180
When deleting or testing macipmap entries, the
182
part is not mandatory.
184
Options to use when creating an macipmap set:
186
\fB\-\-from\fP \fIfrom-addr\fP
188
\fB\-\-to\fP \fIto-addr\fP
189
Create a macipmap set from the specified address range.
191
\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
192
Create a macipmap set from the specified network.
197
parameter specified, IP addresses which could be stored
198
in the set but not set yet, will always match.
204
netfilter kernel modules
207
use the source MAC address from the packet to match, add or delete
208
entries from a macipmap type of set.
210
The portmap set type uses a memory range, where each bit represents
211
one port. A portmap set type can store up to 65536 ports.
212
The portmap set type is very fast and memory cheap.
214
Options to use when creating an portmap set:
216
\fB\-\-from\fP \fIfrom-port\fP
218
\fB\-\-to\fP \fIto-port\fP
219
Create a portmap set from the specified port range.
221
The iphash set type uses a hash to store IP addresses.
222
In order to avoid clashes in the hash double-hashing, and as a last
223
resort, dynamic growing of the hash performed. The iphash set type is
224
great to store random addresses. If the optional
226
parameter is specified with a CIDR prefix length value between 1-31 then
227
network addresses are stored in the given set: i.e an
228
IP address will be in the set if the network address, which is resulted
229
by masking the address with the specified netmask, can be found in the set.
231
Options to use when creating an iphash set:
233
\fB\-\-hashsize\fP \fIhashsize\fP
234
The initial hash size (default 1024)
236
\fB\-\-probes\fP \fIprobes\fP
237
How many times try to resolve clashing at adding an IP to the hash
238
by double-hashing (default 8).
240
\fB\-\-resize\fP \fIpercent\fP
241
Increase the hash size by this many percent (default 50) when adding
242
an IP to the hash could not be performed after
244
number of double-hashing.
246
\fB\-\-netmask\fP \fIprefixlen\fP
249
parameter specified, network addresses will be
250
stored in the set instead of IP addresses. The \fIprefixlen\fP value must
253
The iphash type of sets can store up to 65536 entries. If a set is full,
254
no new entries can be added to it.
256
Sets created by zero valued resize parameter won't be resized at all.
257
The lookup time in an iphash type of set grows approximately linearly with
260
parameter. In general higher
262
value results better utilized hash while smaller value
263
produces larger, sparser hash.
267
ipset \-N test iphash \-\-probes 2
269
The nethash set type uses a hash to store different size of
270
network addresses. The
273
used in the ipset commands must be in the form
274
"\fIaddress\fP\fB/\fP\fIprefixlen\fP"
275
where prefixlen must be in the inclusive range of 1-31.
276
In order to avoid clashes in the hash
277
double-hashing, and as a last resort, dynamic growing of the hash performed.
279
Options to use when creating an nethash set:
281
\fB\-\-hashsize\fP \fIhashsize\fP
282
The initial hash size (default 1024)
284
\fB\-\-probes\fP \fIprobes\fP
285
How many times try to resolve clashing at adding an IP to the hash
286
by double-hashing (default 4).
288
\fB\-\-resize\fP \fIpercent\fP
289
Increase the hash size by this many percent (default 50) when adding
290
an IP to the hash could not be performed after
292
The nethash type of sets can store up to 65536 entries. If a set is full,
293
no new entries can be added to it.
295
An IP address will be in a nethash type of set if it belongs to any of the
296
netblocks added to the set. The matching always start from the smallest
297
size of netblock (most specific netmask) to the largest ones (least
298
specific netmasks). When adding/deleting IP addresses
299
to a nethash set by the
301
netfilter kernel module, it will be added/deleted by the smallest
302
netblock size which can be found in the set, or by /31 if the set is empty.
304
The lookup time in a nethash type of set grows approximately linearly
305
with the times of the
307
parameter and the number of different mask parameters in the hash.
308
Otherwise the same speed and memory efficiency comments applies here
309
as at the iphash type.
311
The ipporthash set type uses a hash to store IP address and port pairs.
312
In order to avoid clashes in the hash double-hashing, and as a last
313
resort, dynamic growing of the hash performed. An ipporthash set can
314
store up to 65536 (B-class network) IP addresses with all possible port
315
values. When adding, deleting and testing values in an ipporthash type of
316
set, the entries must be specified as
317
"\fIaddress\fP\fB,\fP\fIport\fP".
319
The ipporthash types of sets evaluates two src/dst parameters of the
325
Options to use when creating an ipporthash set:
327
\fB\-\-from\fP \fIfrom-addr\fP
329
\fB\-\-to\fP \fIto-addr\fP
330
Create an ipporthash set from the specified address range.
332
\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
333
Create an ipporthash set from the specified network.
335
\fB\-\-hashsize\fP \fIhashsize\fP
336
The initial hash size (default 1024)
338
\fB\-\-probes\fP \fIprobes\fP
339
How many times try to resolve clashing at adding an IP to the hash
340
by double-hashing (default 8).
342
\fB\-\-resize\fP \fIpercent\fP
343
Increase the hash size by this many percent (default 50) when adding
344
an IP to the hash could not be performed after
346
number of double-hashing.
348
The same resizing, speed and memory efficiency comments applies here
349
as at the iphash type.
351
The ipportiphash set type uses a hash to store IP address,port and IP
352
address triples. The first IP address must come form a maximum /16
353
sized network or range while the port number and the second IP address
354
parameters are arbitrary. When adding, deleting and testing values in an
355
ipportiphash type of set, the entries must be specified as
356
"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP".
358
The ipportiphash types of sets evaluates three src/dst parameters of the
364
Options to use when creating an ipportiphash set:
366
\fB\-\-from\fP \fIfrom-addr\fP
368
\fB\-\-to\fP \fIto-addr\fP
369
Create an ipportiphash set from the specified address range.
371
\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
372
Create an ipportiphash set from the specified network.
374
\fB\-\-hashsize\fP \fIhashsize\fP
375
The initial hash size (default 1024)
377
\fB\-\-probes\fP \fIprobes\fP
378
How many times try to resolve clashing at adding an IP to the hash
379
by double-hashing (default 8).
381
\fB\-\-resize\fP \fIpercent\fP
382
Increase the hash size by this many percent (default 50) when adding
383
an IP to the hash could not be performed after
385
number of double-hashing.
387
The same resizing, speed and memory efficiency comments applies here
388
as at the iphash type.
390
The ipportnethash set type uses a hash to store IP address, port, and
391
network address triples. The IP address must come form a maximum /16
392
sized network or range while the port number and the network address
393
parameters are arbitrary, but the size of the network address must be
394
between /1-/31. When adding, deleting
395
and testing values in an ipportnethash type of set, the entries must be
397
"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP\fB/\fP\fIprefixlen\fP".
399
The ipportnethash types of sets evaluates three src/dst parameters of the
405
Options to use when creating an ipportnethash set:
407
\fB\-\-from\fP \fIfrom-address\fP
409
\fB\-\-to\fP \fIto-address\fP
410
Create an ipporthash set from the specified range.
412
\fB\-\-network\fP \fIaddress\fP\fB/\fP\fImask\fP
413
Create an ipporthash set from the specified network.
415
\fB\-\-hashsize\fP \fIhashsize\fP
416
The initial hash size (default 1024)
418
\fB\-\-probes\fP \fIprobes\fP
419
How many times try to resolve clashing at adding an IP to the hash
420
by double-hashing (default 8).
422
\fB\-\-resize\fP \fIpercent\fP
423
Increase the hash size by this many percent (default 50) when adding
424
an IP to the hash could not be performed after
426
number of double-hashing.
428
The same resizing, speed and memory efficiency comments applies here
429
as at the iphash type.
431
The iptree set type uses a tree to store IP addresses, optionally
434
Options to use when creating an iptree set:
436
\fB\-\-timeout\fP \fIvalue\fP
437
The timeout value for the entries in seconds (default 0)
439
If a set was created with a nonzero valued
441
parameter then one may add IP addresses to the set with a specific
442
timeout value using the syntax
443
"\fIaddress\fP\fB,\fP\fItimeout-value\fP".
444
Similarly to the hash types, the iptree type of sets can store up to 65536
447
The iptreemap set type uses a tree to store IP addresses or networks,
448
where the last octet of an IP address are stored in a bitmap.
449
As input entry, you can add IP addresses, CIDR blocks or network ranges
450
to the set. Network ranges can be specified in the format
451
"\fIaddress1\fP\fB-\fP\fIaddress2\fP".
453
Options to use when creating an iptreemap set:
455
\fB\-\-gc\fP \fIvalue\fP
456
How often the garbage collection should be called, in seconds (default 300)
458
The setlist type uses a simple list in which you can store sets. By the
460
command you can add, delete and test sets in a setlist type of set.
461
You can specify the sets as
462
"\fIsetname\fP[\fB,\fP{\fBafter\fP|\fBbefore\fP},\fIsetname\fP]".
463
By default new sets are added after (appended to) the existing
464
elements. Setlist type of sets cannot be added to a setlist type of set.
466
Options to use when creating a setlist type of set:
468
\fB\-\-size\fP \fIsize\fP
469
Create a setlist type of set with the given size (default 8).
477
you can test, add or delete entries in the sets. The match
478
will try to find a matching IP address/port in the sets and
479
the target will try to add the IP address/port to the first set
480
to which it can be added. The number of src,dst options of
481
the match and target are important: sets which eats more src,dst
482
parameters than specified are skipped, while sets with equal
483
or less parameters are checked, elements added. For example
490
are setlist type of sets then in the command
492
iptables \-m set \-\-match\-set a src,dst \-j SET \-\-add-set b src,dst
494
the match and target will skip any set in
499
data triples, but will check all sets with single or double
502
set and add src to the first single or src,dst to the first double
505
You can imagine a setlist type of set as an ordered union of
508
Please note: by the ipset command you can add, delete and
510
the setnames in a setlist type of set, and not the presence of
511
a set's member (such as an IP address).
512
.SH GENERAL RESTRICTIONS
513
Setnames starting with colon (:) cannot be defined. Zero valued set
514
entries cannot be used with hash type of sets.
516
If you want to store same size subnets from a given network
517
(say /24 blocks from a /8 network), use the ipmap set type.
518
If you want to store random same size networks (say random /24 blocks),
519
use the iphash set type. If you have got random size of netblocks,
522
Old separator tokens (':' and '%") are still accepted.
524
Binding support is removed.
526
Various error messages are printed to standard error. The exit code
527
is 0 for correct functioning. Errors which appear to be caused by
528
invalid or abused command line parameters cause an exit code of 2, and
529
other errors cause an exit code of 1.
531
Bugs? No, just funny features. :-)
536
Jozsef Kadlecsik wrote ipset, which is based on ippool by
537
Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
539
Sven Wegener wrote the iptreemap type.
541
.BR "I stand on the shoulders of giants."
added
removed
extensions/ipset-4/ipset.8
