[RFC PATCH docs 4/4] pveum: document 'additive' ACL option

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

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 <t.lamprecht@proxmox.com>
---
 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