From: Zac Dover Date: Thu, 1 May 2025 04:12:45 +0000 (+1000) Subject: doc/mgr: edit administrator.rst X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=859950180f0b7314b097ee9b2f9f192f4cfb3ed4;p=ceph.git 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 --- diff --git a/doc/mgr/administrator.rst b/doc/mgr/administrator.rst index 18f3f0f21908e..140c4751551d1 100644 --- 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 `` and -``ceph mgr module disable `` 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 `` and ``ceph mgr module disable +`` 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 + ceph Configuration -------------