From 3fd6b24ace319b139ec3c4e3031a5f05d21e304e Mon Sep 17 00:00:00 2001 From: Jozsef Kadlecsik Date: Tue, 15 Jun 2010 13:30:55 +0200 Subject: ipset 5 in an almost ready state - milestone Reworked protocol and internal interfaces, missing set types added, backward compatibility verified, lots of tests added (and thanks to the tests, bugs fixed), even the manpage is rewritten ;-). Countless changes everywhere... The missing bits before announcing ipset 5: - net namespace support - new iptables/ip6tables extension library - iptables/ip6tables match and target tests (backward/forward compatibility) - tests on catching syntax errors --- src/ipset.8 | 1109 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 600 insertions(+), 509 deletions(-) (limited to 'src/ipset.8') diff --git a/src/ipset.8 b/src/ipset.8 index fa73298..661d1b4 100644 --- a/src/ipset.8 +++ b/src/ipset.8 @@ -1,537 +1,628 @@ -.TH IPSET 8 "Feb 05, 2004" "" "" -.\" .\" Man page written by Jozsef Kadlecsik -.\" -.\" 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 +.\" +.\" 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" "Jun 11, 2010" "Jozsef Kadlecsik" "" +.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 +.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, 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) +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 creates 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 +.SH "OPTIONS" The options that are recognized by -.B ipset +\fBipset\fR 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] +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 options. 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 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 (expired) to 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 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 +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\-r\fP/\fB\-\-resolve\fP +\fB\-\-resolve\fP option can be used to force name lookups (which may be slow). When the -\fB\-s\fP/\fB\-\-sorted\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] +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 \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. +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: -.TP -\fB\-r\fP, \fB\-\-resolve\fP +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 or services (whenever applicable), which can trigger -.B -slow -DNS -lookups. -.TP -\fB\-s\fP, \fB\-\-sorted\fP +host names which requires +\fBslow\fR +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 +.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\fItype\fR[\fB,\fR\fItype\fR[\fB,\fR\fItype\fR]] + +where the current list of the methods are +\fBbitmap\fR, \fBhash\fR, \fBlist\fR and the possible data types are \fBip\fR, +\fBmac\fR and \fBport\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 + +ipset add foo ipaddr,portnum,ipaddr + +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. +.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 \fIfrom\-ip\fP\-\fIto\-ip\fR|\fIip\fR/\fIcidr\fR [ \fBnetmask\fP \fIcidr\fP ] [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIADD\-ENTRY\fR := { \fIipaddr\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIipaddr\fR/\fIcidr\fR } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIipaddr\fR/\fIcidr\fR } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\fR } +.PP +Mandatory \fBcreate\fR options: +.TP +\fBrange\fP \fIfrom\-ip\fP\-\fIto\-ip\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 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 cidr value, +can be found in the set. +.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 \fIfrom\-ip\fP\-\fIto\-ip\fR|\fIip\fR/\fIcidr\fR [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIADD\-ENTRY\fR := { \fIipaddr\fR[,\fImac\-addr\fR] } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR[,\fImac\-addr\fR] } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\fR[,\fImac\-addr\fR] } +.PP +Mandatory options to use when creating a \fBbitmap:ip,mac\fR type of set: +.TP +\fBrange\fP \fIfrom\-ip\fP\-\fIto\-ip\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, when the first time the entry is +matched by the kernel, it will automatically fill out the missing part 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 +Please note, the \fBset\fR match and \fBSET\fR target netfilter kernel modules +\fBalways\fR use the source MAC address from the packet to match, add or delete +entries from a \fBbitmap:ip,mac\fR type of set. +.PP +Examples: +.IP +ipset create foo bitmap:ip,mac range 192.168.0.0/16 +.IP +ipset add foo 192.168.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 \fIfrom\-port\fP\-\fIto\-port [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIADD\-ENTRY\fR := { \fIport\fR | \fIfrom\-port\fR\-\fIto\-port\fR } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := {\fIport\fR | \fIfrom\-port\fR\-\fIto\-port\fR } +.PP +\fITEST\-ENTRY\fR := { \fIport\fR } +.PP +Mandatory options to use when creating a \fBbitmap:port\fR type of set: +.TP +\fBrange\fP \fIfrom\-port\fP\-\fIto\-port\fR +Create the set from the specified inclusive port range. +.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 addresses. +In order to avoid clashes in the hash a limited number of chaining, and then +if that is exhausted, the doubling of the hash is performed. +.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 +For the \fBinet\fR family one can add or delete multiple entries by specifying +a range or a network: +.PP +\fIADD\-ENTRY\fR := { \fIipaddr\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIipaddr\fR/\fIcidr\fR } +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR | \fIfromaddr\fR\-\fItoaddr\fR | \fIipaddr\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. +.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 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 cidr, can be found in the set. +.PP +Examples: +.IP +ipset create foo hash:ip netmask 24 +.IP +ipset add foo 192.168.1.1 +.IP +ipset test foo 192.168.1.2 +.SS hash:net +The \fBhash:net\fR set type uses a hash to store different sized of IP networks. +In order to avoid clashes in the hash a limited number of chaining, and then +if that is exhausted, the doubling of the hash is performed. +.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] } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR[/\fIcidr\fR] } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\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 parameter is not specified, +then the host cidr value is assumed. +.PP +From the \fBset\fR netfilter match point of view an IP address will be in a \fBhash:net\fR 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 +cidr) to the largest ones (least specific cidr). When adding/deleting IP +addresses 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 +Examples: +.IP +ipset create foo hash:net +.IP +ipset add foo 192.168.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 pairs. +In order to avoid clashes in the hash a limited number of chaining, and then +if that is exhausted, the doubling of the hash is performed. +.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,\fIport\fR } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR,\fIport\fR } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\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 +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.1,80 +.IP +ipset test foo 192.168.1.1,80 +.SS hash:ip,port,ip +The \fBhash:ip,port,ip\fR set type uses a hash to store IP address, port and +IP address triples. In order to avoid clashes in the hash a limited number of +chaining, and then if that is exhausted, the doubling of the hash is performed. +.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,\fIport\fR,\fIipaddr\fR } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR,\fIport\fR,\fIipaddr\fR } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\fR,\fIport\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. +.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,80,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 and +IP network triples. +In order to avoid clashes in the hash a limited number of chaining, and then +if that is exhausted, the doubling of the hash is performed. +.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,\fIport\fR,\fIipaddr\fR[/\fIcidr\fR] } +.PP +\fIADD\-OPTIONS\fR := [ \fBtimeout\fR \fIvalue\fR ] +.PP +\fIDEL\-ENTRY\fR := { \fIipaddr\fR,\fIport\fR,\fIipaddr\fR[/\fIcidr\fR] } +.PP +\fITEST\-ENTRY\fR := { \fIipaddr\fR,\fIport\fR,\fIipaddr\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 parameter is not specified, +then the host cidr value is assumed. +.PP +From the \fBset\fR netfilter match point of view a triple will be in a \fBhash:ip,port,net\fR type of set (when the first IP and the port match) +if the second IP belongs to any of the netblocks added to the set. +The matching always start from the smallest size of netblock (most specific +cidr) to the largest ones (least specific cidr). 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 +sets. +.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 sets in a +\fBlist:set\fR type of set. +.PP +By the \fBset\fR match or \fBSET\fR target of netfiler +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 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 \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 check all sets with single or double +data storage in \fIa\fR set and add src to the first single or src,dst to the first double -data storage set in -\fIb\fP. -.P +data storage set in \fIb\fR. +.PP 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 +.SH "GENERAL RESTRICTIONS" +Zero valued set entries cannot be used with hash methods. +.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. +(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 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 +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. 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. :-) +is 0 for correct functioning. +.SH "BUGS" +Bugs? No, just funny features. :\-) OK, just kidding... -.SH SEE ALSO -.BR iptables (8), -.SH AUTHORS +.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. -.P +.br Sven Wegener wrote the iptreemap type. -.SH LAST REMARK -.BR "I stand on the shoulders of giants." +.SH "LAST REMARK" +\fBI stand on the shoulders of giants.\fR -- cgit v1.2.3