.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. The sets may have a default binding, which is valid for every set element for which there is no binding defined at all. There is no need for the entry to be added to the set for a binding to be defined for it. .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 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-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 from-setname will point to 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 supports it). .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. .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 65535 (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 65535 (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 65535 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 fast and great for use 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 .SS nethash The nethash set type uses a hash to store different size of network addresses. The .I IP "address" used in the ipset command 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 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 2). .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, where the matching start from the smallest size of netblock to the biggest ones. 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 .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 When adding an IP address to a set, one may add it 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. .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 ..