Import ipset-2.3.2a (userspace components)

extensions/ipset/ipset.8

@@ -0,0 +1,470 @@
+.TH IPSET 8 "Feb 05, 2004" "" ""
+.\"
+.\" Man page written by Jozsef Kadlecsik <kadlec@blackhole.kfki.hu>
+.\"
+.\"	This program is free software; you can redistribute it and/or modify
+.\"	it under the terms of the GNU General Public License as published by
+.\"	the Free Software Foundation; either version 2 of the License, or
+.\"	(at your option) any later version.
+.\"
+.\"	This program is distributed in the hope that it will be useful,
+.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\"	GNU General Public License for more details.
+.\"
+.\"	You should have received a copy of the GNU General Public License
+.\"	along with this program; if not, write to the Free Software
+.\"	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+.\"
+.\"
+.SH NAME
+ipset \- administration tool for IP sets
+.SH SYNOPSIS
+.BR "ipset -N " "set type-specification [options]"
+.br
+.BR "ipset -[XFLSHh] " "[set] [options]"
+.br
+.BR "ipset -[EW] " "from-set to-set"
+.br
+.BR "ipset -[ADU] " "set entry"
+.br
+.BR "ipset -B " "set entry -b binding"
+.br
+.BR "ipset -T " "set entry [-b binding]"
+.br
+.BR "ipset -R "
+.SH DESCRIPTION
+.B ipset
+is used to set up, maintain and inspect so called IP sets in the Linux
+kernel. Depending on the type, an IP set may store IP addresses, (TCP/UDP)
+port numbers or additional informations besides IP addresses: the word IP 
+means a general term here. See the set type definitions below.
+.P
+Any entry in a set can be bound to another set, which forms a relationship
+between a set element and the set it is bound to. In order to define a
+binding it is not required that the entry be already added to the set. 
+The sets may have a default binding, which is valid for every set element 
+for which there is no binding defined at all.
+.P
+IP set bindings pointing to sets and iptables matches and targets 
+referring to sets creates references, which protects the given sets in 
+the kernel. A set cannot be removed (destroyed) while there is a single
+reference pointing to it.
+.SH OPTIONS
+The options that are recognized by
+.B ipset
+can be divided into several different groups.
+.SS COMMANDS
+These options specify the specific action to perform.  Only one of them
+can be specified on the command line unless otherwise specified
+below.  For all the long versions of the command and option names, you
+need to use only enough letters to ensure that
+.B ipset
+can differentiate it from all other options.
+.TP
+.BI "-N, --create " "\fIsetname\fP type type-specific-options"
+Create a set identified with setname and specified type. 
+Type-specific options must be supplied.
+.TP
+.BI "-X, --destroy " "[\fIsetname\fP]"
+Destroy the specified set, or all sets if none or the keyword
+.B
+:all:
+is specified.
+Before destroying the set, all bindings belonging to the 
+set elements and the default binding of the set are removed.
+
+If the set has got references, nothing is done.
+.TP
+.BI "-F, --flush " "[\fIsetname\fP]"
+Delete all entries from the specified set, or flush
+all sets if none or the keyword
+.B
+:all:
+is given. Bindings are not affected by the flush operation.
+.TP
+.BI "-E, --rename " "\fIfrom-setname\fP \fIto-setname\fP"
+Rename a set. Set identified by to-setname must not exist.
+.TP
+.BI "-W, --swap " "\fIfrom-setname\fP \fIto-setname\fP"
+Swap two sets as they referenced in the Linux kernel.
+.B
+iptables
+rules or
+.B
+ipset
+bindings pointing to the content of from-setname will point to 
+the content of to-setname and vice versa. Both sets must exist.
+.TP
+.BI "-L, --list " "[\fIsetname\fP]"
+List the entries and bindings for the specified set, or for
+all sets if none or the keyword
+.B
+:all:
+is given. The
+.B "-n, --numeric"
+option can be used to suppress name lookups and generate numeric
+output. When the
+.B "-s, --sorted"
+option is given, the entries are listed sorted (if the given set
+type supports the operation).
+.TP
+.BI "-S, --save " "[\fIsetname\fP]"
+Save the given set, or all sets if none or the keyword
+.B
+:all:
+is specified to stdout in a format that --restore can read.
+.TP
+.BI "-R, --restore "
+Restore a saved session generated by --save. The saved session
+can be fed from stdin.
+
+When generating a session file please note that the supported commands
+(create set, add element, bind) must appear in a strict order: first create
+the set, then add all elements. Then create the next set, add all its elements
+and so on. Finally you can list all binding commands. Also, it is a restore
+operation, so the sets being restored must not exist.
+.TP
+.BI "-A, --add " "\fIsetname\fP \fIIP\fP"
+Add an IP to a set.
+.TP
+.BI "-D, --del " "\fIsetname\fP \fIIP\fP"
+Delete an IP from a set. 
+.TP
+.BI "-T, --test " "\fIsetname\fP \fIIP
+Test wether an IP is in a set or not. Exit status number is zero
+if the tested IP is in the set and nonzero if it is missing from 
+the set.
+.TP
+.BI "-T, --test " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
+Test wether the IP belonging to the set points to the specified binding. 
+Exit status number is zero if the binding points to the specified set, 
+otherwise it is nonzero. The keyword
+.B
+:default:
+can be used to test the default binding of the set.
+.TP
+.BI "-B, --bind " "\fIsetname\fP \fIIP\fP \fI--binding\fP \fIto-setname\fP"
+Bind the IP in setname to to-setname.
+.TP
+.BI "-U, --unbind " "\fIsetname\fP \fIIP\fP"
+Delete the binding belonging to IP in set setname. 
+.TP
+.BI "-H, --help " "[settype]"
+Print help and settype specific help if settype specified.
+.P
+At the
+.B
+-B, -U
+and
+.B 
+-T
+commands you can use the token
+.B
+:default:
+to bind, unbind or test the default binding of a set instead
+of an IP. At the
+.B
+-U
+command you can use the token
+.B
+:all:
+to destroy the bindings of all elements of a set.
+.SS "OTHER OPTIONS"
+The following additional options can be specified:
+.TP
+.B "-b, --binding setname"
+The option specifies the value of the binding for the
+.B "-B"
+binding command, for which it is a mandatory option.
+You can use it in the
+.B "-T"
+test command as well to test bindings.
+.TP
+.B "-s, --sorted"
+Sorted output. When listing sets, entries are listed sorted.
+.TP
+.B "-n, --numeric"
+Numeric output. When listing sets, bindings, IP addresses and 
+port numbers will be printed in numeric format. By default the 
+program will try to display them as host names, network names 
+or services (whenever applicable), which can trigger
+.B
+slow
+DNS 
+lookups.
+.TP
+.B "-q, --quiet"
+Suppress any output to stdout and stderr. ipset will still return
+possible errors.
+.SH SET TYPES
+ipset supports the following set types:
+.SS ipmap
+The ipmap set type uses a memory range, where each bit represents
+one IP address. An ipmap set can store up to 65536 (B-class network)
+IP addresses. The ipmap set type is very fast and memory cheap, great
+for use when one want to match certain IPs in a range. Using the
+.B "--netmask"
+option with a CIDR netmask value between 0-32 when creating an ipmap
+set, you will be able to store and match network addresses: i.e an
+IP address will be in the set if the value resulted by masking the address
+with the specified netmask can be found in the set.
+.P
+Options to use when creating an ipmap set:
+.TP
+.BR "--from " from-IP
+.TP
+.BR "--to " to-IP
+Create an ipmap set from the specified range.
+.TP
+.BR "--network " IP/mask
+Create an ipmap set from the specified network.
+.TP
+.BR "--netmask " CIDR-netmask
+When the optional
+.B "--netmask"
+parameter specified, network addresses will be 
+stored in the set instead of IP addresses, and the from-IP parameter
+must be a network address.
+.SS macipmap
+The macipmap set type uses a memory range, where each 8 bytes
+represents one IP and a MAC addresses. A macipmap set type can store
+up to 65536 (B-class network) IP addresses with MAC.
+When adding an entry to a macipmap set, you must specify the entry as
+.I IP:MAC.
+When deleting or testing macipmap entries, the
+.I :MAC
+part is not mandatory. (The old "%" separation token instead of ":", i.e
+IP%MAC is accepted as well.)
+.P
+Options to use when creating an macipmap set:
+.TP
+.BR "--from " from-IP
+.TP
+.BR "--to " to-IP
+Create a macipmap set from the specified range.
+.TP
+.BR "--network " IP/mask
+Create a macipmap set from the specified network.
+.TP
+.BR "--matchunset"
+When the optional
+.B "--matchunset"
+parameter specified, IP addresses which could be stored 
+in the set but not set yet, will always match.
+.P
+Please note, the 
+.I
+set
+and
+.I
+SET
+netfilter kernel modules
+.B
+always
+use the source MAC address from the packet to match, add or delete
+entries from a macipmap type of set.
+.SS portmap
+The portmap set type uses a memory range, where each bit represents
+one port. A portmap set type can store up to 65536 ports.
+The portmap set type is very fast and memory cheap.
+.P
+Options to use when creating an portmap set:
+.TP
+.BR "--from " from-port
+.TP
+.BR "--to " to-port
+Create a portmap set from the specified range.
+.SS iphash
+The iphash set type uses a hash to store IP addresses.
+In order to avoid clashes in the hash double-hashing, and as a last
+resort, dynamic growing of the hash performed. The iphash set type is
+great to store random addresses. By supplyig the
+.B "--netmask"
+option with a CIDR netmask value between 0-32 at creating the set,
+you will be able to store and match network addresses instead: i.e 
+an IP address will be in the set if the value of the address
+masked with the specified netmask can be found in the set.
+.P
+Options to use when creating an iphash set:
+.TP
+.BR "--hashsize " hashsize
+The initial hash size (default 1024)
+.TP
+.BR "--probes " probes
+How many times try to resolve clashing at adding an IP to the hash 
+by double-hashing (default 8).
+.TP
+.BR "--resize " percent
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+.B
+probes
+number of double-hashing. 
+.TP
+.BR "--netmask " CIDR-netmask
+When the optional
+.B "--netmask"
+parameter specified, network addresses will be 
+stored in the set instead of IP addresses.
+.P
+The iphash type of sets can store up to 65536 entries. If a set is full,
+no new entries can be added to it.
+.P
+Sets created by zero valued resize parameter won't be resized at all.
+The lookup time in an iphash type of set approximately linearly grows with
+the value of the 
+.B
+probes
+parameter. At the same time higher 
+.B
+probes
+values result a better utilized hash while smaller values 
+produce a larger, sparse hash.
+.SS nethash
+The nethash set type uses a hash to store different size of
+network addresses. The
+.I
+IP
+"address" used in the ipset commands must be in the form
+.I
+IP-address/cidr-size
+where the CIDR block size must be in the inclusive range of 1-31.
+In order to avoid clashes in the hash 
+double-hashing, and as a last resort, dynamic growing of the hash performed.
+.P
+Options to use when creating an nethash set:
+.TP
+.BR "--hashsize " hashsize
+The initial hash size (default 1024)
+.TP
+.BR "--probes " probes
+How many times try to resolve clashing at adding an IP to the hash 
+by double-hashing (default 4).
+.TP
+.BR "--resize " percent
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+.P
+The nethash type of sets can store up to 65536 entries. If a set is full,
+no new entries can be added to it.
+.P
+An IP address will be in a nethash type of set if it is in any of the
+netblocks added to the set and the matching always start from the smallest
+size of netblock (most specific netmask) to the biggest ones (least
+specific netmasks). When adding/deleting IP addresses
+to a nethash set by the
+.I
+SET
+netfilter kernel module, it will be added/deleted by the smallest
+netblock size which can be found in the set.
+.P
+The lookup time in a nethash type of set is approximately linearly 
+grows with the times of the
+.B
+probes
+parameter and the number of different mask parameters in the hash.
+Otherwise the same speed and memory efficiency comments applies here 
+as at the iphash type.
+.SS ipporthash
+The ipporthash set type uses a hash to store IP address and port pairs.
+In order to avoid clashes in the hash double-hashing, and as a last
+resort, dynamic growing of the hash performed. An ipporthash set can 
+store up to 65536 (B-class network) IP addresses with all possible port
+values. When adding, deleting and testing values in an ipporthash type of
+set, the entries must be specified as
+.B
+"IP:port".
+(Old "IP%port" format accepted as well.)
+.P
+The ipporthash types of sets evaluates two src/dst parameters of the 
+.I
+set
+match and 
+.I
+SET
+target. 
+.P
+Options to use when creating an ipporthash set:
+.TP
+.BR "--from " from-IP
+.TP
+.BR "--to " to-IP
+Create an ipporthash set from the specified range.
+.TP
+.BR "--network " IP/mask
+Create an ipporthash set from the specified network.
+.TP
+.BR "--hashsize " hashsize
+The initial hash size (default 1024)
+.TP
+.BR "--probes " probes
+How many times try to resolve clashing at adding an IP to the hash 
+by double-hashing (default 8).
+.TP
+.BR "--resize " percent
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+.B
+probes
+number of double-hashing.
+.P
+The same resizing, speed and memory efficiency comments applies here 
+as at the iphash type.
+.SS iptree
+The iptree set type uses a tree to store IP addresses, optionally 
+with timeout values.
+.P
+Options to use when creating an iptree set:
+.TP
+.BR "--timeout " value
+The timeout value for the entries in seconds (default 0)
+.P
+If a set was created with a nonzero valued 
+.B "--timeout"
+parameter then one may add IP addresses to the set with a specific 
+timeout value using the syntax 
+.I IP:timeout-value.
+Similarly to the hash types, the iptree type of sets can store up to 65536
+entries.
+.SS iptreemap
+The iptreemap set type uses a tree to store IP addresses or networks, 
+where the last octet of an IP address are stored in a bitmap.
+As input entry, you can add IP addresses, CIDR blocks or network ranges
+to the set. Network ranges can be specified in the format
+.I IP1:IP2
+.P
+Options to use when creating an iptreemap set:
+.TP
+.BR "--gc " value
+How often the garbage collection should be called, in seconds (default 300)
+.SH GENERAL RESTRICTIONS
+Setnames starting with colon (:) cannot be defined. Zero valued set 
+entries cannot be used with hash type of sets.
+.SH COMMENTS
+If you want to store same size subnets from a given network
+(say /24 blocks from a /8 network), use the ipmap set type.
+If you want to store random same size networks (say random /24 blocks), 
+use the iphash set type. If you have got random size of netblocks, 
+use nethash.
+.SH DIAGNOSTICS
+Various error messages are printed to standard error.  The exit code
+is 0 for correct functioning.  Errors which appear to be caused by
+invalid or abused command line parameters cause an exit code of 2, and
+other errors cause an exit code of 1.
+.SH BUGS
+Bugs? No, just funny features. :-)
+OK, just kidding...
+.SH SEE ALSO
+.BR iptables (8),
+.SH AUTHORS
+Jozsef Kadlecsik wrote ipset, which is based on ippool by
+Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
+.P
+Sven Wegener wrote the iptreemap type.
+.SH LAST REMARK
+.BR "I stand on the shoulder of giants."
+.\" .. and did I mention that we are incredibly cool people?
+.\" .. sexy, too ..
+.\" .. witty, charming, powerful ..
+.\" .. and most of all, modest ..