From: Tatjana Dehler Date: Tue, 21 Apr 2020 14:07:21 +0000 (+0200) Subject: doc/mgr/dashboard: Add troubleshooting guide X-Git-Tag: wip-pdonnell-testing-20200918.022351~1338^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=a241a00452f20e2c511ee9d10c6689a8d63c9ef5;p=ceph-ci.git doc/mgr/dashboard: Add troubleshooting guide Fixes: https://tracker.ceph.com/issues/25196 Signed-off-by: Tatjana Dehler --- diff --git a/doc/images/dashboard/invalid-credentials.png b/doc/images/dashboard/invalid-credentials.png new file mode 100644 index 00000000000..abd78b02440 Binary files /dev/null and b/doc/images/dashboard/invalid-credentials.png differ diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index 5d9cc86f5b2..dc88f36ac4d 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -1070,3 +1070,168 @@ and loosely coupled fashion. .. include:: dashboard_plugins/feature_toggles.inc.rst .. include:: dashboard_plugins/debug.inc.rst + + +Troubleshooting the Dashboard +----------------------------- + +Locating the Dashboard +^^^^^^^^^^^^^^^^^^^^^^ + +If you are unsure of the location of the Ceph Dashboard, run the following command:: + + $ ceph mgr services | jq .dashboard + "https://host:port" + +The command returns the URL where the Ceph Dashboard is located: ``https://:/`` + +.. note:: + + Many Ceph command line tools return results in JSON format. You may have to install + the `jq `_ command-line JSON processor utility on + your operating system beforehand. + + +Accessing the Dashboard +^^^^^^^^^^^^^^^^^^^^^^^ + +If you are unable to access the Ceph Dashboard, run through the following +commands: + +#. Verify the Ceph Dashboard module is enabled:: + + $ 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:: + + [ + "dashboard", + "iostat", + "restful" + ] + +#. If it is not listed, activate the module with the following command:: + + $ 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 if mgr log messages are written to a file by:: + + $ ceph config get mgr log_to_file + true + + * Get the location of the log file (it's ``/var/log/ceph/-.log`` + by default):: + + $ 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:: + + $ ceph config get mgr mgr/dashboard/ssl + + * If the command returns ``true``, verify a certificate exists by:: + + $ ceph config-key get mgr/dashboard/crt + + and:: + + $ ceph config-key get mgr/dashboard/key + + * If it doesn't, run the following command to generate a self-signed + certificate or follow the instructions outlined in + :ref:`dashboard-ssl-tls-support`:: + + $ ceph dashboard create-self-signed-cert + + +Trouble Logging into the Dashboard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are unable to log into the Ceph Dashboard and you receive the following +error, run through the procedural checks below: + +.. image:: ../images/dashboard/invalid-credentials.png + :align: center + +#. 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. + +#. If your user credentials are correct, but you are experiencing the same + error, check that the user account exists:: + + $ 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 + +#. Check if the user is 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:: + + $ ceph dashboard ac-user-enable + +Please see :ref:`dashboard-user-role-management` for more information. + + +A Dashboard Feature is Not Working +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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*, + 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. + + +Ceph Dashboard Logs +^^^^^^^^^^^^^^^^^^^ + +Dashboard Debug Flag +'''''''''''''''''''' + +With this flag enabled, traceback of errors are 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 +*debug* checkbox and update. + +To enable it via the CLI, run the following command:: + + $ ceph dashboard debug enable + + +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:: + + $ 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:: + + $ bin/ceph config set mgr mgr/dashboard/log_level debug