summaryrefslogtreecommitdiffstats
path: root/src/ipset.8
diff options
context:
space:
mode:
Diffstat (limited to 'src/ipset.8')
-rw-r--r--src/ipset.8537
1 files changed, 537 insertions, 0 deletions
diff --git a/src/ipset.8 b/src/ipset.8
new file mode 100644
index 0000000..fa73298
--- /dev/null
+++ b/src/ipset.8
@@ -0,0 +1,537 @@
+.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 \(em administration tool for IP sets
+.SH SYNOPSIS
+.PP
+\fBipset \-N\fP \fIset\fP \fItype-specification\fP [\fIoptions\fP...]
+.PP
+\fBipset\fP {\fB\-F\fP|\fB\-H\fP|\fB\-L\fP|\fB\-S\fP|\fB\-X\fP} [\fIset\fP]
+[\fIoptions\fP...]
+.PP
+\fBipset\fP {\fB\-E\fP|\fB\-W\fP} \fIfrom-set\fP \fIto-set\fP
+.PP
+\fBipset\fP {\fB\-A\fP|\fB\-D\fP|\fB\-T\fP} \fIset\fP \fIentry\fP
+.PP
+\fBipset \-R\fP
+.PP
+\fBipset\fP {\fB-V\fP|\fB\-v\fP}
+.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
+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 single 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
+\fB\-N\fP, \fB\-\-create\fP \fIsetname\fP \fItype\fP \fItype-specific-options\fP
+Create a set identified with setname and specified type.
+Type-specific options must be supplied.
+.TP
+\fB\-X\fP, \fB\-\-destroy\fP [\fIsetname\fP]
+Destroy the specified set or all the sets if none is given.
+
+If the set has got references, nothing is done.
+.TP
+\fB\-F\fP, \fB\-\-flush\fP [\fIsetname\fP]
+Delete all entries from the specified set or flush
+all sets if none is given.
+.TP
+\fB\-E\fP, \fB\-\-rename\fP \fIfrom-setname\fP \fIto-setname\fP
+Rename a set. Set identified by to-setname must not exist.
+.TP
+\fB\-W\fP, \fB\-\-swap\fP \fIfrom-setname\fP \fIto-setname\fP
+Swap the content of two sets, or in another words,
+exchange the name of two sets. The referred sets must exist and
+identical type of sets can be swapped only.
+.TP
+\fB\-L\fP, \fB\-\-list\fP [\fIsetname\fP]
+List the entries for the specified set, or for
+all sets if none is given. The
+\fB\-r\fP/\fB\-\-resolve\fP
+option can be used to force name lookups (which may be slow). When the
+\fB\-s\fP/\fB\-\-sorted\fP
+option is given, the entries are listed sorted (if the given set
+type supports the operation).
+.TP
+\fB\-S\fP, \fB\-\-save\fP [\fIsetname\fP]
+Save the given set, or all sets if none is given
+to stdout in a format that \fB\-\-restore\fP can read.
+.TP
+\fB\-R\fP, \fB\-\-restore\fP
+Restore a saved session generated by \fB\-\-save\fP. The saved session
+can be fed from stdin.
+
+When generating a session file please note that the supported commands
+(create set and add element) must appear in a strict order: first create
+the set, then add all elements. Then create the next set, add all its elements
+and so on. Also, it is a restore operation, so the sets being restored must
+not exist.
+.TP
+\fB\-A\fP, \fB\-\-add\fP \fIsetname\fP \fIentry\fP
+Add an entry to a set.
+.TP
+\fB\-D\fP, \fB\-\-del\fP \fIsetname\fP \fIentry\fP
+Delete an entry from a set.
+.TP
+\fB-T\fP, \fB\-\-test\fP \fIsetname\fP \fIentry\fP
+Test wether an entry is in a set or not. Exit status number is zero
+if the tested entry is in the set and nonzero if it is missing from
+the set.
+.TP
+\fB\-H\fP, \fB\-\-help\fP [\fIsettype\fP]
+Print help and settype specific help if settype specified.
+.TP
+\fB\-V\fP, \fB\-v\fP, \fB\-\-version\fP
+Print program version and protocol version.
+.P
+.SS "OTHER OPTIONS"
+The following additional options can be specified:
+.TP
+\fB\-r\fP, \fB\-\-resolve\fP
+When listing sets, enforce name lookup. The
+program will try to display the IP entries resolved to
+host names or services (whenever applicable), which can trigger
+.B
+slow
+DNS
+lookups.
+.TP
+\fB\-s\fP, \fB\-\-sorted\fP
+Sorted output. When listing sets, entries are listed sorted.
+.TP
+\fB\-n\fP, \fB\-\-numeric\fP
+Numeric output. When listing sets, IP addresses and
+port numbers will be printed in numeric format. This is the default.
+.TP
+\fB\-q\fP, \fB\-\-quiet\fP
+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 65536 (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. If the optional
+\fB\-\-netmask\fP
+parameter is specified with a CIDR netmask value between 1-31 then
+network addresses are stored in the given set: i.e an
+IP address will be in the set if the network address, which is 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
+\fB\-\-from\fP \fIfrom-addr\fP
+.TP
+\fB\-\-to\fP \fIto-addr\fP
+Create an ipmap set from the specified address range.
+.TP
+\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
+Create an ipmap set from the specified network.
+.TP
+\fB\-\-netmask\fP \fIprefixlen\fP
+When the optional
+\fB\-\-netmask\fP
+parameter specified, network addresses will be
+stored in the set instead of IP addresses, and the \fIfrom-addr\fP parameter
+must be a network address. The \fIprefixlen\fP value must be between 1-31.
+.PP
+Example:
+.IP
+ipset \-N test ipmap \-\-network 192.168.0.0/16
+.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 65536 (B-class network) IP addresses with MAC.
+When adding an entry to a macipmap set, you must specify the entry as
+"\fIaddress\fP\fB,\fP\fImac\fP".
+When deleting or testing macipmap entries, the
+"\fB,\fP\fImac\fP"
+part is not mandatory.
+.P
+Options to use when creating an macipmap set:
+.TP
+\fB\-\-from\fP \fIfrom-addr\fP
+.TP
+\fB\-\-to\fP \fIto-addr\fP
+Create a macipmap set from the specified address range.
+.TP
+\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
+Create a macipmap set from the specified network.
+.TP
+\fB\-\-matchunset\fP
+When the optional
+\fB\-\-matchunset\fP
+parameter specified, IP addresses which could be stored
+in the set but not set yet, will always match.
+.P
+Please note, the
+"set"
+and
+"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 65536 ports.
+The portmap set type is very fast and memory cheap.
+.P
+Options to use when creating an portmap set:
+.TP
+\fB\-\-from\fP \fIfrom-port\fP
+.TP
+\fB\-\-to\fP \fIto-port\fP
+Create a portmap set from the specified port 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
+great to store random addresses. If the optional
+\fB\-\-netmask\fP
+parameter is specified with a CIDR prefix length value between 1-31 then
+network addresses are stored in the given set: i.e an
+IP address will be in the set if the network address, which is resulted
+by masking the address with the specified netmask, can be found in the set.
+.P
+Options to use when creating an iphash set:
+.TP
+\fB\-\-hashsize\fP \fIhashsize\fP
+The initial hash size (default 1024)
+.TP
+\fB\-\-probes\fP \fIprobes\fP
+How many times try to resolve clashing at adding an IP to the hash
+by double-hashing (default 8).
+.TP
+\fB\-\-resize\fP \fIpercent\fP
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+\fIprobes\fP
+number of double-hashing.
+.TP
+\fB\-\-netmask\fP \fIprefixlen\fP
+When the optional
+\fB\-\-netmask\fP
+parameter specified, network addresses will be
+stored in the set instead of IP addresses. The \fIprefixlen\fP value must
+be between 1-31.
+.P
+The iphash type of sets can store up to 65536 entries. If a set is full,
+no new entries can be added to it.
+.P
+Sets created by zero valued resize parameter won't be resized at all.
+The lookup time in an iphash type of set grows approximately linearly with
+the value of the
+\fIprobes\fP
+parameter. In general higher
+\fIprobes\fP
+value results better utilized hash while smaller value
+produces larger, sparser hash.
+.PP
+Example:
+.IP
+ipset \-N test iphash \-\-probes 2
+.SS nethash
+The nethash set type uses a hash to store different size of
+network addresses. The
+.I
+entry
+used in the ipset commands must be in the form
+"\fIaddress\fP\fB/\fP\fIprefixlen\fP"
+where prefixlen 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 nethash set:
+.TP
+\fB\-\-hashsize\fP \fIhashsize\fP
+The initial hash size (default 1024)
+.TP
+\fB\-\-probes\fP \fIprobes\fP
+How many times try to resolve clashing at adding an IP to the hash
+by double-hashing (default 4).
+.TP
+\fB\-\-resize\fP \fIpercent\fP
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+.P
+The nethash type of sets can store up to 65536 entries. If a set is full,
+no new entries can be added to it.
+.P
+An IP address will be in a nethash type of set if it belongs to any of the
+netblocks added to the set. The matching always start from the smallest
+size of netblock (most specific netmask) to the largest ones (least
+specific netmasks). When adding/deleting IP addresses
+to a nethash set by the
+"SET"
+netfilter kernel module, it will be added/deleted by the smallest
+netblock size which can be found in the set, or by /31 if the set is empty.
+.P
+The lookup time in a nethash type of set grows approximately linearly
+with the times of the
+\fIprobes\fP
+parameter and the number of different mask parameters in the hash.
+Otherwise the same speed and memory efficiency comments applies here
+as at the iphash type.
+.SS ipporthash
+The ipporthash set type uses a hash to store IP address and port pairs.
+In order to avoid clashes in the hash double-hashing, and as a last
+resort, dynamic growing of the hash performed. An ipporthash set can
+store up to 65536 (B-class network) IP addresses with all possible port
+values. When adding, deleting and testing values in an ipporthash type of
+set, the entries must be specified as
+"\fIaddress\fP\fB,\fP\fIport\fP".
+.P
+The ipporthash types of sets evaluates two src/dst parameters of the
+"set"
+match and
+"SET"
+target.
+.P
+Options to use when creating an ipporthash set:
+.TP
+\fB\-\-from\fP \fIfrom-addr\fP
+.TP
+\fB\-\-to\fP \fIto-addr\fP
+Create an ipporthash set from the specified address range.
+.TP
+\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
+Create an ipporthash set from the specified network.
+.TP
+\fB\-\-hashsize\fP \fIhashsize\fP
+The initial hash size (default 1024)
+.TP
+\fB\-\-probes\fP \fIprobes\fP
+How many times try to resolve clashing at adding an IP to the hash
+by double-hashing (default 8).
+.TP
+\fB\-\-resize\fP \fIpercent\fP
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+\fIprobes\fP
+number of double-hashing.
+.P
+The same resizing, speed and memory efficiency comments applies here
+as at the iphash type.
+.SS ipportiphash
+The ipportiphash set type uses a hash to store IP address,port and IP
+address triples. The first IP address must come form a maximum /16
+sized network or range while the port number and the second IP address
+parameters are arbitrary. When adding, deleting and testing values in an
+ipportiphash type of set, the entries must be specified as
+"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP".
+.P
+The ipportiphash types of sets evaluates three src/dst parameters of the
+"set"
+match and
+"SET"
+target.
+.P
+Options to use when creating an ipportiphash set:
+.TP
+\fB\-\-from\fP \fIfrom-addr\fP
+.TP
+\fB\-\-to\fP \fIto-addr\fP
+Create an ipportiphash set from the specified address range.
+.TP
+\fB\-\-network\fP \fIaddr\fP\fB/\fP\fImask\fP
+Create an ipportiphash set from the specified network.
+.TP
+\fB\-\-hashsize\fP \fIhashsize\fP
+The initial hash size (default 1024)
+.TP
+\fB\-\-probes\fP \fIprobes\fP
+How many times try to resolve clashing at adding an IP to the hash
+by double-hashing (default 8).
+.TP
+\fB\-\-resize\fP \fIpercent\fP
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+\fIprobes\fP
+number of double-hashing.
+.P
+The same resizing, speed and memory efficiency comments applies here
+as at the iphash type.
+.SS ipportnethash
+The ipportnethash set type uses a hash to store IP address, port, and
+network address triples. The IP address must come form a maximum /16
+sized network or range while the port number and the network address
+parameters are arbitrary, but the size of the network address must be
+between /1-/31. When adding, deleting
+and testing values in an ipportnethash type of set, the entries must be
+specified as
+"\fIaddress\fP\fB,\fP\fIport\fP\fB,\fP\fIaddress\fP\fB/\fP\fIprefixlen\fP".
+.P
+The ipportnethash types of sets evaluates three src/dst parameters of the
+"set"
+match and
+"SET"
+target.
+.P
+Options to use when creating an ipportnethash set:
+.TP
+\fB\-\-from\fP \fIfrom-address\fP
+.TP
+\fB\-\-to\fP \fIto-address\fP
+Create an ipporthash set from the specified range.
+.TP
+\fB\-\-network\fP \fIaddress\fP\fB/\fP\fImask\fP
+Create an ipporthash set from the specified network.
+.TP
+\fB\-\-hashsize\fP \fIhashsize\fP
+The initial hash size (default 1024)
+.TP
+\fB\-\-probes\fP \fIprobes\fP
+How many times try to resolve clashing at adding an IP to the hash
+by double-hashing (default 8).
+.TP
+\fB\-\-resize\fP \fIpercent\fP
+Increase the hash size by this many percent (default 50) when adding
+an IP to the hash could not be performed after
+\fIprobes\fP
+number of double-hashing.
+.P
+The same resizing, speed and memory efficiency comments applies here
+as at the iphash type.
+.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
+\fB\-\-timeout\fP \fIvalue\fP
+The timeout value for the entries in seconds (default 0)
+.P
+If a set was created with a nonzero valued
+\fB\-\-timeout\fP
+parameter then one may add IP addresses to the set with a specific
+timeout value using the syntax
+"\fIaddress\fP\fB,\fP\fItimeout-value\fP".
+Similarly to the hash types, the iptree type of sets can store up to 65536
+entries.
+.SS iptreemap
+The iptreemap set type uses a tree to store IP addresses or networks,
+where the last octet of an IP address are stored in a bitmap.
+As input entry, you can add IP addresses, CIDR blocks or network ranges
+to the set. Network ranges can be specified in the format
+"\fIaddress1\fP\fB-\fP\fIaddress2\fP".
+.P
+Options to use when creating an iptreemap set:
+.TP
+\fB\-\-gc\fP \fIvalue\fP
+How often the garbage collection should be called, in seconds (default 300)
+.SS setlist
+The setlist type uses a simple list in which you can store sets. By the
+ipset
+command you can add, delete and test sets in a setlist type of set.
+You can specify the sets as
+"\fIsetname\fP[\fB,\fP{\fBafter\fP|\fBbefore\fP},\fIsetname\fP]".
+By default new sets are added after (appended to) the existing
+elements. Setlist type of sets cannot be added to a setlist type of set.
+.P
+Options to use when creating a setlist type of set:
+.TP
+\fB\-\-size\fP \fIsize\fP
+Create a setlist type of set with the given size (default 8).
+.PP
+By the
+"set"
+match or
+"SET"
+target of
+\fBiptables\fP(8)
+you can test, add or delete entries in the sets. The match
+will try to find a matching IP address/port in the sets and
+the target will try to add the IP address/port to the first set
+to which it can be added. The number of src,dst options of
+the match and target are important: sets which eats more src,dst
+parameters than specified are skipped, while sets with equal
+or less parameters are checked, elements added. For example
+if
+.I
+a
+and
+.I
+b
+are setlist type of sets then in the command
+.IP
+iptables \-m set \-\-match\-set a src,dst \-j SET \-\-add-set b src,dst
+.PP
+the match and target will skip any set in
+.I a
+and
+.I b
+which stores
+data triples, but will check all sets with single or double
+data storage in
+.I a
+set and add src to the first single or src,dst to the first double
+data storage set in
+\fIb\fP.
+.P
+You can imagine a setlist type of set as an ordered union of
+the set elements.
+.SH GENERAL RESTRICTIONS
+Setnames starting with colon (:) cannot be defined. Zero valued set
+entries cannot be used with hash type of sets.
+.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.
+.P
+Old separator tokens (':' and '%") are still accepted.
+.P
+Binding support is removed.
+.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.
+.P
+Sven Wegener wrote the iptreemap type.
+.SH LAST REMARK
+.BR "I stand on the shoulders of giants."