Adding upstream version 14.2.21.upstream/14.2.21upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1030 insertions, 0 deletions

diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst
new file mode 100644
index 00000000..f92bd19d
--- /dev/null
+++ b/doc/mgr/dashboard.rst
@@ -0,0 +1,1030 @@
+.. _mgr-dashboard:
+
+Ceph Dashboard
+==============
+
+Overview
+--------
+
+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.
+
+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
+management capabilities, to make it easier to administer Ceph for users that
+prefer a WebUI over using the command line.
+
+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 plugin is 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
+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``.
+
+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.
+  See :ref:`dashboard-user-role-management` for details.
+* **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`
+  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.
+
+Currently, Ceph Dashboard is capable of monitoring and managing the following
+aspects of your Ceph cluster:
+
+* **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
+  :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
+  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**: Enables creation, re-creation, editing and expiration of
+  Prometheus' Silences, lists the alerting configuration of Prometheus and
+  currently firing alerts. Also shows notifications for firing alerts. Needs
+  configuration.
+* **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,
+  placement groups, replication size, EC profile, CRUSH ruleset, etc.)
+* **OSDs**: List all 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.
+* **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``). See
+  :ref:`dashboard-iscsi-management` for instructions on how to configure this
+  feature.
+* **RBD**: List all RBD images and their properties (size, objects, features).
+  Create, copy, modify and delete RBD images. Define various I/O or bandwidth
+  limitation settings on a global, per-pool or per-image level. Create, delete
+  and rollback snapshots of selected 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 filesystem clients and associated pools,
+  including their usage statistics.
+* **Object Gateway**: List all active object gateways and their performance
+  counters. Display and manage (add/edit/delete) object gateway users and their
+  details (e.g. quotas) as well as the users' buckets and their details (e.g.
+  owner, quotas). See :ref:`dashboard-enabling-object-gateway` for configuration
+  instructions.
+* **NFS**: Manage NFS exports of CephFS filesystems 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.
+
+
+Supported Browsers
+^^^^^^^^^^^^^^^^^^
+
+Ceph Dashboard is primarily tested and developed using the following web
+browsers:
+
++----------------------------------------------+----------+
+|                    Browser                   | Versions |
++==============================================+==========+
+| `Chrome <https://www.google.com/chrome/>`_   | 68+      |
++----------------------------------------------+----------+
+| `Firefox <http://www.mozilla.org/firefox/>`_ | 61+      |
++----------------------------------------------+----------+
+
+While Ceph Dashboard might work in older browsers, we cannot guarantee it and
+recommend you to update your browser to the latest version.
+
+Enabling
+--------
+
+If you have installed ``ceph-mgr-dashboard`` from distribution packages, the
+package management system should have taken care of installing all the required
+dependencies.
+
+If you're installing 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.
+
+Within a running Ceph cluster, the Ceph Dashboard is enabled with::
+
+  $ ceph mgr module enable dashboard
+
+Configuration
+-------------
+
+.. _dashboard-ssl-tls-support:
+
+SSL/TLS Support
+^^^^^^^^^^^^^^^
+
+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::
+
+  $ ceph dashboard create-self-signed-cert
+
+Note that most web browsers will complain about such 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
+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::
+
+  $ openssl req -new -nodes -x509 \
+    -subj "/O=IT/CN=ceph-mgr-dashboard" -days 3650 \
+    -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::
+
+  $ 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,
+the name of the instance can be included as follows (where ``$name`` is the name
+of the ``ceph-mgr`` instance, usually the hostname)::
+
+  $ ceph dashboard set-ssl-certificate $name -i dashboard.crt
+  $ ceph dashboard set-ssl-certificate-key $name -i dashboard.key
+
+SSL can also be disabled by setting this configuration value::
+
+  $ ceph config set mgr mgr/dashboard/ssl false
+
+This might be useful if the dashboard will be running behind a proxy which does
+not support SSL for its upstream servers or other situations where SSL is not
+wanted or required.
+
+.. warning::
+
+  Use caution when disabling SSL as usernames and passwords will be sent to the
+  dashboard unencrypted.
+
+
+.. note::
+
+  You need to restart the Ceph manager processes manually 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)::
+
+    $ ceph mgr module disable dashboard
+    $ ceph mgr module enable dashboard
+
+Host Name and Port
+^^^^^^^^^^^^^^^^^^
+
+Like most web applications, 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.
+
+If no specific address has been configured, the web app will bind to ``::``,
+which corresponds to all available IPv4 and IPv6 addresses.
+
+These defaults can be changed via the configuration key facility on a
+cluster-wide level (so they apply to all manager instances) as follows::
+
+  $ ceph config set mgr mgr/dashboard/server_addr $IP
+  $ 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
+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_addr $IP
+  $ 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.
+
+.. note::
+
+  The command ``ceph mgr services`` will show you all endpoints that are
+  currently configured. Look for the ``dashboard`` key to obtain the URL for
+  accessing the dashboard.
+
+Username and Password
+^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+To create a user with the administrator role you can use the following
+commands::
+
+  $ ceph dashboard ac-user-create <username> -i <file-containing-password> administrator
+
+.. _dashboard-enabling-object-gateway:
+
+Enabling the Object Gateway Management Frontend
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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::
+
+  $ 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.
+
+The credentials of an existing user can also be obtained by using
+`radosgw-admin`::
+
+  $ radosgw-admin user info --uid=<user_id>
+
+Finally, provide the credentials to the dashboard::
+
+  $ ceph dashboard set-rgw-api-access-key -i <file-containing-access-key>
+  $ ceph dashboard set-rgw-api-secret-key -i <file-containing-secret-key>
+
+In a typical default 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.
+
+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,
+but in some circumstances you might want to set the host and port manually::
+
+  $ ceph dashboard set-rgw-api-host <host>
+  $ ceph dashboard set-rgw-api-port <port>
+
+In addition to the settings mentioned so far, the following settings do also
+exist and you may find yourself in the situation that you have to use them::
+
+  $ ceph dashboard set-rgw-api-scheme <scheme>  # http or https
+  $ 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
+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::
+
+  $ ceph dashboard set-rest-requests-timeout <seconds>
+
+The default value is 45 seconds.
+
+.. _dashboard-iscsi-management:
+
+Enabling iSCSI Management
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+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.
+
+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
+verification when accessing ceph-iscsi API.
+
+To disable API SSL verification run the following commmand::
+
+    $ ceph dashboard set-iscsi-api-ssl-verification false
+
+The available iSCSI gateways must be defined using the following commands::
+
+  $ ceph dashboard iscsi-gateway-list
+  $ # Gateway URL format for a new gateway: <scheme>://<username>:<password>@<host>[:port]
+  $ ceph dashboard iscsi-gateway-add -i <file-containing-gateway-url> [<gateway_name>]
+  $ ceph dashboard iscsi-gateway-rm <gateway_name>
+
+
+.. _dashboard-grafana:
+
+Enabling the Embedding of Grafana Dashboards
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Grafana`_ requires 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
+<https://prometheus.io/docs/guides/node-exporter/>`_. The Node exporter is a
+separate application that provides machine metrics.
+
+.. note::
+
+  Prometheus' security model presumes that untrusted users have access to the
+  Prometheus HTTP endpoint and logs. Untrusted users have access to all the
+  (meta)data Prometheus collects that is contained in the database, plus a
+  variety of operational and debugging information.
+
+  However, Prometheus' HTTP API is limited to read-only operations.
+  Configurations can *not* be changed using the API and secrets are not
+  exposed. Moreover, Prometheus has some built-in measures to mitigate the
+  impact of denial of service attacks.
+
+  Please see `Prometheus' Security model
+  <https://prometheus.io/docs/operating/security/>` for more detailed
+  information.
+
+Grafana and Prometheus are likely going to be bundled and installed by some
+orchestration tools along Ceph in the near future, but currently, you will have
+to install and configure both manually. After you have installed Prometheus and
+Grafana on your preferred hosts, proceed with the following steps.
+
+#. Enable the Ceph Exporter which comes as Ceph Manager module by running::
+
+    $ ceph mgr module enable prometheus
+
+More details can be found in the documentation of the :ref:`mgr-prometheus`.
+
+#. Add the corresponding scrape configuration to Prometheus. This may look
+   like::
+
+        global:
+          scrape_interval: 5s
+
+        scrape_configs:
+          - job_name: 'prometheus'
+            static_configs:
+              - targets: ['localhost:9090']
+          - job_name: 'ceph'
+            static_configs:
+              - targets: ['localhost:9283']
+          - job_name: 'node-exporter'
+            static_configs:
+              - targets: ['localhost:9100']
+
+#. Add Prometheus as data source to Grafana
+
+#. Install the `vonage-status-panel and grafana-piechart-panel` plugins using::
+
+        grafana-cli plugins install vonage-status-panel
+        grafana-cli plugins install grafana-piechart-panel
+
+#. Add the Dashboards to Grafana:
+
+   Dashboards can be added to Grafana by importing dashboard jsons.
+   Following command can be used for downloading json files::
+
+	wget https://raw.githubusercontent.com/ceph/ceph/master/monitoring/grafana/dashboards/<Dashboard-name>.json
+
+   You can find all the dashboard jsons `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 adapt anonymous mode::
+
+        [auth.anonymous]
+        enabled = true
+        org_name = Main Org.
+        org_role = Viewer
+
+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 the Grafana instance is
+running/deployed::
+
+  $ ceph dashboard set-grafana-api-url <grafana-server-url>  # default: ''
+
+The format of url is : `<protocol>:<IP-address>:<port>`
+
+.. note::
+  Ceph Dashboard embeds the 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
+  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
+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-grafana-api-ssl-verify False
+
+You can directly access Grafana Instance as well to monitor your cluster.
+
+Alternative URL for Browsers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Ceph Dashboard backend requires the Grafana URL to be able to verify the
+existence of Grafana Dashboards before the frontend even loads them. Due to the
+nature of how Grafana is implemented in Ceph Dashboard, this means that two
+working connections are required in order to be able to see Grafana graphs in
+Ceph Dashboard:
+
+- The backend (Ceph Mgr module) needs to verify the existence of the requested
+  graph. If this request succeeds, it lets the frontend know that it can safely
+  access Grafana.
+- The frontend then requests the Grafana graphs directly from the user's
+  browser using an iframe. The Grafana instance is accessed directly without any
+  detour through Ceph Dashboard.
+
+Now, it might be the case that your environment makes it difficult for the
+user's browser to directly access the URL configured in Ceph Dashboard. To solve
+this issue, a separate URL can be configured which will solely be used to tell
+the frontend (the user's browser) which URL it should use to access Grafana.
+
+To change the URL that is returned to the frontend issue the following command::
+
+  $ ceph dashboard set-grafana-frontend-api-url <grafana-server-url>
+
+If no value is set for that option, it will simply fall back to the value of the
+GRAFANA_API_URL option. If set, it will instruct the browser to use this URL to
+access Grafana.
+
+.. _dashboard-sso-support:
+
+Enabling Single Sign-On (SSO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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).
+
+.. note::
+  Ceph Dashboard SSO support relies on onelogin's
+  `python-saml <https://pypi.org/project/python-saml/>`_ library.
+  Please ensure that this library is installed on your system, either by using
+  your distribution's package management or via Python's `pip` installer.
+
+To configure SSO on Ceph Dashboard, you should use the following command::
+
+  $ ceph dashboard sso setup saml2 <ceph_dashboard_base_url> <idp_metadata> {<idp_username_attribute>} {<idp_entity_id>} {<sp_x_509_cert>} {<sp_private_key>}
+
+Parameters:
+
+* **<ceph_dashboard_base_url>**: Base URL where Ceph Dashboard is accessible (e.g., `https://cephdashboard.local`)
+* **<idp_metadata>**: URL, file path or content of the IdP metadata XML (e.g., `https://myidp/metadata`)
+* **<idp_username_attribute>** *(optional)*: Attribute that should be used to get the username from the authentication response. Defaults to `uid`.
+* **<idp_entity_id>** *(optional)*: Use this when more than one entity id exists on the IdP metadata.
+* **<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.
+
+.. note::
+  The issuer value of SAML requests will follow this pattern:  **<ceph_dashboard_base_url>**/auth/saml2/metadata
+
+To display the current SAML 2.0 configuration, use the following command::
+
+  $ ceph dashboard sso show saml2
+
+.. note::
+  For more information about `onelogin_settings`, please check the `onelogin documentation <https://github.com/onelogin/python-saml>`_.
+
+To disable SSO::
+
+  $ ceph dashboard sso disable
+
+To check if SSO is enabled::
+
+  $ ceph dashboard sso status
+
+To enable SSO::
+
+  $ ceph dashboard sso enable saml2
+
+Enabling Prometheus Alerting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using Prometheus for monitoring, you have to define `alerting rules
+<https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules>`_.
+To manage them you need to use 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.
+
+The Alertmanager capabilities can be consumed by the dashboard in three different
+ways:
+
+#. Use the notification receiver of the dashboard.
+
+#. Use the Prometheus Alertmanager API.
+
+#. Use both sources simultaneously.
+
+All three methods are going to 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.
+
+#. Use the notification receiver of the dashboard:
+
+   This allows you to get notifications as `configured
+   <https://prometheus.io/docs/alerting/configuration/>`_ from the Alertmanager.
+   You will get notified inside the dashboard once a notification is send out,
+   but you are not able to manage alerts.
+
+   Add the dashboard receiver and the new route to your Alertmanager configuration.
+   This should look like::
+
+     route:
+       receiver: 'ceph-dashboard'
+     ...
+     receivers:
+       - name: 'ceph-dashboard'
+         webhook_configs:
+         - url: '<url-to-dashboard>/api/prometheus_receiver'
+
+
+   Please make sure 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>`_.
+
+#. Use the API of Prometheus and the Alertmanager
+
+   This allows you to manage alerts and silences. This will enable the "Active
+   Alerts", "All Alerts" as well as the "Silences" tabs in the "Monitoring"
+   section of the "Cluster" menu entry.
+
+   Alerts can be sorted by name, job, severity, state and start time.
+   Unfortunately it's not possible to know when an alert
+   was sent out through a notification by the Alertmanager based on your
+   configuration, that's why the dashboard will notify the user on any visible
+   change to an alert and will notify the changed alert.
+
+   Silences can be sorted by id, creator, status, start, updated and end time.
+   Silences can be created in various ways, it's also possible to expire them.
+
+   #. Create from scratch
+
+   #. Based on a selected alert
+
+   #. Recreate from expired silence
+
+   #. Update a silence (which will recreate and expire it (default Alertmanager behaviour))
+
+   To use it, specify the host and port of the Alertmanager server::
+
+     $ ceph dashboard set-alertmanager-api-host <alertmanager-host:port>  # default: ''
+
+   For example::
+
+     $ ceph dashboard set-alertmanager-api-host 'http://localhost:9093'
+
+   To be able to see all configured alerts, you will need to configure the URL
+   to the Prometheus API. Using this API, the UI will also help you in verifying
+   that a new silence will match a corresponding alert.
+
+   ::
+
+     $ ceph dashboard set-prometheus-api-host <prometheus-host:port>  # default: ''
+
+   For example::
+
+     $ ceph dashboard set-prometheus-api-host 'http://localhost:9090'
+
+   After setting up the hosts, you have to refresh the dashboard in your browser window.
+
+#. 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.
+
+Accessing the Dashboard
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You can now access the dashboard using your (JavaScript-enabled) web browser, by
+pointing it to any of the host names or IP addresses and the selected TCP port
+where a manager instance is running: e.g., ``httpS://<$IP>:<$PORT>/``.
+
+You should then be greeted by the dashboard login page, requesting your
+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.
+
+.. _dashboard-user-role-management:
+
+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 [<username>]
+
+- *Create User*::
+
+  $ ceph dashboard ac-user-create <username> -i <file-containing-password> [<rolename>] [<name>] [<email>]
+
+- *Delete User*::
+
+  $ ceph dashboard ac-user-delete <username>
+
+- *Change Password*::
+
+  $ ceph dashboard ac-user-set-password <username> -i <file-containing-password>
+
+- *Modify User (name, and email)*::
+
+  $ ceph dashboard ac-user-set-info <username> <name> <email>
+
+
+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.
+
+The Dashboard functionality/modules are grouped within a *security scope*.
+Security scopes are predefined and static. The current available 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.
+- **prometheus**: include all features related to Prometheus alert management.
+- **dashboard-settings**: allows to change dashboard settings.
+
+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 except
+  the dashboard settings.
+- **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 [<rolename>]
+
+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 <rolename> [<description>]
+
+- *Delete Role*::
+
+  $ ceph dashboard ac-role-delete <rolename>
+
+- *Add Scope Permissions to Role*::
+
+  $ ceph dashboard ac-role-add-scope-perms <rolename> <scopename> <permission> [<permission>...]
+
+- *Delete Scope Permission from Role*::
+
+  $ ceph dashboard ac-role-del-perms <rolename> <scopename>
+
+To associate roles to users, the following CLI commands are available:
+
+- *Set User Roles*::
+
+  $ ceph dashboard ac-user-set-roles <username> <rolename> [<rolename>...]
+
+- *Add Roles To User*::
+
+  $ ceph dashboard ac-user-add-roles <username> <rolename> [<rolename>...]
+
+- *Delete Roles from User*::
+
+  $ ceph dashboard ac-user-del-roles <username> <rolename> [<rolename>...]
+
+
+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 -i <file-containing-password>
+
+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
+
+
+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.
+
+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
+instance.
+
+Configuring a URL Prefix
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are accessing the dashboard via a reverse proxy configuration,
+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:
+
+::
+
+  ceph config set mgr mgr/dashboard/url_prefix $PREFIX
+
+so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``.
+
+Disable the redirection
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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)
+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::
+
+  $ 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
+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
+`HAProxy <https://www.haproxy.org/>`_.
+
+Please note that the 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
+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.
+
+::
+
+  defaults
+    log global
+    option log-health-checks
+    timeout connect 5s
+    timeout client 50s
+    timeout server 450s
+
+  frontend dashboard_front
+    mode http
+    bind *:80
+    option httplog
+    redirect scheme https code 301 if !{ ssl_fc }
+
+  frontend dashboard_front_ssl
+    mode tcp
+    bind *:443
+    option tcplog
+    default_backend dashboard_back_ssl
+
+  backend dashboard_back_ssl
+    mode tcp
+    option httpchk GET /
+    http-check expect status 200
+    server x <HOST>:<PORT> check-ssl check verify none
+    server y <HOST>:<PORT> check-ssl check verify none
+    server z <HOST>:<PORT> check-ssl check verify none
+
+.. _dashboard-auditing:
+
+Auditing API Requests
+---------------------
+
+The REST API is capable of logging PUT, POST and DELETE requests to the Ceph
+audit log. This feature is disabled by default, but can be enabled with the
+following command::
+
+  $ ceph dashboard set-audit-api-enabled <true|false>
+
+If enabled, the following parameters are logged per each request:
+
+* from - The origin of the request, e.g. https://[::1]:44410
+* path - The REST API path, e.g. /api/auth
+* method - e.g. PUT, POST or DELETE
+* user - The name of the user, otherwise 'None'
+
+The logging of the request payload (the arguments and their values) is enabled
+by default. Execute the following command to disable this behaviour::
+
+  $ ceph dashboard set-audit-api-log-payload <true|false>
+
+A log entry may look like this::
+
+  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"}'
+
+.. _dashboard-nfs-ganesha-management:
+
+NFS-Ganesha Management
+----------------------
+
+Ceph Dashboard can manage `NFS Ganesha <http://nfs-ganesha.github.io/>`_ exports that use
+CephFS or RadosGW 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.
+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
+exist a RADOS object named ``conf-<daemon_id>``, where ``<daemon_id>`` is an
+arbitrary string that should uniquely identify the daemon instance (e.g., the
+hostname where the daemon is running).
+Each ``conf-<daemon_id>`` object contains the RADOS URLs to the exports that
+the NFS-Ganesha daemon should serve. These URLs are of the form::
+
+  %url rados://<pool_name>[/<namespace>]/export-<id>
+
+Both the ``conf-<daemon_id>`` and ``export-<id>`` objects must be stored in the
+same RADOS pool/namespace.
+
+
+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
+by following the naming convention described above.
+
+The Dashboard command to configure the NFS-Ganesha configuration objects
+location is::
+
+  $ 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.
+
+
+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
+other.
+
+Each NFS-Ganesha cluster should store its configuration objects in a
+different RADOS pool/namespace to isolate the configuration from each other.
+
+To specify the locations of the configuration 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>])*
+
+The ``<cluster_id>`` is an arbitrary string that should uniquely identify the
+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.
+
+
+Plug-ins
+--------
+
+Dashboard Plug-ins allow to extend the functionality of the dashboard in a modular
+and loosely coupled approach.
+
+.. _Grafana: https://grafana.com/
+
+.. include:: dashboard_plugins/feature_toggles.inc.rst