[PATCH pve-docs v6 28/28] 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 dangling, and those references may also be found in
other configs than the one the object is defined in.

Describe the 'dangling-references' option and its different values.

Also point the SDN warning about rules referencing a released IPAM
IPSet at the new section.

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

diff --git a/pve-firewall.adoc b/pve-firewall.adoc
index cf04781..7d49d04 100644
--- a/pve-firewall.adoc
+++ b/pve-firewall.adoc
@@ -468,6 +468,72 @@ 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. Renaming an object preselects `rename` and removing one preselects
+`drop`. 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.
+
+Setting `force-rename` skips that check so a retry can finish the rename; the
+`dangling-references` action is applied as usual. The option 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 rename --force-rename 1
+----
+
+[[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 b701636..85cc344 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -1527,9 +1527,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