From 788abdba4b1d0444be0c7131004d74edcaff8d71 Mon Sep 17 00:00:00 2001
From: Florian Klink <flokli@flokli.de>
Date: Wed, 9 Mar 2022 15:29:35 +0100
Subject: [PATCH] nixos/doc: update rl-2111 w.r.t. iptables-nft migration

Follow-up on https://github.com/NixOS/nixpkgs/pull/161426.

Explain why having legacy iptables rules installed can lead to confusing
firewall behaviour, and provide some guidance on how to fix this.
---
 .../manual/from_md/release-notes/rl-2111.section.xml | 12 +++++++++++-
 nixos/doc/manual/release-notes/rl-2111.section.md    |  7 +++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
index a11baa91dea..b61a0268dee 100644
--- a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
+++ b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
@@ -35,7 +35,17 @@
           This means, <literal>ip[6]tables</literal>,
           <literal>arptables</literal> and <literal>ebtables</literal>
           commands will actually show rules from some specific tables in
-          the <literal>nf_tables</literal> kernel subsystem.
+          the <literal>nf_tables</literal> kernel subsystem. In case
+          you’re migrating from an older release without rebooting,
+          there might be cases where you end up with iptable rules
+          configured both in the legacy <literal>iptables</literal>
+          kernel backend, as well as in the <literal>nf_tables</literal>
+          backend. This can lead to confusing firewall behaviour. An
+          <literal>iptables-save</literal> after switching will complain
+          about <quote>iptables-legacy tables present</quote>. It’s
+          probably best to reboot after the upgrade, or manually
+          removing all legacy iptables rules (via the
+          <literal>iptables-legacy</literal> package).
         </para>
       </listitem>
       <listitem>
diff --git a/nixos/doc/manual/release-notes/rl-2111.section.md b/nixos/doc/manual/release-notes/rl-2111.section.md
index f3644c32832..310d32cfdd7 100644
--- a/nixos/doc/manual/release-notes/rl-2111.section.md
+++ b/nixos/doc/manual/release-notes/rl-2111.section.md
@@ -13,6 +13,13 @@ In addition to numerous new and upgraded packages, this release has the followin
   [Fedora](https://fedoraproject.org/wiki/Changes/iptables-nft-default).
   This means, `ip[6]tables`, `arptables` and `ebtables` commands  will actually
   show rules from some specific tables in the `nf_tables` kernel subsystem.
+  In case you're migrating from an older release without rebooting, there might
+  be cases where you end up with iptable rules configured both in the legacy
+  `iptables` kernel backend, as well as in the `nf_tables` backend.
+  This can lead to confusing firewall behaviour. An `iptables-save` after
+  switching will complain about "iptables-legacy tables present".
+  It's probably best to reboot after the upgrade, or manually removing all
+  legacy iptables rules (via the `iptables-legacy` package).
 
 - systemd got an `nftables` backend, and configures (networkd) rules in their
   own `io.systemd.*` tables. Check `nft list ruleset` to see these rules, not