From: Casey Bodley <cbodley@redhat.com>
Date: Thu, 17 Apr 2025 21:52:27 +0000 (-0400)
Subject: doc/rgw: document Admin and System Users
X-Git-Tag: v20.3.0~66^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=dc93b888f16793b00390b32d6814f9243b6808e2;p=ceph.git

doc/rgw: document Admin and System Users

Signed-off-by: Casey Bodley <cbodley@redhat.com>
---

diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst
index 483269b38339b..002702c7f21df 100644
--- a/doc/radosgw/admin.rst
+++ b/doc/radosgw/admin.rst
@@ -397,8 +397,41 @@ following form:
 .. prompt:: bash
 
    radosgw-admin caps rm --uid=johndoe --caps={caps}
-  
 
+Admin and System Users
+----------------------
+
+Users with the ``--admin`` or ``--system`` flag have global read and write
+permissions. These permissions apply to all APIs including S3 and Swift,
+unlike Admin Capabilities, and cannot be denied by IAM policy.
+
+The ``--system`` flag should only be used as documented in `Multisite Configuration`_.
+
+The ``--admin`` flag can be useful for troubleshooting and recovery. For
+example, if a user accidentally removes their permissions to a bucket or
+object, the admin user's credentials can be used to issue the S3/Swift API
+requests necessary to restore them.
+
+.. warning:: When not in use, consider deleting the admin user or disabling
+   its access keys. Do not give admin permissions to untrusted users.
+
+To create an admin user:
+
+.. prompt:: bash
+
+   radosgw-admin user create --uid={username} --display-name="{display-name}" --admin
+
+To add the admin flag to an existing user:
+
+.. prompt:: bash
+
+   radosgw-admin user modify --uid={username} --admin
+
+To remove the admin flag from an existing user:
+
+.. prompt:: bash
+
+   radosgw-admin user modify --uid={username} --admin=0
 
 Quota Management
 ================
@@ -903,3 +936,4 @@ example commands:
 .. _Ceph Object Gateway Config Reference: ../config-ref/
 .. _Accounts: ../account/
 .. _Admin Ops API: ../adminops/
+.. _Multisite Configuration: ../multisite/