X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ipset%2Fipset.8;fp=ipset%2Fipset.8;h=89a86ce859ca2934a1390f645190a1b2307b196e;hb=3bbf6cde0b81310fdef47ebead675dfa6d346f8b;hp=0000000000000000000000000000000000000000;hpb=6afea0b41dfbc3824956d11d960ad80097218feb;p=iptables.git diff --git a/ipset/ipset.8 b/ipset/ipset.8 new file mode 100644 index 0000000..89a86ce --- /dev/null +++ b/ipset/ipset.8 @@ -0,0 +1,445 @@ +.TH IPSET 8 "Feb 05, 2004" "" "" +.\" +.\" Man page written by Jozsef Kadlecsik +.\" +.\" 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. +.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 +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 +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". +.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. +.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. +.\" .. and did I mention that we are incredibly cool people? +.\" .. sexy, too .. +.\" .. witty, charming, powerful .. +.\" .. and most of all, modest ..