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.
 238 .P
 239 Options to use when creating an macipmap set:
 240 .TP
 241 .BR "--from " from-IP
 242 .TP
 243 .BR "--to " to-IP
 244 Create a macipmap set from the specified range.
 245 .TP
 246 .BR "--network " IP/mask
 247 Create a macipmap set from the specified network.
 248 .TP
 249 .BR "--matchunset"
 250 When the optional
 251 .B "--matchunset"
 252 parameter specified, IP addresses which could be stored
 253 in the set but not set yet, will always match.
 254 .P
 255 Please note, the
 256 .I
 257 set
 258 and
 259 .I
 260 SET
 261 netfilter kernel modules
 262 .B
 263 always
 264 use the source MAC address from the packet to match, add or delete
 265 entries from a macipmap type of set.
 266 .SS portmap
 267 The portmap set type uses a memory range, where each bit represents
 268 one port. A portmap set type can store up to 65536 ports.
 269 The portmap set type is very fast and memory cheap.
 270 .P
 271 Options to use when creating an portmap set:
 272 .TP
 273 .BR "--from " from-port
 274 .TP
 275 .BR "--to " to-port
 276 Create a portmap set from the specified range.
 277 .SS iphash
 278 The iphash set type uses a hash to store IP addresses.
 279 In order to avoid clashes in the hash double-hashing, and as a last
 280 resort, dynamic growing of the hash performed. The iphash set type is
 281 great to store random addresses. By supplyig the
 282 .B "--netmask"
 283 option with a CIDR netmask value between 0-32 at creating the set,
 284 you will be able to store and match network addresses instead: i.e
 285 an IP address will be in the set if the value of the address
 286 masked with the specified netmask can be found in the set.
 287 .P
 288 Options to use when creating an iphash set:
 289 .TP
 290 .BR "--hashsize " hashsize
 291 The initial hash size (default 1024)
 292 .TP
 293 .BR "--probes " probes
 294 How many times try to resolve clashing at adding an IP to the hash
 295 by double-hashing (default 8).
 296 .TP
 297 .BR "--resize " percent
 298 Increase the hash size by this many percent (default 50) when adding
 299 an IP to the hash could not be performed after
 300 .B
 301 probes
 302 number of double-hashing.
 303 .TP
 304 .BR "--netmask " CIDR-netmask
 305 When the optional
 306 .B "--netmask"
 307 parameter specified, network addresses will be
 308 stored in the set instead of IP addresses.
 309 .P
 310 Sets created by zero valued resize parameter won't be resized at all.
 311 The lookup time in an iphash type of set approximately linearly grows with
 312 the value of the
 313 .B
 314 probes
 315 parameter. At the same time higher
 316 .B
 317 probes
 318 values result a better utilized hash while smaller values
 319 produce a larger, sparse hash.
 320 .SS nethash
 321 The nethash set type uses a hash to store different size of
 322 network addresses. The
 323 .I
 324 IP
 325 "address" used in the ipset commands must be in the form
 326 .I
 327 IP-address/cidr-size
 328 where the CIDR block size must be in the inclusive range of 1-31.
 329 In order to avoid clashes in the hash
 330 double-hashing, and as a last resort, dynamic growing of the hash performed.
 331 .P
 332 Options to use when creating an nethash set:
 333 .TP
 334 .BR "--hashsize " hashsize
 335 The initial hash size (default 1024)
 336 .TP
 337 .BR "--probes " probes
 338 How many times try to resolve clashing at adding an IP to the hash
 339 by double-hashing (default 4).
 340 .TP
 341 .BR "--resize " percent
 342 Increase the hash size by this many percent (default 50) when adding
 343 an IP to the hash could not be performed after
 344 .P
 345 An IP address will be in a nethash type of set if it is in any of the
 346 netblocks added to the set and the matching always start from the smallest
 347 size of netblock (most specific netmask) to the biggest ones (least
 348 specific netmasks). When adding/deleting IP addresses
 349 to a nethash set by the
 350 .I
 351 SET
 352 netfilter kernel module, it will be added/deleted by the smallest
 353 netblock size which can be found in the set.
 354 .P
 355 The lookup time in a nethash type of set is approximately linearly
 356 grows with the times of the
 357 .B
 358 probes
 359 parameter and the number of different mask parameters in the hash.
 360 Otherwise the same speed and memory efficiency comments applies here
 361 as at the iphash type.
 362 .SS ipporthash
 363 The ipporthash set type uses a hash to store IP address and port pairs.
 364 In order to avoid clashes in the hash double-hashing, and as a last
 365 resort, dynamic growing of the hash performed. An ipporthash set can
 366 store up to 65536 (B-class network) IP addresses with all possible port
 367 values. When adding, deleting and testing values in an ipporthash type of
 368 set, the entries must be specified as
 369 .B
 370 "IP%port".
 371 .P
 372 The ipporthash types of sets evaluates two src/dst parameters of the
 373 .I
 374 set
 375 match and
 376 .I
 377 SET
 378 target.
 379 .P
 380 Options to use when creating an ipporthash set:
 381 .TP
 382 .BR "--from " from-IP
 383 .TP
 384 .BR "--to " to-IP
 385 Create an ipporthash set from the specified range.
 386 .TP
 387 .BR "--network " IP/mask
 388 Create an ipporthash set from the specified network.
 389 .TP
 390 .BR "--hashsize " hashsize
 391 The initial hash size (default 1024)
 392 .TP
 393 .BR "--probes " probes
 394 How many times try to resolve clashing at adding an IP to the hash
 395 by double-hashing (default 8).
 396 .TP
 397 .BR "--resize " percent
 398 Increase the hash size by this many percent (default 50) when adding
 399 an IP to the hash could not be performed after
 400 .B
 401 probes
 402 number of double-hashing.
 403 .P
 404 The same resizing, speed and memory efficiency comments applies here
 405 as at the iphash type.
 406 .SS iptree
 407 The iptree set type uses a tree to store IP addresses, optionally
 408 with timeout values.
 409 .P
 410 Options to use when creating an iptree set:
 411 .TP
 412 .BR "--timeout " value
 413 The timeout value for the entries in seconds (default 0)
 414 .P
 415 If a set was created with a nonzero valued
 416 .B "--timeout"
 417 parameter then one may add IP addresses to the set with a specific
 418 timeout value using the syntax
 419 .I IP%timeout-value.
 420 .SH GENERAL RESTRICTIONS
 421 Setnames starting with colon (:) cannot be defined. Zero valued set
 422 entries cannot be used with hash type of sets.
 423 .SH COMMENTS
 424 If you want to store same size subnets from a given network
 425 (say /24 blocks from a /8 network), use the ipmap set type.
 426 If you want to store random same size networks (say random /24 blocks),
 427 use the iphash set type. If you have got random size of netblocks,
 428 use nethash.
 429 .SH DIAGNOSTICS
 430 Various error messages are printed to standard error.  The exit code
 431 is 0 for correct functioning.  Errors which appear to be caused by
 432 invalid or abused command line parameters cause an exit code of 2, and
 433 other errors cause an exit code of 1.
 434 .SH BUGS
 435 Bugs? No, just funny features. :-)
 436 OK, just kidding...
 437 .SH SEE ALSO
 438 .BR iptables (8),
 439 .SH AUTHORS
 440 Jozsef Kadlecsik wrote ipset, which is based on ippool by
 441 Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
 442 .\" .. and did I mention that we are incredibly cool people?
 443 .\" .. sexy, too ..
 444 .\" .. witty, charming, powerful ..
 445 .\" .. and most of all, modest ..