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 <filename>           Read input from <filename>
  -i, interactive               Read input from interactive CLI
  -I, includepath <directory>   Add <directory> 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 <level [,level...]> 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 <arturo@netfilter.org>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>

diff --git a/doc/nft.txt b/doc/nft.txt
index ba0c8c0bef445509ca2498be7a49b9c35989f09e..5326de167de8f035a6c4c58740ea96c09198c2c4 100644 (file)
--- 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
 ------------------

diff --git a/src/main.c b/src/main.c
index 6c18235821fc190a9f125d5437be8a1687fdc266..3c26f51029ff3e979d0d584578ef2ef0b5d7077a 100644 (file)
--- a/src/main.c
+++ b/src/main.c
@@ -24,17 +24,37 @@
 
 static struct nft_ctx *nft;
 
-/*
- * These options are grouped separately in the help, so we give them named
- * indices for use there.
- */
 enum opt_indices {
+        /* General options */
        IDX_HELP,
        IDX_VERSION,
        IDX_VERSION_LONG,
-       IDX_CHECK,
+        /* Ruleset input handling */
        IDX_FILE,
+#define IDX_RULESET_INPUT_START        IDX_FILE
        IDX_INTERACTIVE,
+        IDX_INCLUDEPATH,
+       IDX_CHECK,
+#define IDX_RULESET_INPUT_END  IDX_CHECK
+        /* Ruleset list formatting */
+        IDX_HANDLE,
+#define IDX_RULESET_LIST_START IDX_HANDLE
+        IDX_STATELESS,
+        IDX_TERSE,
+        IDX_SERVICE,
+        IDX_REVERSEDNS,
+        IDX_GUID,
+        IDX_NUMERIC,
+        IDX_NUMERIC_PRIO,
+        IDX_NUMERIC_PROTO,
+        IDX_NUMERIC_TIME,
+#define IDX_RULESET_LIST_END IDX_NUMERIC_TIME
+        /* Command output formatting */
+        IDX_ECHO,
+#define IDX_CMD_OUTPUT_START   IDX_ECHO
+        IDX_JSON,
+        IDX_DEBUG,
+#define IDX_CMD_OUTPUT_END     IDX_DEBUG
 };
 
 enum opt_vals {
@@ -72,46 +92,46 @@ struct nft_opt {
        (struct nft_opt) { .name = n, .val = v, .arg = a, .help = h }
 
 static const struct nft_opt nft_options[] = {
-       NFT_OPT("help",                 OPT_HELP,               NULL,
-               "Show this help"),
-       NFT_OPT("version",              OPT_VERSION,            NULL,
-               "Show version information"),
-       NFT_OPT(NULL,                   OPT_VERSION_LONG,       NULL,
-               "Show extended version information"),
-       NFT_OPT("check",                OPT_CHECK,              NULL,
-               "Check commands validity without actually applying the changes."),
-       NFT_OPT("file",                 OPT_FILE,               "<filename>",
-               "Read input from <filename>"),
-       NFT_OPT("interactive",          OPT_INTERACTIVE,        NULL,
-               "Read input from interactive CLI"),
-       NFT_OPT("numeric",              OPT_NUMERIC,            NULL,
-               "Print fully numerical output."),
-       NFT_OPT("stateless",            OPT_STATELESS,          NULL,
-               "Omit stateful information of ruleset."),
-       NFT_OPT("reversedns",           OPT_IP2NAME,            NULL,
-               "Translate IP addresses to names."),
-       NFT_OPT("service",              OPT_SERVICE,            NULL,
-               "Translate ports to service names as described in /etc/services."),
-       NFT_OPT("includepath",          OPT_INCLUDEPATH,        "<directory>",
-               "Add <directory> to the paths searched for include files. Default is: " DEFAULT_INCLUDE_PATH),
-       NFT_OPT("debug",                OPT_DEBUG,              "<level [,level...]>",
-               "Specify debugging level (scanner, parser, eval, netlink, mnl, proto-ctx, segtree, all)"),
-       NFT_OPT("handle",               OPT_HANDLE_OUTPUT,      NULL,
-               "Output rule handle."),
-       NFT_OPT("echo",                 OPT_ECHO,               NULL,
-               "Echo what has been added, inserted or replaced."),
-       NFT_OPT("json",                 OPT_JSON,               NULL,
-               "Format output in JSON"),
-       NFT_OPT("guid",                 OPT_GUID,               NULL,
-               "Print UID/GID as defined in /etc/passwd and /etc/group."),
-       NFT_OPT("numeric-priority",     OPT_NUMERIC_PRIO,       NULL,
-               "Print chain priority numerically."),
-       NFT_OPT("numeric-protocol",     OPT_NUMERIC_PROTO,      NULL,
-               "Print layer 4 protocols numerically."),
-       NFT_OPT("numeric-time",         OPT_NUMERIC_TIME,       NULL,
-               "Print time values numerically."),
-       NFT_OPT("terse",                OPT_TERSE,              NULL,
-               "Omit contents of sets."),
+       [IDX_HELP]          = NFT_OPT("help",                   OPT_HELP,               NULL,
+                                    "Show this help"),
+       [IDX_VERSION]       = NFT_OPT("version",                        OPT_VERSION,            NULL,
+                                    "Show version information"),
+       [IDX_VERSION_LONG]  = NFT_OPT(NULL,                     OPT_VERSION_LONG,       NULL,
+                                    "Show extended version information"),
+       [IDX_FILE]          = NFT_OPT("file",                   OPT_FILE,               "<filename>",
+                                    "Read input from <filename>"),
+       [IDX_INTERACTIVE]   = NFT_OPT("interactive",            OPT_INTERACTIVE,        NULL,
+                                    "Read input from interactive CLI"),
+       [IDX_INCLUDEPATH]   = NFT_OPT("includepath",            OPT_INCLUDEPATH,        "<directory>",
+                                    "Add <directory> to the paths searched for include files. Default is: " DEFAULT_INCLUDE_PATH),
+       [IDX_CHECK]         = NFT_OPT("check",                  OPT_CHECK,              NULL,
+                                    "Check commands validity without actually applying the changes."),
+       [IDX_HANDLE]        = NFT_OPT("handle",                 OPT_HANDLE_OUTPUT,      NULL,
+                                    "Output rule handle."),
+       [IDX_STATELESS]     = NFT_OPT("stateless",              OPT_STATELESS,          NULL,
+                                    "Omit stateful information of ruleset."),
+       [IDX_TERSE]         = NFT_OPT("terse",                  OPT_TERSE,              NULL,
+                                     "Omit contents of sets."),
+       [IDX_SERVICE]       = NFT_OPT("service",                        OPT_SERVICE,            NULL,
+                                    "Translate ports to service names as described in /etc/services."),
+       [IDX_REVERSEDNS]    = NFT_OPT("reversedns",             OPT_IP2NAME,            NULL,
+                                    "Translate IP addresses to names."),
+       [IDX_GUID]          = NFT_OPT("guid",                   OPT_GUID,               NULL,
+                                    "Print UID/GID as defined in /etc/passwd and /etc/group."),
+       [IDX_NUMERIC]       = NFT_OPT("numeric",                        OPT_NUMERIC,            NULL,
+                                    "Print fully numerical output."),
+       [IDX_NUMERIC_PRIO]  = NFT_OPT("numeric-priority",       OPT_NUMERIC_PRIO,       NULL,
+                                    "Print chain priority numerically."),
+       [IDX_NUMERIC_PROTO] = NFT_OPT("numeric-protocol",       OPT_NUMERIC_PROTO,      NULL,
+                                    "Print layer 4 protocols numerically."),
+       [IDX_NUMERIC_TIME]  = NFT_OPT("numeric-time",           OPT_NUMERIC_TIME,       NULL,
+                                     "Print time values numerically."),
+       [IDX_ECHO]          = NFT_OPT("echo",                   OPT_ECHO,               NULL,
+                                    "Echo what has been added, inserted or replaced."),
+       [IDX_JSON]          = NFT_OPT("json",                   OPT_JSON,               NULL,
+                                    "Format output in JSON"),
+       [IDX_DEBUG]         = NFT_OPT("debug",                  OPT_DEBUG,              "<level [,level...]>",
+                                    "Specify debugging level (scanner, parser, eval, netlink, mnl, proto-ctx, segtree, all)"),
 };
 
 #define NR_NFT_OPTIONS (sizeof(nft_options) / sizeof(nft_options[0]))
@@ -169,25 +189,35 @@ static void print_option(const struct nft_opt *opt)
 
 static void show_help(const char *name)
 {
-       size_t i;
+       int i;
 
        printf("Usage: %s [ options ] [ cmds... ]\n"
               "\n"
-              "Options:\n", name);
+              "Options (general):\n", name);
 
        print_option(&nft_options[IDX_HELP]);
        print_option(&nft_options[IDX_VERSION]);
        print_option(&nft_options[IDX_VERSION_LONG]);
 
-       fputs("\n", stdout);
+       printf("\n"
+              "Options (ruleset input handling):"
+              "\n");
 
-       print_option(&nft_options[IDX_CHECK]);
-       print_option(&nft_options[IDX_FILE]);
-       print_option(&nft_options[IDX_INTERACTIVE]);
+       for (i = IDX_RULESET_INPUT_START; i <= IDX_RULESET_INPUT_END; i++)
+               print_option(&nft_options[i]);
 
-       fputs("\n", stdout);
+       printf("\n"
+              "Options (ruleset list formatting):"
+              "\n");
+
+       for (i = IDX_RULESET_LIST_START; i <= IDX_RULESET_LIST_END; i++)
+               print_option(&nft_options[i]);
+
+       printf("\n"
+              "Options (command output formatting):"
+              "\n");
 
-       for (i = IDX_INTERACTIVE + 1; i < NR_NFT_OPTIONS; ++i)
+       for (i = IDX_CMD_OUTPUT_START; i <= IDX_CMD_OUTPUT_END; i++)
                print_option(&nft_options[i]);
 
        fputs("\n", stdout);