OK, this is mostly a rant, but after spending several days with nft I'm
pretty frustrated.
Let me start with this:
root@barley:~# /usr/sbin/nft --check -f /etc/network/ban
root@barley:~# echo $?
1
1. The command to see if the file is OK does nothing but produce a return
code. Shouldn't a program that is running a check say something, at least
if there's an error? The usual Unix convention AFAIK is silence =
success. But this is not success.
2. Even figuring out that --check and -f both needed to be specified was
not obvious from the man page.
3. It is documented that 1 is an error code--good that it's documented--but
it is non-specific (one reason I wondered if I had the command line syntax
right).
Of course, I'd love to check myself if my "ban" file is syntactically and
semantically correct, but that information is not laid out on the man page
or on the nft web site. That website says that 2 syntaxes are available,
but only has a reasonably clear specification (I think) of the first,
command line oriented syntax. It doesn't even say if the 2 can be mixed;
apparently sometimes they can and sometimes they can't (see debian bug
879684, in which the Debian maintainer says they can't be mixed). It
doesn't say if comments are allowed in the second syntax. So...
4. Format of input files is nowhere fully specified.
5. Much else is nowhere specified. For example, by trial and error (see
item 8 below) I found that a set containing a range like 1.2.3.4/18 needed
to have "flags interval" specified. The documentation mentions that
interval is a possible value for a flag but, as far as I can tell, doesn't
say what that does or means at all. Furthermore, the only related use of
interval is gc-interval, and that is a time interval.
6. And apparently the flag interval only works with a table inet family,
not the ip family, unless there is something else going on (e.g., maybe I
need to delete the set explicitly before changing the flag).
Even the cosmetics are off:
7. The man page for nft is filled with stray characters (apparently putting
0 before and after every term) and runs alternate syntaxes together without
a line break. The summary for tables is
-----------------------
{add | create} table [family] table [ { flags flags } ] {delete | list |
flush} table [family] table delete table
[family] handle handle
----------------------------
These cosmetic problems seem confined to viewing with the KDE Help Center;
things look OK with man nft in a terminal.
Finally, more substantively
8. nft did produce useful error messages with short input files. But with
long ones it was silent (ban has a bit over 11K lines).
I dislike writing documentation, and I'd guess so do the people working on
nftables. Further, since they spend their time immersed in the network
stack they have a lot of background information that it may be difficult
for them to recognize is unknown by their potential users. But the result
IMO is a mess.
Ross Boylan
