diff options
Diffstat (limited to 'src/ipset.8')
| -rw-r--r-- | src/ipset.8 | 537 |
1 files changed, 537 insertions, 0 deletions
diff --git a/src/ipset.8 b/src/ipset.8 new file mode 100644 index 0000000..fa73298 --- /dev/null +++ b/src/ipset.8 @@ -0,0 +1,537 @@ +.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 \(em administration tool for IP sets +.SH SYNOPSIS +.PP +\fBipset \-N\fP \fIset\fP \fItype-specification\fP [\fIoptions\fP...] +.PP +\fBipset\fP {\fB\-F\fP|\fB\-H\fP|\fB\-L\fP|\fB\-S\fP|\fB\-X\fP} [\fIset\fP] +[\fIoptions\fP...] +.PP +\fBipset\fP {\fB\-E\fP|\fB\-W\fP} \fIfrom-set\fP \fIto-set\fP +.PP +\fBipset\fP {\fB\-A\fP|\fB\-D\fP|\fB\-T\fP} \fIset\fP \fIentry\fP +.PP +\fBipset \-R\fP +.PP +\fBipset\fP {\fB-V\fP|\fB\-v\fP} +.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 +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 +\fB\-N\fP, \fB\-\-create\fP \fIsetname\fP \fItype\fP \fItype-specific-options\fP +Create a set identified with setname and specified type. +Type-specific options must be supplied. +.TP +\fB\-X\fP, \fB\-\-destroy\fP [\fIsetname\fP] +Destroy the specified set or all the sets if none is given. + +If the set has got references, nothing is done. +.TP +\fB\-F\fP, \fB\-\-flush\fP [\fIsetname\fP] +Delete all entries from the specified set or flush +all sets if none is given. +.TP +\fB\-E\fP, \fB\-\-rename\fP \fIfrom-setname\fP \fIto-setname\fP +Rename a set. Set identified by to-setname must not exist. +.TP +\fB\-W\fP, \fB\-\-swap\fP \fIfrom-setname\fP \fIto-setname\fP +Swap the content of two sets, or in another words, +exchange the name of two sets. The referred sets must exist and +identical type of sets can be swapped only. +.TP +\fB\-L\fP, \fB\-\-list\fP [\fIsetname\fP] +List the entries for the specified set, or for +all sets if none is given. The +\fB\-r\fP/\fB\-\-resolve\fP +option can be used to force name lookups (which may be slow). When the +\fB\-s\fP/\fB\-\-sorted\fP +option is given, the entries are listed sorted (if the given set +type supports the operation). +.TP +\fB\-S\fP, \fB\-\-save\fP [\fIsetname\fP] +Save the given set, or all sets if none is given +to stdout in a format that \fB\-\-restore\fP can read. +.TP +\fB\-R\fP, \fB\-\-restore\fP +Restore a saved session generated by \fB\-\-save\fP. The saved session +can be fed from stdin. + +When generating a session file please note that the supported commands +(create set and add element) 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. Also, it is a restore operation, so the sets being restored must +not exist. +.TP +\fB\-A\fP, \fB\-\-add\fP \fIsetname\fP \fIentry\fP +Add an entry to a set. +.TP +\fB\-D\fP, \fB\-\-del\fP \fIsetname\fP \fIentry\fP +Delete an entry from a set. +.TP +\fB-T\fP, \fB\-\-test\fP \fIsetname\fP \fIentry\fP +Test wether an entry is in a set or not. Exit status number is zero +if the tested entry is in the set and nonzero if it is missing from +the set. +.TP +\fB\-H\fP, \fB\-\-help\fP [\fIsettype\fP] +Print help and settype specific help if settype specified. +.TP +\fB\-V\fP, \fB\-v\fP, \fB\-\-version\fP +Print program version and protocol version. +.P +.SS "OTHER OPTIONS" +The following additional options can be specified: +.TP +\fB\-r\fP, \fB\-\-resolve\fP +When listing sets, enforce name lookup. The +program will try to display the IP entries resolved to +host names or services (whenever applicable), which can trigger +.B +slow +DNS +lookups. +.TP +\fB\-s\fP, \fB\-\-sorted\fP +Sorted output. When listing sets, entries are listed sorted. +.TP +\fB\-n\fP, \fB\-\-numeric\fP +Numeric output. When listing sets, IP addresses and +port numbers will be printed in numeric format. This is the default. +.TP +\fB\-q\fP, \fB\-\-quiet\fP +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. If the optional +\fB\-\-netmask\fP +parameter is specified with a CIDR netmask value between 1-31 then +network addresses are stored in the given set: i.e an +IP address will be in the set if the network address, which is 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 +\fB\-\-from\fP \fIfrom-addr\fP +.TP +\fB\-\-to\fP \fIto-addr\fP +Create an ipmap set from the specified address range. +.TP +\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP +Create an ipmap set from the specified network. +.TP +\fB\-\-netmask\fP \fIprefixlen\fP +When the optional +\fB\-\-netmask\fP +parameter specified, network addresses will be +stored in the set instead of IP addresses, and the \fIfrom-addr\fP parameter +must be a network address. The \fIprefixlen\fP value must be between 1-31. +.PP +Example: +.IP +ipset \-N test ipmap \-\-network 192.168.0.0/16 +.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 +"\fIaddress\fP\fB,\fP\fImac\fP". +When deleting or testing macipmap entries, the +"\fB,\fP\fImac\fP" +part is not mandatory. +.P +Options to use when creating an macipmap set: +.TP +\fB\-\-from\fP \fIfrom-addr\fP +.TP +\fB\-\-to\fP \fIto-addr\fP +Create a macipmap set from the specified address range. +.TP +\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP +Create a macipmap set from the specified network. +.TP +\fB\-\-matchunset\fP +When the optional +\fB\-\-matchunset\fP +parameter specified, IP addresses which could be stored +in the set but not set yet, will always match. +.P +Please note, the +"set" +and +"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 +\fB\-\-from\fP \fIfrom-port\fP +.TP +\fB\-\-to\fP \fIto-port\fP +Create a portmap set from the specified port 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. If the optional +\fB\-\-netmask\fP +parameter is specified with a CIDR prefix length value between 1-31 then +network addresses are stored in the given set: i.e an +IP address will be in the set if the network address, which is resulted +by masking the address with the specified netmask, can be found in the set. +.P +Options to use when creating an iphash set: +.TP +\fB\-\-hashsize\fP \fIhashsize\fP +The initial hash size (default 1024) +.TP +\fB\-\-probes\fP \fIprobes\fP +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +\fB\-\-resize\fP \fIpercent\fP +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +\fIprobes\fP +number of double-hashing. +.TP +\fB\-\-netmask\fP \fIprefixlen\fP +When the optional +\fB\-\-netmask\fP +parameter specified, network addresses will be +stored in the set instead of IP addresses. The \fIprefixlen\fP value must +be between 1-31. +.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 grows approximately linearly with +the value of the +\fIprobes\fP +parameter. In general higher +\fIprobes\fP +value results better utilized hash while smaller value +produces larger, sparser hash. +.PP +Example: +.IP +ipset \-N test iphash \-\-probes 2 +.SS nethash +The nethash set type uses a hash to store different size of +network addresses. The +.I +entry +used in the ipset commands must be in the form +"\fIaddress\fP\fB/\fP\fIprefixlen\fP" +where prefixlen 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 +\fB\-\-hashsize\fP \fIhashsize\fP +The initial hash size (default 1024) +.TP +\fB\-\-probes\fP \fIprobes\fP +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 4). +.TP +\fB\-\-resize\fP \fIpercent\fP +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 belongs to any of the +netblocks added to the set. The matching always start from the smallest +size of netblock (most specific netmask) to the largest ones (least +specific netmasks). When adding/deleting IP addresses +to a nethash set by the +"SET" +netfilter kernel module, it will be added/deleted by the smallest +netblock size which can be found in the set, or by /31 if the set is empty. +.P +The lookup time in a nethash type of set grows approximately linearly +with the times of the +\fIprobes\fP +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 +"\fIaddress\fP\fB,\fP\fIport\fP". +.P +The ipporthash types of sets evaluates two src/dst parameters of the +"set" +match and +"SET" +target. +.P +Options to use when creating an ipporthash set: +.TP +\fB\-\-from\fP \fIfrom-addr\fP +.TP +\fB\-\-to\fP \fIto-addr\fP +Create an ipporthash set from the specified address range. +.TP +\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP +Create an ipporthash set from the specified network. +.TP +\fB\-\-hashsize\fP \fIhashsize\fP +The initial hash size (default 1024) +.TP +\fB\-\-probes\fP \fIprobes\fP +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +\fB\-\-resize\fP \fIpercent\fP +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +\fIprobes\fP +number of double-hashing. +.P +The same resizing, speed and memory efficiency comments applies here +as at the iphash type. +.SS ipportiphash +The ipportiphash set type uses a hash to store IP address,port and IP +address triples. The first IP address must come form a maximum /16 +sized network or range while the port number and the second IP address +parameters are arbitrary. When adding, deleting and testing values in an +ipportiphash type of set, the entries must be specified as +"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP". +.P +The ipportiphash types of sets evaluates three src/dst parameters of the +"set" +match and +"SET" +target. +.P +Options to use when creating an ipportiphash set: +.TP +\fB\-\-from\fP \fIfrom-addr\fP +.TP +\fB\-\-to\fP \fIto-addr\fP +Create an ipportiphash set from the specified address range. +.TP +\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP +Create an ipportiphash set from the specified network. +.TP +\fB\-\-hashsize\fP \fIhashsize\fP +The initial hash size (default 1024) +.TP +\fB\-\-probes\fP \fIprobes\fP +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +\fB\-\-resize\fP \fIpercent\fP +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +\fIprobes\fP +number of double-hashing. +.P +The same resizing, speed and memory efficiency comments applies here +as at the iphash type. +.SS ipportnethash +The ipportnethash set type uses a hash to store IP address, port, and +network address triples. The IP address must come form a maximum /16 +sized network or range while the port number and the network address +parameters are arbitrary, but the size of the network address must be +between /1-/31. When adding, deleting +and testing values in an ipportnethash type of set, the entries must be +specified as +"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP\fB/\fP\fIprefixlen\fP". +.P +The ipportnethash types of sets evaluates three src/dst parameters of the +"set" +match and +"SET" +target. +.P +Options to use when creating an ipportnethash set: +.TP +\fB\-\-from\fP \fIfrom-address\fP +.TP +\fB\-\-to\fP \fIto-address\fP +Create an ipporthash set from the specified range. +.TP +\fB\-\-network\fP \fIaddress\fP\fB/\fP\fImask\fP +Create an ipporthash set from the specified network. +.TP +\fB\-\-hashsize\fP \fIhashsize\fP +The initial hash size (default 1024) +.TP +\fB\-\-probes\fP \fIprobes\fP +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +\fB\-\-resize\fP \fIpercent\fP +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +\fIprobes\fP +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 +\fB\-\-timeout\fP \fIvalue\fP +The timeout value for the entries in seconds (default 0) +.P +If a set was created with a nonzero valued +\fB\-\-timeout\fP +parameter then one may add IP addresses to the set with a specific +timeout value using the syntax +"\fIaddress\fP\fB,\fP\fItimeout-value\fP". +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 +"\fIaddress1\fP\fB-\fP\fIaddress2\fP". +.P +Options to use when creating an iptreemap set: +.TP +\fB\-\-gc\fP \fIvalue\fP +How often the garbage collection should be called, in seconds (default 300) +.SS setlist +The setlist type uses a simple list in which you can store sets. By the +ipset +command you can add, delete and test sets in a setlist type of set. +You can specify the sets as +"\fIsetname\fP[\fB,\fP{\fBafter\fP|\fBbefore\fP},\fIsetname\fP]". +By default new sets are added after (appended to) the existing +elements. Setlist type of sets cannot be added to a setlist type of set. +.P +Options to use when creating a setlist type of set: +.TP +\fB\-\-size\fP \fIsize\fP +Create a setlist type of set with the given size (default 8). +.PP +By the +"set" +match or +"SET" +target of +\fBiptables\fP(8) +you can test, add or delete entries in the sets. The match +will try to find a matching IP address/port in the sets and +the target will try to add the IP address/port to the first set +to which it can be added. The number of src,dst options of +the match and target are important: sets which eats more src,dst +parameters than specified are skipped, while sets with equal +or less parameters are checked, elements added. For example +if +.I +a +and +.I +b +are setlist type of sets then in the command +.IP +iptables \-m set \-\-match\-set a src,dst \-j SET \-\-add-set b src,dst +.PP +the match and target will skip any set in +.I a +and +.I b +which stores +data triples, but will check all sets with single or double +data storage in +.I a +set and add src to the first single or src,dst to the first double +data storage set in +\fIb\fP. +.P +You can imagine a setlist type of set as an ordered union of +the set elements. +.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. +.P +Old separator tokens (':' and '%") are still accepted. +.P +Binding support is removed. +.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 shoulders of giants." |