[PATCH pve-docs v4 19/27] firewall: document renaming and removing objects

[Arthur Bied-Charreton <a.bied-charreton@proxmox.com>]

Renaming or removing a security group, IP alias or IP set leaves every
reference to it naming something that no longer exists, and those
references are not confined to the configuration the object is defined
in. Describe where they live, what each value of the
'dangling-references' option does with them, and why 'force-rename'
exists and is kept to the command line.

The option descriptions in the API and the GUI are deliberately short,
so this is where the reasoning behind each choice belongs.

Point the SDN warning about rules referencing a released IPAM IPSet at
the new section, since destroying a guest now offers to deal with them.

Signed-off-by: Arthur Bied-Charreton <a.bied-charreton@proxmox.com>
---
 pve-firewall.adoc | 64 +++++++++++++++++++++++++++++++++++++++++++++++
 pvesdn.adoc       |  9 ++++---
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index cf04781..b4d7068 100644
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -468,6 +468,70 @@ discovery protocol to work.
 ----
 
 
+[[pve_firewall_dangling_references]]
+Renaming and Removing Firewall Objects
+--------------------------------------
+
+Firewall objects (aliases, IPSets and security groups) are referenced by name
+from the rest of the firewall configuration:
+
+* a security group is referenced by the action of a `GROUP` rule
+* an IPSet or alias is referenced by the source and destination properties of a
+  rule, and an alias additionally by the members of an IPSet
+
+A reference to a firewall object that does not exist because it was renamed or
+removed cannot be resolved. A rule referencing a renamed or removed object
+leads to errors during ruleset generation and should be avoided.
+
+The rename and delete operations take a `dangling-references` option that
+defines what to do with the references a change would break. The GUI exposes
+this option in the advanced section of the dialogs that rename or remove the
+object. The different values are as follows:
+
+`keep`::
+    Leave references as they are.
+`disable`::
+    Disable all rules referencing the object. This keeps the references around
+    in the firewall configuration so they can be reviewed and re-enabled later.
+    An IPSet member has no disabled state, so members referencing a removed or
+    renamed alias are removed instead.
+`drop`::
+    Remove all rules and IPSet members referencing the object from the firewall
+    configuration.
+`rename`::
+    Rewrite all references to the object so they point to the new name. This is
+    only available when renaming.
+
+Changes made to the firewall configuration are recorded in the task log.
+
+Recovering From an Interrupted Rename
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A rename of a cluster-level object needs to update references in all downstream
+configurations, i.e. the ones for hosts, guests and VNets, so it cannot be
+atomic. If the rename is interrupted in between, both the old and the new name
+are in the cluster config, and retrying it fails because an object with the
+target name already exists.
+
+The `force-rename` option skips that check so a retry can finish the rename. It
+is not exposed in the UI and can be used with `pvesh` as follows:
+
+----
+pvesh create /cluster/firewall/ipset --name foo --rename bar --dangling-references force-rename
+----
+
+[[pve_firewall_automatically_generated_ipsets]]
+Automatically Generated IPSets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The same applies to the IPSets the SDN stack generates, which disappear when
+applying an SDN configuration that removes a VNet, and destroying a guest with
+IPAM entries. See xref:pvesdn_firewall_integration[Firewall Integration] for
+what those IP sets contain.
+
+Both operations take a `dangling-ipset-references` option, which accepts
+`keep`, `disable` and `drop` with the same meaning as above.
+
 [[pve_firewall_services_commands]]
 Services and Commands
 ---------------------
diff --git a/pvesdn.adoc b/pvesdn.adoc
index 3fd3533..69cfa93 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -1526,9 +1526,12 @@ then the IPset would contain the IPs from *all* VNets.
 When entries get added / updated / deleted, then the respective IPSets will be
 updated accordingly.
 
-WARNING: When removing all entries for a guest and there are firewall rules
-still referencing the auto-generated IPSet then the firewall will fail to update
-the ruleset, since it references a non-existing IPSet.
+WARNING: When removing all entries for a guest or a VNet and there are firewall
+rules still referencing the auto-generated IPSet then the firewall will fail to
+update the ruleset, since it references a non-existing IPSet. Destroying a guest
+and applying an SDN configuration that removes a VNet both offer to disable or
+remove the rules that would be left behind, see
+xref:pve_firewall_dangling_references[Renaming and Removing Firewall Objects].
 
 [[pvesdn_setup_examples]]
 Examples
-- 
2.47.3