doc/mgr: edit administrator.rst

Edit doc/mgr/administrator.rst. Add prompts and correct some of the
inelegant English present in the file.

This commit is part of a project to separate out the twenty-five files
that were committed to https://github.com/ceph/ceph/pull/62782.

Credit for this initiative should go to Ville Ojamo.

Signed-off-by: Zac Dover <zac.dover@proton.me>

diff --git a/doc/mgr/administrator.rst b/doc/mgr/administrator.rst
index 18f3f0f21908edc0f1ec1eca637290b06084d320..140c4751551d16325e2fb724dc57b1f9bcdc98ee 100644 (file)
--- a/doc/mgr/administrator.rst
+++ b/doc/mgr/administrator.rst
@@ -10,31 +10,37 @@ 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:
 
-    ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'
+.. prompt:: bash #
 
-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``.
+   ``ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'``
 
-Start the ceph-mgr daemon::
+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``.
 
-    ceph-mgr -i $name
+Start the ceph-mgr daemon:
 
-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 #
+
+   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::
 
     mgr active: $name
 
 Client authentication
 ---------------------
 
-The manager is a new daemon which requires new CephX capabilities. If you upgrade
-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
-`Modifying User Capabilities`_.
+The manager is a new daemon which requires new CephX capabilities. If you
+upgrade 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 `Modifying User
+Capabilities`_.
 
 High availability
 -----------------
@@ -66,38 +72,40 @@ issues when requesting large structures. As an example, an OSDMap with 1000 osds
 has a approximate size of 4MiB. With heavy load, on a 3000 osd cluster there has
 been a 1.5x improvement enabling the cache.
 
-Furthermore, you can run ``ceph daemon mgr.${MGRNAME} perf dump`` to retrieve perf
-counters of a mgr module. In ``mgr.cache_hit`` and ``mgr.cache_miss`` you'll find the
-hit/miss ratio of the mgr cache.
+Furthermore, you can run ``ceph daemon mgr.${MGRNAME} perf dump`` to retrieve
+perf counters of a mgr module. In ``mgr.cache_hit`` and ``mgr.cache_miss``
+you'll find the hit/miss ratio of the mgr cache.
 
 Using modules
 -------------
 
-Use the command ``ceph mgr module ls`` to see which modules are
-available, and which are currently enabled. Use ``ceph mgr module ls --format=json-pretty``
-to view detailed metadata about disabled modules. Enable or disable modules
-using the commands ``ceph mgr module enable <module>`` and
-``ceph mgr module disable <module>`` respectively.
+Use the command ``ceph mgr module ls`` to see which modules are available, and
+which are currently enabled. Use ``ceph mgr module ls --format=json-pretty`` to
+view detailed metadata about disabled modules. Enable or disable modules using
+the commands ``ceph mgr module enable <module>`` and ``ceph mgr module disable
+<module>`` respectively.
 
-If a module is *enabled* then the active ceph-mgr daemon will load
-and execute it.  In the case of modules that provide a service,
-such as an HTTP server, the module may publish its address when it
-is loaded.  To see the addresses of such modules, use the command
-``ceph mgr services``.
+If a module is *enabled* then the active ceph-mgr daemon will load and execute
+it.  In the case of modules that provide a service, such as an HTTP server, the
+module may publish its address when it is loaded.  To see the addresses of such
+modules, use the command ``ceph mgr services``.
 
-Some modules may also implement a special standby mode which runs on
-standby ceph-mgr daemons as well as the active daemon.  This enables
-modules that provide services to redirect their clients to the active
-daemon, if the client tries to connect to a standby.
+Some modules may also implement a special standby mode which runs on standby
+ceph-mgr daemons as well as the active daemon.  This enables modules that
+provide services to redirect their clients to the active daemon, if the client
+tries to connect to a standby.
 
 Consult the documentation pages for individual manager modules for more
 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"
@@ -107,8 +115,14 @@ Here is an example of enabling the :term:`Dashboard` module:
                ]
        }
 
-       $ ceph mgr module enable dashboard
-       $ ceph mgr module ls
+
+.. prompt:: bash $
+
+   ceph mgr module enable dashboard
+   ceph mgr module ls
+
+.. code-block:: console
+
        {
                "enabled_modules": [
                        "status",
@@ -118,18 +132,22 @@ Here is an example of enabling the :term:`Dashboard` module:
                ]
        }
 
-       $ ceph mgr services
+.. prompt:: bash $
+
+   ceph mgr services
+
+.. code-block:: console
+
        {
                "dashboard": "http://myserver.com:7789/"
        }
 
 
 The first time the cluster starts, it uses the :confval:`mgr_initial_modules`
-setting to override which modules to enable.  However, this setting
-is ignored through the rest of the lifetime of the cluster: only
-use it for bootstrapping.  For example, before starting your
-monitor daemons for the first time, you might add a section like
-this to your ``ceph.conf``:
+setting to override which modules to enable.  However, this setting is ignored
+through the rest of the lifetime of the cluster: only use it for bootstrapping.
+For example, before starting your monitor daemons for the first time, you might
+add a section like this to your ``ceph.conf``:
 
 .. code-block:: ini
 
@@ -157,9 +175,11 @@ 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.::
+the module.:
+
+.. prompt:: bash #
 
-    ceph <command | help>
+   ceph <command | help>
 
 Configuration
 -------------