doc: make usage of libxt_rateest more obvious
Signed-off-by: Jan Engelhardt <jengelh@medozas.de>
diff --git a/extensions/libxt_rateest.man b/extensions/libxt_rateest.man
index 75303c5..42a82f3 100644
--- a/extensions/libxt_rateest.man
+++ b/extensions/libxt_rateest.man
@@ -1,25 +1,38 @@
The rate estimator can match on estimated rates as collected by the RATEEST
target. It supports matching on absolute bps/pps values, comparing two rate
estimators and matching on the difference between two rate estimators.
-.TP
-\fB\-\-rateest1\fP \fIname\fP
-Name of the first rate estimator.
-.TP
-\fB\-\-rateest2\fP \fIname\fP
-Name of the second rate estimator (if difference is to be calculated).
+.PP
+For a better understanding of the available options, these are all possible
+combinations:
+.\" * Absolute:
+.IP \(bu 4
+\fBrateest\fP \fIoperator\fP \fBrateest-bps\fP
+.IP \(bu 4
+\fBrateest\fP \fIoperator\fP \fBrateest-pps\fP
+.\" * Absolute + Delta:
+.IP \(bu 4
+(\fBrateest\fP minus \fBrateest-bps1\fP) \fIoperator\fP \fBrateest-bps2\fP
+.IP \(bu 4
+(\fBrateest\fP minus \fBrateest-pps1\fP) \fIoperator\fP \fBrateest-pps2\fP
+.\" * Relative:
+.IP \(bu 4
+\fBrateest1\fP \fIoperator\fP \fBrateest2\fP \fBrateest-bps\fP(without rate!)
+.IP \(bu 4
+\fBrateest1\fP \fIoperator\fP \fBrateest2\fP \fBrateest-pps\fP(without rate!)
+.\" * Relative + Delta:
+.IP \(bu 4
+(\fBrateest1\fP minus \fBrateest-bps1\fP) \fIoperator\fP
+(\fBrateest2\fP minus \fBrateest-bps2\fP)
+.IP \(bu 4
+(\fBrateest1\fP minus \fBrateest-pps1\fP) \fIoperator\fP
+(\fBrateest2\fP minus \fBrateest-pps2\fP)
.TP
\fB\-\-rateest\-delta\fP
-Compare difference(s) to given rate(s)
-.TP
-\fB\-\-rateest\-bps1\fP [\fIvalue\fP]
-.TP
-\fB\-\-rateest\-bps2\fP [\fIvalue\fP]
-Compare bytes per second.
-.TP
-\fB\-\-rateest\-pps1\fP [\fIvalue\fP]
-.TP
-\fB\-\-rateest\-pps2\fP [\fIvalue\fP]
-Compare packets per second.
+For each estimator (either absolute or relative mode), calculate the difference
+between the estimator-determined flow rate and the static value chosen with the
+BPS/PPS options. If the flow rate is higher than the specified BPS/PPS, 0 will
+be used instead of a negative value. In other words, "max(0, rateest#_rate -
+rateest#_bps)" is used.
.TP
[\fB!\fP] \fB\-\-rateest\-lt\fP
Match if rate is less than given rate/estimator.
@@ -30,6 +43,34 @@
[\fB!\fP] \fB\-\-rateest\-eq\fP
Match if rate is equal to given rate/estimator.
.PP
+In the so-called "absolute mode", only one rate estimator is used and compared
+against a static value, while in "relative mode", two rate estimators are
+compared against another.
+.TP
+\fB\-\-rateest\fP \fIname\fP
+Name of the one rate estimator for absolute mode.
+.TP
+\fB\-\-rateest1\fP \fIname\fP
+.TP
+\fB\-\-rateest2\fP \fIname\fP
+The names of the two rate estimators for relative mode.
+.TP
+\fB\-\-rateest\-bps\fP [\fIvalue\fP]
+.TP
+\fB\-\-rateest\-pps\fP [\fIvalue\fP]
+.TP
+\fB\-\-rateest\-bps1\fP [\fIvalue\fP]
+.TP
+\fB\-\-rateest\-bps2\fP [\fIvalue\fP]
+.TP
+\fB\-\-rateest\-pps1\fP [\fIvalue\fP]
+.TP
+\fB\-\-rateest\-pps2\fP [\fIvalue\fP]
+Compare the estimator(s) by bytes or packets per second, and compare against
+the chosen value. See the above bullet list for which option is to be used in
+which case. A unit suffix may be used - available ones are: bit, [kmgt]bit,
+[KMGT]ibit, Bps, [KMGT]Bps, [KMGT]iBps.
+.PP
Example: This is what can be used to route outgoing data connections from an
FTP server over two lines based on the available bandwidth at the time the data
connection was started: