.\" 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.
-.TH "IPSET" "8" "May 23, 2012" "Jozsef Kadlecsik" ""
+.TH "IPSET" "8" "Apr 4, 2013" "Jozsef Kadlecsik" ""
.SH "NAME"
ipset \(em administration tool for IP sets
.SH "SYNOPSIS"
The saved session can be fed from stdin or the option
\fB\-file\fR
can be used to specify a filename instead of stdin.
+
+Please note, existing sets and elements are not erased by
+\fBrestore\fP unless specified so in the restore file. All commands
+are allowed in restore mode except \fBlist\fP, \fBhelp\fP,
+\fBversion\fP, interactive mode and \fBrestore\fP itself.
.TP
\fBflush\fP [ \fISETNAME\fP ]
Flush all entries from the specified set or flush
cannot be abbreviated.
.TP
\fB\-!\fP, \fB\-exist\fP
-Ignore errors when the exactly the same set is to be created or already
+Ignore errors when exactly the same set is to be created or already
added entry is added or missing entry is deleted.
.TP
\fB\-o\fP, \fB\-output\fP { \fBplain\fR | \fBsave\fR | \fBxml\fR }
List the set names and headers, i.e. suppress listing of set members.
.TP
\fB\-f\fP, \fB\-file\fP \fIfilename\fR
-Specidy a filename to print into instead of stdout
+Specify a filename to print into instead of stdout
(\fBlist\fR
or
\fBsave\fR
commands) or read from instead of stdin
(\fBrestore\fR
command).
-.SH "SET TYPES"
+.SH "INTRODUCTION"
A set type comprises of the storage method by which the data is stored and
the data type(s) which are stored in the set. Therefore the
\fITYPENAME\fR
When adding, deleting or testing entries in a set, the same comma separated
data syntax must be used for the entry parameter of the commands, i.e
-
+.IP
ipset add foo ipaddr,portnum,ipaddr
+.PP
+If host names or service names with dash in the name are used instead of IP
+addresses or service numbers, then the host name or service name must be enclosed
+in square brackets. Example:
+.IP
+ipset add foo [test\-hostname],[ftp\-data]
+.PP
+In the case of host names the DNS resolver is called internally
+by \fBipset\fR but if it returns multiple IP addresses, only the
+first one is used.
The \fBbitmap\fR and \fBlist\fR types use a fixed sized storage. The \fBhash\fR
types use a hash to store the elements. In order to avoid clashes in the hash,
\fBiptables/ip6tables\fR,
then the hash size is fixed and the set won't be duplicated, even if the new
entry cannot be added to the set.
-
-All set types support the optional
-
-\fBtimeout\fR \fIvalue\fR
-
+.SH "GENERIC CREATE AND ADD OPTIONS"
+.SS timeout
+All set types supports the optional \fBtimeout\fR
parameter when creating a set and adding entries. The value of the \fBtimeout\fR
parameter for the \fBcreate\fR command means the default timeout value (in seconds)
for new entries. If a set is created with timeout support, then the same
\fBtimeout\fR option can be used to specify non\-default timeout values
when adding entries. Zero timeout value means the entry is added permanent to the set.
The timeout value of already added elements can be changed by readding the element
-using the \fB\-exist\fR option.
-
+using the \fB\-exist\fR option. Example:
+.IP
+ipset create test hash:ip timeout 300
+.IP
+ipset add test 192.168.0.1 timeout 60
+.IP
+ipset -exist add test 192.168.0.1 timeout 600
+.PP
+.SS nomatch
The \fBhash\fR set types which can store \fBnet\fR type of data (i.e. hash:*net*)
-support the optional
-
-\fBnomatch\fR
-
+support the optional \fBnomatch\fR
option when adding entries. When matching elements in the set, entries marked
-as \fBnomatch\fR are skipped as if those were no added to the set, which makes
+as \fBnomatch\fR are skipped as if those were not added to the set, which makes
possible to build up sets with exceptions. See the example at hash type
\fBhash:net\fR below.
-If host names or service names with dash in the name are used instead of IP
-addresses or service numbers, then the host name or service name must be enclosed
-in square brackets. Example:
-
-.IP
-ipset add foo [test\-hostname],[ftp\-data]
+When elements are tested by \fBipset\fR, the \fBnomatch\fR
+flags are taken into account. If one wants to test the existence of an element
+marked with \fBnomatch\fR in a set, then the flag must be specified too.
+.SS "counters, packets, bytes"
+All set types support the optional \fBcounters\fR
+option when creating a set. If the option is specified then the set is created
+with packet and byte counters per element support. The packet and byte counters
+are initialized to zero when the elements are (re\-)added to the set,
+unless the packet and byte counter values are explicitly specified by the
+\fBpackets\fR and \fBbytes\fR options. An example when an element is added
+to a set with non\-zero counter values:
+.IP
+ipset create foo hash:ip counters
+.IP
+ipset add foo 192.168.1.1 packets 42 bytes 1024
+.PP
+.SH "SET TYPES"
.SS bitmap:ip
The \fBbitmap:ip\fR set type uses a memory range to store either IPv4 host
(default) or IPv4 network addresses. A \fBbitmap:ip\fR type of set can store up
to 65536 entries.
.PP
-\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR [ \fBnetmask\fP \fIcidr\fP ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR [ \fBnetmask\fP \fIcidr\fP ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := { \fIip\fR | \fIfromip\fR\-\fItoip\fR | \fIip\fR/\fIcidr\fR }
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := { \fIip\fR | \fIfromip\fR\-\fItoip\fR | \fIip\fR/\fIcidr\fR }
.PP
stored in the set instead of IP host addresses. The \fIcidr\fR prefix value must be
between 1\-32.
An IP address will be in the set if the network address, which is resulted by
-masking the address with the specified netmask calculated from the prefix,
-can be found in the set.
+masking the address with the specified netmask, can be found in the set.
.PP
The \fBbitmap:ip\fR type supports adding or deleting multiple entries in one
command.
.SS bitmap:ip,mac
The \fBbitmap:ip,mac\fR set type uses a memory range to store IPv4 and a MAC address pairs. A \fBbitmap:ip,mac\fR type of set can store up to 65536 entries.
.PP
-\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIip\fR[,\fImacaddr\fR]
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIip\fR[,\fImacaddr\fR]
.PP
.PP
The \fBbitmap:ip,mac\fR type of sets require two \fBsrc/dst\fR parameters of
the \fBset\fR match and \fBSET\fR target netfilter kernel modules and the second
-one must be \fBsrc\fR to match, add or delete entries because the \fBset\fR match
-and \fBSET\fR target have access to the source MAC address only.
+one must be \fBsrc\fR to match, add or delete entries, because the \fBset\fR
+match and \fBSET\fR target have access to the source MAC address only.
.PP
Examples:
.IP
The \fBbitmap:port\fR set type uses a memory range to store port numbers
and such a set can store up to 65536 ports.
.PP
-\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromport\fP\-\fItoport [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := \fBrange\fP \fIfromport\fP\-\fItoport [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := { \fIport\fR | \fIfromport\fR\-\fItoport\fR }
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := { \fIport\fR | \fIfromport\fR\-\fItoport\fR }
.PP
network addresses. Zero valued IP address cannot be stored in a \fBhash:ip\fR
type of set.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBnetmask\fP \fIcidr\fP ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBnetmask\fP \fIcidr\fP ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIipaddr\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIipaddr\fR
.PP
When the optional \fBnetmask\fP parameter specified, network addresses will be
stored in the set instead of IP host addresses. The \fIcidr\fP prefix value must be
between 1\-32 for IPv4 and between 1\-128 for IPv6. An IP address will be in the set
-if the network address, which is resulted by masking the address with the netmask
-calculated from the prefix, can be found in the set.
+if the network address, which is resulted by masking the address with the netmask,
+can be found in the set.
.PP
For the \fBinet\fR family one can add or delete multiple entries by specifying
a range or a network:
The \fBhash:net\fR set type uses a hash to store different sized IP network addresses.
Network address with zero prefix size cannot be stored in this type of sets.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fInetaddr\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fInetaddr\fR
.PP
.PP
When matching the elements in the set above, all IP addresses will match
from the networks 192.168.0.0/24, 10.1.0.0/16 and 192.168.0/24 except
-192.168.0/30.
+the ones from 192.168.0/30.
.SS hash:ip,port
The \fBhash:ip,port\fR set type uses a hash to store IP address and port number pairs.
The port number is interpreted together with a protocol (default TCP) and zero
protocol number cannot be used.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR
.PP
(default TCP) and zero protocol number cannot be used. Network
address with zero prefix size is not accepted either.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fInetaddr\fR,[\fIproto\fR:]\fIport\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fInetaddr\fR,[\fIproto\fR:]\fIport\fR
.PP
and a second IP address triples. The port number is interpreted together with a
protocol (default TCP) and zero protocol number cannot be used.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR
.PP
protocol (default TCP) and zero protocol number cannot be used. Network
address with zero prefix size cannot be stored either.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fInetaddr\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fInetaddr\fR
.PP
The \fBhash:net,iface\fR set type uses a hash to store different sized IP network
address and interface name pairs.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBfamily\fR { \fBinet\fR | \fBinet6\fR } ] | [ \fBhashsize\fR \fIvalue\fR ] [ \fBmaxelem\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fInetaddr\fR,[\fBphysdev\fR:]\fIiface\fR
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBnomatch\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fInetaddr\fR,[\fBphysdev\fR:]\fIiface\fR
.PP
The \fBlist:set\fR type uses a simple list in which you can store
set names.
.PP
-\fICREATE\-OPTIONS\fR := [ \fBsize\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ]
+\fICREATE\-OPTIONS\fR := [ \fBsize\fR \fIvalue\fR ] [ \fBtimeout\fR \fIvalue\fR ] [ \fBcounters\fP ]
.PP
\fIADD\-ENTRY\fR := \fIsetname\fR [ { \fBbefore\fR | \fBafter\fR } \fIsetname\fR ]
.PP
-\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
+\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] [ \fBpackets\fR \fIvalue\fR ] [ \fBbytes\fR \fIvalue\fR ]
.PP
\fIDEL\-ENTRY\fR := \fIsetname\fR [ { \fBbefore\fR | \fBafter\fR } \fIsetname\fR ]
.PP
projects / ipset / commitdiff