summaryrefslogtreecommitdiffstats
path: root/ipset.8
diff options
context:
space:
mode:
authorkadlec <kadlec>2004-02-09 13:47:01 +0000
committerkadlec <kadlec>2004-02-09 13:47:01 +0000
commit2c3e49def40b41677182fc9243128f11c5e148e9 (patch)
tree53574085f70bc86589c22ea7cff030b03486e596 /ipset.8
Userspace part of sets: ipset added (JK)
Diffstat (limited to 'ipset.8')
-rw-r--r--ipset.8289
1 files changed, 289 insertions, 0 deletions
diff --git a/ipset.8 b/ipset.8
new file mode 100644
index 0000000..e7aea08
--- /dev/null
+++ b/ipset.8
@@ -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 ..