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

[Phil Sutter <phil@nwl.cc>]

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