From 1538d570ad046c2edd17bcce1a2caf6478e4354f Mon Sep 17 00:00:00 2001 From: Ricardo Dias Date: Fri, 1 Jun 2018 12:16:27 +0100 Subject: [PATCH] doc/mgr/dashboard: user and role management documentation Signed-off-by: Ricardo Dias --- doc/mgr/dashboard.rst | 184 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 178 insertions(+), 6 deletions(-) diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index bba14ed867e..fed3a920cd5 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -40,7 +40,8 @@ information and statistics about the Ceph cluster using a web server hosted by The dashboard currently provides the following features to monitor and manage various aspects of your Ceph cluster: -* **Username/password protection**: The dashboard can only be accessed by +* **Multi-User and Role Management**: The dashboard supports the management of + multiple user accounts, and the management of permission roles. providing a configurable username and password. * **SSL/TLS support**: All HTTP communication between the web browser and the dashboard is secured via SSL. A self-signed certificate can be created with @@ -181,13 +182,16 @@ app. Username and password ^^^^^^^^^^^^^^^^^^^^^ -In order to be able to log in, you need to define a username and password, which -will be stored in the MON's configuration database:: +In order to be able to log in, you need to create a user account and associate +it with at least one role. We provide a set of predefined *system roles* that +you can use. For more details please refer to the `User and Role Management`_ +section. - $ ceph dashboard set-login-credentials +To create a user with the administrator role you can use the following +commands:: + + $ ceph dashboard ac-user-create administrator -The password will be stored in the configuration database in encrypted form -using ``bcrypt``. This is a global setting that applies to all dashboard instances. Enabling the Object Gateway management frontend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -316,6 +320,173 @@ previously defined username and password. Select the **Keep me logged in** checkbox if you want to skip the username/password request when accessing the dashboard in the future. + +User and Role Management +------------------------ + +User Accounts +^^^^^^^^^^^^^ + +Ceph Dashboard supports managing multiple user accounts. Each user account +consists of a username, a password (stored in encrypted form using ``bcrypt``), +an optional name, and an optional email address. + +User accounts are stored in MON's configuration database, and are globally +shared across all ceph-mgr instances. + +We provide a set of CLI commands to manage user accounts: + +- *Show User(s)*:: + + $ ceph dashboard ac-user-show [] + +- *Create User*:: + + $ ceph dashboard ac-user-create [] [] [] + +- *Delete User*:: + + $ ceph dashboard ac-user-delete + +- *Change Password*:: + + $ ceph dashboard ac-user-set-password + +- *Modify User (name, and email)*:: + + $ ceph dashboard ac-user-set-info + + +User Roles and Permissions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User accounts are also associated with a set of roles that define which +dashboard fuctionality can be accessed by the user. + +Dashboard functionality/modules are grouped within a *security scope*. +Security scopes are predefined and static. The current avaliable security +scopes are: + +- **hosts**: includes all features related to the ``Hosts`` menu + entry. +- **config-opt**: includes all features related to management of Ceph + configuration options. +- **pool**: includes all features related to pool management. +- **osd**: includes all features related to OSD management. +- **monitor**: includes all features related to Monitor management. +- **rbd-image**: includes all features related to RBD image + management. +- **rbd-mirroring**: includes all features related to RBD-Mirroring + management. +- **iscsi**: includes all features related to iSCSI management. +- **rgw**: includes all features related to Rados Gateway management. +- **cephfs**: includes all features related to CephFS management. +- **manager**: include all features related to Ceph Manager + management. +- **log**: include all features related to Ceph logs management. +- **grafana**: include all features related to Grafana proxy. + +A *role* specifies a set of mappings between a *security scope* and a set of +*permissions*. There are four types of permissions: + +- **read** +- **create** +- **update** +- **delete** + +See below for an example of a role specification based on a Python dictionary:: + + # example of a role + { + 'role': 'my_new_role', + 'description': 'My new role', + 'scopes_permissions': { + 'pool': ['read', 'create'], + 'rbd-image': ['read', 'create', 'update', 'delete'] + } + } + +The above role dictates that a user has *read* and *create* permissions for +features related to pool management, and has full permissions for +features related to RBD image management. + +The Dashboard already provides a set of predefined roles that we call +*system roles*, and can be used right away in a fresh Ceph Dashboard +installation. + +The list of system roles are: + +- **administrator**: provides full permissions for all security scopes. +- **read-only**: provides *read* permission for all security scopes. +- **block-manager**: provides full permissions for *rbd-image*, + *rbd-mirroring*, and *iscsi* scopes. +- **rgw-manager**: provides full permissions for the *rgw* scope +- **cluster-manager**: provides full permissions for the *hosts*, *osd*, + *monitor*, *manager*, and *config-opt* scopes. +- **pool-manager**: provides full permissions for the *pool* scope. +- **cephfs-manager**: provides full permissions for the *cephfs* scope. + +The list of currently available roles can be retrieved by the following +command:: + + $ ceph dashboard ac-role-show [] + +It is also possible to create new roles using CLI commands. The available +commands to manage roles are the following: + +- *Create Role*:: + + $ ceph dashboard ac-role-create [] + +- *Delete Role*:: + + $ ceph dashboard ac-role-delete + +- *Add Scope Permissions to Role*:: + + $ ceph dashboard ac-role-add-scope-perms [...] + +- *Delete Scope Permission from Role*:: + + $ ceph dashboard ac-role-del-perms + +To associate roles to users, the following CLI commands are available: + +- *Set User Roles*:: + + $ ceph dashboard ac-user-set-roles [...] + +- *Add Roles To User*:: + + $ ceph dashboard ac-user-add-roles [...] + +- *Delete Roles from User*:: + + $ ceph dashboard ac-user-del-roles [...] + + +Example of user and custom role creation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section we show a full example of the commands that need to be used +in order to create a user account, that should be able to manage RBD images, +view and create Ceph pools, and have read-only access to any other scopes. + +1. *Create the user*:: + + $ ceph dashboard ac-user-create bob mypassword + +2. *Create role and specify scope permissions*:: + + $ ceph dashboard ac-role-create rbd/pool-manager + $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager rbd-image read create update delete + $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager pool read create + +3. *Associate roles to user*:: + + $ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only + + Reverse proxies --------------- @@ -329,3 +500,4 @@ to use hyperlinks that include your prefix, you can set the ceph config set mgr mgr/dashboard/url_prefix $PREFIX so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``. + -- 2.39.5