mirror of
git://git.code.sf.net/p/xtables-addons/xtables-addons
synced 2025-09-21 12:04:56 +02:00
2dc79fe008
* Handle EAGAIN from autoloading code. * Turn one nfgenmsg site into genlmsg to avoid protocol mismatch
759 lines
28 KiB
Groff
759 lines
28 KiB
Groff
.\" 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.
|
|
.TH "IPSET" "8" "Oct 15, 2010" "Jozsef Kadlecsik" ""
|
|
.SH "NAME"
|
|
ipset \(em administration tool for IP sets
|
|
.SH "SYNOPSIS"
|
|
\fBipset\fR [ \fIOPTIONS\fR ] \fICOMMAND\fR [ \fICOMMAND\-OPTIONS\fR ]
|
|
.PP
|
|
COMMANDS := { \fBcreate\fR | \fBadd\fR | \fBdel\fR | \fBtest\fR | \fBdestroy\fR | \fBlist\fR | \fBsave\fR | \fBrestore\fR | \fBflush\fR | \fBrename\fR | \fBswap\fR | \fBhelp\fR | \fBversion\fR | \fB\-\fR }
|
|
.PP
|
|
\fIOPTIONS\fR := { \fB\-exist\fR | \fB\-output\fR { \fBplain\fR | \fBsave\fR | \fBxml\fR } | \fB\-quiet\fR | \fB\-resolve\fR | \fB\-sorted\fR }
|
|
.PP
|
|
\fBipset\fR \fBcreate\fR \fISETNAME\fR \fITYPENAME\fR [ \fICREATE\-OPTIONS\fR ]
|
|
.PP
|
|
\fBipset\fR \fBadd\fR \fISETNAME\fR \fIADD\-ENTRY\fR [ \fIADD\-OPTIONS\fR ]
|
|
.PP
|
|
\fBipset\fR \fBdel\fR \fISETNAME\fR \fIDEL\-ENTRY\fR [ \fIDEL\-OPTIONS\fR ]
|
|
.PP
|
|
\fBipset\fR \fBtest\fR \fISETNAME\fR \fITEST\-ENTRY\fR [ \fITEST\-OPTIONS\fR ]
|
|
.PP
|
|
\fBipset\fR \fBdestroy\fR [ \fISETNAME\fR ]
|
|
.PP
|
|
\fBipset\fR \fBlist\fR [ \fISETNAME\fR ]
|
|
.PP
|
|
\fBipset\fR \fBsave\fR [ \fISETNAME\fR ]
|
|
.PP
|
|
\fBipset\fR \fBrestore\fR
|
|
.PP
|
|
\fBipset\fR \fBflush\fR [ \fISETNAME\fR ]
|
|
.PP
|
|
\fBipset\fR \fBrename\fR \fISETNAME\-FROM\fR \fISETNAME\-TO\fR
|
|
.PP
|
|
\fBipset\fR \fBswap\fR \fISETNAME\-FROM\fR \fISETNAME\-TO\fR
|
|
.PP
|
|
\fBipset\fR \fBhelp\fR [ \fITYPENAME\fR ]
|
|
.PP
|
|
\fBipset\fR \fBversion\fR
|
|
.PP
|
|
\fBipset\fR \fB\-\fR
|
|
.SH "DESCRIPTION"
|
|
\fBipset\fR
|
|
is used to set up, maintain and inspect so called IP sets in the Linux
|
|
kernel. Depending on the type of the set, an IP set may store IP(v4/v6)
|
|
addresses, (TCP/UDP) port numbers, IP and MAC address pairs, IP address
|
|
and port number pairs, etc. See the set type definitions below.
|
|
.PP
|
|
\fBIptables\fR
|
|
matches and targets referring to sets create references, which
|
|
protect the given sets in the kernel. A set cannot be destroyed
|
|
while there is a single reference pointing to it.
|
|
.SH "OPTIONS"
|
|
The options that are recognized by
|
|
\fBipset\fR
|
|
can be divided into several different groups.
|
|
.SS COMMANDS
|
|
These options specify the desired 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 names, you need to use only enough
|
|
letters to ensure that
|
|
\fBipset\fR
|
|
can differentiate it from all other commands. The
|
|
\fBipset\fR
|
|
parser follows the order here when looking for the shortest match
|
|
in the long command names.
|
|
.TP
|
|
\fBn\fP, \fBcreate\fP \fISETNAME\fP \fITYPENAME\fP [ \fICREATE\-OPTIONS\fP ]
|
|
Create a set identified with setname and specified type. The type may require
|
|
type specific options. If the
|
|
\fB\-exist\fR
|
|
option is specified,
|
|
\fBipset\fR
|
|
ignores the error otherwise raised when the same set (setname and create parameters
|
|
are identical) already exists.
|
|
.TP
|
|
\fBadd\fP \fISETNAME\fP \fIADD\-ENTRY\fP [ \fIADD\-OPTIONS\fP ]
|
|
Add a given entry to the set. If the
|
|
\fB\-exist\fR
|
|
option is specified,
|
|
\fBipset\fR
|
|
ignores if the entry already added to the set.
|
|
.TP
|
|
\fBdel\fP \fISETNAME\fP \fIDEL\-ENTRY\fP [ \fIDEL\-OPTIONS\fP ]
|
|
Delete an entry from a set. If the
|
|
\fB\-exist\fR
|
|
option is specified,
|
|
\fBipset\fR
|
|
ignores if the entry does not added to (already expired from) the set.
|
|
.TP
|
|
\fBtest\fP \fISETNAME\fP \fITEST\-ENTRY\fP [ \fITEST\-OPTIONS\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
|
|
\fBx\fP, \fBdestroy\fP [ \fISETNAME\fP ]
|
|
Destroy the specified set or all the sets if none is given.
|
|
|
|
If the set has got reference(s), nothing is done and no set destroyed.
|
|
.TP
|
|
\fBlist\fP [ \fISETNAME\fP ]
|
|
List the header data and the entries for the specified set, or for
|
|
all sets if none is given. The
|
|
\fB\-resolve\fP
|
|
option can be used to force name lookups (which may be slow). When the
|
|
\fB\-sorted\fP
|
|
option is given, the entries are listed sorted (if the given set
|
|
type supports the operation). The option
|
|
\fB\-output\fR
|
|
can be used to control the format of the listing:
|
|
\fBplain\fR, \fBsave\fR or \fBxml\fR.
|
|
The default is
|
|
\fBplain\fR.
|
|
.TP
|
|
\fBsave\fP [ \fISETNAME\fP ]
|
|
Save the given set, or all sets if none is given
|
|
to stdout in a format that
|
|
\fBrestore\fP
|
|
can read.
|
|
.TP
|
|
\fBrestore\fP
|
|
Restore a saved session generated by
|
|
\fBsave\fP.
|
|
The saved session can be fed from stdin.
|
|
.TP
|
|
\fBflush\fP [ \fISETNAME\fP ]
|
|
Flush all entries from the specified set or flush
|
|
all sets if none is given.
|
|
.TP
|
|
\fBe\fP, \fBrename\fP \fISETNAME\-FROM\fP \fISETNAME\-TO\fP
|
|
Rename a set. Set identified by
|
|
\fISETNAME\-TO\fR
|
|
must not exist.
|
|
.TP
|
|
\fBw\fP, \fBswap\fP \fISETNAME\-FROM\fP \fISETNAME\-TO\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
|
|
\fBhelp\fP [ \fITYPENAME\fP ]
|
|
Print help and set type specific help if
|
|
\fITYPENAME\fR
|
|
is specified.
|
|
.TP
|
|
\fBversion\fP
|
|
Print program version.
|
|
.TP
|
|
\fB\-\fP
|
|
If a dash is specified as command, then
|
|
\fBipset\fR
|
|
enters a simple interactive mode and the commands are read from the standard input.
|
|
The interactive mode can be finished by entering the pseudo\-command
|
|
\fBquit\fR.
|
|
.P
|
|
.SS "OTHER OPTIONS"
|
|
The following additional options can be specified. The long option names
|
|
cannot be abbreviated.
|
|
.TP
|
|
\fB\-!\fP, \fB\-exist\fP
|
|
Ignore errors when the 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 }
|
|
Select the output format to the
|
|
\fBlist\fR
|
|
command.
|
|
.TP
|
|
\fB\-q\fP, \fB\-quiet\fP
|
|
Suppress any output to stdout and stderr.
|
|
\fBipset\fR
|
|
will still exit with error if it cannot continue.
|
|
.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 which requires
|
|
\fBslow\fR
|
|
DNS lookups.
|
|
.TP
|
|
\fB\-s\fP, \fB\-sorted\fP
|
|
Sorted output. When listing sets entries are listed sorted. Not supported yet.
|
|
.SH "SET TYPES"
|
|
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
|
|
parameter of the
|
|
\fBcreate\fR
|
|
command follows the syntax
|
|
|
|
\fITYPENAME\fR := \fImethod\fR\fB:\fR\fIdatatype\fR[\fB,\fR\fIdatatype\fR[\fB,\fR\fIdatatype\fR]]
|
|
|
|
where the current list of the methods are
|
|
\fBbitmap\fR, \fBhash\fR, and \fBlist\fR and the possible data types
|
|
are \fBip\fR, \fBmac\fR and \fBport\fR. The dimension of a set
|
|
is equal to the number of data types in its type name.
|
|
|
|
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
|
|
|
|
ipset add foo ipaddr,portnum,ipaddr
|
|
|
|
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,
|
|
a limited number of chaining, and if that is exhausted, the doubling of the hash size
|
|
is performed when adding entries by the
|
|
\fBipset\fR
|
|
command. When entries added by the
|
|
\fBSET\fR
|
|
target of
|
|
\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
|
|
|
|
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.
|
|
.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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := { \fIip\fR | \fIfromip\fR\-\fItoip\fR | \fIip\fR/\fIcidr\fR }
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := { \fIip\fR | \fIfromip\fR\-\fItoip\fR | \fIip\fR/\fIcidr\fR }
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIip\fR
|
|
.PP
|
|
Mandatory \fBcreate\fR options:
|
|
.TP
|
|
\fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR
|
|
Create the set from the specified inclusive address range expressed in an
|
|
IPv4 address range or network. The size of the range (in entries) cannot exceed
|
|
the limit of maximum 65536 elements.
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBnetmask\fP \fIcidr\fP
|
|
When the optional \fBnetmask\fP parameter specified, network addresses will be
|
|
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.
|
|
.PP
|
|
The \fBbitmap:ip\fR type supports adding or deleting multiple entries in one
|
|
command.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo bitmap:ip range 192.168.0.0/16
|
|
.IP
|
|
ipset add foo 192.168.1/24
|
|
.IP
|
|
ipset test foo 192.168.1.1
|
|
.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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIip\fR[,\fImacaddr\fR]
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIip\fR[,\fImacaddr\fR]
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIip\fR[,\fImacaddr\fR]
|
|
.PP
|
|
Mandatory options to use when creating a \fBbitmap:ip,mac\fR type of set:
|
|
.TP
|
|
\fBrange\fP \fIfromip\fP\-\fItoip\fR|\fIip\fR/\fIcidr\fR
|
|
Create the set from the specified inclusive address range expressed in an
|
|
IPv4 address range or network. The size of the range cannot exceed the limit
|
|
of maximum 65536 entries.
|
|
.PP
|
|
The \fBbitmap:ip,mac\fR type is exceptional in the sense that the MAC part can
|
|
be left out when adding/deleting/testing entries in the set. If we add an entry
|
|
without the MAC address specified, then when the first time the entry is
|
|
matched by the kernel, it will automatically fill out the missing MAC address with the
|
|
source MAC address from the packet. If the entry was specified with a timeout value,
|
|
the timer starts off when the IP and MAC address pair is complete.
|
|
.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.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo bitmap:ip,mac range 192.168.0.0/16
|
|
.IP
|
|
ipset add foo 192.168.1.1,12:34:56:78:9A:BC
|
|
.IP
|
|
ipset test foo 192.168.1.1
|
|
.SS bitmap:port
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := { \fIport\fR | \fIfromport\fR\-\fItoport\fR }
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := { \fIport\fR | \fIfromport\fR\-\fItoport\fR }
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIport\fR
|
|
.PP
|
|
Mandatory options to use when creating a \fBbitmap:port\fR type of set:
|
|
.TP
|
|
\fBrange\fP \fIfromport\fP\-\fItoport\fR
|
|
Create the set from the specified inclusive port range.
|
|
.PP
|
|
The \fBset\fR match and \fBSET\fR target netfilter kernel modules interpret
|
|
the stored numbers as TCP or UDP port numbers.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo bitmap:port range 0\-1024
|
|
.IP
|
|
ipset add foo 80
|
|
.IP
|
|
ipset test foo 80
|
|
.SS hash:ip
|
|
The \fBhash:ip\fR set type uses a hash to store IP host addresses (default) or
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIipaddr\fR
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIipaddr\fR
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIipaddr\fR
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value.
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.TP
|
|
\fBnetmask\fP \fIcidr\fP
|
|
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.
|
|
.PP
|
|
For the \fBinet\fR family one can add or delete multiple entries by specifying
|
|
a range or a network:
|
|
.PP
|
|
\fIipaddr\fR := { \fIip\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIip\fR/\fIcidr\fR }
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:ip netmask 30
|
|
.IP
|
|
ipset add foo 192.168.1.0/24
|
|
.IP
|
|
ipset test foo 192.168.1.2
|
|
.SS hash:net
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value.
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.PP
|
|
When adding/deleting/testing entries, if the cidr prefix parameter is not specified,
|
|
then the host prefix value is assumed. When adding/deleting entries, the exact
|
|
element is added/deleted and overlapping elements are not checked by the kernel.
|
|
When testing entries, if a host address is tested, then the kernel tries to match
|
|
the host address in the networks added to the set and reports the result accordingly.
|
|
.PP
|
|
From the \fBset\fR netfilter match point of view the searching for a match
|
|
always starts from the smallest size of netblock (most specific
|
|
prefix) to the largest one (least specific prefix) added to the set.
|
|
When adding/deleting IP addresses to the set by the \fBSET\fR netfilter target,
|
|
it will be added/deleted by the most specific prefix which can be found in the
|
|
set, or by the host prefix value if the set is empty.
|
|
.PP
|
|
The lookup time grows linearly with the number of the different prefix
|
|
values added to the set.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:net
|
|
.IP
|
|
ipset add foo 192.168.0.0/24
|
|
.IP
|
|
ipset add foo 10.1.0.0/16
|
|
.IP
|
|
ipset test foo 192.168.0/24
|
|
.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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.PP
|
|
For the \fBinet\fR family one can add or delete multiple entries by specifying
|
|
a range or a network of IPv4 addresses in the IP address part of the entry:
|
|
.PP
|
|
\fIipaddr\fR := { \fIip\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIip\fR/\fIcidr\fR }
|
|
.PP
|
|
The
|
|
[\fIproto\fR:]\fIport\fR
|
|
part of the elements may be expressed in the following forms, where the range
|
|
variations are valid when adding or deleting entries:
|
|
.TP
|
|
\fIportname[\-portname]\fR
|
|
TCP port or range of ports expressed in TCP portname identifiers from /etc/services
|
|
.TP
|
|
\fIportnumber[\-portnumber]\fR
|
|
TCP port or range of ports expressed in TCP port numbers
|
|
.TP
|
|
\fBtcp\fR|\fBsctp\fR|\fBudp\fR|\fBudplite\fR:\fIportname\fR|\fIportnumber\fR[\-\fIportname\fR|\fIportnumber\fR]
|
|
TCP, SCTP, UDP or UDPLITE port or port range expressed in port name(s) or port number(s)
|
|
.TP
|
|
\fBicmp\fR:\fIcodename\fR|\fItype\fR/\fIcode\fR
|
|
ICMP codename or type/code. The supported ICMP codename identifiers can always
|
|
be listed by the help command.
|
|
.TP
|
|
\fBicmpv6\fR:\fIcodename\fR|\fItype\fR/\fIcode\fR
|
|
ICMPv6 codename or type/code. The supported ICMPv6 codename identifiers can always
|
|
be listed by the help command.
|
|
.TP
|
|
\fIproto\fR:0
|
|
All other protocols, as an identifier from /etc/protocols or number. The pseudo
|
|
port number must be zero.
|
|
.PP
|
|
The \fBhash:ip,port\fR type of sets require
|
|
two \fBsrc\fR/\fBdst\fR parameters of the \fBset\fR match and \fBSET\fR
|
|
target kernel modules.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:ip,port
|
|
.IP
|
|
ipset add foo 192.168.1.0/24,80\-82
|
|
.IP
|
|
ipset add foo 192.168.1.1,udp:53
|
|
.IP
|
|
ipset add foo 192.168.1.1,vrrp:0
|
|
.IP
|
|
ipset test foo 192.168.1.1,80
|
|
.SS hash:net,port
|
|
The \fBhash:net,port\fR set type uses a hash to store different sized IP network
|
|
address and port pairs. The port number is interpreted together with a protocol
|
|
(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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIipaddr\fR[/\fIcidr\fR],[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIipaddr\fR[/\fIcidr\fR],[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIipaddr\fR[/\fIcidr\fR],[\fIproto\fR:]\fIport\fR
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value.
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.PP
|
|
For the
|
|
[\fIproto\fR:]\fIport\fR
|
|
part of the elements see the description at the
|
|
\fBhash:ip,port\fR set type.
|
|
.PP
|
|
When adding/deleting/testing entries, if the cidr prefix parameter is not specified,
|
|
then the host prefix value is assumed. When adding/deleting entries, the exact
|
|
element is added/deleted and overlapping elements are not checked by the kernel.
|
|
When testing entries, if a host address is tested, then the kernel tries to match
|
|
the host address in the networks added to the set and reports the result accordingly.
|
|
.PP
|
|
From the \fBset\fR netfilter match point of view the searching for a match
|
|
always starts from the smallest size of netblock (most specific
|
|
prefix) to the largest one (least specific prefix) added to the set.
|
|
When adding/deleting IP
|
|
addresses to the set by the \fBSET\fR netfilter target, it will be
|
|
added/deleted by the most specific prefix which can be found in the
|
|
set, or by the host prefix value if the set is empty.
|
|
.PP
|
|
The lookup time grows linearly with the number of the different prefix
|
|
values added to the set.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:net,port
|
|
.IP
|
|
ipset add foo 192.168.0/24,25
|
|
.IP
|
|
ipset add foo 10.1.0.0/16,80
|
|
.IP
|
|
ipset test foo 192.168.0/24,25
|
|
.SS hash:ip,port,ip
|
|
The \fBhash:ip,port,ip\fR set type uses a hash to store IP address, port number
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR
|
|
.PP
|
|
For the first \fIipaddr\fR and
|
|
[\fIproto\fR:]\fIport\fR
|
|
parts of the elements see the descriptions at the
|
|
\fBhash:ip,port\fR set type.
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value.
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.PP
|
|
The \fBhash:ip,port,ip\fR type of sets require
|
|
three \fBsrc\fR/\fBdst\fR parameters of the \fBset\fR match and \fBSET\fR
|
|
target kernel modules.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:ip,port,ip
|
|
.IP
|
|
ipset add foo 192.168.1.1,80,10.0.0.1
|
|
.IP
|
|
ipset test foo 192.168.1.1,udp:53,10.0.0.1
|
|
.SS hash:ip,port,net
|
|
The \fBhash:ip,port,net\fR set type uses a hash to store IP address, port number
|
|
and IP network address triples. The port number is interpreted together with a
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIipaddr\fR,[\fIproto\fR:]\fIport\fR,\fIip\fR[/\fIcidr\fR]
|
|
.PP
|
|
For the first \fIipaddr\fR and
|
|
[\fIproto\fR:]\fIport\fR
|
|
parts of the elements see the descriptions at the
|
|
\fBhash:ip,port\fR set type.
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBfamily\fR { \fBinet\fR | \fBinet6\fR }
|
|
The protocol family of the IP addresses to be stored in the set. The default is
|
|
\fBinet\fR, i.e IPv4.
|
|
.TP
|
|
\fBhashsize\fR \fIvalue\fR
|
|
The initial hash size for the set, default is 1024. The hash size must be a power
|
|
of two, the kernel automatically rounds up non power of two hash sizes to the first
|
|
correct value.
|
|
.TP
|
|
\fBmaxelem\fR \fIvalue\fR
|
|
The maximal number of elements which can be stored in the set, default 65536.
|
|
.PP
|
|
From the \fBset\fR netfilter match point of view the searching for a match
|
|
always starts from the smallest size of netblock (most specific
|
|
cidr) to the largest one (least specific cidr) added to the set.
|
|
When adding/deleting triples
|
|
to the set by the \fBSET\fR netfilter target, it will be
|
|
added/deleted by the most specific cidr which can be found in the
|
|
set, or by the host cidr value if the set is empty.
|
|
.PP
|
|
The lookup time grows linearly with the number of the different \fIcidr\fR
|
|
values added to the set.
|
|
.PP
|
|
The \fBhash:ip,port,net\fR type of sets require three \fBsrc\fR/\fBdst\fR parameters of
|
|
the \fBset\fR match and \fBSET\fR target kernel modules.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
ipset create foo hash:ip,port,net
|
|
.IP
|
|
ipset add foo 192.168.1,80,10.0.0/24
|
|
.IP
|
|
ipset add foo 192.168.2,25,10.1.0.0/16
|
|
.IP
|
|
ipset test foo 192.168.1,80.10.0.0/24
|
|
.SS list:set
|
|
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 ]
|
|
.PP
|
|
\fIADD\-ENTRY\fR := \fIsetname\fR [ { \fBbefore\fR | \fBafter\fR } \fIsetname\fR ]
|
|
.PP
|
|
\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ]
|
|
.PP
|
|
\fIDEL\-ENTRY\fR := \fIsetname\fR [ { \fBbefore\fR | \fBafter\fR } \fIsetname\fR ]
|
|
.PP
|
|
\fITEST\-ENTRY\fR := \fIsetname\fR [ { \fBbefore\fR | \fBafter\fR } \fIsetname\fR ]
|
|
.PP
|
|
Optional \fBcreate\fR options:
|
|
.TP
|
|
\fBsize\fR \fIvalue\fR
|
|
The size of the list, the default is 8.
|
|
.PP
|
|
By the \fBipset\fR commad you can add, delete and test set names in a
|
|
\fBlist:set\fR type of set.
|
|
.PP
|
|
By the \fBset\fR match or \fBSET\fR target of netfilter
|
|
you can test, add or delete entries in the sets added to the \fBlist:set\fR
|
|
type of set. The match will try to find a matching entry in the sets and
|
|
the target will try to add an entry to the first set to which it can be added.
|
|
The number of direction options of the match and target are important: sets which
|
|
require more parameters than specified are skipped, while sets with equal
|
|
or less parameters are checked, elements added/deleted. For example if \fIa\fR and
|
|
\fIb\fR are \fBlist:set\fR 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 \fIa\fR and \fIb\fR
|
|
which stores data triples, but will match all sets with single or double
|
|
data storage in \fIa\fR set and stop matching at the first successful set,
|
|
and add src to the first single or src,dst to the first double data storage set
|
|
in \fIb\fR to which the entry can be added. You can imagine a \fBlist:set\fR
|
|
type of set as an ordered union of the set elements.
|
|
.PP
|
|
Please note: by the \fBipset\fR commad you can add, delete and \fBtest\fR
|
|
the setnames in a \fBlist:set\fR type of set, and \fBnot\fR the presence of
|
|
a set's member (such as an IP address).
|
|
.SH "GENERAL RESTRICTIONS"
|
|
Zero valued set entries cannot be used with hash methods. Zero protocol value with ports
|
|
cannot be used.
|
|
.SH "COMMENTS"
|
|
If you want to store same size subnets from a given network
|
|
(say /24 blocks from a /8 network), use the \fBbitmap:ip\fR set type.
|
|
If you want to store random same size networks (say random /24 blocks),
|
|
use the \fBhash:ip\fR set type. If you have got random size of netblocks,
|
|
use \fBhash:net\fR.
|
|
.PP
|
|
Backward compatibility is maintained and old \fBipset\fR syntax is still supported.
|
|
.PP
|
|
The \fBiptree\fR and \fBiptreemap\fR set types are removed: if you refer to them,
|
|
they are automatically replaced by \fBhash:ip\fR type of sets.
|
|
.SH "DIAGNOSTICS"
|
|
Various error messages are printed to standard error. The exit code
|
|
is 0 for correct functioning.
|
|
.SH "BUGS"
|
|
Bugs? No, just funny features. :\-)
|
|
OK, just kidding...
|
|
.SH "SEE ALSO"
|
|
\fBiptables\fR(8),
|
|
\fBip6tables\fR(8)
|
|
.SH "AUTHORS"
|
|
Jozsef Kadlecsik wrote ipset, which is based on ippool by
|
|
Joakim Axelsson, Patrick Schaaf and Martin Josefsson.
|
|
.br
|
|
Sven Wegener wrote the iptreemap type.
|
|
.SH "LAST REMARK"
|
|
\fBI stand on the shoulders of giants.\fR
|