path: root/ipset.8

.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 ..