--------
The Ceph Dashboard is a built-in web-based Ceph management and monitoring
-application to administer various aspects and objects of the cluster. It is
-implemented as a :ref:`ceph-manager-daemon` module.
+application through which you can inspect and administer various aspects
+and resources within the cluster. It is implemented as a :ref:`ceph-manager-daemon` module.
The original Ceph Dashboard that was shipped with Ceph Luminous started
-out as a simple read-only view into various run-time information and performance
-data of a Ceph cluster. It used a very simple architecture to achieve the
-original goal. However, there was a growing demand for adding more web-based
+out as a simple read-only view into run-time information and performance
+data of Ceph clusters. It used a very simple architecture to achieve the
+original goal. However, there was growing demand for richer web-based
management capabilities, to make it easier to administer Ceph for users that
-prefer a WebUI over using the command line.
+prefer a WebUI over the CLI.
-The new :term:`Ceph Dashboard` module is a replacement of the previous one and
-adds a built-in web based monitoring and administration application to the Ceph
-Manager. The architecture and functionality of this new module is derived from
+The new :term:`Ceph Dashboard` module adds web-based monitoring and
+administration to the Ceph Manager. The architecture and functionality of this new
+module are derived from
and inspired by the `openATTIC Ceph management and monitoring tool
-<https://openattic.org/>`_. The development is actively driven by the team
-behind openATTIC at `SUSE <https://www.suse.com/>`_, with a lot of support from
-companies like `Red Hat <https://redhat.com/>`_ and other members of the Ceph
+<https://openattic.org/>`_. Development is actively driven by the
+openATTIC team at `SUSE <https://www.suse.com/>`_, with support from
+companies including `Red Hat <https://redhat.com/>`_ and members of the Ceph
community.
-The dashboard module's backend code uses the CherryPy framework and a custom
-REST API implementation. The WebUI implementation is based on
-Angular/TypeScript, merging both functionality from the original dashboard as
-well as adding new functionality originally developed for the standalone version
-of openATTIC. The Ceph Dashboard module is implemented as a web
-application that visualizes information and statistics about the Ceph cluster
-using a web server hosted by ``ceph-mgr``.
+The dashboard module's backend code uses the CherryPy framework and implements
+a custom REST API. The WebUI implementation is based on
+Angular/TypeScript and includes both functionality from the original dashboard
+and new features originally developed for the standalone version
+of openATTIC. The Ceph Dashboard module is implemented as an
+application that provides a graphical representation of information and statistics
+through a web server hosted by ``ceph-mgr``.
Feature Overview
^^^^^^^^^^^^^^^^
The dashboard provides the following features:
* **Multi-User and Role Management**: The dashboard supports multiple user
- accounts with different permissions (roles). The user accounts and roles
- can be modified on both the command line and via the WebUI. The dashboard
- supports various methods to enhance password security, e.g. by enforcing
- configurable password complexity rules, forcing users to change their password
+ accounts with different permissions (roles). User accounts and roles
+ can be managed via both the command line and the WebUI. The dashboard
+ supports various methods to enhance password security. Password
+ complexity rules may be configured, requiring users to change their password
after the first login or after a configurable time period. See
:ref:`dashboard-user-role-management` for details.
-* **Single Sign-On (SSO)**: the dashboard supports authentication
+* **Single Sign-On (SSO)**: The dashboard supports authentication
via an external identity provider using the SAML 2.0 protocol. See
:ref:`dashboard-sso-support` for details.
* **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
a built-in command, but it's also possible to import custom certificates
signed and issued by a CA. See :ref:`dashboard-ssl-tls-support` for details.
-* **Auditing**: the dashboard backend can be configured to log all PUT, POST
- and DELETE API requests in the Ceph audit log. See :ref:`dashboard-auditing`
+* **Auditing**: The dashboard backend can be configured to log all ``PUT``, ``POST``
+ and ``DELETE`` API requests in the Ceph audit log. See :ref:`dashboard-auditing`
for instructions on how to enable this feature.
-* **Internationalization (I18N)**: the dashboard can be used in different
- languages that can be selected at run-time.
+* **Internationalization (I18N)**: The language used for dashboard text can be
+ selected at run-time.
-Currently, Ceph Dashboard is capable of monitoring and managing the following
-aspects of your Ceph cluster:
+The Ceph Dashboard offers the following monitoring and management capabilities:
-* **Overall cluster health**: Display overall cluster status, performance
- and capacity metrics.
-* **Embedded Grafana Dashboards**: Ceph Dashboard is capable of embedding
- `Grafana`_ dashboards in many locations, to display additional information
- and performance metrics gathered by the :ref:`mgr-prometheus`. See
+* **Overall cluster health**: Display performance and capacity metrics as well
+ as cluster status.
+* **Embedded Grafana Dashboards**: Ceph Dashboard
+ `Grafana`_ dashboards may be embedded in external applications and web pages
+ to surface information and performance metrics gathered by
+ the :ref:`mgr-prometheus` module. See
:ref:`dashboard-grafana` for details on how to configure this functionality.
* **Cluster logs**: Display the latest updates to the cluster's event and
audit log files. Log entries can be filtered by priority, date or keyword.
-* **Hosts**: Display a list of all hosts associated to the cluster, which
- disks are attached, which services are running and which version of Ceph is
+* **Hosts**: Display a list of all cluster hosts along with their
+ storage drives, which services are running, and which version of Ceph is
installed.
* **Performance counters**: Display detailed service-specific statistics for
each running service.
-* **Monitors**: List all MONs, their quorum status, open sessions.
-* **Monitoring**: Enable creation, re-creation, editing and expiration of
- Prometheus' silences, list the alerting configuration of Prometheus and all
+* **Monitors**: List all Mons, their quorum status, and open sessions.
+* **Monitoring**: Enable creation, re-creation, editing, and expiration of
+ Prometheus' silences, list the alerting configuration and all
configured and firing alerts. Show notifications for firing alerts.
* **Configuration Editor**: Display all available configuration options,
- their description, type and default values and edit the current values.
-* **Pools**: List all Ceph pools and their details (e.g. applications,
+ their descriptions, types, default and currently set values. These may be edited as well.
+* **Pools**: List Ceph pools and their details (e.g. applications,
pg-autoscaling, placement groups, replication size, EC profile, CRUSH
rulesets, quotas etc.)
-* **OSDs**: List all OSDs, their status and usage statistics as well as
+* **OSDs**: List OSDs, their status and usage statistics as well as
detailed information like attributes (OSD map), metadata, performance
counters and usage histograms for read/write operations. Mark OSDs
up/down/out, purge and reweight OSDs, perform scrub operations, modify
- various scrub-related configuration options, select different profiles to
- adjust the level of backfilling activity. List all disks associated with an
+ various scrub-related configuration options, select profiles to
+ adjust the level of backfilling activity. List all drives associated with an
OSD. Set and change the device class of an OSD, display and sort OSDs by
- device class. Deploy new OSDs on new disks/hosts.
+ device class. Deploy OSDs on new drives and hosts.
* **Device management**: List all hosts known by the orchestrator. List all
- disks and their properties attached to a node. Display disk health information
- (health prediction and SMART data). Blink enclosure LEDs.
+ drives attached to a host and their properties. Display drive
+ health predictions and SMART data. Blink enclosure LEDs.
* **iSCSI**: List all hosts that run the TCMU runner service, display all
images and their performance characteristics (read/write ops, traffic).
- Create, modify and delete iSCSI targets (via ``ceph-iscsi``). Display the
- iSCSI gateway status on the landing page and info about active initiators.
+ Create, modify, and delete iSCSI targets (via ``ceph-iscsi``). Display the
+ iSCSI gateway status and info about active initiators.
See :ref:`dashboard-iscsi-management` for instructions on how to configure
this feature.
* **RBD**: List all RBD images and their properties (size, objects, features).
images, protect/unprotect these snapshots against modification. Copy or clone
snapshots, flatten cloned images.
* **RBD mirroring**: Enable and configure RBD mirroring to a remote Ceph server.
- Lists all active sync daemons and their status, pools and RBD images including
- their synchronization state.
-* **CephFS**: List all active file system clients and associated pools,
- including their usage statistics. Evict active CephFS clients. Manage CephFS
+ List active daemons and their status, pools and RBD images including
+ sync progress.
+* **CephFS**: List active file system clients and associated pools,
+ including usage statistics. Evict active CephFS clients. Manage CephFS
quotas and snapshots. Browse a CephFS directory structure.
* **Object Gateway**: List all active object gateways and their performance
counters. Display and manage (add/edit/delete) object gateway users and their
* **NFS**: Manage NFS exports of CephFS file systems and RGW S3 buckets via NFS
Ganesha. See :ref:`dashboard-nfs-ganesha-management` for details on how to
enable this functionality.
-* **Ceph Manager Modules**: Enable and disable all Ceph Manager modules, change
- the module-specific configuration settings.
+* **Ceph Manager Modules**: Enable and disable Ceph Manager modules, manage
+ module-specific configuration settings.
Overview of the Dashboard Landing Page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Displays overall cluster status, performance and capacity metrics. Gives instant
-feedback to changes in the cluster and provides easy access to subpages of the
+Displays overall cluster status, performance, and capacity metrics. Shows instant
+feedback for changes in the cluster and provides easy access to subpages of the
dashboard.
.. _dashboard-landing-page-status:
* **Cluster Status**: Displays overall cluster health. In case of any error it
displays a short description of the error and provides a link to the logs.
* **Hosts**: Displays the total number of hosts associated to the cluster and
- links to the subpage displaying the list and descriptions of all hosts.
-* **Monitors**: Displays the total number of all MONs and their quorum status,
- open sessions and links to the subpage providing a list and descriptions of all
- the MONs.
-* **OSDs**: Displays total number of object storage daemons for Ceph (ceph-osds)
- and the total number of OSDs running (up), total number of OSDs in the cluster
- (in) and total number of OSDs out of the cluster (out). Provides link to the
- subpage containing a list of all OSDs and related management actions.
-* **Managers**: Displays the total number of active and standby Ceph Manager
- daemons (ceph-mgr) running alongside monitor daemons.
-* **Object Gateway**: Displays the total number of active object gateways and
- provides a link to the subpage displaying a list of all object gateway daemons.
-* **Metadata Servers**: Displays total number of active and standby metadata
- servers daemons for CephFS (ceph-mds).
-* **iSCSI Gateways**: Display the total number of iSCSI gateways available, total
- number of active iSCSI gateways (up) and total number of inactive iSCSI
- Gateways (down). Provides link to the subpage providing a list of all iSCSI
- Gateways.
+ links to a subpage that lists and describes each.
+* **Monitors**: Displays mons and their quorum status and
+ open sessions. Links to a subpage that lists and describes each.
+* **OSDs**: Displays object storage daemons (ceph-osds) and
+ the numbers of OSDs running (up), in service
+ (in), and out of the cluster (out). Provides links to
+ subpages providing a list of all OSDs and related management actions.
+* **Managers**: Displays active and standby Ceph Manager
+ daemons (ceph-mgr).
+* **Object Gateway**: Displays active object gateways (RGWs) and
+ provides links to subpages that list all object gateway daemons.
+* **Metadata Servers**: Displays active and standby CephFS metadata
+ service daemons (ceph-mds).
+* **iSCSI Gateways**: Display iSCSI gateways available,
+ active (up), and inactive (down). Provides a link to a subpage
+ showing a list of all iSCSI Gateways.
.. _dashboard-landing-page-capacity:
Capacity
""""""""
-* **Raw Capacity**: Displays the total physical capacity used out of the total
- physical capacity provided by the ceph storage nodes (OSDs).
-* **Objects**: Displays the number of objects in use and the status of objects
- including the percentage of healthy, misplaced, degraded and unfound status of
- objects. An object is the smallest unit of data storage in Ceph cluster.
-* **PG Status**: Displays the total number of placement groups in use and the
- status of placement groups, including the percentage of clean, working,
- warning and unknown status of placement groups.
-* **Pools**: Displays the total number of pools and links to the subpage that
- lists all Ceph pools and their details.
-* **PGs per OSD**: Displays the number of placement groups per object storage
- daemons.
+* **Raw Capacity**: Displays the capacity used out of the total
+ physical capacity provided by storage nodes (OSDs).
+* **Objects**: Displays the number and status of RADOS objects
+ including the percentages of healthy, misplaced, degraded, and unfound
+ objects.
+* **PG Status**: Displays the total number of placement groups and
+ their status, including the percentage clean, working,
+ warning, and unknown.
+* **Pools**: Displays pools and links to a subpage listing details.
+* **PGs per OSD**: Displays the number of placement groups assigned to
+ object storage daemons.
.. _dashboard-landing-page-performance:
Performance
"""""""""""
-* **Client READ/Write**: Displays an overview of rate the read/write operations,
- the total number of input and output operations performed by the cluster on
- storage devices on the client side.
-* **Client Throughput**: Displays the data transfer rate to and from Ceph clients.
-* **Recovery throughput**: Displays rate of moving the data back to the cluster
- if the cluster is recovering to parity when the hard drive is lost.
-* **Scrubbing**: Displays whether Ceph is comparing the data to other pieces of
- data to ensure there is no data corruption on the cluster's storage devices.
+* **Client READ/Write**: Displays an overview of
+ client input and output operations.
+* **Client Throughput**: Displays the data transfer rates to and from Ceph clients.
+* **Recovery throughput**: Displays rate of cluster healing and balancing operations.
+* **Scrubbing**: Displays light and deep scrub status.
Supported Browsers
^^^^^^^^^^^^^^^^^^
| `Firefox ESR <https://www.mozilla.org/firefox/enterprise/>`_ | latest major version |
+---------------------------------------------------------------+---------------------------------------+
-While Ceph Dashboard might work in older browsers, we cannot guarantee it and
-recommend you to update your browser to the latest version.
+While Ceph Dashboard might work in older browsers, we cannot guarantee compatibility and
+recommend keeping your browser up to date.
Enabling
--------
If you have installed ``ceph-mgr-dashboard`` from distribution packages, the
-package management system should have taken care of installing all the required
+package management system should take care of installing all required
dependencies.
-If you're installing Ceph from source and want to start the dashboard from your
+If you're building Ceph from source and want to start the dashboard from your
development environment, please see the files ``README.rst`` and ``HACKING.rst``
-in directory ``src/pybind/mgr/dashboard`` of the source code.
+in the source directory ``src/pybind/mgr/dashboard``.
Within a running Ceph cluster, the Ceph Dashboard is enabled with::
All HTTP connections to the dashboard are secured with SSL/TLS by default.
To get the dashboard up and running quickly, you can generate and install a
-self-signed certificate using the following built-in command::
+self-signed certificate::
$ ceph dashboard create-self-signed-cert
-Note that most web browsers will complain about such self-signed certificates
+Note that most web browsers will complain about self-signed certificates
and require explicit confirmation before establishing a secure connection to the
dashboard.
-To properly secure a deployment and to remove the certificate warning, a
+To properly secure a deployment and to remove the warning, a
certificate that is issued by a certificate authority (CA) should be used.
For example, a key pair can be generated with a command similar to::
-keyout dashboard.key -out dashboard.crt -extensions v3_ca
The ``dashboard.crt`` file should then be signed by a CA. Once that is done, you
-can enable it for all Ceph manager instances by running the following commands::
+can enable it for Ceph manager instances by running the following commands::
$ ceph dashboard set-ssl-certificate -i dashboard.crt
$ ceph dashboard set-ssl-certificate-key -i dashboard.key
-If different certificates are desired for each manager instance for some reason,
+If unique certificates are desired for each manager instance,
the name of the instance can be included as follows (where ``$name`` is the name
of the ``ceph-mgr`` instance, usually the hostname)::
.. note::
- You need to restart the Ceph manager processes manually after changing the SSL
+ You must restart Ceph manager processes after changing the SSL
certificate and key. This can be accomplished by either running ``ceph mgr
fail mgr`` or by disabling and re-enabling the dashboard module (which also
triggers the manager to respawn itself)::
Host Name and Port
^^^^^^^^^^^^^^^^^^
-Like most web applications, dashboard binds to a TCP/IP address and TCP port.
+Like most web applications, the dashboard binds to a TCP/IP address and TCP port.
By default, the ``ceph-mgr`` daemon hosting the dashboard (i.e., the currently
active manager) will bind to TCP port 8443 or 8080 when SSL is disabled.
$ ceph config set mgr mgr/dashboard/server_port $PORT
$ ceph config set mgr mgr/dashboard/ssl_server_port $PORT
-Since each ``ceph-mgr`` hosts its own instance of dashboard, it may also be
+Since each ``ceph-mgr`` hosts its own instance of the dashboard, it may be
necessary to configure them separately. The IP address and port for a specific
manager instance can be changed with the following commands::
$ ceph config set mgr mgr/dashboard/$name/server_port $PORT
$ ceph config set mgr mgr/dashboard/$name/ssl_server_port $PORT
-Replace ``$name`` with the ID of the ceph-mgr instance hosting the dashboard web
-app.
+Replace ``$name`` with the ID of the ceph-mgr instance hosting the dashboard.
.. note::
pointing it to any of the host names or IP addresses and the selected TCP port
where a manager instance is running: e.g., ``http(s)://<$IP>:<$PORT>/``.
-You should then be greeted by the dashboard login page, requesting your
-previously defined username and password.
+The dashboard page displays and requests a previously defined username and
+password.
.. _dashboard-enabling-object-gateway:
To use the Object Gateway management functionality of the dashboard, you will
need to provide the login credentials of a user with the ``system`` flag
-enabled.
-
-If you do not have a user which shall be used for providing those credentials,
-you will also need to create one::
+enabled. If you do not have a ``system`` user already, you must create one::
$ radosgw-admin user create --uid=<user_id> --display-name=<display_name> \
--system
-Take note of the keys ``access_key`` and ``secret_key`` in the output of this
-command.
+Take note of the keys ``access_key`` and ``secret_key`` in the output.
-The credentials of an existing user can also be obtained by using
-`radosgw-admin`::
+To obtain the credentials of an existing user via `radosgw-admin`::
$ radosgw-admin user info --uid=<user_id>
$ ceph dashboard set-rgw-api-access-key <access_key>
$ ceph dashboard set-rgw-api-secret-key <secret_key>
-In a typical default configuration with a single RGW endpoint, this is all you
+In a simple configuration with a single RGW endpoint, this is all you
have to do to get the Object Gateway management functionality working. The
-dashboard will try to automatically determine the host and port of the Object
-Gateway by obtaining this information from the Ceph Manager's service map.
+dashboard will try to automatically determine the host and port
+from the Ceph Manager's service map.
If multiple zones are used, it will automatically determine the host within the
master zone group and master zone. This should be sufficient for most setups,
$ ceph dashboard set-rgw-api-admin-resource <admin_resource>
$ ceph dashboard set-rgw-api-user-id <user_id>
-If you are using a self-signed certificate in your Object Gateway setup, then
+If you are using a self-signed certificate in your Object Gateway setup,
you should disable certificate verification in the dashboard to avoid refused
connections, e.g. caused by certificates signed by unknown CA or not matching
the host name::
$ ceph dashboard set-rgw-api-ssl-verify False
If the Object Gateway takes too long to process requests and the dashboard runs
-into timeouts, then you can set the timeout value to your needs::
+into timeouts, you can set the timeout value to your needs::
$ ceph dashboard set-rest-requests-timeout <seconds>
^^^^^^^^^^^^^^^^^^^^^^^^^
The Ceph Dashboard can manage iSCSI targets using the REST API provided by the
-`rbd-target-api` service of the :ref:`ceph-iscsi`. Please make sure that it's
+``rbd-target-api`` service of the :ref:`ceph-iscsi`. Please make sure that it is
installed and enabled on the iSCSI gateways.
.. note::
The iSCSI management functionality of Ceph Dashboard depends on the latest
version 3 of the `ceph-iscsi <https://github.com/ceph/ceph-iscsi>`_ project.
Make sure that your operating system provides the correct version, otherwise
- the dashboard won't enable the management features.
+ the dashboard will not enable the management features.
-If ceph-iscsi REST API is configured in HTTPS mode and its using a self-signed
-certificate, then you need to configure the dashboard to avoid SSL certificate
+If the ``ceph-iscsi`` REST API is configured in HTTPS mode and its using a self-signed
+certificate, you need to configure the dashboard to avoid SSL certificate
verification when accessing ceph-iscsi API.
To disable API SSL verification run the following command::
Enabling the Embedding of Grafana Dashboards
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`Grafana`_ requires data from `Prometheus <https://prometheus.io/>`_. Although
+`Grafana`_ pulls data from `Prometheus <https://prometheus.io/>`_. Although
Grafana can use other data sources, the Grafana dashboards we provide contain
queries that are specific to Prometheus. Our Grafana dashboards therefore
-require Prometheus as the data source. The Ceph :ref:`mgr-prometheus` also only
-exports its data in the Prometheus' common format. The Grafana dashboards rely
-on metric names from the Prometheus module and `Node exporter
+require Prometheus as the data source. The Ceph :ref:`mgr-prometheus`
+module exports its data in the Prometheus exposition format. These Grafana
+dashboards rely on metric names from the Prometheus module and `Node exporter
<https://prometheus.io/docs/guides/node-exporter/>`_. The Node exporter is a
separate application that provides machine metrics.
""""""""""""""""""""""""""""""""""""""""""""
Grafana and Prometheus can be installed using :ref:`cephadm`. They will
-automatically be configured by `cephadm`. Please see
+automatically be configured by ``cephadm``. Please see
:ref:`mgr-cephadm-monitoring` documentation for more details on how to use
-cephadm for installing and configuring Prometheus and Grafana.
+``cephadm`` for installing and configuring Prometheus and Grafana.
Manual Installation and Configuration
"""""""""""""""""""""""""""""""""""""
The following process describes how to configure Grafana and Prometheus
-manually. After you have installed Prometheus, Grafana and the Node exporter
-on your preferred hosts, proceed with the following steps.
+manually. After you have installed Prometheus, Grafana, and the Node exporter
+on appropriate hosts, proceed with the following steps.
#. Enable the Ceph Exporter which comes as Ceph Manager module by running::
.. note::
- Please note that in the aforementioned example, Prometheus is configured
+ Please note that in the above example, Prometheus is configured
to scrape data from itself (port 9090), the Ceph manager module
- `prometheus` (port 9283), which exports Ceph internal data and the Node
- exporter (port 9100), which provides metrics of a machine.
+ `prometheus` (port 9283), which exports Ceph internal data, and the Node
+ Exporter (port 9100), which provides OS and hardware metrics for each host.
Depending on your configuration, you may need to change the hostname in
- this configuration or add additional configuration entries for the Node
- exporter. It is unlikely that you will need to change the provided ports.
+ or add additional configuration entries for the Node
+ Exporter. It is unlikely that you will need to change the default TCP ports.
Moreover, you don't *need* to have more than one target for Ceph specific
data, provided by the `prometheus` mgr module. But it is recommended to
configure Prometheus to scrape Ceph specific data from all existing Ceph
- managers. This enables a built-in high availability mechanism, where
- services run on a manager will be restarted automatically on a second
- manager instance if one Ceph Manager goes down.
+ managers. This enables a built-in high availability mechanism, so that
+ services run on a manager host will be restarted automatically on a different
+ manager host if one Ceph Manager goes down.
#. Add Prometheus as data source to Grafana `using the Grafana Web UI
<https://grafana.com/docs/grafana/latest/features/datasources/add-a-data-source/>`_.
grafana-cli plugins install vonage-status-panel
grafana-cli plugins install grafana-piechart-panel
-#. Add the Dashboards to Grafana:
+#. Add Dashboards to Grafana:
Dashboards can be added to Grafana by importing dashboard JSON files.
Use the following command to download the JSON files::
wget https://raw.githubusercontent.com/ceph/ceph/master/monitoring/grafana/dashboards/<Dashboard-name>.json
- You can find all the dashboard JSON files `here <https://github.com/ceph/ceph/tree/
+ You can find various dashboard JSON files `here <https://github.com/ceph/ceph/tree/
master/monitoring/grafana/dashboards>`_ .
For Example, for ceph-cluster overview you can use::
wget https://raw.githubusercontent.com/ceph/ceph/master/monitoring/grafana/dashboards/ceph-cluster.json
-#. Configure Grafana in ``/etc/grafana/grafana.ini`` to enable anonymous mode::
+ You may also author your own dashboards.
+
+#. Configure anonymous mode in ``/etc/grafana/grafana.ini``::
[auth.anonymous]
enabled = true
org_role = Viewer
In newer versions of Grafana (starting with 6.2.0-beta1) a new setting named
- ``allow_embedding`` has been introduced. This setting needs to be explicitly
- set to ``true`` for the Grafana integration in Ceph Dashboard to work, as its
+ ``allow_embedding`` has been introduced. This setting must be explicitly
+ set to ``true`` for the Grafana integration in Ceph Dashboard to work, as the
default is ``false``.
::
Enabling RBD-Image monitoring
"""""""""""""""""""""""""""""
-Due to performance reasons, monitoring of RBD images is disabled by default. For
-more information please see :ref:`prometheus-rbd-io-statistics`. If disabled,
-the overview and details dashboards will stay empty in Grafana and the metrics
-will not be visible in Prometheus.
+Monitoring of RBD images is disabled by default, as it can significantly impact
+performance. For more information please see :ref:`prometheus-rbd-io-statistics`.
+When disabled, the overview and details dashboards will be empty in Grafana and
+metrics will not be visible in Prometheus.
Configuring Dashboard
"""""""""""""""""""""
After you have set up Grafana and Prometheus, you will need to configure the
connection information that the Ceph Dashboard will use to access Grafana.
-You need to tell the dashboard on which url Grafana instance is running/deployed::
+Tell the dashboard the URL for the deployed Grafana instance::
$ ceph dashboard set-grafana-api-url <grafana-server-url> # default: ''
.. note::
- Ceph Dashboard embeds the Grafana dashboards via ``iframe`` HTML elements.
+ The Ceph Dashboard embeds Grafana dashboards via ``iframe`` HTML elements.
If Grafana is configured without SSL/TLS support, most browsers will block the
- embedding of insecure content into a secured web page, if the SSL support in
- the dashboard has been enabled (which is the default configuration). If you
+ embedding of insecure content if SSL support is
+ enabled for the dashboard (which is the default). If you
can't see the embedded Grafana dashboards after enabling them as outlined
above, check your browser's documentation on how to unblock mixed content.
Alternatively, consider enabling SSL/TLS support in Grafana.
-If you are using a self-signed certificate in your Grafana setup, then you should
+If you are using a self-signed certificate for Grafana,
disable certificate verification in the dashboard to avoid refused connections,
-e.g. caused by certificates signed by unknown CA or not matching the host name::
+which can be a result of certificates signed by an unknown CA or that do not
+matchn the host name::
$ ceph dashboard set-grafana-api-ssl-verify False
-You can directly access Grafana Instance as well to monitor your cluster.
+You can also access Grafana directly to monitor your cluster.
+
+.. note::
+
+ Ceph Dashboard configuration information can also be unset. For example, to
+ clear the Grafana API URL we configured above::
+
+ $ ceph dashboard reset-grafana-api-url
.. _dashboard-sso-support:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Ceph Dashboard supports external authentication of users via the
-`SAML 2.0 <https://en.wikipedia.org/wiki/SAML_2.0>`_ protocol. You need to create
-the user accounts and associate them with the desired roles first, as authorization
-is still performed by the Dashboard. However, the authentication process can be
-performed by an existing Identity Provider (IdP).
+`SAML 2.0 <https://en.wikipedia.org/wiki/SAML_2.0>`_ protocol. You need to
+first create user accounts and associate them with desired roles, as
+authorization is performed by the Dashboard. However, the authentication
+process can be performed by an existing Identity Provider (IdP).
.. note::
Enabling Prometheus Alerting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Using Prometheus for monitoring, you have to define `alerting rules
+To use Prometheus for alerting you must define `alerting rules
<https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules>`_.
-To manage them you need to use the `Alertmanager
+These are managed by the `Alertmanager
<https://prometheus.io/docs/alerting/alertmanager>`_.
-If you are not using the Alertmanager yet, please `install it
-<https://github.com/prometheus/alertmanager#install>`_ as it's mandatory in
-order to receive and manage alerts from Prometheus.
+If you are not yet using the Alertmanager, `install it
+<https://github.com/prometheus/alertmanager#install>`_ as it receives
+and manages alerts from Prometheus.
-The Alertmanager capabilities can be consumed by the dashboard in three different
+Alertmanager capabilities can be consumed by the dashboard in three different
ways:
#. Use the notification receiver of the dashboard.
#. Use both sources simultaneously.
-All three methods are going to notify you about alerts. You won't be notified
+All three methods notify you about alerts. You won't be notified
twice if you use both sources, but you need to consume at least the Alertmanager API
in order to manage silences.
- url: '<url-to-dashboard>/api/prometheus_receiver'
- Please make sure that the Alertmanager considers your SSL certificate in terms
+ Ensure that the Alertmanager considers your SSL certificate in terms
of the dashboard as valid. For more information about the correct
configuration checkout the `<http_config> documentation
<https://prometheus.io/docs/alerting/configuration/#%3Chttp_config%3E>`_.
2. Use the API of Prometheus and the Alertmanager
- This allows you to manage alerts and silences. This will enable the "Active
+ This allows you to manage alerts and silences and will enable the "Active
Alerts", "All Alerts" as well as the "Silences" tabs in the "Monitoring"
section of the "Cluster" menu entry.
$ ceph dashboard set-prometheus-api-host 'http://localhost:9090'
- After setting up the hosts, you have to refresh the dashboard in your browser window.
+ After setting up the hosts, refresh your browser's dashboard window or tab.
3. Use both methods
- The different behaviors of both methods are configured in a way that they
- should not disturb each other through annoying duplicated notifications
- popping up.
+ The behaviors of both methods are configured in a way that they
+ should not disturb each other, through annoying duplicated notifications
+ may pop up.
If you are using a self-signed certificate in your Prometheus or your
Alertmanager setup, you should disable certificate verification in the
-dashboard to avoid refused connections, e.g. caused by certificates signed by
-unknown CA or not matching the host name.
+dashboard to avoid refused connections caused by certificates signed by
+an unknown CA or that do not match the host name.
- For Prometheus::
Password Policy
^^^^^^^^^^^^^^^
-By default the password policy feature is enabled including the following
-checks:
+By default the password policy feature is enabled, which includes the
+following checks:
- Is the password longer than N characters?
- Are the old and new password the same?
$ ceph dashboard set-pwd-policy-enabled <true|false>
-The following individual checks can be switched on or off::
+The following individual checks can also be switched on or off::
$ ceph dashboard set-pwd-policy-check-length-enabled <true|false>
$ ceph dashboard set-pwd-policy-check-oldpwd-enabled <true|false>
$ ceph dashboard set-pwd-policy-check-sequential-chars-enabled <true|false>
$ ceph dashboard set-pwd-policy-check-repetitive-chars-enabled <true|false>
-Additionally the following options are available to configure the password
-policy behaviour.
+Additionally the following options are available to configure password
+policy.
-- The minimum password length (defaults to 8)::
+- Minimum password length (defaults to 8)::
$ ceph dashboard set-pwd-policy-min-length <N>
-- The minimum password complexity (defaults to 10)::
+- Minimum password complexity (defaults to 10)::
$ ceph dashboard set-pwd-policy-min-complexity <N>
- The password complexity is calculated by classifying each character in
+ Password complexity is calculated by classifying each character in
the password. The complexity count starts by 0. A character is rated by
the following rules in the given order.
User Accounts
^^^^^^^^^^^^^
-Ceph Dashboard supports managing multiple user accounts. Each user account
+The Ceph Dashboard supports 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.
-If a new user is created via Web UI, it is possible to set an option that this
+If a new user is created via the Web UI, it is possible to set an option that the
user must assign a new password when they log in for the first time.
-User accounts are stored in MON's configuration database, and are globally
-shared across all ceph-mgr instances.
+User accounts are stored in the monitors' configuration database, and are
+available to all ``ceph-mgr`` instances.
We provide a set of CLI commands to manage user accounts:
$ ceph dashboard ac-user-create [--enabled] [--force-password] [--pwd_update_required] <username> [<password>] [<rolename>] [<name>] [<email>] [<pwd_expiration_date>]
- To bypass the password policy checks use the `force-password` option.
- Use the option `pwd_update_required` so that a newly created user has
+ To bypass password policy checks use the `force-password` option.
+ Add the option `pwd_update_required` so that a newly created user has
to change their password after the first login.
- *Delete User*::
User Roles and Permissions
^^^^^^^^^^^^^^^^^^^^^^^^^^
-User accounts are also associated with a set of roles that define which
-dashboard functionality can be accessed by the user.
+User accounts are associated with a set of roles that define which
+dashboard functionality can be accessed.
The Dashboard functionality/modules are grouped within a *security scope*.
Security scopes are predefined and static. The current available security
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.
+- **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
+- **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.
+- **rgw**: includes all features related to RADOS Gateway (RGW) management.
- **cephfs**: includes all features related to CephFS management.
- **manager**: include all features related to Ceph Manager
management.
- **update**
- **delete**
-See below for an example of a role specification based on a Python dictionary::
+See below for an example of a role specification, in the form of a Python dictionary::
# example of a role
{
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
+The Dashboard provides a set of predefined roles that we call
+*system roles*, which can be used right away by 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 except
- the dashboard settings.
-- **block-manager**: provides full permissions for *rbd-image*,
+- **administrator**: allows full permissions for all security scopes.
+- **read-only**: allows *read* permission for all security scopes except
+ dashboard settings.
+- **block-manager**: allows 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*,
+- **rgw-manager**: allows full permissions for the *rgw* scope
+- **cluster-manager**: allows 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.
+- **pool-manager**: allows full permissions for the *pool* scope.
+- **cephfs-manager**: allows full permissions for the *cephfs* scope.
-The list of currently available roles can be retrieved by the following
-command::
+The list of available roles can be retrieved with the following command::
$ ceph dashboard ac-role-show [<rolename>]
-It is also possible to create new roles using CLI commands. The available
-commands to manage roles are the following:
+You can also use the CLI to create new roles. The available commands are the
+following:
- *Create Role*::
$ ceph dashboard ac-role-del-scope-perms <rolename> <scopename>
-To associate roles to users, the following CLI commands are available:
+To assign roles to users, the following commands are available:
- *Set User 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.
+In this section we show a complete example of the commands that
+create a user account that can manage RBD images, view and create Ceph pools,
+and has read-only access to other scopes.
1. *Create the user*::
Proxy Configuration
-------------------
-In a Ceph cluster with multiple ceph-mgr instances, only the dashboard running
-on the currently active ceph-mgr daemon will serve incoming requests. Accessing
-the dashboard's TCP port on any of the other ceph-mgr instances that are
-currently on standby will perform a HTTP redirect (303) to the currently active
-manager's dashboard URL. This way, you can point your browser to any of the
-ceph-mgr instances in order to access the dashboard.
+In a Ceph cluster with multiple ``ceph-mgr`` instances, only the dashboard
+running on the currently active ``ceph-mgr`` daemon will serve incoming requests.
+Connections to the dashboard's TCP port on standby ``ceph-mgr`` instances
+will receive an HTTP redirect (303) to the active manager's dashboard URL.
+This enables you to point your browser to any ``ceph-mgr`` instance in
+order to access the dashboard.
If you want to establish a fixed URL to reach the dashboard or if you don't want
to allow direct connections to the manager nodes, you could set up a proxy that
-automatically forwards incoming requests to the currently active ceph-mgr
+automatically forwards incoming requests to the active ``ceph-mgr``
instance.
Configuring a URL Prefix
^^^^^^^^^^^^^^^^^^^^^^^^
-If you are accessing the dashboard via a reverse proxy configuration,
+If you are accessing the dashboard via a reverse proxy,
you may wish to service it under a URL prefix. To get the dashboard
to use hyperlinks that include your prefix, you can set the
``url_prefix`` setting:
^^^^^^^^^^^^^^^^^^^^^^^
If the dashboard is behind a load-balancing proxy like `HAProxy <https://www.haproxy.org/>`_
-you might want to disable the redirection behaviour to prevent situations that
-internal (unresolvable) URL's are published to the frontend client. Use the
-following command to get the dashboard to respond with a HTTP error (500 by default)
+you might want to disable redirection to prevent situations in which
+internal (unresolvable) URLs are published to the frontend client. Use the
+following command to get the dashboard to respond with an HTTP error (500 by default)
instead of redirecting to the active dashboard::
$ ceph config set mgr mgr/dashboard/standby_behaviour "error"
-To reset the setting to the default redirection behaviour, use the following command::
+To reset the setting to default redirection, use the following command::
$ ceph config set mgr mgr/dashboard/standby_behaviour "redirect"
Configure the error status code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When the redirection behaviour is disabled, then you want to customize the HTTP status
+When redirection is disabled, you may want to customize the HTTP status
code of standby dashboards. To do so you need to run the command::
$ ceph config set mgr mgr/dashboard/standby_error_status_code 503
HAProxy example configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Below you will find an example configuration for SSL/TLS pass through using
+Below you will find an example configuration for SSL/TLS passthrough using
`HAProxy <https://www.haproxy.org/>`_.
-Please note that the configuration works under the following conditions.
+Please note that this configuration works under the following conditions.
If the dashboard fails over, the front-end client might receive a HTTP redirect
(303) response and will be redirected to an unresolvable host. This happens when
-the failover occurs during two HAProxy health checks. In this situation the
+failover occurs between two HAProxy health checks. In this situation the
previously active dashboard node will now respond with a 303 which points to
-the new active node. To prevent that situation you should consider to disable
-the redirection behaviour on standby nodes.
+the new active node. To prevent that situation you should consider disabling
+redirection on standby nodes.
::
Auditing API Requests
---------------------
-The REST API is capable of logging PUT, POST and DELETE requests to the Ceph
+The REST API can log PUT, POST and DELETE requests to the Ceph
audit log. This feature is disabled by default, but can be enabled with the
following command::
NFS-Ganesha Management
----------------------
-Ceph Dashboard can manage `NFS Ganesha <http://nfs-ganesha.github.io/>`_ exports that use
-CephFS or RadosGW as their backstore.
+The Ceph Dashboard can manage `NFS Ganesha <http://nfs-ganesha.github.io/>`_ exports that use
+CephFS or RGW as their backstore.
To enable this feature in Ceph Dashboard there are some assumptions that need
to be met regarding the way NFS-Ganesha services are configured.
The dashboard manages NFS-Ganesha config files stored in RADOS objects on the Ceph Cluster.
NFS-Ganesha must store part of their configuration in the Ceph cluster.
-These configuration files must follow some conventions.
+These configuration files follow the below conventions.
Each export block must be stored in its own RADOS object named
``export-<id>``, where ``<id>`` must match the ``Export_ID`` attribute of the
export configuration. Then, for each NFS-Ganesha service daemon there should
Configuring NFS-Ganesha in the Dashboard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To enable the management of NFS-Ganesha exports in Ceph Dashboard, we only
-need to tell the Dashboard, in which RADOS pool and namespace the
-configuration objects are stored. Then, Ceph Dashboard can access the objects
+To enable management of NFS-Ganesha exports in the Ceph Dashboard, we
+need to tell the Dashboard the RADOS pool and namespace in which
+configuration objects are stored. The Ceph Dashboard can then access them
by following the naming convention described above.
The Dashboard command to configure the NFS-Ganesha configuration objects
$ ceph dashboard set-ganesha-clusters-rados-pool-namespace <pool_name>[/<namespace>]
-After running the above command, Ceph Dashboard is able to find the NFS-Ganesha
-configuration objects and we can start manage the exports through the Web UI.
+After running the above command, the Ceph Dashboard is able to find the NFS-Ganesha
+configuration objects and we can manage exports through the Web UI.
.. note::
- A separate pool for the NFS shares should be used. Otherwise it can cause the
+ A dedicated pool for the NFS shares should be used. Otherwise it can cause the
`known issue <https://tracker.ceph.com/issues/46176>`_ with listing of shares
if the NFS objects are stored together with a lot of other objects in a single
pool.
Support for Multiple NFS-Ganesha Clusters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Ceph Dashboard also supports the management of NFS-Ganesha exports belonging
-to different NFS-Ganesha clusters. An NFS-Ganesha cluster is a group of
-NFS-Ganesha service daemons sharing the same exports. Different NFS-Ganesha
-clusters are independent and don't share the exports configuration between each
+The Ceph Dashboard also supports management of NFS-Ganesha exports belonging
+to other NFS-Ganesha clusters. An NFS-Ganesha cluster is a group of
+NFS-Ganesha service daemons sharing the same exports. NFS-Ganesha
+clusters are independent and don't share the exports configuration among each
other.
Each NFS-Ganesha cluster should store its configuration objects in a
-different RADOS pool/namespace to isolate the configuration from each other.
+unique RADOS pool/namespace to isolate the configuration.
-To specify the locations of the configuration of each NFS-Ganesha cluster we
+To specify the the configuration location of each NFS-Ganesha cluster we
can use the same command as above but with a different value pattern::
$ ceph dashboard set-ganesha-clusters-rados-pool-namespace <cluster_id>:<pool_name>[/<namespace>](,<cluster_id>:<pool_name>[/<namespace>])*
NFS-Ganesha cluster.
When configuring the Ceph Dashboard with multiple NFS-Ganesha clusters, the
-Web UI will automatically allow to choose to which cluster an export belongs.
+Web UI will allow you to choose to which cluster an export belongs.
Support for NFS-Ganesha Clusters Deployed by the Orchestrator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Ceph Dashboard can be used to manage NFS-Ganesha clusters deployed by the
-Orchestrator. It can detect the clusters automatically. For more details
+The Ceph Dashboard can be used to manage NFS-Ganesha clusters deployed by the
+Orchestrator and will detect them automatically. For more details
on deploying NFS-Ganesha clusters with the Orchestrator, please see :ref:`orchestrator-cli-stateless-services`.
Or particularly, see :ref:`deploy-cephadm-nfs-ganesha` for how to deploy
NFS-Ganesha clusters with the Cephadm backend.
Plug-ins
--------
-Dashboard Plug-ins extend the functionality of the dashboard in a modular
+Plug-ins extend the functionality of the Ceph Dashboard in a modular
and loosely coupled fashion.
.. _Grafana: https://grafana.com/
.. note::
- Many Ceph command line tools return results in JSON format. You may have to install
- the `jq <https://stedolan.github.io/jq>`_ command-line JSON processor utility on
- your operating system beforehand.
+ Many Ceph tools return results in JSON format. We suggest that
+ you install the `jq <https://stedolan.github.io/jq>`_ command-line
+ utility to faciliate working with JSON data.
Accessing the Dashboard
^^^^^^^^^^^^^^^^^^^^^^^
-If you are unable to access the Ceph Dashboard, run through the following
+If you are unable to access the Ceph Dashboard, run the following
commands:
#. Verify the Ceph Dashboard module is enabled::
$ ceph mgr module enable dashboard
-#. Check the Ceph Dashboard and/or mgr log file for any errors. The exact
- location of the log files depends on the Ceph configuration.
+#. Check the Ceph Dashboard and/or ``ceph-mgr`` log files for any errors.
- * Check if mgr log messages are written to a file by::
+ * Check if ``ceph-mgr`` log messages are written to a file by::
$ ceph config get mgr log_to_file
true
$ ceph config-key get mgr/dashboard/key
- * If it doesn't, run the following command to generate a self-signed
+ * If it doesn't return ``true``, run the following command to generate a self-signed
certificate or follow the instructions outlined in
:ref:`dashboard-ssl-tls-support`::
#. Check that your user credentials are correct. If you are seeing the
notification message above when trying to log into the Ceph Dashboard, it
is likely you are using the wrong credentials. Double check your username
- and password, and ensure the caps lock key is not enabled by accident.
+ and password, and ensure that your keyboard's caps lock is not enabled by accident.
#. If your user credentials are correct, but you are experiencing the same
error, check that the user account exists::
When an error occurs on the backend, you will usually receive an error
notification on the frontend. Run through the following scenarios to debug.
-#. Check the Ceph Dashboard/mgr logfile(s) for any errors. These can be
- identified by searching for keywords, such as *500 Internal Server Error*,
+#. Check the Ceph Dashboard and ``ceph-mgr`` logfile(s) for any errors. These can
+ found by searching for keywords, such as *500 Internal Server Error*,
followed by ``traceback``. The end of a traceback contains more details about
what exact error occurred.
#. Check your web browser's Javascript Console for any errors.
Dashboard Debug Flag
""""""""""""""""""""
-With this flag enabled, traceback of errors are included in backend responses.
+With this flag enabled, error traceback is included in backend responses.
To enable this flag via the Ceph Dashboard, navigate from *Cluster* to *Manager
modules*. Select *Dashboard module* and click the edit button. Click the
* To adjust it via the CLI, run the following command::
$ bin/ceph config set mgr mgr/dashboard/log_level debug
+
+#. High log levels can result in considerable log volume, which can
+easily fill up your filesystem. Set a calendar reminder for an hour, a day,
+or a week in the future to revert this temporary logging increase. This looks
+something like this::
+
+ $ ceph config log
+ ...
+ --- 11 --- 2020-11-07 11:11:11.960659 --- mgr.x/dashboard/log_level = debug ---
+ ...
+ $ ceph config reset 11
+
projects / ceph.git / commitdiff