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 83B271FF0B3 for ; Wed, 11 Nov 2026 14:22:47 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 7B7CB21972; Wed, 11 Nov 2026 14:20:13 +0100 (CET) From: Arthur Bied-Charreton To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v6 28/28] firewall: document renaming and removing objects Date: Wed, 11 Nov 2026 14:19:01 +0100 Message-ID: <20261111131901.1791124-29-a.bied-charreton@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261111131901.1791124-1-a.bied-charreton@proxmox.com> References: <20261111131901.1791124-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: 1794403149437 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.058 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: RTRNOC2FRM3SIPQ5PX2NPYJW2CPBS7QI X-Message-ID-Hash: RTRNOC2FRM3SIPQ5PX2NPYJW2CPBS7QI 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 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 --- 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