diff options
Diffstat (limited to 'ipset.8')
| -rw-r--r-- | ipset.8 | 217 |
1 files changed, 178 insertions, 39 deletions
@@ -87,14 +87,9 @@ is given. Bindings are not affected by the flush operation. Rename a set. Set identified by to-setname must not exist. .TP .BI "-W, --swap " "\fIfrom-setname\fP \fIto-setname\fP" -Swap two sets as they referenced in the Linux kernel. -.B -iptables -rules or -.B -ipset -bindings pointing to the content of from-setname will point to -the content of to-setname and vice versa. Both sets must exist. +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 .BI "-L, --list " "[\fIsetname\fP]" List the entries and bindings for the specified set, or for @@ -203,12 +198,12 @@ ipset supports the following set types: 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. Using the +for use when one want to match certain IPs in a range. If the optional .B "--netmask" -option with a CIDR netmask value between 0-32 when creating an ipmap -set, you will be able to store and match network addresses: i.e an -IP address will be in the set if the value resulted by masking the address -with the specified netmask can be found in the set. +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 @@ -225,17 +220,16 @@ When the optional .B "--netmask" parameter specified, network addresses will be stored in the set instead of IP addresses, and the from-IP parameter -must be a network address. +must be a network address. The CIDR-netmask value must be between 1-31. .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 -.I IP:MAC. +.I IP,MAC. When deleting or testing macipmap entries, the -.I :MAC -part is not mandatory. (The old "%" separation token instead of ":", i.e -IP%MAC is accepted as well.) +.I ,MAC +part is not mandatory. .P Options to use when creating an macipmap set: .TP @@ -279,12 +273,12 @@ Create a portmap set from the specified range. 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. By supplyig the +great to store random addresses. If the optional .B "--netmask" -option with a CIDR netmask value between 0-32 at creating the set, -you will be able to store and match network addresses instead: i.e -an IP address will be in the set if the value of the address -masked with the specified netmask can be found in the set. +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 iphash set: .TP @@ -306,21 +300,22 @@ number of double-hashing. When the optional .B "--netmask" parameter specified, network addresses will be -stored in the set instead of IP addresses. +stored in the set instead of IP addresses. The CIDR-netmask 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 approximately linearly grows with +The lookup time in an iphash type of set grows approximately linearly with the value of the .B probes -parameter. At the same time higher +parameter. In general higher .B -probes -values result a better utilized hash while smaller values -produce a larger, sparse hash. +probe +value results better utilized hash while smaller value +produces larger, sparser hash. .SS nethash The nethash set type uses a hash to store different size of network addresses. The @@ -349,18 +344,18 @@ an IP to the hash could not be performed after 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 is in any of the -netblocks added to the set and the matching always start from the smallest -size of netblock (most specific netmask) to the biggest ones (least +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 .I SET netfilter kernel module, it will be added/deleted by the smallest -netblock size which can be found in the set. +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 is approximately linearly -grows with the times of the +The lookup time in a nethash type of set grows approximately linearly +with the times of the .B probes parameter and the number of different mask parameters in the hash. @@ -374,8 +369,7 @@ 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 .B -"IP:port". -(Old "IP%port" format accepted as well.) +"IP,port". .P The ipporthash types of sets evaluates two src/dst parameters of the .I @@ -411,6 +405,94 @@ 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 +.B +"IP,port,IP". +.P +The ipportiphash types of sets evaluates three src/dst parameters of the +.I +set +match and +.I +SET +target. +.P +Options to use when creating an ipportiphash set: +.TP +.BR "--from " from-IP +.TP +.BR "--to " to-IP +Create an ipportiphash set from the specified range. +.TP +.BR "--network " IP/mask +Create an ipportiphash set from the specified network. +.TP +.BR "--hashsize " hashsize +The initial hash size (default 1024) +.TP +.BR "--probes " probes +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +.BR "--resize " percent +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +.B +probes +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 +.B +"IP,port,IP/cidr-size". +.P +The ipportnethash types of sets evaluates three src/dst parameters of the +.I +set +match and +.I +SET +target. +.P +Options to use when creating an ipportnethash set: +.TP +.BR "--from " from-IP +.TP +.BR "--to " to-IP +Create an ipporthash set from the specified range. +.TP +.BR "--network " IP/mask +Create an ipporthash set from the specified network. +.TP +.BR "--hashsize " hashsize +The initial hash size (default 1024) +.TP +.BR "--probes " probes +How many times try to resolve clashing at adding an IP to the hash +by double-hashing (default 8). +.TP +.BR "--resize " percent +Increase the hash size by this many percent (default 50) when adding +an IP to the hash could not be performed after +.B +probes +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. @@ -424,7 +506,7 @@ If a set was created with a nonzero valued .B "--timeout" parameter then one may add IP addresses to the set with a specific timeout value using the syntax -.I IP:timeout-value. +.I IP,timeout-value. Similarly to the hash types, the iptree type of sets can store up to 65536 entries. .SS iptreemap @@ -432,12 +514,67 @@ 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 -.I IP1:IP2 +.I IP1-IP2 .P Options to use when creating an iptreemap set: .TP .BR "--gc " value 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 +.I +ipset +command you can add, delete and test sets in a setlist type of set. +You can specify the sets as +.B +"setname[,after|before,setname]". +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 +.BR "--size " size +Create a setlist type of set with the given size (default 8). +.P +By the +.I +set +match or +.I +SET +target of +.I +iptables +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 +.TP +iptables -m set --match-set a src,dst -j SET --add-set b src,dst +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 +.I b. +.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. @@ -447,6 +584,8 @@ If you want to store same size subnets from a given network 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. .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 |