From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id B51021FF0C2 for ; Thu, 22 Oct 2026 14:49:54 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 29F7C216BD; Thu, 22 Oct 2026 14:48:33 +0200 (CEST) From: Arthur Bied-Charreton To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v4 19/27] firewall: document renaming and removing objects Date: Thu, 22 Oct 2026 14:47:00 +0200 Message-ID: <20261022124708.429069-20-a.bied-charreton@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261022124708.429069-1-a.bied-charreton@proxmox.com> References: <20261022124708.429069-1-a.bied-charreton@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1792673237776 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.299 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_ASCII_DIVIDERS 0.8 Email that uses ascii formatting dividers and possible spam tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: QH3R4HADYJVF2EUFD7Z3DLMI4KNDWMPM X-Message-ID-Hash: QH3R4HADYJVF2EUFD7Z3DLMI4KNDWMPM X-MailFrom: a.bied-charreton@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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