.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 \- IP set administration .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 -[ADT] " "set entry" .br .BR "ipset -R " .SH DESCRIPTION .B Ipset is used to set up, maintain, and inspect so called IP sets in the Linux kernel. Each set can contain a fixed number of entries and at every entry there might be child sets, up to a given level. Child sets at the same level must have the same type. .P In spite it is called IP sets, depending on the type the sets may store not only IP addresses but (TCP/UDP) port numbers as well, or additional informations besides IP addresses: the word IP means a general term here. See the set type definitions below. .P Child sets are identified by `IP', without the possible additional informations stored in the set. There is no other relationship between the set entry and the child set at that entry: the set entry can be added, deleted without disturbing the child set and vice versa. Therefore below we denote pure IPs identifying a child set by `IP', while entries in a set by `entry'. .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 type0[,type1...] type0-options" Create a set identified with setname, with listed types. Type0-specific options must be supplied. When more than one set type is given on the command line, room for the first level child sets are automatically reserved. .TP .BI "-N, --create " "\fIsetname:IP[,...]\fP type type-options" Create a child set at setname:IP[,...] identified with type, which must correspond to the set type used when the set was created. The parent set and parent child sets must exist. When the .B "-c, --childsets" option is used, space for child sets will be reserved. .TP .BI "-X, --destroy " "[\fIsetname[:IP,...]\fP]" Destroy the specified set or child set, or all sets if none is given. .TP .BI "-F, --flush " "[\fIsetname[:IP,...]\fP]" Delete all entries from the specified set or child set, or from all sets if none is given. When the .B "-c, --childsets" option is specified, child sets are recursively flushed too. .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 the content of two sets. Both sets must exist. .TP .BI "-L, --list " "[\fIsetname[:IP,...]\fP]" List the entries from the specified set or child set, or from all sets if none is given. When the .B "-c, --childsets" option is specified, child sets are recursively listed too. 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. .TP .BI "-S, --save " "[\fIsetname[:IP,...]\fP]" Save the set or child set, or all sets if none specified to stdout in a format, that --restore can read. .TP .BI "-R, --restore " Restore from stdin a saved session generated by --save. .TP .BI "-A, --add " "\fIsetname[:IP,...]\fP \fIentry[:entry,...]\fP" Add an entry to a (child) set or multiple entries to the child sets defined by the entries. In another words, the command .nf ipset -A set entry1,entry2 .fi is equivalent to .nf ipset -A set entry1 ipset -A set:entry1-IP entry2 .fi .TP .BI "-D, --del " "\fIsetname[:IP,...]\fP \fIentry[:entry,...]\fP" Delete an entry from a (child) set or multiple entries from the child sets defined by the entries. .P When multiple entries are added or deleted and the command fails at a deeper level, the successfully added/deleted entries are not restored to their previous value. .TP .BI "-T, --test " "\fIsetname[:IP,...]\fP \fIentry[:entry,...]\fP" Test if an entry or multiple entries exist in a (child) set. Exit status number is nonzero if any tested entry is missing from the set and zero if they are all exists. .TP .BI "-H, --help " "[settype] [options]" Print help and settype specific help. Some set types has additional help options, see below. .SS "OTHER OPTIONS" The following additional options can be specified: .TP .B "-s, --sorted" Sorted output. When listing sets, entries are listed sorted. .TP .B "-n, --numeric" Numeric output. When listing sets, 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). .TP .B "-q, --quiet" Suppress any output to stdout and stderr. Ipset will still return possible errors. .TP .B "-c, --childsets" Space will be reserved for child sets when creating a set, or list/flush operation valid for child sets too. .TP .B "-i, --hint" Hint best settype initialization parameters (for hash type sets). .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. .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 fixed size hash to store the IP addresses and can store up to 65535 (size of a B-class network) addresses. 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. When adding and IP address to the hash, the IP address can be preceded by `+', by which you can force to overwrite already existing entries in the hash. .P In help mode you can use the .B "--hint" option to find the the smallest hashsize with the corresponding initval for your hash entries. .P Options to use when creating an iphash set: .TP .BR "--hashsize " hashsize .TP .BR "--initval " hash-initval Create an iphash set with the specified hashsize and initial (random) hash parameter. (The .B "--initval" parameter is optional.) .TP .BR "--netmask " CIDR-netmask When the optional .B "--netmask" parameter specified, network addresses will be stored in the set instead of IP addresses. .TP The possible help mode options are: .TP .BI "-i, --hint" Enable hinting mode to find the best (smallest) hash size. The entries are fed via standard input. .TP .BI "--try " number How many times should the program try the same hash size with different random initvals (default 8). .TP .BI "--factor " number The starting hash size is so many times the number of the entries (default 4). .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 ..