From: Zac Dover Date: Mon, 21 Apr 2025 09:33:01 +0000 (+1000) Subject: doc: Revert "doc/mgr: Promptify CLI commands and other formatting fixes" X-Git-Tag: v20.3.0~37^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=1d0ca2458eff78967e541b20a7b91c26468a31ee;p=ceph.git doc: Revert "doc/mgr: Promptify CLI commands and other formatting fixes" This reverts commit c4f0f8edad46c852961a622795d14b735f660d94. Signed-off-by: Zac Dover --- diff --git a/doc/mgr/administrator.rst b/doc/mgr/administrator.rst index 9baa20b2e294d..18f3f0f21908e 100644 --- a/doc/mgr/administrator.rst +++ b/doc/mgr/administrator.rst @@ -10,27 +10,21 @@ Usually, you would set up a ceph-mgr daemon using a tool such as ceph-ansible. These instructions describe how to set up a ceph-mgr daemon manually. -First, create an authentication key for your daemon: +First, create an authentication key for your daemon:: -.. prompt:: bash # - - ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *' + ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *' Place that key as file named ``keyring`` into ``mgr data`` path, which for a cluster "ceph" and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo`` respective ``/var/lib/ceph/mgr/ceph-foo/keyring``. -Start the ceph-mgr daemon: - -.. prompt:: bash # +Start the ceph-mgr daemon:: - ceph-mgr -i $name + ceph-mgr -i $name Check that the mgr has come up by looking at the output -of ``ceph status``, which should now include a mgr status line: - -.. prompt:: bash # +of ``ceph status``, which should now include a mgr status line:: - mgr active: $name + mgr active: $name Client authentication --------------------- @@ -39,7 +33,7 @@ The manager is a new daemon which requires new CephX capabilities. If you upgrad a cluster from an old version of Ceph, or use the default install/deploy tools, your admin client should get this capability automatically. If you use tooling from elsewhere, you may get EACCES errors when invoking certain ceph cluster commands. -To fix that, add a ``mgr allow \*`` stanza to your client's cephx capabilities by +To fix that, add a "mgr allow \*" stanza to your client's cephx capabilities by `Modifying User Capabilities`_. High availability @@ -101,12 +95,9 @@ information about what functionality each module provides. Here is an example of enabling the :term:`Dashboard` module: -.. prompt:: bash # - - ceph mgr module ls - -:: +.. code-block:: console + $ ceph mgr module ls { "enabled_modules": [ "status" @@ -116,13 +107,8 @@ Here is an example of enabling the :term:`Dashboard` module: ] } -.. prompt:: bash # - - ceph mgr module enable dashboard - ceph mgr module ls - -:: - + $ ceph mgr module enable dashboard + $ ceph mgr module ls { "enabled_modules": [ "status", @@ -132,12 +118,7 @@ Here is an example of enabling the :term:`Dashboard` module: ] } -.. prompt:: bash # - - ceph mgr services - -:: - + $ ceph mgr services { "dashboard": "http://myserver.com:7789/" } @@ -176,11 +157,9 @@ Calling module commands Where a module implements command line hooks, the commands will be accessible as ordinary Ceph commands. Ceph will automatically incorporate module commands into the standard CLI interface and route them appropriately to -the module. - -.. prompt:: bash # +the module.:: - ceph + ceph Configuration ------------- diff --git a/doc/mgr/alerts.rst b/doc/mgr/alerts.rst index 87bfac5cdd038..8428424a371a3 100644 --- a/doc/mgr/alerts.rst +++ b/doc/mgr/alerts.rst @@ -16,58 +16,44 @@ as well. Enabling -------- -The *alerts* module is enabled with: +The *alerts* module is enabled with:: -.. prompt:: bash # - - ceph mgr module enable alerts + ceph mgr module enable alerts Configuration ------------- To configure SMTP, all of the following config options must be set -(When setting ``mgr/alerts/smtp_destination``, you can use commas to separate multiple): - -.. prompt:: bash # - - ceph config set mgr mgr/alerts/smtp_host ** - ceph config set mgr mgr/alerts/smtp_destination ** - ceph config set mgr mgr/alerts/smtp_sender ** - -By default, the module will use SSL and port 465. To change that: +(When setting ``mgr/alerts/smtp_destination``, you can use commas to separate multiple):: -.. prompt:: bash # + ceph config set mgr mgr/alerts/smtp_host ** + ceph config set mgr mgr/alerts/smtp_destination ** + ceph config set mgr mgr/alerts/smtp_sender ** - ceph config set mgr mgr/alerts/smtp_ssl false # if not SSL - ceph config set mgr mgr/alerts/smtp_port ** # if not 465 +By default, the module will use SSL and port 465. To change that,:: -To authenticate to the SMTP server, you must set the user and password: + ceph config set mgr mgr/alerts/smtp_ssl false # if not SSL + ceph config set mgr mgr/alerts/smtp_port ** # if not 465 -.. prompt:: bash # +To authenticate to the SMTP server, you must set the user and password:: - ceph config set mgr mgr/alerts/smtp_user ** - ceph config set mgr mgr/alerts/smtp_password ** + ceph config set mgr mgr/alerts/smtp_user ** + ceph config set mgr mgr/alerts/smtp_password ** By default, the name in the ``From:`` line is simply ``Ceph``. To -change that (e.g., to identify which cluster this is): +change that (e.g., to identify which cluster this is),:: -.. prompt:: bash # - - ceph config set mgr mgr/alerts/smtp_from_name 'Ceph Cluster Foo' + ceph config set mgr mgr/alerts/smtp_from_name 'Ceph Cluster Foo' By default, the module will check the cluster health once per minute and, if there is a change, send a message. To change that -frequency: - -.. prompt:: bash # +frequency,:: - ceph config set mgr mgr/alerts/interval ** # e.g., "5m" for 5 minutes + ceph config set mgr mgr/alerts/interval ** # e.g., "5m" for 5 minutes Commands -------- -To force an alert to be send immediately: - -.. prompt:: bash # +To force an alert to be send immediately,:: - ceph alerts send + ceph alerts send diff --git a/doc/mgr/ceph_api/index.rst b/doc/mgr/ceph_api/index.rst index 7bdc484dab270..1cdc9a97bfb56 100644 --- a/doc/mgr/ceph_api/index.rst +++ b/doc/mgr/ceph_api/index.rst @@ -53,11 +53,9 @@ be obtained, and it may then be reused for subsequent requests. The { "token": "", ...} The token obtained must be passed together with every API request in the -``Authorization`` HTTP header: +``Authorization`` HTTP header:: -.. prompt:: bash $ - - curl -H "Authorization: Bearer " ... + curl -H "Authorization: Bearer " ... Authentication and authorization can be further configured from the Ceph CLI, the Ceph-Dashboard UI and the Ceph API itself (please refer to diff --git a/doc/mgr/cli_api.rst b/doc/mgr/cli_api.rst index 6223d2bc05ce0..81a99ae44ac18 100644 --- a/doc/mgr/cli_api.rst +++ b/doc/mgr/cli_api.rst @@ -7,47 +7,33 @@ benchmarked for further testing. Enabling -------- -The *cli api commands* module is enabled with: +The *cli api commands* module is enabled with:: -.. prompt:: bash # + ceph mgr module enable cli_api - ceph mgr module enable cli_api +To check that it is enabled, run:: -To check that it is enabled, run: - -.. prompt:: bash # - - ceph mgr module ls | grep cli_api + ceph mgr module ls | grep cli_api Usage -------- -To run a mgr module command, run: - -.. prompt:: bash # - - ceph mgr cli - -For example, use the following command to print the list of servers: - -.. prompt:: bash # - - ceph mgr cli list_servers +To run a mgr module command, run:: -List all available mgr module commands with: + ceph mgr cli -.. prompt:: bash # +For example, use the following command to print the list of servers:: - ceph mgr cli --help + ceph mgr cli list_servers -To benchmark a command, run: +List all available mgr module commands with:: -.. prompt:: bash # + ceph mgr cli --help - ceph mgr cli_benchmark +To benchmark a command, run:: -For example, use the following command to benchmark the command to get osd_map: + ceph mgr cli_benchmark -.. prompt:: bash # +For example, use the following command to benchmark the command to get osd_map:: - ceph mgr cli_benchmark 100 10 get osd_map + ceph mgr cli_benchmark 100 10 get osd_map diff --git a/doc/mgr/crash.rst b/doc/mgr/crash.rst index c3725c26d207c..656c7a2d4ef31 100644 --- a/doc/mgr/crash.rst +++ b/doc/mgr/crash.rst @@ -6,17 +6,13 @@ it in the Ceph cluster for later analysis. Enabling -------- -The *crash* module is enabled with: +The *crash* module is enabled with:: -.. prompt:: bash # + ceph mgr module enable crash - ceph mgr module enable crash +The *crash* upload key is generated with:: -The *crash* upload key is generated with: - -.. prompt:: bash # - - ceph auth get-or-create client.crash mon 'profile crash' mgr 'profile crash' + ceph auth get-or-create client.crash mon 'profile crash' mgr 'profile crash' On each node, you should store this key in ``/etc/ceph/ceph.client.crash.keyring``. @@ -43,57 +39,57 @@ and a keyring needs to be in ``/etc/ceph``. Commands -------- -.. prompt:: bash # +:: - ceph crash post -i + ceph crash post -i Save a crash dump. The metadata file is a JSON blob stored in the crash dir as ``meta``. As usual, the ceph command can be invoked with ``-i -``, and will read from stdin. -.. prompt:: bash # +:: - ceph crash rm + ceph crash rm Remove a specific crash dump. -.. prompt:: bash # +:: - ceph crash ls + ceph crash ls List the timestamp/uuid crashids for all new and archived crash info. -.. prompt:: bash # +:: - ceph crash ls-new + ceph crash ls-new List the timestamp/uuid crashids for all newcrash info. -.. prompt:: bash # +:: - ceph crash stat + ceph crash stat Show a summary of saved crash info grouped by age. -.. prompt:: bash # +:: - ceph crash info + ceph crash info Show all details of a saved crash. -.. prompt:: bash # +:: ceph crash prune Remove saved crashes older than 'keep' days. must be an integer. -.. prompt:: bash # +:: ceph crash archive Archive a crash report so that it is no longer considered for the ``RECENT_CRASH`` health check and does not appear in the ``crash ls-new`` output (it will still appear in the ``crash ls`` output). -.. prompt:: bash # +:: ceph crash archive-all diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index 87b56ab56a1e0..76e815cdb466e 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -218,7 +218,7 @@ in the source directory ``src/pybind/mgr/dashboard``. Within a running Ceph cluster, the Ceph Dashboard is enabled with: -.. prompt:: bash # +.. prompt:: bash $ ceph mgr module enable dashboard @@ -235,7 +235,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard create-self-signed-cert @@ -257,7 +257,7 @@ For example, a key pair can be generated with a command similar to: 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-ssl-certificate -i dashboard.crt ceph dashboard set-ssl-certificate-key -i dashboard.key @@ -266,14 +266,14 @@ 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): -.. prompt:: bash # +.. prompt:: bash $ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/ssl false @@ -294,7 +294,7 @@ wanted or required. See :ref:`dashboard-proxy-configuration` for more details. fail mgr`` or by disabling and re-enabling the dashboard module (which also triggers the manager to respawn itself): - .. prompt:: bash # + .. prompt:: bash $ ceph mgr module disable dashboard ceph mgr module enable dashboard @@ -315,7 +315,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/server_addr $IP ceph config set mgr mgr/dashboard/server_port $PORT @@ -325,7 +325,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/$name/server_addr $IP ceph config set mgr mgr/dashboard/$name/server_port $PORT @@ -350,7 +350,7 @@ section. To create a user with the administrator role you can use the following commands: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard ac-user-create -i administrator @@ -362,7 +362,7 @@ for multiple times. It is enabled by default to prevent brute-force or dictionar attacks. The user can get or set the default number of lock-out attempts using these commands respectively: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard get-account-lockout-attempts ceph dashboard set-account-lockout-attempts @@ -373,7 +373,7 @@ these commands respectively: However, by disabling this feature, the account is more vulnerable to brute-force or dictionary based attacks. This can be disabled by: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-account-lockout-attempts 0 @@ -384,7 +384,7 @@ If a user account is disabled as a result of multiple invalid login attempts, th it needs to be manually enabled by the administrator. This can be done by the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard ac-user-enable @@ -407,7 +407,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-rgw-credentials @@ -416,7 +416,7 @@ the system. If you've configured a custom 'admin' resource in your RGW admin API, you should set it here also: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-rgw-api-admin-resource @@ -425,27 +425,27 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-rgw-api-ssl-verify False To set a custom hostname or address for an RGW gateway, set the value of ``RGW_HOSTNAME_PER_DAEMON`` accordingly: -.. promt:: bash # +.. promt:: bash $ ceph dashboard set-rgw-hostname The setting can be unset using: -.. promt:: bash # +.. promt:: bash $ ceph dashboard unset-rgw-hostname 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-rest-requests-timeout @@ -473,13 +473,13 @@ verification when accessing ceph-iscsi API. To disable API SSL verification run the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-iscsi-api-ssl-verification false The available iSCSI gateways must be defined using the following commands: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard iscsi-gateway-list # Gateway URL format for a new gateway: ://:@[:port] @@ -514,7 +514,7 @@ separate application that provides machine metrics. impact of denial of service attacks. Please see `Prometheus' Security model - `_ for more detailed + ` for more detailed information. Installation and Configuration using cephadm @@ -534,7 +534,7 @@ on appropriate hosts, proceed with the following steps. #. Enable the Ceph Exporter which comes as Ceph Manager module by running: - .. prompt:: bash # + .. prompt:: bash $ ceph mgr module enable prometheus @@ -582,10 +582,10 @@ on appropriate hosts, proceed with the following steps. #. Install the `vonage-status-panel and grafana-piechart-panel` plugins using: - .. prompt:: bash # + .. prompt:: bash $ - grafana-cli plugins install vonage-status-panel - grafana-cli plugins install grafana-piechart-panel + grafana-cli plugins install vonage-status-panel + grafana-cli plugins install grafana-piechart-panel #. Add Dashboards to Grafana: @@ -641,7 +641,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-grafana-api-url # default: '' @@ -662,7 +662,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-grafana-api-ssl-verify False @@ -673,7 +673,7 @@ You can also access Grafana directly to monitor your cluster. Ceph Dashboard configuration information can also be unset. For example, to clear the Grafana API URL we configured above: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard reset-grafana-api-url @@ -697,18 +697,18 @@ 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. -This setting won't ever be changed automatically, unlike the ``GRAFANA_API_URL`` +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: -.. prompt:: bash # +.. prompt:: bash $ 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 +GRAFANA_API_URL option. If set, it will instruct the browser to use this URL to access Grafana. .. _dashboard-sso-support: @@ -731,7 +731,7 @@ process can be performed by an existing Identity Provider (IdP). To configure SSO on Ceph Dashboard, you should use the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard sso setup saml2 {} {} {} {} @@ -749,7 +749,7 @@ Parameters: To display the current SAML 2.0 configuration, use the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard sso show saml2 @@ -759,19 +759,19 @@ To display the current SAML 2.0 configuration, use the following command: To disable SSO: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard sso disable To check if SSO is enabled: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard sso status To enable SSO: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard sso enable saml2 @@ -850,13 +850,13 @@ in order to manage silences. To use it, specify the host and port of the Alertmanager server: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-alertmanager-api-host # default: '' For example: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-alertmanager-api-host 'http://localhost:9093' @@ -865,13 +865,13 @@ in order to manage silences. that a new silence will match a corresponding alert. - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-prometheus-api-host # default: '' For example: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-prometheus-api-host 'http://localhost:9090' @@ -890,13 +890,13 @@ an unknown CA or that do not match the host name. - For Prometheus: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-prometheus-api-ssl-verify False - For Alertmanager: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-alertmanager-api-ssl-verify False @@ -916,34 +916,34 @@ following checks: The password policy feature can be switched on or off completely: -.. prompt:: bash # +.. 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: -.. prompt:: bash # +.. 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 + 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): - .. prompt:: bash # +.. prompt:: bash $ - ceph dashboard set-pwd-policy-min-length + ceph dashboard set-pwd-policy-min-length - Minimum password complexity (defaults to 10): - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-pwd-policy-min-complexity @@ -960,7 +960,7 @@ policy. - A list of comma separated words that are not allowed to be used in a password: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard set-pwd-policy-exclusion-list [,...] @@ -982,35 +982,35 @@ We provide a set of CLI commands to manage user accounts: - *Show User(s)*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-show [] - *Create User*: - .. prompt:: bash # + .. prompt:: bash $ 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 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*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-delete - *Change Password*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-set-password [--force-password] -i - *Change Password Hash*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-set-password-hash -i @@ -1019,19 +1019,19 @@ We provide a set of CLI commands to manage user accounts: - *Modify User (name, and email)*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-set-info - *Disable User*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-disable - *Enable User*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-enable @@ -1110,7 +1110,7 @@ The list of system roles are: The list of available roles can be retrieved with the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard ac-role-show [] @@ -1119,25 +1119,25 @@ following: - *Create Role*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-role-create [] - *Delete Role*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-role-delete - *Add Scope Permissions to Role*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-role-add-scope-perms [...] - *Delete Scope Permission from Role*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-role-del-scope-perms @@ -1145,19 +1145,19 @@ To assign roles to users, the following commands are available: - *Set User Roles*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-set-roles [...] - *Add Roles To User*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-add-roles [...] - *Delete Roles from User*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-del-roles [...] @@ -1171,13 +1171,13 @@ and has read-only access to other scopes. 1. *Create the user*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-create bob -i 2. *Create role and specify scope permissions*: - .. prompt:: bash # + .. 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 @@ -1185,7 +1185,7 @@ and has read-only access to other scopes. 3. *Associate roles to user*: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-set-roles bob rbd/pool-manager read-only @@ -1214,7 +1214,7 @@ 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 # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/url_prefix $PREFIX @@ -1229,13 +1229,13 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/standby_behaviour "error" To reset the setting to default redirection, use the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/standby_behaviour "redirect" @@ -1245,7 +1245,7 @@ Configure the error status code 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: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/standby_error_status_code 503 @@ -1266,7 +1266,7 @@ not the IP addresses of those hosts, hostname redirection would be preferable. To activate redirection from standby dashboards to active dashboards via the manager's hostname, run the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph config set mgr mgr/dashboard/redirect_resolve_ip_addr True @@ -1336,7 +1336,7 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-audit-api-enabled @@ -1350,7 +1350,7 @@ If enabled, the following parameters are logged per each request: The logging of the request payload (the arguments and their values) is enabled by default. Execute the following command to disable this behaviour: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard set-audit-api-log-payload @@ -1387,7 +1387,7 @@ Locating the Dashboard If you are unsure of the location of the Ceph Dashboard, run the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph mgr services | jq .dashboard @@ -1412,7 +1412,7 @@ commands: #. Verify the Ceph Dashboard module is enabled: - .. prompt:: bash # + .. prompt:: bash $ ceph mgr module ls | jq .enabled_modules @@ -1427,7 +1427,7 @@ commands: #. If it is not listed, activate the module with the following command: - .. prompt:: bash # + .. prompt:: bash $ ceph mgr module enable dashboard @@ -1435,42 +1435,42 @@ commands: * Check if ``ceph-mgr`` log messages are written to a file by: - .. prompt:: bash # + .. prompt:: bash $ ceph config get mgr log_to_file :: - true + true * Get the location of the log file (it's ``/var/log/ceph/-.log`` by default): - .. prompt:: bash # + .. prompt:: bash $ ceph config get mgr log_file :: - /var/log/ceph/$cluster-$name.log + /var/log/ceph/$cluster-$name.log #. Ensure the SSL/TLS support is configured properly: * Check if the SSL/TLS support is enabled: - .. prompt:: bash # + .. prompt:: bash $ ceph config get mgr mgr/dashboard/ssl * If the command returns ``true``, verify a certificate exists by: - .. prompt:: bash # + .. prompt:: bash $ ceph config-key get mgr/dashboard/crt and: - .. prompt:: bash # + .. prompt:: bash $ ceph config-key get mgr/dashboard/key @@ -1478,7 +1478,7 @@ commands: certificate or follow the instructions outlined in :ref:`dashboard-ssl-tls-support`: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard create-self-signed-cert @@ -1500,7 +1500,7 @@ error, run through the procedural checks below: #. If your user credentials are correct, but you are experiencing the same error, check that the user account exists: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-show @@ -1511,18 +1511,18 @@ error, run through the procedural checks below: #. Check if the user is enabled: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-show | jq .enabled :: - true + true Check if ``enabled`` is set to ``true`` for your user. If not the user is not enabled, run: - .. prompt:: bash # + .. prompt:: bash $ ceph dashboard ac-user-enable @@ -1556,7 +1556,7 @@ modules*. Select *Dashboard module* and click the edit button. Click the To enable it via the CLI, run the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard debug enable @@ -1569,7 +1569,7 @@ debugging. #. Increase the logging level of manager daemons: - .. prompt:: bash # + .. prompt:: bash $ ceph tell mgr config set debug_mgr 20 @@ -1580,26 +1580,26 @@ debugging. and click the edit button. Modify the ``log_level`` configuration. * To adjust it via the CLI, run the following command: - .. prompt:: bash # + .. prompt:: bash $ - ceph config set mgr mgr/dashboard/log_level debug + bin/ceph config set mgr mgr/dashboard/log_level debug 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: - .. prompt:: bash # + .. prompt:: bash $ ceph config log :: - ... - --- 11 --- 2020-11-07 11:11:11.960659 --- mgr.x/dashboard/log_level = debug --- - ... + ... + --- 11 --- 2020-11-07 11:11:11.960659 --- mgr.x/dashboard/log_level = debug --- + ... - .. prompt:: bash # + .. prompt:: bash $ ceph config reset 11 @@ -1617,13 +1617,13 @@ To learn more about centralized logging, see :ref:`cephadm-monitoring-centralize 3. To see debug-level messages as well as info-level events, run the following command via CLI: - .. prompt:: bash # + .. prompt:: bash $ ceph config set mgr mgr/cephadm/log_to_cluster_level debug 4. To enable logging to files, run the following commands via CLI: - .. prompt:: bash # + .. prompt:: bash $ ceph config set global log_to_file true ceph config set global mon_cluster_log_to_file true @@ -1649,18 +1649,17 @@ 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: -.. prompt:: bash # +.. prompt:: bash $ - ceph dashboard set-issue-tracker-api-key -i + ``ceph dashboard set-issue-tracker-api-key -i `` Then on successful update, you can create an issue using: -.. prompt:: bash # +.. prompt:: bash $ - ceph dashboard create issue + ``ceph dashboard create issue `` The available projects to create an issue on are: - #. dashboard #. block #. object @@ -1671,7 +1670,6 @@ The available projects to create an issue on are: #. core_ceph The available tracker types are: - #. bug #. feature diff --git a/doc/mgr/dashboard_plugins/debug.inc.rst b/doc/mgr/dashboard_plugins/debug.inc.rst index 7cad8fc7647fd..883419cbf57c8 100644 --- a/doc/mgr/dashboard_plugins/debug.inc.rst +++ b/doc/mgr/dashboard_plugins/debug.inc.rst @@ -6,7 +6,7 @@ Debug This plugin allows to customize the behaviour of the dashboard according to the debug mode. It can be enabled, disabled or checked with the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard debug status @@ -14,7 +14,7 @@ debug mode. It can be enabled, disabled or checked with the following command: Debug: 'disabled' -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard debug enable @@ -22,7 +22,7 @@ debug mode. It can be enabled, disabled or checked with the following command: Debug: 'enabled' -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard debug disable diff --git a/doc/mgr/dashboard_plugins/feature_toggles.inc.rst b/doc/mgr/dashboard_plugins/feature_toggles.inc.rst index ef72075b38587..7c96b0faaaf5b 100644 --- a/doc/mgr/dashboard_plugins/feature_toggles.inc.rst +++ b/doc/mgr/dashboard_plugins/feature_toggles.inc.rst @@ -27,29 +27,29 @@ By default all features come enabled. To retrieve a list of features and their current statuses: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard feature status :: - Feature 'cephfs': 'enabled' - Feature 'iscsi': 'enabled' - Feature 'mirroring': 'enabled' - Feature 'rbd': 'enabled' - Feature 'rgw': 'enabled' - Feature 'nfs': 'enabled' + Feature 'cephfs': 'enabled' + Feature 'iscsi': 'enabled' + Feature 'mirroring': 'enabled' + Feature 'rbd': 'enabled' + Feature 'rgw': 'enabled' + Feature 'nfs': 'enabled' To enable or disable the status of a single or multiple features: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard feature disable iscsi mirroring :: - Feature 'iscsi': disabled - Feature 'mirroring': disabled + Feature 'iscsi': disabled + Feature 'mirroring': disabled After a feature status has changed, the API REST endpoints immediately respond to that change, while for the front-end UI elements, it may take up to 20 seconds to diff --git a/doc/mgr/dashboard_plugins/motd.inc.rst b/doc/mgr/dashboard_plugins/motd.inc.rst index 7b66a8ae8fd58..0f9cc199a9737 100644 --- a/doc/mgr/dashboard_plugins/motd.inc.rst +++ b/doc/mgr/dashboard_plugins/motd.inc.rst @@ -6,31 +6,31 @@ Message of the day (MOTD) Displays a configured `message of the day` at the top of the Ceph Dashboard. The importance of a MOTD can be configured by its severity, which is -``info``, ``warning`` or ``danger``. The MOTD can expire after a given time, +`info`, `warning` or `danger`. The MOTD can expire after a given time, this means it will not be displayed in the UI anymore. Use the following -syntax to specify the expiration time: ``Ns|m|h|d|w`` for seconds, minutes, -hours, days and weeks. If the MOTD should expire after 2 hours, use ``2h`` -or ``5w`` for 5 weeks. Use ``0`` to configure a MOTD that does not expire. +syntax to specify the expiration time: `Ns|m|h|d|w` for seconds, minutes, +hours, days and weeks. If the MOTD should expire after 2 hours, use `2h` +or `5w` for 5 weeks. Use `0` to configure a MOTD that does not expire. To configure a MOTD, run the following command: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard motd set To show the configured MOTD: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard motd get To clear the configured MOTD run: -.. prompt:: bash # +.. prompt:: bash $ ceph dashboard motd clear -A MOTD with a ``info`` or ``warning`` severity can be closed by the user. The -``info`` MOTD is not displayed anymore until the local storage cookies are +A MOTD with a `info` or `warning` severity can be closed by the user. The +`info` MOTD is not displayed anymore until the local storage cookies are cleared or a new MOTD with a different severity is displayed. A MOTD with -a ``warning`` severity will be displayed again in a new session. +a 'warning' severity will be displayed again in a new session. diff --git a/doc/mgr/diskprediction.rst b/doc/mgr/diskprediction.rst index f176e22d0bc15..f4b69751102e6 100644 --- a/doc/mgr/diskprediction.rst +++ b/doc/mgr/diskprediction.rst @@ -10,24 +10,18 @@ Enabling ======== Run the following command to enable the *diskprediction_local* module in the Ceph -environment: +environment:: -.. prompt:: bash # + ceph mgr module enable diskprediction_local - ceph mgr module enable diskprediction_local +To enable the local predictor:: -To enable the local predictor: + ceph config set global device_failure_prediction_mode local -.. prompt:: bash # +To disable prediction:: - ceph config set global device_failure_prediction_mode local - -To disable prediction: - -.. prompt:: bash # - - ceph config set global device_failure_prediction_mode none + ceph config set global device_failure_prediction_mode none *diskprediction_local* requires at least six datasets of device health metrics to @@ -36,19 +30,17 @@ collected only if health monitoring is :ref:`enabled `. Run the following command to retrieve the life expectancy of given device. -.. prompt:: bash # +:: - ceph device predict-life-expectancy + ceph device predict-life-expectancy Configuration ============= The module performs the prediction on a daily basis by default. You can adjust -this interval with: - -.. prompt:: bash # +this interval with:: - ceph config set mgr mgr/diskprediction_local/predict_interval + ceph config set mgr mgr/diskprediction_local/predict_interval Debugging ========= @@ -63,5 +55,5 @@ use the following command. debug mgr = 20 With logging set to debug for the manager the module will print out logging -message with prefix ``mgr[diskprediction]`` for easy filtering. +message with prefix *mgr[diskprediction]* for easy filtering. diff --git a/doc/mgr/hello.rst b/doc/mgr/hello.rst index 6c7a004b1923e..725355fc97012 100644 --- a/doc/mgr/hello.rst +++ b/doc/mgr/hello.rst @@ -6,36 +6,26 @@ This is a simple module skeleton for documentation purposes. Enabling -------- -The *hello* module is enabled with: +The *hello* module is enabled with:: -.. prompt:: bash # + ceph mgr module enable hello - ceph mgr module enable hello +To check that it is enabled, run:: -To check that it is enabled, run: + ceph mgr module ls -.. prompt:: bash # +After editing the module file (found in ``src/pybind/mgr/hello/module.py``), you can see changes by running:: - ceph mgr module ls + ceph mgr module disable hello + ceph mgr module enable hello -After editing the module file (found in ``src/pybind/mgr/hello/module.py``), you can see changes by running: +or:: -.. prompt:: bash # + init-ceph restart mgr - ceph mgr module disable hello - ceph mgr module enable hello +To execute the module, run:: -or: - -.. prompt:: bash # - - init-ceph restart mgr - -To execute the module, run: - -.. prompt:: bash # - - ceph hello + ceph hello The log is found at:: diff --git a/doc/mgr/influx.rst b/doc/mgr/influx.rst index fd60bbe3d2469..2622d3919d08a 100644 --- a/doc/mgr/influx.rst +++ b/doc/mgr/influx.rst @@ -15,16 +15,16 @@ Enabling To enable the module, use the following command: -.. prompt:: bash # +.. prompt:: bash $ - ceph mgr module enable influx + ceph mgr module enable influx If you wish to subsequently disable the module, you can use the equivalent *disable* command: -.. prompt:: bash # +.. prompt:: bash $ - ceph mgr module disable influx + ceph mgr module disable influx ------------- Configuration @@ -36,20 +36,20 @@ credentials. Set configuration values using the following command: -.. prompt:: bash # +.. prompt:: bash $ - ceph config set mgr mgr/influx/ + ceph config set mgr mgr/influx/ The most important settings are :confval:`mgr/influx/hostname`, :confval:`mgr/influx/username` and :confval:`mgr/influx/password`. For example, a typical configuration might look like this: -.. prompt:: bash # +.. prompt:: bash $ - ceph config set mgr mgr/influx/hostname influx.mydomain.com - ceph config set mgr mgr/influx/username admin123 - ceph config set mgr mgr/influx/password p4ssw0rd + ceph config set mgr mgr/influx/hostname influx.mydomain.com + ceph config set mgr mgr/influx/username admin123 + ceph config set mgr mgr/influx/password p4ssw0rd Following is the list of all configuration settings: @@ -71,7 +71,7 @@ Debugging By default, a few debugging statements as well as error statements have been set to print in the log files. Users can add more if necessary. To make use of the debugging option in the module: -- Add this to the ``ceph.conf`` file. +- Add this to the ceph.conf file. .. code-block:: ini @@ -79,7 +79,7 @@ To make use of the debugging option in the module: debug_mgr = 20 - Use this command ``ceph influx self-test``. -- Check the log files. Users may find it easier to filter the log files using ``mgr[influx]``. +- Check the log files. Users may find it easier to filter the log files using *mgr[influx]*. -------------------- Interesting counters diff --git a/doc/mgr/insights.rst b/doc/mgr/insights.rst index ffa6f6d0cd064..37b8903f165a1 100644 --- a/doc/mgr/insights.rst +++ b/doc/mgr/insights.rst @@ -23,23 +23,21 @@ depends on. The insights reports contains the following: Enabling -------- -The *insights* module is enabled with: +The *insights* module is enabled with:: -.. prompt:: bash # - - ceph mgr module enable insights + ceph mgr module enable insights Commands -------- -.. prompt:: bash # +:: - ceph insights + ceph insights Generate the full report. -.. prompt:: bash # +:: - ceph insights prune-health + ceph insights prune-health Remove historical health data older than . Passing `0` for will clear all health data. diff --git a/doc/mgr/iostat.rst b/doc/mgr/iostat.rst index 9bcb6d8d581b4..f9f8493831bca 100644 --- a/doc/mgr/iostat.rst +++ b/doc/mgr/iostat.rst @@ -8,35 +8,25 @@ This module shows the current throughput and IOPS done on the Ceph cluster. Enabling -------- -To check if the *iostat* module is enabled, run: +To check if the *iostat* module is enabled, run:: -.. prompt:: bash # + ceph mgr module ls - ceph mgr module ls +The module can be enabled with:: -The module can be enabled with: + ceph mgr module enable iostat -.. prompt:: bash # +To execute the module, run:: - ceph mgr module enable iostat - -To execute the module, run: - -.. prompt:: bash # - - ceph iostat + ceph iostat To change the frequency at which the statistics are printed, use the ``-p`` -option: - -.. prompt:: bash # - - ceph iostat -p +option:: -For example, use the following command to print the statistics every 5 seconds: + ceph iostat -p -.. prompt:: bash # +For example, use the following command to print the statistics every 5 seconds:: - ceph iostat -p 5 + ceph iostat -p 5 To stop the module, press Ctrl-C. diff --git a/doc/mgr/localpool.rst b/doc/mgr/localpool.rst index 7f955b1987f50..2812925caf302 100644 --- a/doc/mgr/localpool.rst +++ b/doc/mgr/localpool.rst @@ -13,11 +13,9 @@ behavior of specific drive, NIC, or chassis models in isolation. Enabling -------- -The *localpool* module is enabled with: +The *localpool* module is enabled with:: -.. prompt:: bash # - - ceph mgr module enable localpool + ceph mgr module enable localpool Configuring ----------- @@ -33,11 +31,9 @@ The *localpool* module understands the following options: :default: by-$subtreetype- These options are set via the config-key interface. For example, to -change the replication level to 2x with only 64 PGs: - -.. prompt:: bash # +change the replication level to 2x with only 64 PGs, :: - ceph config set mgr mgr/localpool/num_rep 2 - ceph config set mgr mgr/localpool/pg_num 64 + ceph config set mgr mgr/localpool/num_rep 2 + ceph config set mgr mgr/localpool/pg_num 64 .. mgr_module:: None diff --git a/doc/mgr/mds_autoscaler.rst b/doc/mgr/mds_autoscaler.rst index 8d6ed30adbb3a..46fc441552248 100644 --- a/doc/mgr/mds_autoscaler.rst +++ b/doc/mgr/mds_autoscaler.rst @@ -5,7 +5,7 @@ The MDS Autoscaler Module monitors file systems to ensure sufficient MDS daemons are available. It works by adjusting the placement specification for the orchestrator backend of the MDS service. To enable, use: -.. prompt:: bash # +.. sh: ceph mgr module enable mds_autoscaler diff --git a/doc/mgr/modules.rst b/doc/mgr/modules.rst index 5a13f00eec9a0..667664139739f 100644 --- a/doc/mgr/modules.rst +++ b/doc/mgr/modules.rst @@ -13,9 +13,9 @@ ceph-mgr module developer's guide Creating a module ----------------- -In ``pybind/mgr/``, create a python module. Within your module, create a class +In pybind/mgr/, create a python module. Within your module, create a class that inherits from ``MgrModule``. For ceph-mgr to detect your module, your -directory must contain a file called ``module.py``. +directory must contain a file called `module.py`. The most important methods to override are: @@ -38,11 +38,9 @@ Installing a module Once your module is present in the location set by the ``mgr module path`` configuration setting, you can enable it -via the ``ceph mgr module enable`` command: +via the ``ceph mgr module enable`` command:: -.. prompt:: bash # - - ceph mgr module enable mymodule + ceph mgr module enable mymodule Note that the MgrModule interface is not stable, so any modules maintained outside of the Ceph tree are liable to break when run against any newer @@ -60,12 +58,10 @@ import the ``logging`` package and get a logger instance with the Each module has a ``log_level`` option that specifies the current Python logging level of the module. To change or query the logging level of the module use the following Ceph -commands: - -.. prompt:: bash # +commands:: - ceph config get mgr mgr//log_level - ceph config set mgr mgr//log_level + ceph config get mgr mgr//log_level + ceph config set mgr mgr//log_level The logging level used upon the module's start is determined by the current logging level of the mgr daemon, unless if the ``log_level`` option was @@ -78,11 +74,9 @@ level is mapped to the module python logging level as follows: * <= +inf is DEBUG We can unset the module log level and fallback to the mgr daemon logging level -by running the following command: - -.. prompt:: bash # +by running the following command:: - ceph config set mgr mgr//log_level '' + ceph config set mgr mgr//log_level '' By default, modules' logging messages are processed by the Ceph logging layer where they will be recorded in the mgr daemon's log file. @@ -93,9 +87,7 @@ log file with the following name pattern:: ..log -To enable the file logging on a module use the following command: - -.. prompt:: bash # +To enable the file logging on a module use the following command:: ceph config set mgr mgr//log_to_file true @@ -104,9 +96,7 @@ being written to the mgr daemon's log file and are only written to the module's log file. It's also possible to check the status and disable the file logging with the -following commands: - -.. prompt:: bash # +following commands:: ceph config get mgr mgr//log_to_file ceph config set mgr mgr//log_to_file false @@ -421,13 +411,13 @@ You must declare your available configuration options in the Option(name="my_option") ] -If you try to use ``set_module_option`` or ``get_module_option`` on options -not declared in ``MODULE_OPTIONS``, an exception will be raised. +If you try to use set_module_option or get_module_option on options not declared +in ``MODULE_OPTIONS``, an exception will be raised. You may choose to provide setter commands in your module to perform high level validation. Users can also modify configuration using -the normal ``ceph config set`` command, where the configuration options -for a mgr module are named like ``mgr//