Add more explanations to the manpage about the maxelem and hashsize parameters

Fixes bugzilla #1804.

Signed-off-by: Jozsef Kadlecsik <kadlec@netfilter.org>

diff --git a/src/ipset.8 b/src/ipset.8
index bb425b85a2df16317f7476ad7a191a23f18b9488..39912ee163364c7f19b4f4c8e35c854ec596cd85 100644 (file)
--- a/src/ipset.8
+++ b/src/ipset.8
@@ -251,17 +251,13 @@ 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,
+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.
+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
+hash won't be duplicated, even if the new entry cannot be added to the set.
 .SH "GENERIC CREATE AND ADD OPTIONS"
 .SS timeout
 All set types supports the optional \fBtimeout\fR
@@ -335,28 +331,43 @@ ipset create foo hash:ip skbinfo
 .IP
 ipset add foo 192.168.0.1 skbmark 0x1111/0xff00ffff skbprio 1:10 skbqueue 10
 .PP
+.SS maxelem
+This parameter is valid for the \fBcreate\fR command of all \fBhash\fR type sets.
+It defines the maximal number of elements which can be stored in the set, default 65536.
+It is the hard limit for the possible elements in a hash type of set. If
+the set is full (i.e. it contains \fBmaxelem\fR number of elements), new
+elements cannot be added neither by the \fBipset\fR command nor by the
+\fBSET\fR target.
+Example:
+.IP
+ipset create test hash:ip maxelem 2048
+.PP
 .SS hashsize
 This parameter is valid for the \fBcreate\fR command of all \fBhash\fR type sets.
 It defines 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.
-Example:
+correct value. If you intend to use a set so that new elements are added by the \fBipset\fR
+command only, then you can start with a default/small \fBhashsize\fR value and the hash
+will grow automatically as you add new entries until \fBmaxelem\fR values
+are added. If you want to use a set so that new
+elements are added by the \fBSET\fR target, then choose the maximal \fBhashsize\fR
+value with respect of the \fBbucketsize\fR parameter so that number of planned elements
+will fit into the hash.
 .IP
-ipset create test hash:ip hashsize 1536
+hashsize == maxelem / bucketsize
 .PP
-.SS maxelem
-This parameter is valid for the \fBcreate\fR command of all \fBhash\fR type sets.
-It defines the maximal number of elements which can be stored in the set, default 65536.
-Example:
+is the smallest possible approximation but a larger hash size is better to
+make sure all elements can really be stored in the set. Example:
 .IP
-ipset create test hash:ip maxelem 2048
+ipset create test hash:ip hashsize 1536
 .PP
 .SS bucketsize
 This parameter is valid for the \fBcreate\fR command of all \fBhash\fR type sets.
 It specifies the maximal number of elements which can be stored in a hash
 bucket. Possible values are any even number between 2-12 and the default is
-12. Setting the value lower forces ipset to create larger hashes which
-consumes more memory but gives more speed at matching in the set.
+12. Setting the value lower forces ipset to create larger hashes when adding
+new elements to a set by the \fBipset\fR command which consumes more memory
+but gives more speed at matching in the set.
 Example:
 .IP
 ipset create test hash:ip bucketsize 2