9 The Ceph Dashboard is a built-in web-based Ceph management and monitoring
10 application to administer various aspects and objects of the cluster. It is
11 implemented as a :ref:`ceph-manager-daemon` module.
13 The original Ceph Dashboard that was shipped with Ceph Luminous started
14 out as a simple read-only view into various run-time information and performance
15 data of a Ceph cluster. It used a very simple architecture to achieve the
16 original goal. However, there was a growing demand for adding more web-based
17 management capabilities, to make it easier to administer Ceph for users that
18 prefer a WebUI over using the command line.
20 The new :term:`Ceph Dashboard` module is a replacement of the previous one and
21 adds a built-in web based monitoring and administration application to the Ceph
22 Manager. The architecture and functionality of this new plugin is derived from
23 and inspired by the `openATTIC Ceph management and monitoring tool
24 <https://openattic.org/>`_. The development is actively driven by the team
25 behind openATTIC at `SUSE <https://www.suse.com/>`_, with a lot of support from
26 companies like `Red Hat <https://redhat.com/>`_ and other members of the Ceph
29 The dashboard module's backend code uses the CherryPy framework and a custom
30 REST API implementation. The WebUI implementation is based on
31 Angular/TypeScript, merging both functionality from the original dashboard as
32 well as adding new functionality originally developed for the standalone version
33 of openATTIC. The Ceph Dashboard module is implemented as a web
34 application that visualizes information and statistics about the Ceph cluster
35 using a web server hosted by ``ceph-mgr``.
40 The dashboard provides the following features:
42 * **Multi-User and Role Management**: The dashboard supports multiple user
43 accounts with different permissions (roles). The user accounts and roles
44 can be modified on both the command line and via the WebUI.
45 See :ref:`dashboard-user-role-management` for details.
46 * **Single Sign-On (SSO)**: the dashboard supports authentication
47 via an external identity provider using the SAML 2.0 protocol. See
48 :ref:`dashboard-sso-support` for details.
49 * **SSL/TLS support**: All HTTP communication between the web browser and the
50 dashboard is secured via SSL. A self-signed certificate can be created with
51 a built-in command, but it's also possible to import custom certificates
52 signed and issued by a CA. See :ref:`dashboard-ssl-tls-support` for details.
53 * **Auditing**: the dashboard backend can be configured to log all PUT, POST
54 and DELETE API requests in the Ceph audit log. See :ref:`dashboard-auditing`
55 for instructions on how to enable this feature.
56 * **Internationalization (I18N)**: the dashboard can be used in different
57 languages that can be selected at run-time.
59 Currently, Ceph Dashboard is capable of monitoring and managing the following
60 aspects of your Ceph cluster:
62 * **Overall cluster health**: Display overall cluster status, performance
64 * **Embedded Grafana Dashboards**: Ceph Dashboard is capable of embedding
65 `Grafana <https://grafana.com>`_ dashboards in many locations, to display
66 additional information and performance metrics gathered by the
67 :ref:`mgr-prometheus`. See :ref:`dashboard-grafana` for details on how to
68 configure this functionality.
69 * **Cluster logs**: Display the latest updates to the cluster's event and
70 audit log files. Log entries can be filtered by priority, date or keyword.
71 * **Hosts**: Display a list of all hosts associated to the cluster, which
72 services are running and which version of Ceph is installed.
73 * **Performance counters**: Display detailed service-specific statistics for
75 * **Monitors**: List all MONs, their quorum status, open sessions.
76 * **Configuration Editor**: Display all available configuration options,
77 their description, type and default values and edit the current values.
78 * **Pools**: List all Ceph pools and their details (e.g. applications,
79 placement groups, replication size, EC profile, CRUSH ruleset, etc.)
80 * **OSDs**: List all OSDs, their status and usage statistics as well as
81 detailed information like attributes (OSD map), metadata, performance
82 counters and usage histograms for read/write operations. Mark OSDs
83 up/down/out, purge and reweight OSDs, perform scrub operations, modify
84 various scrub-related configuration options, select different profiles to
85 adjust the level of backfilling activity.
86 * **iSCSI**: List all hosts that run the TCMU runner service, display all
87 images and their performance characteristics (read/write ops, traffic).
88 Create, modify and delete iSCSI targets (via ``ceph-iscsi``). See
89 :ref:`dashboard-iscsi-management` for instructions on how to configure this
91 * **RBD**: List all RBD images and their properties (size, objects, features).
92 Create, copy, modify and delete RBD images. Define various I/O or bandwidth
93 limitation settings on a global, per-pool or per-image level. Create, delete
94 and rollback snapshots of selected images, protect/unprotect these snapshots
95 against modification. Copy or clone snapshots, flatten cloned images.
96 * **RBD mirroring**: Enable and configure RBD mirroring to a remote Ceph server.
97 Lists all active sync daemons and their status, pools and RBD images including
98 their synchronization state.
99 * **CephFS**: List all active filesystem clients and associated pools,
100 including their usage statistics.
101 * **Object Gateway**: List all active object gateways and their performance
102 counters. Display and manage (add/edit/delete) object gateway users and their
103 details (e.g. quotas) as well as the users' buckets and their details (e.g.
104 owner, quotas). See :ref:`dashboard-enabling-object-gateway` for configuration
106 * **NFS**: Manage NFS exports of CephFS filesystems and RGW S3 buckets via NFS
107 Ganesha. See :ref:`dashboard-nfs-ganesha-management` for details on how to
108 enable this functionality.
109 * **Ceph Manager Modules**: Enable and disable all Ceph Manager modules, change
110 the module-specific configuration settings.
116 Ceph Dashboard is primarily tested and developed using the following web
119 +----------------------------------------------+----------+
120 | Browser | Versions |
121 +==============================================+==========+
122 | `Chrome <https://www.google.com/chrome/>`_ | 68+ |
123 +----------------------------------------------+----------+
124 | `Firefox <http://www.mozilla.org/firefox/>`_ | 61+ |
125 +----------------------------------------------+----------+
127 While Ceph Dashboard might work in older browsers, we cannot guarantee it and
128 recommend you to update your browser to the latest version.
133 If you have installed ``ceph-mgr-dashboard`` from distribution packages, the
134 package management system should have taken care of installing all the required
137 If you're installing Ceph from source and want to start the dashboard from your
138 development environment, please see the files ``README.rst`` and ``HACKING.rst``
139 in directory ``src/pybind/mgr/dashboard`` of the source code.
141 Within a running Ceph cluster, the Ceph Dashboard is enabled with::
143 $ ceph mgr module enable dashboard
148 .. _dashboard-ssl-tls-support:
153 All HTTP connections to the dashboard are secured with SSL/TLS by default.
155 To get the dashboard up and running quickly, you can generate and install a
156 self-signed certificate using the following built-in command::
158 $ ceph dashboard create-self-signed-cert
160 Note that most web browsers will complain about such self-signed certificates
161 and require explicit confirmation before establishing a secure connection to the
164 To properly secure a deployment and to remove the certificate warning, a
165 certificate that is issued by a certificate authority (CA) should be used.
167 For example, a key pair can be generated with a command similar to::
169 $ openssl req -new -nodes -x509 \
170 -subj "/O=IT/CN=ceph-mgr-dashboard" -days 3650 \
171 -keyout dashboard.key -out dashboard.crt -extensions v3_ca
173 The ``dashboard.crt`` file should then be signed by a CA. Once that is done, you
174 can enable it for all Ceph manager instances by running the following commands::
176 $ ceph dashboard set-ssl-certificate -i dashboard.crt
177 $ ceph dashboard set-ssl-certificate-key -i dashboard.key
179 If different certificates are desired for each manager instance for some reason,
180 the name of the instance can be included as follows (where ``$name`` is the name
181 of the ``ceph-mgr`` instance, usually the hostname)::
183 $ ceph dashboard set-ssl-certificate $name -i dashboard.crt
184 $ ceph dashboard set-ssl-certificate-key $name -i dashboard.key
186 SSL can also be disabled by setting this configuration value::
188 $ ceph config set mgr mgr/dashboard/ssl false
190 This might be useful if the dashboard will be running behind a proxy which does
191 not support SSL for its upstream servers or other situations where SSL is not
196 Use caution when disabling SSL as usernames and passwords will be sent to the
197 dashboard unencrypted.
202 You need to restart the Ceph manager processes manually after changing the SSL
203 certificate and key. This can be accomplished by either running ``ceph mgr
204 fail mgr`` or by disabling and re-enabling the dashboard module (which also
205 triggers the manager to respawn itself)::
207 $ ceph mgr module disable dashboard
208 $ ceph mgr module enable dashboard
213 Like most web applications, dashboard binds to a TCP/IP address and TCP port.
215 By default, the ``ceph-mgr`` daemon hosting the dashboard (i.e., the currently
216 active manager) will bind to TCP port 8443 or 8080 when SSL is disabled.
218 If no specific address has been configured, the web app will bind to ``::``,
219 which corresponds to all available IPv4 and IPv6 addresses.
221 These defaults can be changed via the configuration key facility on a
222 cluster-wide level (so they apply to all manager instances) as follows::
224 $ ceph config set mgr mgr/dashboard/server_addr $IP
225 $ ceph config set mgr mgr/dashboard/server_port $PORT
226 $ ceph config set mgr mgr/dashboard/ssl_server_port $PORT
228 Since each ``ceph-mgr`` hosts its own instance of dashboard, it may also be
229 necessary to configure them separately. The IP address and port for a specific
230 manager instance can be changed with the following commands::
232 $ ceph config set mgr mgr/dashboard/$name/server_addr $IP
233 $ ceph config set mgr mgr/dashboard/$name/server_port $PORT
234 $ ceph config set mgr mgr/dashboard/$name/ssl_server_port $PORT
236 Replace ``$name`` with the ID of the ceph-mgr instance hosting the dashboard web
241 The command ``ceph mgr services`` will show you all endpoints that are
242 currently configured. Look for the ``dashboard`` key to obtain the URL for
243 accessing the dashboard.
245 Username and Password
246 ^^^^^^^^^^^^^^^^^^^^^
248 In order to be able to log in, you need to create a user account and associate
249 it with at least one role. We provide a set of predefined *system roles* that
250 you can use. For more details please refer to the `User and Role Management`_
253 To create a user with the administrator role you can use the following
256 $ ceph dashboard ac-user-create <username> <password> administrator
258 .. _dashboard-enabling-object-gateway:
260 Enabling the Object Gateway Management Frontend
261 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
263 To use the Object Gateway management functionality of the dashboard, you will
264 need to provide the login credentials of a user with the ``system`` flag
267 If you do not have a user which shall be used for providing those credentials,
268 you will also need to create one::
270 $ radosgw-admin user create --uid=<user_id> --display-name=<display_name> \
273 Take note of the keys ``access_key`` and ``secret_key`` in the output of this
276 The credentials of an existing user can also be obtained by using
279 $ radosgw-admin user info --uid=<user_id>
281 Finally, provide the credentials to the dashboard::
283 $ ceph dashboard set-rgw-api-access-key <access_key>
284 $ ceph dashboard set-rgw-api-secret-key <secret_key>
286 In a typical default configuration with a single RGW endpoint, this is all you
287 have to do to get the Object Gateway management functionality working. The
288 dashboard will try to automatically determine the host and port of the Object
289 Gateway by obtaining this information from the Ceph Manager's service map.
291 If multiple zones are used, it will automatically determine the host within the
292 master zone group and master zone. This should be sufficient for most setups,
293 but in some circumstances you might want to set the host and port manually::
295 $ ceph dashboard set-rgw-api-host <host>
296 $ ceph dashboard set-rgw-api-port <port>
298 In addition to the settings mentioned so far, the following settings do also
299 exist and you may find yourself in the situation that you have to use them::
301 $ ceph dashboard set-rgw-api-scheme <scheme> # http or https
302 $ ceph dashboard set-rgw-api-admin-resource <admin_resource>
303 $ ceph dashboard set-rgw-api-user-id <user_id>
305 If you are using a self-signed certificate in your Object Gateway setup, then
306 you should disable certificate verification in the dashboard to avoid refused
307 connections, e.g. caused by certificates signed by unknown CA or not matching
310 $ ceph dashboard set-rgw-api-ssl-verify False
312 If the Object Gateway takes too long to process requests and the dashboard runs
313 into timeouts, then you can set the timeout value to your needs::
315 $ ceph dashboard set-rest-requests-timeout <seconds>
317 The default value is 45 seconds.
319 .. _dashboard-iscsi-management:
321 Enabling iSCSI Management
322 ^^^^^^^^^^^^^^^^^^^^^^^^^
324 The Ceph Dashboard can manage iSCSI targets using the REST API provided by the
325 `rbd-target-api` service of the :ref:`ceph-iscsi`. Please make sure that it's
326 installed and enabled on the iSCSI gateways.
329 The iSCSI management functionality of Ceph Dashboard depends on the latest
330 version 3 of the `ceph-iscsi <https://github.com/ceph/ceph-iscsi>`_ project.
331 Make sure that your operating system provides the correct version, otherwise
332 the dashboard won't enable the management features.
334 If ceph-iscsi REST API is configured in HTTPS mode and its using a self-signed
335 certificate, then you need to configure the dashboard to avoid SSL certificate
336 verification when accessing ceph-iscsi API.
338 To disable API SSL verification run the following commmand::
340 $ ceph dashboard set-iscsi-api-ssl-verification false
342 The available iSCSI gateways must be defined using the following commands::
344 $ ceph dashboard iscsi-gateway-list
345 $ ceph dashboard iscsi-gateway-add <scheme>://<username>:<password>@<host>[:port]
346 $ ceph dashboard iscsi-gateway-rm <gateway_name>
349 .. _dashboard-grafana:
351 Enabling the Embedding of Grafana Dashboards
352 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
354 Grafana and Prometheus are likely going to be bundled and installed by some
355 orchestration tools along Ceph in the near future, but currently, you will have
356 to install and configure both manually. After you have installed Prometheus and
357 Grafana on your preferred hosts, proceed with the following steps.
359 #. Enable the Ceph Exporter which comes as Ceph Manager module by running::
361 $ ceph mgr module enable prometheus
363 More details can be found in the documentation of the :ref:`mgr-prometheus`.
365 #. Add the corresponding scrape configuration to Prometheus. This may look
372 - job_name: 'prometheus'
374 - targets: ['localhost:9090']
377 - targets: ['localhost:9283']
378 - job_name: 'node-exporter'
380 - targets: ['localhost:9100']
382 #. Add Prometheus as data source to Grafana
384 #. Install the `vonage-status-panel and grafana-piechart-panel` plugins using::
386 grafana-cli plugins install vonage-status-panel
387 grafana-cli plugins install grafana-piechart-panel
389 #. Add the Dashboards to Grafana:
391 Dashboards can be added to Grafana by importing dashboard jsons.
392 Following command can be used for downloading json files::
394 wget https://raw.githubusercontent.com/ceph/ceph/master/monitoring/grafana/dashboards/<Dashboard-name>.json
396 You can find all the dashboard jsons `here <https://github.com/ceph/ceph/tree/
397 master/monitoring/grafana/dashboards>`_ .
399 For Example, for ceph-cluster overview you can use::
401 wget https://raw.githubusercontent.com/ceph/ceph/master/monitoring/grafana/dashboards/ceph-cluster.json
403 #. Configure Grafana in `/etc/grafana/grafana.ini` to adapt anonymous mode::
410 After you have set up Grafana and Prometheus, you will need to configure the
411 connection information that the Ceph Dashboard will use to access Grafana.
413 You need to tell the dashboard on which url Grafana instance is running/deployed::
415 $ ceph dashboard set-grafana-api-url <grafana-server-url> # default: ''
417 The format of url is : `<protocol>:<IP-address>:<port>`
420 Ceph Dashboard embeds the Grafana dashboards via ``iframe`` HTML elements.
421 If Grafana is configured without SSL/TLS support, most browsers will block the
422 embedding of insecure content into a secured web page, if the SSL support in
423 the dashboard has been enabled (which is the default configuration). If you
424 can't see the embedded Grafana dashboards after enabling them as outlined
425 above, check your browser's documentation on how to unblock mixed content.
426 Alternatively, consider enabling SSL/TLS support in Grafana.
428 If you are using a self-signed certificate in your Grafana setup, then you should
429 disable certificate verification in the dashboard to avoid refused connections,
430 e.g. caused by certificates signed by unknown CA or not matching the host name::
432 $ ceph dashboard set-grafana-api-ssl-verify False
434 You can directly access Grafana Instance as well to monitor your cluster.
436 .. _dashboard-sso-support:
438 Enabling Single Sign-On (SSO)
439 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
441 The Ceph Dashboard supports external authentication of users via the
442 `SAML 2.0 <https://en.wikipedia.org/wiki/SAML_2.0>`_ protocol. You need to create
443 the user accounts and associate them with the desired roles first, as authorization
444 is still performed by the Dashboard. However, the authentication process can be
445 performed by an existing Identity Provider (IdP).
448 Ceph Dashboard SSO support relies on onelogin's
449 `python-saml <https://pypi.org/project/python-saml/>`_ library.
450 Please ensure that this library is installed on your system, either by using
451 your distribution's package management or via Python's `pip` installer.
453 To configure SSO on Ceph Dashboard, you should use the following command::
455 $ ceph dashboard sso setup saml2 <ceph_dashboard_base_url> <idp_metadata> {<idp_username_attribute>} {<idp_entity_id>} {<sp_x_509_cert>} {<sp_private_key>}
459 * **<ceph_dashboard_base_url>**: Base URL where Ceph Dashboard is accessible (e.g., `https://cephdashboard.local`)
460 * **<idp_metadata>**: URL, file path or content of the IdP metadata XML (e.g., `https://myidp/metadata`)
461 * **<idp_username_attribute>** *(optional)*: Attribute that should be used to get the username from the authentication response. Defaults to `uid`.
462 * **<idp_entity_id>** *(optional)*: Use this when more than one entity id exists on the IdP metadata.
463 * **<sp_x_509_cert> / <sp_private_key>** *(optional)*: File path or content of the certificate that should be used by Ceph Dashboard (Service Provider) for signing and encryption.
466 The issuer value of SAML requests will follow this pattern: **<ceph_dashboard_base_url>**/auth/saml2/metadata
468 To display the current SAML 2.0 configuration, use the following command::
470 $ ceph dashboard sso show saml2
473 For more information about `onelogin_settings`, please check the `onelogin documentation <https://github.com/onelogin/python-saml>`_.
477 $ ceph dashboard sso disable
479 To check if SSO is enabled::
481 $ ceph dashboard sso status
485 $ ceph dashboard sso enable saml2
487 Enabling Prometheus Alerting
488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
490 Using Prometheus for monitoring, you have to define `alerting rules
491 <https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules>`_.
492 To manage them you need to use the `Alertmanager
493 <https://prometheus.io/docs/alerting/alertmanager>`_.
494 If you are not using the Alertmanager yet, please `install it
495 <https://github.com/prometheus/alertmanager#install>`_ as it's mandatory in
496 order to receive and manage alerts from Prometheus.
498 The Alertmanager capabilities can be consumed by the dashboard in three different
501 #. Use the notification receiver of the dashboard.
503 #. Use the Prometheus Alertmanager API.
505 #. Use both sources simultaneously.
507 All three methods are going to notify you about alerts. You won't be notified
508 twice if you use both sources, but you need to consume at least the Alertmanager API
509 in order to manage silences.
511 #. Use the notification receiver of the dashboard:
513 This allows you to get notifications as `configured
514 <https://prometheus.io/docs/alerting/configuration/>`_ from the Alertmanager.
515 You will get notified inside the dashboard once a notification is send out,
516 but you are not able to manage alerts.
518 Add the dashboard receiver and the new route to your Alertmanager configuration.
519 This should look like::
522 receiver: 'ceph-dashboard'
525 - name: 'ceph-dashboard'
527 - url: '<url-to-dashboard>/api/prometheus_receiver'
530 Please make sure that the Alertmanager considers your SSL certificate in terms
531 of the dashboard as valid. For more information about the correct
532 configuration checkout the `<http_config> documentation
533 <https://prometheus.io/docs/alerting/configuration/#%3Chttp_config%3E>`_.
535 #. Use the API of Prometheus and the Alertmanager
537 This allows you to manage alerts and silences. You will see all alerts and silences
538 the Alertmanager currently knows of in the corresponding listing.
539 Both can be found in the *Cluster* submenu.
541 Alerts can be sorted by name, job, severity, state and start time.
542 Unfortunately it's not possible to know when an alert
543 was sent out through a notification by the Alertmanager based on your
544 configuration, that's why the dashboard will notify the user on any visible
545 change to an alert and will notify the changed alert.
547 Silences can be sorted by id, creator, status, start, updated and end time.
548 Silences can be created in various ways, it's also possible to expire them.
550 #. Create from scratch
552 #. Based on a selected alert
554 #. Recreate from expired silence
556 #. Update a silence (which will recreate and expire it (default Alertmanager behaviour))
558 To use it, specify the host and port of the Alertmanager server::
560 $ ceph dashboard set-alertmanager-api-host <alertmanager-host:port> # default: ''
564 $ ceph dashboard set-alertmanager-api-host 'http://localhost:9093'
566 To be able to show what a silence will match beforehand, you have to add the host
567 and port of the Prometheus server::
569 $ ceph dashboard set-prometheus-api-host <prometheus-host:port> # default: ''
573 $ ceph dashboard set-prometheus-api-host 'http://localhost:9090'
575 After setting up the hosts, you have to refresh your the dashboard in your browser window.
579 The different behaviors of both methods are configured in a way that they
580 should not disturb each other through annoying duplicated notifications
583 Accessing the Dashboard
584 ^^^^^^^^^^^^^^^^^^^^^^^
586 You can now access the dashboard using your (JavaScript-enabled) web browser, by
587 pointing it to any of the host names or IP addresses and the selected TCP port
588 where a manager instance is running: e.g., ``httpS://<$IP>:<$PORT>/``.
590 You should then be greeted by the dashboard login page, requesting your
591 previously defined username and password. Select the **Keep me logged in**
592 checkbox if you want to skip the username/password request when accessing the
593 dashboard in the future.
595 .. _dashboard-user-role-management:
597 User and Role Management
598 ------------------------
603 Ceph Dashboard supports managing multiple user accounts. Each user account
604 consists of a username, a password (stored in encrypted form using ``bcrypt``),
605 an optional name, and an optional email address.
607 User accounts are stored in MON's configuration database, and are globally
608 shared across all ceph-mgr instances.
610 We provide a set of CLI commands to manage user accounts:
614 $ ceph dashboard ac-user-show [<username>]
618 $ ceph dashboard ac-user-create <username> [<password>] [<rolename>] [<name>] [<email>]
622 $ ceph dashboard ac-user-delete <username>
624 - *Change Password*::
626 $ ceph dashboard ac-user-set-password <username> <password>
628 - *Modify User (name, and email)*::
630 $ ceph dashboard ac-user-set-info <username> <name> <email>
633 User Roles and Permissions
634 ^^^^^^^^^^^^^^^^^^^^^^^^^^
636 User accounts are also associated with a set of roles that define which
637 dashboard functionality can be accessed by the user.
639 The Dashboard functionality/modules are grouped within a *security scope*.
640 Security scopes are predefined and static. The current available security
643 - **hosts**: includes all features related to the ``Hosts`` menu
645 - **config-opt**: includes all features related to management of Ceph
646 configuration options.
647 - **pool**: includes all features related to pool management.
648 - **osd**: includes all features related to OSD management.
649 - **monitor**: includes all features related to Monitor management.
650 - **rbd-image**: includes all features related to RBD image
652 - **rbd-mirroring**: includes all features related to RBD-Mirroring
654 - **iscsi**: includes all features related to iSCSI management.
655 - **rgw**: includes all features related to Rados Gateway management.
656 - **cephfs**: includes all features related to CephFS management.
657 - **manager**: include all features related to Ceph Manager
659 - **log**: include all features related to Ceph logs management.
660 - **grafana**: include all features related to Grafana proxy.
661 - **prometheus**: include all features related to Prometheus alert management.
662 - **dashboard-settings**: allows to change dashboard settings.
664 A *role* specifies a set of mappings between a *security scope* and a set of
665 *permissions*. There are four types of permissions:
672 See below for an example of a role specification based on a Python dictionary::
676 'role': 'my_new_role',
677 'description': 'My new role',
678 'scopes_permissions': {
679 'pool': ['read', 'create'],
680 'rbd-image': ['read', 'create', 'update', 'delete']
684 The above role dictates that a user has *read* and *create* permissions for
685 features related to pool management, and has full permissions for
686 features related to RBD image management.
688 The Dashboard already provides a set of predefined roles that we call
689 *system roles*, and can be used right away in a fresh Ceph Dashboard
692 The list of system roles are:
694 - **administrator**: provides full permissions for all security scopes.
695 - **read-only**: provides *read* permission for all security scopes except
696 the dashboard settings.
697 - **block-manager**: provides full permissions for *rbd-image*,
698 *rbd-mirroring*, and *iscsi* scopes.
699 - **rgw-manager**: provides full permissions for the *rgw* scope
700 - **cluster-manager**: provides full permissions for the *hosts*, *osd*,
701 *monitor*, *manager*, and *config-opt* scopes.
702 - **pool-manager**: provides full permissions for the *pool* scope.
703 - **cephfs-manager**: provides full permissions for the *cephfs* scope.
705 The list of currently available roles can be retrieved by the following
708 $ ceph dashboard ac-role-show [<rolename>]
710 It is also possible to create new roles using CLI commands. The available
711 commands to manage roles are the following:
715 $ ceph dashboard ac-role-create <rolename> [<description>]
719 $ ceph dashboard ac-role-delete <rolename>
721 - *Add Scope Permissions to Role*::
723 $ ceph dashboard ac-role-add-scope-perms <rolename> <scopename> <permission> [<permission>...]
725 - *Delete Scope Permission from Role*::
727 $ ceph dashboard ac-role-del-perms <rolename> <scopename>
729 To associate roles to users, the following CLI commands are available:
733 $ ceph dashboard ac-user-set-roles <username> <rolename> [<rolename>...]
735 - *Add Roles To User*::
737 $ ceph dashboard ac-user-add-roles <username> <rolename> [<rolename>...]
739 - *Delete Roles from User*::
741 $ ceph dashboard ac-user-del-roles <username> <rolename> [<rolename>...]
744 Example of User and Custom Role Creation
745 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
747 In this section we show a full example of the commands that need to be used
748 in order to create a user account, that should be able to manage RBD images,
749 view and create Ceph pools, and have read-only access to any other scopes.
751 1. *Create the user*::
753 $ ceph dashboard ac-user-create bob mypassword
755 2. *Create role and specify scope permissions*::
757 $ ceph dashboard ac-role-create rbd/pool-manager
758 $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager rbd-image read create update delete
759 $ ceph dashboard ac-role-add-scope-perms rbd/pool-manager pool read create
761 3. *Associate roles to user*::
763 $ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only
769 In a Ceph cluster with multiple ceph-mgr instances, only the dashboard running
770 on the currently active ceph-mgr daemon will serve incoming requests. Accessing
771 the dashboard's TCP port on any of the other ceph-mgr instances that are
772 currently on standby will perform a HTTP redirect (303) to the currently active
773 manager's dashboard URL. This way, you can point your browser to any of the
774 ceph-mgr instances in order to access the dashboard.
776 If you want to establish a fixed URL to reach the dashboard or if you don't want
777 to allow direct connections to the manager nodes, you could set up a proxy that
778 automatically forwards incoming requests to the currently active ceph-mgr
781 Configuring a URL Prefix
782 ^^^^^^^^^^^^^^^^^^^^^^^^
784 If you are accessing the dashboard via a reverse proxy configuration,
785 you may wish to service it under a URL prefix. To get the dashboard
786 to use hyperlinks that include your prefix, you can set the
787 ``url_prefix`` setting:
791 ceph config set mgr mgr/dashboard/url_prefix $PREFIX
793 so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``.
795 Disable the redirection
796 ^^^^^^^^^^^^^^^^^^^^^^^
798 If the dashboard is behind a load-balancing proxy like `HAProxy <https://www.haproxy.org/>`_
799 you might want to disable the redirection behaviour to prevent situations that
800 internal (unresolvable) URL's are published to the frontend client. Use the
801 following command to get the dashboard to respond with a HTTP error (500 by default)
802 instead of redirecting to the active dashboard::
804 $ ceph config set mgr mgr/dashboard/standby_behaviour "error"
806 To reset the setting to the default redirection behaviour, use the following command::
808 $ ceph config set mgr mgr/dashboard/standby_behaviour "redirect"
810 Configure the error status code
811 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
813 When the redirection behaviour is disabled, then you want to customize the HTTP status
814 code of standby dashboards. To do so you need to run the command::
816 $ ceph config set mgr mgr/dashboard/standby_error_status_code 503
818 HAProxy example configuration
819 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
821 Below you will find an example configuration for SSL/TLS pass through using
822 `HAProxy <https://www.haproxy.org/>`_.
824 Please note that the configuration works under the following conditions.
825 If the dashboard fails over, the front-end client might receive a HTTP redirect
826 (303) response and will be redirected to an unresolvable host. This happens when
827 the failover occurs during two HAProxy health checks. In this situation the
828 previously active dashboard node will now respond with a 303 which points to
829 the new active node. To prevent that situation you should consider to disable
830 the redirection behaviour on standby nodes.
836 option log-health-checks
841 frontend dashboard_front
845 redirect scheme https code 301 if !{ ssl_fc }
847 frontend dashboard_front_ssl
851 default_backend dashboard_back_ssl
853 backend dashboard_back_ssl
856 http-check expect status 200
857 server x <HOST>:<PORT> check-ssl check verify none
858 server y <HOST>:<PORT> check-ssl check verify none
859 server z <HOST>:<PORT> check-ssl check verify none
861 .. _dashboard-auditing:
863 Auditing API Requests
864 ---------------------
866 The REST API is capable of logging PUT, POST and DELETE requests to the Ceph
867 audit log. This feature is disabled by default, but can be enabled with the
870 $ ceph dashboard set-audit-api-enabled <true|false>
872 If enabled, the following parameters are logged per each request:
874 * from - The origin of the request, e.g. https://[::1]:44410
875 * path - The REST API path, e.g. /api/auth
876 * method - e.g. PUT, POST or DELETE
877 * user - The name of the user, otherwise 'None'
879 The logging of the request payload (the arguments and their values) is enabled
880 by default. Execute the following command to disable this behaviour::
882 $ ceph dashboard set-audit-api-log-payload <true|false>
884 A log entry may look like this::
886 2018-10-22 15:27:01.302514 mgr.x [INF] [DASHBOARD] from='https://[::ffff:127.0.0.1]:37022' path='/api/rgw/user/klaus' method='PUT' user='admin' params='{"max_buckets": "1000", "display_name": "Klaus Mustermann", "uid": "klaus", "suspended": "0", "email": "klaus.mustermann@ceph.com"}'
888 .. _dashboard-nfs-ganesha-management:
890 NFS-Ganesha Management
891 ----------------------
893 Ceph Dashboard can manage `NFS Ganesha <http://nfs-ganesha.github.io/>`_ exports that use
894 CephFS or RadosGW as their backstore.
896 To enable this feature in Ceph Dashboard there are some assumptions that need
897 to be met regarding the way NFS-Ganesha services are configured.
899 The dashboard manages NFS-Ganesha config files stored in RADOS objects on the Ceph Cluster.
900 NFS-Ganesha must store part of their configuration in the Ceph cluster.
902 These configuration files must follow some conventions.
904 Each export block must be stored in its own RADOS object named
905 ``export-<id>``, where ``<id>`` must match the ``Export_ID`` attribute of the
906 export configuration. Then, for each NFS-Ganesha service daemon there should
907 exist a RADOS object named ``conf-<daemon_id>``, where ``<daemon_id>`` is an
908 arbitrary string that should uniquely identify the daemon instance (e.g., the
909 hostname where the daemon is running).
910 Each ``conf-<daemon_id>`` object contains the RADOS URLs to the exports that
911 the NFS-Ganesha daemon should serve. These URLs are of the form::
913 %url rados://<pool_name>[/<namespace>]/export-<id>
915 Both the ``conf-<daemon_id>`` and ``export-<id>`` objects must be stored in the
916 same RADOS pool/namespace.
919 Configuring NFS-Ganesha in the Dashboard
920 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
922 To enable the management of NFS-Ganesha exports in Ceph Dashboard, we only
923 need to tell the Dashboard, in which RADOS pool and namespace the
924 configuration objects are stored. Then, Ceph Dashboard can access the objects
925 by following the naming convention described above.
927 The Dashboard command to configure the NFS-Ganesha configuration objects
930 $ ceph dashboard set-ganesha-clusters-rados-pool-namespace <pool_name>[/<namespace>]
932 After running the above command, Ceph Dashboard is able to find the NFS-Ganesha
933 configuration objects and we can start manage the exports through the Web UI.
936 Support for Multiple NFS-Ganesha Clusters
937 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
939 Ceph Dashboard also supports the management of NFS-Ganesha exports belonging
940 to different NFS-Ganesha clusters. An NFS-Ganesha cluster is a group of
941 NFS-Ganesha service daemons sharing the same exports. Different NFS-Ganesha
942 clusters are independent and don't share the exports configuration between each
945 Each NFS-Ganesha cluster should store its configuration objects in a
946 different RADOS pool/namespace to isolate the configuration from each other.
948 To specify the locations of the configuration of each NFS-Ganesha cluster we
949 can use the same command as above but with a different value pattern::
951 $ ceph dashboard set-ganesha-clusters-rados-pool-namespace <cluster_id>:<pool_name>[/<namespace>](,<cluster_id>:<pool_name>[/<namespace>])*
953 The ``<cluster_id>`` is an arbitrary string that should uniquely identify the
956 When configuring the Ceph Dashboard with multiple NFS-Ganesha clusters, the
957 Web UI will automatically allow to choose to which cluster an export belongs.
963 Dashboard Plug-ins allow to extend the functionality of the dashboard in a modular
964 and loosely coupled approach.
966 .. include:: dashboard_plugins/feature_toggles.inc.rst