[pve-devel] [PATCH v3 docs 17/17] pveum: add SU privilege and SA role

[Oguz Bektas <o.bektas@proxmox.com>]

Signed-off-by: Oguz Bektas <o.bektas@proxmox.com>
---
v2->v3:
* separate SU and SA from the general privileges list (since they're not categorized easily)
* put actual notes inside and warn about potential danger and limitations regarding the privilege/role

 pveum.adoc | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/pveum.adoc b/pveum.adoc
index a5c8906..60c357d 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -684,7 +684,11 @@ Roles
 A role is simply a list of privileges. Proxmox VE comes with a number
 of predefined roles, which satisfy most requirements.
 
-* `Administrator`: has full privileges
+* `SuperAdministrator`: has full privileges including `SuperUser`
+
+NOTE: `SuperAdministrator` role is equivalent to 'root@pam', be careful when giving it to a user!
+
+* `Administrator`: has all privileges except `SuperUser`
 * `NoAccess`: has no privileges (used to forbid access)
 * `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`)
 * `PVEAuditor`: has read only access
@@ -725,6 +729,12 @@ assigned to users and paths without being part of a role.
 
 We currently support the following privileges:
 
+* `SuperUser`: modify root-only configuration options (dangerous! don't give this privilege to untrusted users)
+
+NOTE: the `SuperUser` privilege alone is not enough to provide root-equivalent access to a user.
+
+NOTE: certain actions on users with this privilege are restricted, such as modifying password or 2FA settings.
+
 Node / System related privileges::
 
 * `Permissions.Modify`: modify access permissions
-- 
2.30.2