From 003a78e90279e6d0c5ec3c91b6b8112cbbb22bc1 Mon Sep 17 00:00:00 2001 From: Arturo Borrero Gonzalez Date: Thu, 23 Jul 2020 12:41:31 +0200 Subject: nft: rearrange help output to group related options together It has been reported that nft options are a bit chaotic. With a growing list of options for the nft CLI, we can do better when presenting them to the user who requests help. This patch introduces a textual output grouping for options, in 4 groups: * Options (general) -- common Unix utility options * Options (operative) -- the options that modify the operative behaviour of nft * Options (translation) -- output text modifiers for data translation * Options (parsing) -- output text modifiers for parsing and other operations There is no behavior change in this patch, is mostly a cosmetic change in the hope that users will find the nft tool a bit less confusing to use. After this patch, the help output is: === 8< === % nft --help Usage: nft [ options ] [ cmds... ] Options (general): -h, help Show this help -v, version Show version information -V Show extended version information Options (ruleset input handling): -f, file Read input from -i, interactive Read input from interactive CLI -I, includepath Add to the paths searched for include files. Defaul[..] -c, check Check commands validity without actually applying the changes. Options (ruleset list formatting): -a, handle Output rule handle. -s, stateless Omit stateful information of ruleset. -t, terse Omit contents of sets. -S, service Translate ports to service names as described in /etc/services. -N, reversedns Translate IP addresses to names. -u, guid Print UID/GID as defined in /etc/passwd and /etc/group. -n, numeric Print fully numerical output. -y, numeric-priority Print chain priority numerically. -p, numeric-protocol Print layer 4 protocols numerically. -T, numeric-time Print time values numerically. Options (command output format): -e, echo Echo what has been added, inserted or replaced. -j, json Format output in JSON -d, debug Specify debugging level (scanner, parser, eval, netlink, mnl, p[..] === 8< === While at it, refresh the man page to better reflex this new grouping, and add some missing options. Joint work with Pablo. Signed-off-by: Arturo Borrero Gonzalez Signed-off-by: Pablo Neira Ayuso --- doc/nft.txt | 94 ++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 38 deletions(-) (limited to 'doc/nft.txt') diff --git a/doc/nft.txt b/doc/nft.txt index ba0c8c0b..5326de16 100644 --- a/doc/nft.txt +++ b/doc/nft.txt @@ -22,7 +22,10 @@ for Netfilter. OPTIONS ------- -For a full summary of options, run *nft --help*. +The command accepts several different options which are documented here in groups for better +understanding of their meaning. You can get information about options by running *nft --help*. + +.General options: *-h*:: *--help*:: @@ -32,42 +35,73 @@ For a full summary of options, run *nft --help*. *--version*:: Show version. -*-n*:: -*--numeric*:: - Print fully numerical output. +*-V*:: + Show long version information, including compile-time configuration. + +.Ruleset input handling options that specify to how to load rulesets: + +*-f*:: +*--file 'filename'*:: + Read input from 'filename'. If 'filename' is -, read from stdin. + +*-i*:: +*--interactive*:: + Read input from an interactive readline CLI. You can use quit to exit, or use the EOF marker, + normally this is CTRL-D. + +*-I*:: +*--includepath directory*:: + Add the directory 'directory' to the list of directories to be searched for included files. This + option may be specified multiple times. + +*-c*:: +*--check*:: + Check commands validity without actually applying the changes. + +.Ruleset list output formatting that modify the output of the list ruleset command: + +*-a*:: +*--handle*:: + Show object handles in output. *-s*:: *--stateless*:: Omit stateful information of rules and stateful objects. -*-N*:: -*--reversedns*:: - Translate IP address to names via reverse DNS lookup. This may slow down - your listing since it generates network traffic. +*-t*:: +*--terse*:: + Omit contents of sets from output. *-S*:: *--service*:: Translate ports to service names as defined by /etc/services. +*-N*:: +*--reversedns*:: + Translate IP address to names via reverse DNS lookup. This may slow down + your listing since it generates network traffic. + *-u*:: *--guid*:: Translate numeric UID/GID to names as defined by /etc/passwd and /etc/group. -*-p*:: -*--numeric-protocol*:: - Display layer 4 protocol numerically. +*-n*:: +*--numeric*:: + Print fully numerical output. *-y*:: *--numeric-priority*:: Display base chain priority numerically. -*-c*:: -*--check*:: - Check commands validity without actually applying the changes. +*-p*:: +*--numeric-protocol*:: + Display layer 4 protocol numerically. -*-a*:: -*--handle*:: - Show object handles in output. +*-T*:: +*--numeric-time*:: + Show time, day and hour values in numeric format. + +.Command output formatting: *-e*:: *--echo*:: @@ -78,27 +112,11 @@ For a full summary of options, run *nft --help*. *--json*:: Format output in JSON. See libnftables-json(5) for a schema description. -*-I*:: -*--includepath directory*:: - Add the directory 'directory' to the list of directories to be searched for included files. This - option may be specified multiple times. - -*-f*:: -*--file 'filename'*:: - Read input from 'filename'. If 'filename' is -, read from stdin. - -*-i*:: -*--interactive*:: - Read input from an interactive readline CLI. You can use quit to exit, or use the EOF marker, - normally this is CTRL-D. - -*-T*:: -*--numeric-time*:: - Show time, day and hour values in numeric format. - -*-t*:: -*--terse*:: - Omit contents of sets from output. +*-d*:: +*--debug* 'level':: + Enable debugging output. The debug level can be any of *scanner*, *parser*, *eval*, + *netlink*, *mnl*, *proto-ctx*, *segtree*, *all*. You can combine more than one by + separating by the ',' symbol, for example '-d eval,mnl'. INPUT FILE FORMATS ------------------ -- cgit v1.2.3