Illustrate potential pitfalls when entering nft commands on command line and list possible counter-measures. Signed-off-by: Phil Sutter <phil@xxxxxx> --- doc/nft.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/nft.txt b/doc/nft.txt index abb9260d3f2f6..d69c2283f52db 100644 --- a/doc/nft.txt +++ b/doc/nft.txt @@ -802,6 +802,32 @@ On success, nft exits with a status of 0. Unspecified errors cause it to exit with a status of 1, memory allocation errors with a status of 2, unable to open Netlink socket with 3. +BUGS +----- +COMMAND LINE PARSING +~~~~~~~~~~~~~~~~~~~~ +The syntax used in nftables is prone to cause problems when given on command +line. For instance, *semi-colon* is used in all relevant shells to delimit +commands. + +In some places, *quoted strings* are expected. If not escaped, the shell will +silently eat them away. + +There is also an internal problem regarding *negative priority values* (e.g., +when defining base-chains or flowtables): The leading dash catches getopt's +attention which in turn assumes user specified an unknown option flag. Getopt +allows to ignore any option-like parameter after the first non-option, but +that would prevent typical commands like *nft list ruleset -a*. + +There are multiple ways to mitigate these issues: Shells can be prevented from +interpreting special characters by prefixing them with the escape character +(typically *backslash*), getopt won't recognize options following a parameter +consisting of *two dashes* alone (which in turn is ignored as well). Probably +the easiest way to avoid even unforseen issues is to enclose the whole +nftables syntax in *single quotes*. This turns the multiple non-option words +on command line into a single argument which is passed to the parser just like +before but the shell as well as getopt will leave it alone. + SEE ALSO -------- [verse] -- 2.24.0
