ipset/ipset.8

   1 .TH IPSET 8 "Feb 05, 2004" "" ""
   2 .\"
   3 .\" Man page written by Jozsef Kadlecsik <kadlec@blackhole.kfki.hu>
   4 .\"
   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.
   9 .\"
  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.
  14 .\"
  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.
  18 .\"
  19 .\"
  20 .SH NAME
  21 ipset \- administration tool for IP sets
  22 .SH SYNOPSIS
  23 .BR "ipset -N " "set type-specification [options]"
  24 .br
  25 .BR "ipset -[XFLSHh] " "[set] [options]"
  26 .br
  27 .BR "ipset -[EW] " "from-set to-set"
  28 .br
  29 .BR "ipset -[ADU] " "set entry"
  30 .br
  31 .BR "ipset -B " "set entry -b binding"
  32 .br
  33 .BR "ipset -T " "set entry [-b binding]"
  34 .br
  35 .BR "ipset -R "
  36 .SH DESCRIPTION
  37 .B ipset
  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.
  42 .P
  43 Any entry in a set can be bound to another set, which forms a relationship
  44 between a set element and the set it is bound to. In order to define a
  45 binding it is not required that the entry be already added to the set.
  46 The sets may have a default binding, which is valid for every set element
  47 for which there is no binding defined at all.
  48 .P
  49 IP set bindings pointing to sets and iptables matches and targets
  50 referring to sets creates references, which protects the given sets in
  51 the kernel. A set cannot be removed (destroyed) while there is a single
  52 reference pointing to it.
  53 .SH OPTIONS
  54 The options that are recognized by
  55 .B ipset
  56 can be divided into several different groups.
  57 .SS COMMANDS
  58 These options specify the specific action to perform.  Only one of them
  59 can be specified on the command line unless otherwise specified
  60 below.  For all the long versions of the command and option names, you
  61 need to use only enough letters to ensure that
  62 .B ipset
  63 can differentiate it from all other options.
  64 .TP
  65 .BI "-N, --create " "\fIsetname\fP type type-specific-options"
  66 Create a set identified with setname and specified type.
  67 Type-specific options must be supplied.
  68 .TP
  69 .BI "-X, --destroy " "[\fIsetname\fP]"
  70 Destroy the specified set, or all sets if none or the keyword
  71 .B
  72 :all:
  73 is specified.
  74 Before destroying the set, all bindings belonging to the
  75 set elements and the default binding of the set are removed.
  76
  77 If the set has got references, nothing is done.
  78 .TP
  79 .BI "-F, --flush " "[\fIsetname\fP]"
  80 Delete all entries from the specified set, or flush
  81 all sets if none or the keyword
  82 .B
  83 :all:
  84 is given. Bindings are not affected by the flush operation.
  85 .TP
  86 .BI "-E, --rename " "\fIfrom-setname\fP \fIto-setname\fP"
  87 Rename a set. Set identified by to-setname must not exist.
  88 .TP
  89 .BI "-W, --swap " "\fIfrom-setname\fP \fIto-setname\fP"
  90 Swap two sets as they referenced in the Linux kernel.
  91 .B
  92 iptables
  93 rules or
  94 .B
  95 ipset
  96 bindings pointing to the content of from-setname will point to
  97 the content of to-setname and vice versa. Both sets must exist.
  98 .TP
  99 .BI "-L, --list " "[\fIsetname\fP]"
 100 List the entries and bindings for the specified set, or for
 101 all sets if none or the keyword
 102 .B
 103 :all:
 104 is given. The
 105 .B "-n, --numeric"
 106 option can be used to suppress name lookups and generate numeric
 107 output. When the
 108 .B "-s, --sorted"
 109 option is given, the entries are listed sorted (if the given set
 110 type supports the operation).
 111 .TP
 112 .BI "-S, --save " "[\fIsetname\fP]"
 113 Save the given set, or all sets if none or the keyword
 114 .B
 115 :all:
 116 is specified to stdout in a format that --restore can read.
 117 .TP
 118 .BI "-R, --restore "
 119 Restore a saved session generated by --save. The saved session
 120 can be fed from stdin.
 121
 122 When generating a session file please note that the supported commands
 123 (create set, add element, bind) must appear in a strict order: first create
 124 the set, then add all elements. Then create the next set, add all its elements
 125 and so on. Finally you can list all binding commands. Also, it is a restore
 126 operation, so the sets being restored must not exist.
 127 .TP
 128 .BI "-A, --add " "\fIsetname\fP \fIIP\fP"
 129 Add an IP to a set.
 130 .TP
 131 .BI "-D, --del " "\fIsetname\fP \fIIP\fP"
 132 Delete an IP from a set.
 133 .TP
 134 .BI "-T, --test " "\fIsetname\fP \fIIP
 135 Test wether an IP is in a set or not. Exit status number is zero
 136 if the tested IP is in the set and nonzero if it is missing from
 137 the set.
 138 .TP
 139 .BI "-T, --test " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
 140 Test wether the IP belonging to the set points to the specified binding.
 141 Exit status number is zero if the binding points to the specified set,
 142 otherwise it is nonzero. The keyword
 143 .B
 144 :default:
 145 can be used to test the default binding of the set.
 146 .TP
 147 .BI "-B, --bind " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
 148 Bind the IP in setname to to-setname.
 149 .TP
 150 .BI "-U, --unbind " "\fIsetname\fP \fIIP\fP"
 151 Delete the binding belonging to IP in set setname.
 152 .TP
 153 .BI "-H, --help " "[settype]"
 154 Print help and settype specific help if settype specified.
 155 .P
 156 At the
 157 .B
 158 -B, -U
 159 and
 160 .B
 161 -T
 162 commands you can use the token
 163 .B
 164 :default:
 165 to bind, unbind or test the default binding of a set instead
 166 of an IP. At the
 167 .B
 168 -U
 169 command you can use the token
 170 .B
 171 :all:
 172 to destroy the bindings of all elements of a set.
 173 .SS "OTHER OPTIONS"
 174 The following additional options can be specified:
 175 .TP
 176 .B "-b, --binding setname"
 177 The option specifies the value of the binding for the
 178 .B "-B"
 179 binding command, for which it is a mandatory option.
 180 You can use it in the
 181 .B "-T"
 182 test command as well to test bindings.
 183 .TP
 184 .B "-s, --sorted"
 185 Sorted output. When listing sets, entries are listed sorted.
 186 .TP
 187 .B "-n, --numeric"
 188 Numeric output. When listing sets, bindings, IP addresses and
 189 port numbers will be printed in numeric format. By default the
 190 program will try to display them as host names, network names
 191 or services (whenever applicable), which can trigger
 192 .B
 193 slow
 194 DNS
 195 lookups.
 196 .TP
 197 .B "-q, --quiet"
 198 Suppress any output to stdout and stderr. ipset will still return
 199 possible errors.
 200 .SH SET TYPES
 201 ipset supports the following set types:
 202 .SS ipmap
 203 The ipmap set type uses a memory range, where each bit represents
 204 one IP address. An ipmap set can store up to 65536 (B-class network)
 205 IP addresses. The ipmap set type is very fast and memory cheap, great
 206 for use when one want to match certain IPs in a range. Using the
 207 .B "--netmask"
 208 option with a CIDR netmask value between 0-32 when creating an ipmap
 209 set, you will be able to store and match network addresses: i.e an
 210 IP address will be in the set if the value resulted by masking the address
 211 with the specified netmask can be found in the set.
 212 .P
 213 Options to use when creating an ipmap set:
 214 .TP
 215 .BR "--from " from-IP
 216 .TP
 217 .BR "--to " to-IP
 218 Create an ipmap set from the specified range.
 219 .TP
 220 .BR "--network " IP/mask
 221 Create an ipmap set from the specified network.
 222 .TP
 223 .BR "--netmask " CIDR-netmask
 224 When the optional
 225 .B "--netmask"
 226 parameter specified, network addresses will be
 227 stored in the set instead of IP addresses, and the from-IP parameter
 228 must be a network address.
 229 .SS macipmap
 230 The macipmap set type uses a memory range, where each 8 bytes
 231 represents one IP and a MAC addresses. A macipmap set type can store
 232 up to 65536 (B-class network) IP addresses with MAC.
 233 When adding an entry to a macipmap set, you must specify the entry as
 234 .I IP:MAC.
 235 When deleting or testing macipmap entries, the
 236 .I :MAC
 237 part is not mandatory. (The old "%" separation token instead of ":", i.e
 238 IP%MAC is accepted as well.)
 239 .P
 240 Options to use when creating an macipmap set:
 241 .TP
 242 .BR "--from " from-IP
 243 .TP
 244 .BR "--to " to-IP
 245 Create a macipmap set from the specified range.
 246 .TP
 247 .BR "--network " IP/mask
 248 Create a macipmap set from the specified network.
 249 .TP
 250 .BR "--matchunset"
 251 When the optional
 252 .B "--matchunset"
 253 parameter specified, IP addresses which could be stored
 254 in the set but not set yet, will always match.
 255 .P
 256 Please note, the
 257 .I
 258 set
 259 and
 260 .I
 261 SET
 262 netfilter kernel modules
 263 .B
 264 always
 265 use the source MAC address from the packet to match, add or delete
 266 entries from a macipmap type of set.
 267 .SS portmap
 268 The portmap set type uses a memory range, where each bit represents
 269 one port. A portmap set type can store up to 65536 ports.
 270 The portmap set type is very fast and memory cheap.
 271 .P
 272 Options to use when creating an portmap set:
 273 .TP
 274 .BR "--from " from-port
 275 .TP
 276 .BR "--to " to-port
 277 Create a portmap set from the specified range.
 278 .SS iphash
 279 The iphash set type uses a hash to store IP addresses.
 280 In order to avoid clashes in the hash double-hashing, and as a last
 281 resort, dynamic growing of the hash performed. The iphash set type is
 282 great to store random addresses. By supplyig the
 283 .B "--netmask"
 284 option with a CIDR netmask value between 0-32 at creating the set,
 285 you will be able to store and match network addresses instead: i.e
 286 an IP address will be in the set if the value of the address
 287 masked with the specified netmask can be found in the set.
 288 .P
 289 Options to use when creating an iphash set:
 290 .TP
 291 .BR "--hashsize " hashsize
 292 The initial hash size (default 1024)
 293 .TP
 294 .BR "--probes " probes
 295 How many times try to resolve clashing at adding an IP to the hash
 296 by double-hashing (default 8).
 297 .TP
 298 .BR "--resize " percent
 299 Increase the hash size by this many percent (default 50) when adding
 300 an IP to the hash could not be performed after
 301 .B
 302 probes
 303 number of double-hashing.
 304 .TP
 305 .BR "--netmask " CIDR-netmask
 306 When the optional
 307 .B "--netmask"
 308 parameter specified, network addresses will be
 309 stored in the set instead of IP addresses.
 310 .P
 311 The iphash type of sets can store up to 65535 entries. If a set is full,
 312 no new entries can be added to it.
 313 .P
 314 Sets created by zero valued resize parameter won't be resized at all.
 315 The lookup time in an iphash type of set approximately linearly grows with
 316 the value of the
 317 .B
 318 probes
 319 parameter. At the same time higher
 320 .B
 321 probes
 322 values result a better utilized hash while smaller values
 323 produce a larger, sparse hash.
 324 .SS nethash
 325 The nethash set type uses a hash to store different size of
 326 network addresses. The
 327 .I
 328 IP
 329 "address" used in the ipset commands must be in the form
 330 .I
 331 IP-address/cidr-size
 332 where the CIDR block size must be in the inclusive range of 1-31.
 333 In order to avoid clashes in the hash
 334 double-hashing, and as a last resort, dynamic growing of the hash performed.
 335 .P
 336 Options to use when creating an nethash set:
 337 .TP
 338 .BR "--hashsize " hashsize
 339 The initial hash size (default 1024)
 340 .TP
 341 .BR "--probes " probes
 342 How many times try to resolve clashing at adding an IP to the hash
 343 by double-hashing (default 4).
 344 .TP
 345 .BR "--resize " percent
 346 Increase the hash size by this many percent (default 50) when adding
 347 an IP to the hash could not be performed after
 348 .P
 349 The nethash type of sets can store up to 65535 entries. If a set is full,
 350 no new entries can be added to it.
 351 .P
 352 An IP address will be in a nethash type of set if it is in any of the
 353 netblocks added to the set and the matching always start from the smallest
 354 size of netblock (most specific netmask) to the biggest ones (least
 355 specific netmasks). When adding/deleting IP addresses
 356 to a nethash set by the
 357 .I
 358 SET
 359 netfilter kernel module, it will be added/deleted by the smallest
 360 netblock size which can be found in the set.
 361 .P
 362 The lookup time in a nethash type of set is approximately linearly
 363 grows with the times of the
 364 .B
 365 probes
 366 parameter and the number of different mask parameters in the hash.
 367 Otherwise the same speed and memory efficiency comments applies here
 368 as at the iphash type.
 369 .SS ipporthash
 370 The ipporthash set type uses a hash to store IP address and port pairs.
 371 In order to avoid clashes in the hash double-hashing, and as a last
 372 resort, dynamic growing of the hash performed. An ipporthash set can
 373 store up to 65536 (B-class network) IP addresses with all possible port
 374 values. When adding, deleting and testing values in an ipporthash type of
 375 set, the entries must be specified as
 376 .B
 377 "IP:port".
 378 (Old "IP%port" format accepted as well.)
 379 .P
 380 The ipporthash types of sets evaluates two src/dst parameters of the
 381 .I
 382 set
 383 match and
 384 .I
 385 SET
 386 target.
 387 .P
 388 Options to use when creating an ipporthash set:
 389 .TP
 390 .BR "--from " from-IP
 391 .TP
 392 .BR "--to " to-IP
 393 Create an ipporthash set from the specified range.
 394 .TP
 395 .BR "--network " IP/mask
 396 Create an ipporthash set from the specified network.
 397 .TP
 398 .BR "--hashsize " hashsize
 399 The initial hash size (default 1024)
 400 .TP
 401 .BR "--probes " probes
 402 How many times try to resolve clashing at adding an IP to the hash
 403 by double-hashing (default 8).
 404 .TP
 405 .BR "--resize " percent
 406 Increase the hash size by this many percent (default 50) when adding
 407 an IP to the hash could not be performed after
 408 .B
 409 probes
 410 number of double-hashing.
 411 .P
 412 The same resizing, speed and memory efficiency comments applies here
 413 as at the iphash type.
 414 .SS iptree
 415 The iptree set type uses a tree to store IP addresses, optionally
 416 with timeout values.
 417 .P
 418 Options to use when creating an iptree set:
 419 .TP
 420 .BR "--timeout " value
 421 The timeout value for the entries in seconds (default 0)
 422 .P
 423 If a set was created with a nonzero valued
 424 .B "--timeout"
 425 parameter then one may add IP addresses to the set with a specific
 426 timeout value using the syntax
 427 .I IP:timeout-value.
 428 Similarly to the hash types, the iptree type of sets can store up to 65535
 429 entries.
 430 .SS iptreemap
 431 The iptreemap set type uses a tree to store IP addresses or networks,
 432 where the last octet of an IP address are stored in a bitmap.
 433 As input entry, you can add IP addresses, CIDR blocks or network ranges
 434 to the set. Network ranges can be specified in the format
 435 .I IP1:IP2
 436 .P
 437 Options to use when creating an iptreemap set:
 438 .TP
 439 .BR "--gc " value
 440 How often the garbage collection should be called, in seconds (default 300)
 441 .SH GENERAL RESTRICTIONS
 442 Setnames starting with colon (:) cannot be defined. Zero valued set
 443 entries cannot be used with hash type of sets.
 444 .SH COMMENTS
 445 If you want to store same size subnets from a given network
 446 (say /24 blocks from a /8 network), use the ipmap set type.
 447 If you want to store random same size networks (say random /24 blocks),
 448 use the iphash set type. If you have got random size of netblocks,
 449 use nethash.
 450 .SH DIAGNOSTICS
 451 Various error messages are printed to standard error.  The exit code
 452 is 0 for correct functioning.  Errors which appear to be caused by
 453 invalid or abused command line parameters cause an exit code of 2, and
 454 other errors cause an exit code of 1.
 455 .SH BUGS
 456 Bugs? No, just funny features. :-)
 457 OK, just kidding...
 458 .SH SEE ALSO
 459 .BR iptables (8),
 460 .SH AUTHORS
 461 Jozsef Kadlecsik wrote ipset, which is based on ippool by
 462 Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
 463 .P
 464 Sven Wegener wrote the iptreemap type.
 465 .\" .. and did I mention that we are incredibly cool people?
 466 .\" .. sexy, too ..
 467 .\" .. witty, charming, powerful ..
 468 .\" .. and most of all, modest ..