From: Zac Dover Date: Thu, 25 Aug 2022 15:56:41 +0000 (+1000) Subject: doc/mgr: add prompt directives to dashboard.rst X-Git-Tag: v17.2.4~61^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=b41fa88fbd8946973d8a6fd418c2963df4f1a7be;p=ceph.git doc/mgr: add prompt directives to dashboard.rst This commit adds prompt directives (.. prompt:: bash $) to the commands in dashboard.rst. There are several ".. include::" directives in the dashboard.rst file, which means that part of this page is sourced from elsewhere than the dashboard.rst file. Because I have not yet added prompt directives to those files, there is an inconsistency in the rendering of this file. Most of the commands on this page have unselectable prompts (unselectable prompts are the prompts that don't get added to the buffer when you copy them to one of the clipboards). But the commands on this page that come from those ".. include::" directives do not yet have unselectable prompts. This file is over 1600 lines long. It was perhaps not optimally wise of me to have edited all of it in one fell swoop. It took many hours, and carefully checking it will probably take at least one hour. I suggest that whoever reviews this should not spend much time on it, but should instead make a quick pass over the page and make sure that it looks passable. The English syntax on this page (and throughout the Dashboard doc- umentation) will be tightened to remove ambiguity and to improve readability in the near future, so hold all English-language-related comments for a future pull request. Signed-off-by: Zac Dover (cherry picked from commit d8064b46815e5e5c3c173f81d72b21c0a8949db7) --- diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index 14e3b6850481..3f3e92520e87 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -215,9 +215,11 @@ 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 the source directory ``src/pybind/mgr/dashboard``. -Within a running Ceph cluster, the Ceph Dashboard is enabled with:: +Within a running Ceph cluster, the Ceph Dashboard is enabled with: - $ ceph mgr module enable dashboard +.. prompt:: bash $ + + ceph mgr module enable dashboard Configuration ------------- @@ -230,9 +232,11 @@ 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:: +self-signed certificate: + +.. prompt:: bash $ - $ ceph dashboard create-self-signed-cert + ceph dashboard create-self-signed-cert Note that most web browsers will complain about self-signed certificates and require explicit confirmation before establishing a secure connection to the @@ -241,28 +245,36 @@ dashboard. 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:: +For example, a key pair can be generated with a command similar to: + +.. prompt:: bash $ - $ openssl req -new -nodes -x509 \ - -subj "/O=IT/CN=ceph-mgr-dashboard" -days 3650 \ - -keyout dashboard.key -out dashboard.crt -extensions v3_ca + 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 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 +.. prompt:: bash $ + + ceph dashboard set-ssl-certificate -i dashboard.crt + ceph dashboard set-ssl-certificate-key -i dashboard.key 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):: +of the ``ceph-mgr`` instance, usually the hostname): + +.. prompt:: bash $ + + ceph dashboard set-ssl-certificate $name -i dashboard.crt + ceph dashboard set-ssl-certificate-key $name -i dashboard.key - $ 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: -SSL can also be disabled by setting this configuration value:: +.. prompt:: bash $ - $ ceph config set mgr mgr/dashboard/ssl false + 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 @@ -279,10 +291,12 @@ wanted or required. See :ref:`dashboard-proxy-configuration` for more details. 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):: + triggers the manager to respawn itself): + + .. prompt:: bash $ - $ ceph mgr module disable dashboard - $ ceph mgr module enable dashboard + ceph mgr module disable dashboard + ceph mgr module enable dashboard .. _dashboard-host-name-and-port: @@ -298,19 +312,23 @@ 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:: +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 +.. prompt:: bash $ + + 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 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:: +manager instance can be changed with the following commands: + +.. prompt:: bash $ - $ 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 + 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. @@ -329,9 +347,11 @@ 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:: +commands: - $ ceph dashboard ac-user-create -i administrator +.. prompt:: bash $ + + ceph dashboard ac-user-create -i administrator Account Lock-out ^^^^^^^^^^^^^^^^ @@ -339,27 +359,33 @@ Account Lock-out It disables a user account if a user repeatedly enters the wrong credentials for multiple times. It is enabled by default to prevent brute-force or dictionary attacks. The user can get or set the default number of lock-out attempts using -these commands respectively:: +these commands respectively: + +.. prompt:: bash $ - $ ceph dashboard get-account-lockout-attempts - $ ceph dashboard set-account-lockout-attempts + ceph dashboard get-account-lockout-attempts + ceph dashboard set-account-lockout-attempts .. warning:: This feature can be disabled by setting the default number of lock-out attempts to 0. However, by disabling this feature, the account is more vulnerable to brute-force or - dictionary based attacks. This can be disabled by:: + dictionary based attacks. This can be disabled by: + + .. prompt:: bash $ - $ ceph dashboard set-account-lockout-attempts 0 + ceph dashboard set-account-lockout-attempts 0 Enable a Locked User ^^^^^^^^^^^^^^^^^^^^ If a user account is disabled as a result of multiple invalid login attempts, then it needs to be manually enabled by the administrator. This can be done by the following -command:: +command: - $ ceph dashboard ac-user-enable +.. prompt:: bash $ + + ceph dashboard ac-user-enable Accessing the Dashboard ^^^^^^^^^^^^^^^^^^^^^^^ @@ -378,28 +404,36 @@ Enabling the Object Gateway Management Frontend When RGW is deployed with cephadm, the RGW credentials used by the dashboard will be automatically configured. You can also manually force the -credentials to be set up with:: +credentials to be set up with: + +.. prompt:: bash $ - $ ceph dashboard set-rgw-credentials + ceph dashboard set-rgw-credentials This will create an RGW user with uid ``dashboard`` for each realm in the system. -If you've configured a custom 'admin' resource in your RGW admin API, you should set it here also:: +If you've configured a custom 'admin' resource in your RGW admin API, you should set it here also: + +.. prompt:: bash $ - $ ceph dashboard set-rgw-api-admin-resource + ceph dashboard set-rgw-api-admin-resource 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:: +the host name: - $ ceph dashboard set-rgw-api-ssl-verify False +.. prompt:: bash $ + + ceph dashboard set-rgw-api-ssl-verify False If the Object Gateway takes too long to process requests and the dashboard runs -into timeouts, you can set the timeout value to your needs:: +into timeouts, you can set the timeout value to your needs: + +.. prompt:: bash $ - $ ceph dashboard set-rest-requests-timeout + ceph dashboard set-rest-requests-timeout The default value is 45 seconds. @@ -423,16 +457,20 @@ If the ``ceph-iscsi`` REST API is configured in HTTPS mode and its using a self- 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:: +To disable API SSL verification run the following command: + +.. prompt:: bash $ - $ ceph dashboard set-iscsi-api-ssl-verification false + ceph dashboard set-iscsi-api-ssl-verification false -The available iSCSI gateways must be defined using the following commands:: +The available iSCSI gateways must be defined using the following commands: - $ ceph dashboard iscsi-gateway-list - $ # Gateway URL format for a new gateway: ://:@[:port] - $ ceph dashboard iscsi-gateway-add -i [] - $ ceph dashboard iscsi-gateway-rm +.. prompt:: bash $ + + ceph dashboard iscsi-gateway-list + # Gateway URL format for a new gateway: ://:@[:port] + ceph dashboard iscsi-gateway-add -i [] + ceph dashboard iscsi-gateway-rm .. _dashboard-grafana: @@ -480,9 +518,11 @@ The following process describes how to configure Grafana and Prometheus 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:: +#. Enable the Ceph Exporter which comes as Ceph Manager module by running: + + .. prompt:: bash $ - $ ceph mgr module enable prometheus + ceph mgr module enable prometheus More details can be found in the documentation of the :ref:`mgr-prometheus`. @@ -524,7 +564,9 @@ on appropriate hosts, proceed with the following steps. #. Add Prometheus as data source to Grafana `using the Grafana Web UI `_. -#. Install the `vonage-status-panel and grafana-piechart-panel` plugins using:: +#. Install the `vonage-status-panel and grafana-piechart-panel` plugins using: + + .. prompt:: bash $ grafana-cli plugins install vonage-status-panel grafana-cli plugins install grafana-piechart-panel @@ -532,16 +574,20 @@ on appropriate hosts, proceed with the following steps. #. Add Dashboards to Grafana: Dashboards can be added to Grafana by importing dashboard JSON files. - Use the following command to download the JSON files:: + Use the following command to download the JSON files: - wget https://raw.githubusercontent.com/ceph/ceph/main/monitoring/ceph-mixin/dashboards_out/.json + .. prompt:: bash $ + + wget https://raw.githubusercontent.com/ceph/ceph/main/monitoring/ceph-mixin/dashboards_out/.json You can find various dashboard JSON files `here `_ . + main/monitoring/ceph-mixin/dashboards_out>`_. + + For Example, for ceph-cluster overview you can use: - For Example, for ceph-cluster overview you can use:: + .. prompt:: bash $ - wget https://raw.githubusercontent.com/ceph/ceph/main/monitoring/ceph-mixin/dashboards_out/ceph-cluster.json + wget https://raw.githubusercontent.com/ceph/ceph/main/monitoring/ceph-mixin/dashboards_out/ceph-cluster.json You may also author your own dashboards. @@ -577,9 +623,11 @@ 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:: +running/deployed: + +.. prompt:: bash $ - $ ceph dashboard set-grafana-api-url # default: '' + ceph dashboard set-grafana-api-url # default: '' The format of the URL : `://:` @@ -596,18 +644,22 @@ The format of the URL : `://:` If you are using a self-signed certificate for Grafana, disable certificate verification in the dashboard to avoid refused connections, which can be a result of certificates signed by an unknown CA or that do not -match the host name:: +match the host name: - $ ceph dashboard set-grafana-api-ssl-verify False +.. prompt:: bash $ + + ceph dashboard set-grafana-api-ssl-verify False 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:: + clear the Grafana API URL we configured above: + + .. prompt:: bash $ - $ ceph dashboard reset-grafana-api-url + ceph dashboard reset-grafana-api-url Alternative URL for Browsers """""""""""""""""""""""""""" @@ -633,9 +685,11 @@ This setting won't ever be changed automatically, unlike the GRAFANA_API_URL which is set by :ref:`cephadm` (only if cephadm is used to deploy monitoring services). -To change the URL that is returned to the frontend issue the following command:: +To change the URL that is returned to the frontend issue the following command: + +.. prompt:: bash $ - $ ceph dashboard set-grafana-frontend-api-url + ceph dashboard set-grafana-frontend-api-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 @@ -659,9 +713,11 @@ process can be performed by an existing Identity Provider (IdP). 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:: +To configure SSO on Ceph Dashboard, you should use the following command: - $ ceph dashboard sso setup saml2 {} {} {} {} +.. prompt:: bash $ + + ceph dashboard sso setup saml2 {} {} {} {} Parameters: @@ -675,25 +731,33 @@ Parameters: The issuer value of SAML requests will follow this pattern: ****/auth/saml2/metadata -To display the current SAML 2.0 configuration, use the following command:: +To display the current SAML 2.0 configuration, use the following command: + +.. prompt:: bash $ - $ ceph dashboard sso show saml2 + ceph dashboard sso show saml2 .. note:: For more information about `onelogin_settings`, please check the `onelogin documentation `_. -To disable SSO:: +To disable SSO: + +.. prompt:: bash $ - $ ceph dashboard sso disable + ceph dashboard sso disable -To check if SSO is enabled:: +To check if SSO is enabled: - $ ceph dashboard sso status +.. prompt:: bash $ -To enable SSO:: + ceph dashboard sso status - $ ceph dashboard sso enable saml2 +To enable SSO: + +.. prompt:: bash $ + + ceph dashboard sso enable saml2 .. _dashboard-alerting: @@ -768,25 +832,32 @@ in order to manage silences. #. Update a silence (which will recreate and expire it (default Alertmanager behaviour)) - To use it, specify the host and port of the Alertmanager server:: + To use it, specify the host and port of the Alertmanager server: + + .. prompt:: bash $ - $ ceph dashboard set-alertmanager-api-host # default: '' + ceph dashboard set-alertmanager-api-host # default: '' - For example:: + For example: + + .. prompt:: bash $ - $ ceph dashboard set-alertmanager-api-host 'http://localhost:9093' + 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. - :: + + .. prompt:: bash $ + + ceph dashboard set-prometheus-api-host # default: '' - $ ceph dashboard set-prometheus-api-host # default: '' + For example: - For example:: + .. prompt:: bash $ - $ ceph dashboard set-prometheus-api-host 'http://localhost:9090' + ceph dashboard set-prometheus-api-host 'http://localhost:9090' After setting up the hosts, refresh your browser's dashboard window or tab. @@ -801,13 +872,17 @@ Alertmanager setup, you should disable certificate verification in the dashboard to avoid refused connections caused by certificates signed by an unknown CA or that do not match the host name. -- For Prometheus:: +- For Prometheus: - $ ceph dashboard set-prometheus-api-ssl-verify False +.. prompt:: bash $ -- For Alertmanager:: + ceph dashboard set-prometheus-api-ssl-verify False - $ ceph dashboard set-alertmanager-api-ssl-verify False +- For Alertmanager: + +.. prompt:: bash $ + + ceph dashboard set-alertmanager-api-ssl-verify False .. _dashboard-user-role-management: @@ -823,30 +898,38 @@ following checks: - Is the password longer than N characters? - Are the old and new password the same? -The password policy feature can be switched on or off completely:: +The password policy feature can be switched on or off completely: + +.. prompt:: bash $ - $ ceph dashboard set-pwd-policy-enabled + ceph dashboard set-pwd-policy-enabled -The following individual checks can also be switched on or off:: +The following individual checks can also be switched on or off: - $ ceph dashboard set-pwd-policy-check-length-enabled - $ ceph dashboard set-pwd-policy-check-oldpwd-enabled - $ ceph dashboard set-pwd-policy-check-username-enabled - $ ceph dashboard set-pwd-policy-check-exclusion-list-enabled - $ ceph dashboard set-pwd-policy-check-complexity-enabled - $ ceph dashboard set-pwd-policy-check-sequential-chars-enabled - $ ceph dashboard set-pwd-policy-check-repetitive-chars-enabled +.. prompt:: bash $ + + ceph dashboard set-pwd-policy-check-length-enabled + ceph dashboard set-pwd-policy-check-oldpwd-enabled + ceph dashboard set-pwd-policy-check-username-enabled + ceph dashboard set-pwd-policy-check-exclusion-list-enabled + ceph dashboard set-pwd-policy-check-complexity-enabled + ceph dashboard set-pwd-policy-check-sequential-chars-enabled + ceph dashboard set-pwd-policy-check-repetitive-chars-enabled Additionally the following options are available to configure password policy. -- Minimum password length (defaults to 8):: +- Minimum password length (defaults to 8): + +.. prompt:: bash $ + + ceph dashboard set-pwd-policy-min-length - $ ceph dashboard set-pwd-policy-min-length +- Minimum password complexity (defaults to 10): -- Minimum password complexity (defaults to 10):: + .. prompt:: bash $ - $ ceph dashboard set-pwd-policy-min-complexity + ceph dashboard set-pwd-policy-min-complexity Password complexity is calculated by classifying each character in the password. The complexity count starts by 0. A character is rated by @@ -859,9 +942,11 @@ policy. - Increase by 5 if the character has not been classified by one of the previous rules. - A list of comma separated words that are not allowed to be used in a - password:: + password: - $ ceph dashboard set-pwd-policy-exclusion-list [,...] + .. prompt:: bash $ + + ceph dashboard set-pwd-policy-exclusion-list [,...] User Accounts @@ -879,44 +964,60 @@ available to all ``ceph-mgr`` instances. We provide a set of CLI commands to manage user accounts: -- *Show User(s)*:: +- *Show User(s)*: + + .. prompt:: bash $ - $ ceph dashboard ac-user-show [] + ceph dashboard ac-user-show [] -- *Create User*:: +- *Create User*: + + .. prompt:: bash $ - $ ceph dashboard ac-user-create [--enabled] [--force-password] [--pwd_update_required] -i [] [] [] [] + ceph dashboard ac-user-create [--enabled] [--force-password] [--pwd_update_required] -i [] [] [] [] 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*:: +- *Delete User*: + + .. prompt:: bash $ - $ ceph dashboard ac-user-delete + ceph dashboard ac-user-delete -- *Change Password*:: +- *Change Password*: - $ ceph dashboard ac-user-set-password [--force-password] -i + .. prompt:: bash $ -- *Change Password Hash*:: + ceph dashboard ac-user-set-password [--force-password] -i - $ ceph dashboard ac-user-set-password-hash -i +- *Change Password Hash*: + + .. prompt:: bash $ + + ceph dashboard ac-user-set-password-hash -i The hash must be a bcrypt hash and salt, e.g. ``$2b$12$Pt3Vq/rDt2y9glTPSV.VFegiLkQeIpddtkhoFetNApYmIJOY8gau2``. This can be used to import users from an external database. -- *Modify User (name, and email)*:: +- *Modify User (name, and email)*: + + .. prompt:: bash $ - $ ceph dashboard ac-user-set-info + ceph dashboard ac-user-set-info -- *Disable User*:: +- *Disable User*: - $ ceph dashboard ac-user-disable + .. prompt:: bash $ -- *Enable User*:: + ceph dashboard ac-user-disable - $ ceph dashboard ac-user-enable +- *Enable User*: + + .. prompt:: bash $ + + ceph dashboard ac-user-enable User Roles and Permissions ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -991,42 +1092,58 @@ The list of system roles are: - **pool-manager**: allows full permissions for the *pool* scope. - **cephfs-manager**: allows full permissions for the *cephfs* scope. -The list of available roles can be retrieved with the following command:: +The list of available roles can be retrieved with the following command: + +.. prompt:: bash $ - $ ceph dashboard ac-role-show [] + ceph dashboard ac-role-show [] You can also use the CLI to create new roles. The available commands are the following: -- *Create Role*:: +- *Create Role*: - $ ceph dashboard ac-role-create [] + .. prompt:: bash $ -- *Delete Role*:: + ceph dashboard ac-role-create [] - $ ceph dashboard ac-role-delete +- *Delete Role*: -- *Add Scope Permissions to Role*:: + .. prompt:: bash $ - $ ceph dashboard ac-role-add-scope-perms [...] + ceph dashboard ac-role-delete -- *Delete Scope Permission from Role*:: +- *Add Scope Permissions to Role*: - $ ceph dashboard ac-role-del-scope-perms + .. prompt:: bash $ + + ceph dashboard ac-role-add-scope-perms [...] + +- *Delete Scope Permission from Role*: + + .. prompt:: bash $ + + ceph dashboard ac-role-del-scope-perms To assign roles to users, the following commands are available: -- *Set User Roles*:: +- *Set User Roles*: + + .. prompt:: bash $ + + ceph dashboard ac-user-set-roles [...] - $ ceph dashboard ac-user-set-roles [...] +- *Add Roles To User*: -- *Add Roles To User*:: + .. prompt:: bash $ - $ ceph dashboard ac-user-add-roles [...] + ceph dashboard ac-user-add-roles [...] -- *Delete Roles from User*:: +- *Delete Roles from User*: - $ ceph dashboard ac-user-del-roles [...] + .. prompt:: bash $ + + ceph dashboard ac-user-del-roles [...] Example of User and Custom Role Creation @@ -1036,19 +1153,25 @@ 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*:: +1. *Create the user*: + + .. prompt:: bash $ + + ceph dashboard ac-user-create bob -i - $ ceph dashboard ac-user-create bob -i +2. *Create role and specify scope permissions*: -2. *Create role and specify scope permissions*:: + .. prompt:: bash $ - $ 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 + 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*:: +3. *Associate roles to user*: - $ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only + .. prompt:: bash $ + + ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only .. _dashboard-proxy-configuration: @@ -1075,9 +1198,9 @@ 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: -:: +.. prompt:: bash $ - ceph config set mgr mgr/dashboard/url_prefix $PREFIX + ceph config set mgr mgr/dashboard/url_prefix $PREFIX so you can access the dashboard at ``http://$IP:$PORT/$PREFIX/``. @@ -1088,21 +1211,27 @@ If the dashboard is behind a load-balancing proxy like `HAProxy + ceph dashboard set-audit-api-enabled If enabled, the following parameters are logged per each request: @@ -1166,9 +1297,11 @@ If enabled, the following parameters are logged per each request: * 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:: +by default. Execute the following command to disable this behaviour: - $ ceph dashboard set-audit-api-log-payload +.. prompt:: bash $ + + ceph dashboard set-audit-api-log-payload A log entry may look like this:: @@ -1201,9 +1334,14 @@ Troubleshooting the Dashboard Locating the Dashboard ^^^^^^^^^^^^^^^^^^^^^^ -If you are unsure of the location of the Ceph Dashboard, run the following command:: +If you are unsure of the location of the Ceph Dashboard, run the following command: + +.. prompt:: bash $ + + ceph mgr services | jq .dashboard + +:: - $ ceph mgr services | jq .dashboard "https://host:port" The command returns the URL where the Ceph Dashboard is located: ``https://:/`` @@ -1221,9 +1359,11 @@ Accessing the Dashboard If you are unable to access the Ceph Dashboard, run the following commands: -#. Verify the Ceph Dashboard module is enabled:: +#. Verify the Ceph Dashboard module is enabled: + + .. prompt:: bash $ - $ ceph mgr module ls | jq .enabled_modules + ceph mgr module ls | jq .enabled_modules Ensure the Ceph Dashboard module is listed in the return value of the command. Example snipped output from the command above:: @@ -1234,42 +1374,62 @@ commands: "restful" ] -#. If it is not listed, activate the module with the following command:: +#. If it is not listed, activate the module with the following command: - $ ceph mgr module enable dashboard + .. prompt:: bash $ + + ceph mgr module enable dashboard #. Check the Ceph Dashboard and/or ``ceph-mgr`` log files for any errors. - * Check if ``ceph-mgr`` log messages are written to a file by:: + * Check if ``ceph-mgr`` log messages are written to a file by: + + .. prompt:: bash $ + + ceph config get mgr log_to_file + + :: - $ ceph config get mgr log_to_file true * Get the location of the log file (it's ``/var/log/ceph/-.log`` - by default):: + by default): + + .. prompt:: bash $ + + ceph config get mgr log_file + + :: - $ ceph config get mgr log_file /var/log/ceph/$cluster-$name.log #. Ensure the SSL/TSL support is configured properly: - * Check if the SSL/TSL support is enabled:: + * Check if the SSL/TSL support is enabled: + + .. prompt:: bash $ + + ceph config get mgr mgr/dashboard/ssl + + * If the command returns ``true``, verify a certificate exists by: - $ ceph config get mgr mgr/dashboard/ssl + .. prompt:: bash $ - * If the command returns ``true``, verify a certificate exists by:: + ceph config-key get mgr/dashboard/crt - $ ceph config-key get mgr/dashboard/crt + and: - and:: + .. prompt:: bash $ - $ ceph config-key get mgr/dashboard/key + ceph config-key get mgr/dashboard/key * 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`:: + :ref:`dashboard-ssl-tls-support`: - $ ceph dashboard create-self-signed-cert + .. prompt:: bash $ + + ceph dashboard create-self-signed-cert Trouble Logging into the Dashboard @@ -1287,24 +1447,33 @@ error, run through the procedural checks below: 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:: + error, check that the user account exists: + + .. prompt:: bash $ - $ ceph dashboard ac-user-show + ceph dashboard ac-user-show This command returns your user data. If the user does not exist, it will print:: - $ Error ENOENT: User does not exist + Error ENOENT: User does not exist + +#. Check if the user is enabled: -#. Check if the user is enabled:: + .. prompt:: bash $ + + ceph dashboard ac-user-show | jq .enabled + + :: - $ ceph dashboard ac-user-show | jq .enabled true Check if ``enabled`` is set to ``true`` for your user. If not the user is - not enabled, run:: + not enabled, run: + + .. prompt:: bash $ - $ ceph dashboard ac-user-enable + ceph dashboard ac-user-enable Please see :ref:`dashboard-user-role-management` for more information. @@ -1334,9 +1503,11 @@ To enable this flag via the Ceph Dashboard, navigate from *Cluster* to *Manager modules*. Select *Dashboard module* and click the edit button. Click the *debug* checkbox and update. -To enable it via the CLI, run the following command:: +To enable it via the CLI, run the following command: - $ ceph dashboard debug enable +.. prompt:: bash $ + + ceph dashboard debug enable Setting Logging Level of Dashboard Module @@ -1345,29 +1516,41 @@ Setting Logging Level of Dashboard Module Setting the logging level to debug makes the log more verbose and helpful for debugging. -#. Increase the logging level of manager daemons:: +#. Increase the logging level of manager daemons: + + .. prompt:: bash $ - $ ceph tell mgr config set debug_mgr 20 + ceph tell mgr config set debug_mgr 20 #. Adjust the logging level of the Ceph Dashboard module via the Dashboard or CLI: * Navigate from *Cluster* to *Manager modules*. Select *Dashboard module* and click the edit button. Modify the ``log_level`` configuration. - * To adjust it via the CLI, run the following command:: + * To adjust it via the CLI, run the following command: + + .. prompt:: bash $ - $ bin/ceph config set mgr mgr/dashboard/log_level debug + bin/ceph config set mgr mgr/dashboard/log_level debug -#. High log levels can result in considerable log volume, which can +3. 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:: +something like this: - $ ceph config log - ... - --- 11 --- 2020-11-07 11:11:11.960659 --- mgr.x/dashboard/log_level = debug --- - ... - $ ceph config reset 11 + .. prompt:: bash $ + + ceph config log + + :: + + ... + --- 11 --- 2020-11-07 11:11:11.960659 --- mgr.x/dashboard/log_level = debug --- + ... + + .. prompt:: bash $ + + ceph config reset 11 .. _centralized-logging: @@ -1381,15 +1564,18 @@ To learn more about centralized logging, see :ref:`cephadm-monitoring-centralize 2. Similarly create the Promtail service which will be by default deployed on all the running hosts. -3. To see debug-level messages as well as info-level events, run the following command via CLI:: +3. To see debug-level messages as well as info-level events, run the following command via CLI: - $ ceph config set mgr mgr/cephadm/log_to_cluster_level debug + .. prompt:: bash $ -4. To enable logging to files, run the following commands via CLI:: + ceph config set mgr mgr/cephadm/log_to_cluster_level debug - $ ceph config set global log_to_file true +4. To enable logging to files, run the following commands via CLI: - $ ceph config set global mon_cluster_log_to_file true + .. prompt:: bash $ + + ceph config set global log_to_file true + ceph config set global mon_cluster_log_to_file true 5. Click on the Daemon Logs tab under Cluster -> Logs. @@ -1412,11 +1598,15 @@ on the issue tracker. Under the ``my account`` tab in the Ceph Issue Tracker, the user can see their API access key. This key is used for authentication when creating a new issue. To store the Ceph API access key, in the CLI run: -``ceph dashboard set-issue-tracker-api-key -i `` +.. prompt:: bash $ + + ``ceph dashboard set-issue-tracker-api-key -i `` Then on successful update, you can create an issue using: -``ceph dashboard create issue `` +.. prompt:: bash $ + + ``ceph dashboard create issue `` The available projects to create an issue on are: #. dashboard