diff options
Diffstat (limited to 'ipset.8')
| -rw-r--r-- | ipset.8 | 289 |
1 files changed, 289 insertions, 0 deletions
@@ -0,0 +1,289 @@ +.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 \- 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 .. |