[nft PATCH 1/2] doc: nft.8: Describe nftables transactions and their limitations

[nft PATCH 1/2] doc: nft.8: Describe nftables transactions and their limitations

[Phil Sutter]

Given the exceptions to the rule, describing how nftables handles
batches might clear some confusion.

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

diff --git a/doc/nft.txt b/doc/nft.txt
index 0f37782c23a0b..15e5c0de33f4d 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -1039,6 +1039,57 @@ These are some additional commands included in nft.
 
 include::additional-commands.txt[]
 
+TRANSACTIONAL RULESET UPDATES
+-----------------------------
+The nft tool accepts multiple commands at once, either on command-line
+(separated by semi-colon) or in a file. Even when restoring a dump in nested
+syntax it resolves into individual commands adding the various ruleset elements
+found in there. It collects these commands in a batch.
+
+The kernel treats a batch as a transaction, i.e. if one of the commands fails
+to apply, previous ones are unrolled and the transaction fails. Multiple
+transactions are serialized and thus won't interfere nondeterministically.
+
+.Trying to create a NAT chain
+---------------------
+# nft "add table t; add chain t c { type nat hook input priority 0; }"
+---------------------
+If nft_chain_nat.ko is unavailable, chain creation fails in above example. Due
+to the transactional behaviour the table won't be created, either.
+
+There are a few exceptions to the above rule though: list and reset commands
+are not integrated into the transaction system on kernel-side and "happen" in
+user space during cache population. The latter is a preparation step for other
+commands. For reference, here are the rough command processing steps in nft:
+
+. Parse input into list of commands
+. Gather cache requirements for each command
+. Fetch data from kernel and populate cache
+. Process each command (sanity checks, serialize into batch)
+. Submit batch to kernel
+. Receive response, report errors or echo updated input if requested
+
+Data for list command is fetched in step 3, output is printed in step 4. With
+reset command, the actual data reset happens in step 3 and printing of the old
+values happens in step 4.
+
+.Trying to create a NAT chain and list in between
+---------------------
+# nft "add table t; list table t; add chain t c { type nat hook input priority 0; }"
+---------------------
+The above command will list table t's (empty) contents irrespective of whether
+the transaction fails or not. In fact, it lists the table before even
+attempting to create it: The add table command populates nft's cache while
+being processed (in step 4 above) so following commands find it there.
+
+As a conclusion to the above:
+
+* Don't rely upon list command output alone to verify success of a ruleset
+  modification, at least not if in the same batch. At least make sure the batch
+  succeeds and nft returns zero.
+* Keep in mind that reset command won't unroll. Its effects will persist
+  despite the failing transaction which reverts all other commands.
+
 ERROR REPORTING
 ---------------
 When an error is detected, nft shows the line(s) containing the error, the
-- 
2.54.0

[nft PATCH 2/2] doc: nft.8: Document caveats when mixing clients

[Phil Sutter]

The "do not touch" warning message nft emits for tables with rules using
compat expressions has been complained about for being confusing.
Replace it with a reference to nft.8 and describe the implications there.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 doc/nft.txt | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 src/rule.c  |  4 ++--
 2 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/doc/nft.txt b/doc/nft.txt
index 15e5c0de33f4d..a7ef9a7183b5b 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -1090,6 +1090,52 @@ being processed (in step 4 above) so following commands find it there.
 * Keep in mind that reset command won't unroll. Its effects will persist
   despite the failing transaction which reverts all other commands.
 
+MIXED USE
+---------
+A kernel ruleset created by nft may be read and modified by any other program.
+This practicaly constitutes a form of inter-process communication with the
+kernel as data channel. Nftables' flexible ruleset specification makes
+compatibility issues likely.
+
+WITH IPTABLES-NFT
+~~~~~~~~~~~~~~~~~
+In general, mixed use of iptables-nft and nft within the same host/netns is not
+advisable and may lead to obscure bugs in both tools. A ruleset created by
+iptables-nft should not be modified using nft and vice-versa.
+
+In order to replicate legacy behaviour, iptables-nft makes use of compat
+expressions in kernel. These allow nftables to call xtables kernel extensions.
+Content of compat expressions is extension-specific, nft requires libxtables to
+interpret the data. If available, it will use its xlate callbacks to print
+equivalent nftables statements, just like iptables-translate does.
+
+If a ruleset dump containing such (translated) compat expressions is restored
+again using nft, the resulting ruleset will not contain any compat expressions
+anymore. This may cause subtle changes in behaviour but will almost certainly
+break ruleset parsing in iptables-nft.
+
+If a translation is not possible, nft prints the well-known compat expression
+fields (type and name) in a format the parser will detect and reject with a
+verbose message. This is to make sure such an incomplete ruleset dump is not
+restored by accident.
+
+WITH OTHER VERSIONS OF NFT
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+While nft is supposed to be backwards-compatible, i.e. Rulesets created by any
+older version must parse correctly, the other direction is hard to even handle
+sanely. The result of parsing a ruleset "from the future" may vary from success
+to crash and from obviously broken rulesets to subtle bugs or minimal changes
+in behaviour.
+
+If a ruleset should remain readable by all involved versions, only the oldest
+version should make modifications and all others should limit themselves to
+read-only access.
+
+Starting with version 1.1.6, nft annotates created tables with its own version
+and warns if tables fetched from kernel are annotated with a newer version.
+While its absence is not a guarantee, its presence clearly indicates a
+problematic setup.
+
 ERROR REPORTING
 ---------------
 When an error is detected, nft shows the line(s) containing the error, the
diff --git a/src/rule.c b/src/rule.c
index 0ffe2ca1955da..552c17df05f83 100644
--- a/src/rule.c
+++ b/src/rule.c
@@ -1284,11 +1284,11 @@ static void table_print(const struct table *table, struct output_ctx *octx)
 
 	if (table->has_xt_stmts)
 		fprintf(octx->error_fp,
-			"# Warning: table %s %s is managed by iptables-nft, do not touch!\n",
+			"# Warning: Table %s %s is managed by iptables-nft, see MIXED USE in nft(8).\n",
 			family, table->handle.table.name);
 	if (table->is_from_future)
 		fprintf(octx->error_fp,
-			"# Warning: table %s %s was created by a newer version of nftables? Content may be incomplete!\n",
+			"# Warning: Table %s %s was created by a newer version of nft, see MIXED USE in nft(8).\n",
 			family, table->handle.table.name);
 
 	nft_print(octx, "table %s %s {", family, table->handle.table.name);
-- 
2.54.0

Re: [nft PATCH 2/2] doc: nft.8: Document caveats when mixing clients

[Phil Sutter]

On Thu, Sep 17, 2026 at 07:31:59PM +0200, Phil Sutter wrote:
> The "do not touch" warning message nft emits for tables with rules using
> compat expressions has been complained about for being confusing.
> Replace it with a reference to nft.8 and describe the implications there.
> 
> Signed-off-by: Phil Sutter <phil@nwl.cc>

This required adjustment in parsing/compat_xlate shell test case.

Both patches applied.