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 9F1051FF0E9 for ; Thu, 16 Jul 2026 01:22:05 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 64D68214AE; Thu, 16 Jul 2026 01:22:01 +0200 (CEST) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [RFC PATCH docs 4/4] pveum: document 'additive' ACL option Date: Thu, 16 Jul 2026 01:20:02 +0200 Message-ID: <20260715232121.1009607-5-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260715232121.1009607-1-t.lamprecht@proxmox.com> References: <20260715232121.1009607-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1784157668539 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.249 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_LOW -0.7 Sender listed at https://www.dnswl.org/, low 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: QACKZL634VXZ26NWIXFTSZOLPM26OCJ2 X-Message-ID-Hash: QACKZL634VXZ26NWIXFTSZOLPM26OCJ2 X-MailFrom: t.lamprecht@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: The additive flag overrides the default "deeper replaces upper" rule for individual ACL entries. Describe the semantics, the interaction with NoAccess, and the requirement for 'propagate' so admins can choose between replace-based scoped delegation and accumulate-based broad permissions. Signed-off-by: Thomas Lamprecht --- pveum.adoc | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/pveum.adoc b/pveum.adoc index d089cb6..b8781e1 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -983,6 +983,54 @@ set by default). We use the following inheritance rules: Additionally, privilege separated tokens can never have permissions on any given path that their associated user does not have. +[[pveum_additive_permissions]] +Additive Permissions +++++++++++++++++++++ + +By default, an ACL entry on a deeper path fully replaces the roles inherited +from ancestor paths. Sometimes you want a broader set of permissions granted +at a high level to remain in effect even where a more specific ACL entry is +set below. A typical case is auditors that should keep read access across +the entire tree regardless of scoped delegations further down. + +Setting the `additive` flag on an ACL entry makes its roles accumulate rather +than be replaced: the entry's roles are merged with roles granted by more +specific ACL entries below, instead of being overridden by them. + +For example, granting an `auditors` group `PVEAuditor` additively at the +root path: + +---- +# pveum acl modify / --groups auditors --roles PVEAuditor --propagate 1 --additive 1 +---- + +then assigning a regular non-additive role to a user on a specific VM: + +---- +# pveum acl modify /vms/100 --users alice@pve --roles PVEVMAdmin +---- + +leaves `alice@pve` (assuming they are a member of the `auditors` group) with +both `PVEAuditor` (carried from the additive ancestor entry) and +`PVEVMAdmin` (from the direct ACL) when accessing VM 100. + +Notes: + +* `additive` requires `propagate` to be set; an entry that does not cascade + down has nothing to merge into deeper paths. +* `additive` is independent of tier precedence: even when a higher-tier ACL + entry (`token` over `user` over `group`) wins the role set at a given + level, additive roles from any tier at that level still carry forward. +* `NoAccess` on an additive entry blocks all access at deeper paths, even + against roles granted by more specific ACL entries below. Conversely, a + non-additive `NoAccess` set at a deeper path cancels carried additive + roles at and below that path, matching the rule that `NoAccess` cancels + all other roles on a given path. +* Privilege separated API tokens are evaluated against their own ACL tree. + Additive entries on the underlying user do not leak into the token's + effective roles; its effective privileges remain the intersection of its + own ACL grants and the user's privileges. + [[pveum_pools]] Pools ~~~~~ base-commit: f2632cea11fc1000ddff53249527ca2493372a13 -- 2.47.3