diff mbox series

[nft] doc: nft.8: Add BUGS section about command line parsing

Message ID 20191211161020.1327-1-phil@nwl.cc
State Under Review
Delegated to: Pablo Neira
Headers show
Series [nft] doc: nft.8: Add BUGS section about command line parsing | expand

Commit Message

Phil Sutter Dec. 11, 2019, 4:10 p.m. UTC
Illustrate potential pitfalls when entering nft commands on command
line and list possible counter-measures.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 doc/nft.txt | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
diff mbox series

Patch

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]