ceph/doc/mgr/administrator.rst

   1 .. _mgr-administrator-guide:
   2
   3 ceph-mgr administrator's guide
   4 ==============================
   5
   6 Manual setup
   7 ------------
   8
   9 Usually, you would set up a ceph-mgr daemon using a tool such
  10 as ceph-ansible.  These instructions describe how to set up
  11 a ceph-mgr daemon manually.
  12
  13 First, create an authentication key for your daemon::
  14
  15     ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'
  16
  17 Place that key into ``mgr data`` path, which for a cluster "ceph"
  18 and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo``.
  19
  20 Start the ceph-mgr daemon::
  21
  22     ceph-mgr -i $name
  23
  24 Check that the mgr has come up by looking at the output
  25 of ``ceph status``, which should now include a mgr status line::
  26
  27     mgr active: $name
  28
  29 Client authentication
  30 ---------------------
  31
  32 The manager is a new daemon which requires new CephX capabilities. If you upgrade
  33 a cluster from an old version of Ceph, or use the default install/deploy tools,
  34 your admin client should get this capability automatically. If you use tooling from
  35 elsewhere, you may get EACCES errors when invoking certain ceph cluster commands.
  36 To fix that, add a "mgr allow \*" stanza to your client's cephx capabilities by
  37 `Modifying User Capabilities`_.
  38
  39 High availability
  40 -----------------
  41
  42 In general, you should set up a ceph-mgr on each of the hosts
  43 running a ceph-mon daemon to achieve the same level of availability.
  44
  45 By default, whichever ceph-mgr instance comes up first will be made
  46 active by the monitors, and the others will be standbys.  There is
  47 no requirement for quorum among the ceph-mgr daemons.
  48
  49 If the active daemon fails to send a beacon to the monitors for
  50 more than ``mon mgr beacon grace`` (default 30s), then it will be replaced
  51 by a standby.
  52
  53 If you want to pre-empt failover, you can explicitly mark a ceph-mgr
  54 daemon as failed using ``ceph mgr fail <mgr name>``.
  55
  56 Using modules
  57 -------------
  58
  59 Use the command ``ceph mgr module ls`` to see which modules are
  60 available, and which are currently enabled.  Enable or disable modules
  61 using the commands ``ceph mgr module enable <module>`` and
  62 ``ceph mgr module disable <module>`` respectively.
  63
  64 If a module is *enabled* then the active ceph-mgr daemon will load
  65 and execute it.  In the case of modules that provide a service,
  66 such as an HTTP server, the module may publish its address when it
  67 is loaded.  To see the addresses of such modules, use the command
  68 ``ceph mgr services``.
  69
  70 Some modules may also implement a special standby mode which runs on
  71 standby ceph-mgr daemons as well as the active daemon.  This enables
  72 modules that provide services to redirect their clients to the active
  73 daemon, if the client tries to connect to a standby.
  74
  75 Consult the documentation pages for individual manager modules for more
  76 information about what functionality each module provides.
  77
  78 Here is an example of enabling the :term:`Dashboard` module:
  79
  80 ::
  81
  82         $ ceph mgr module ls
  83         {
  84                 "enabled_modules": [
  85                         "restful",
  86                         "status"
  87                 ],
  88                 "disabled_modules": [
  89                         "dashboard"
  90                 ]
  91         }
  92
  93         $ ceph mgr module enable dashboard
  94         $ ceph mgr module ls
  95         {
  96                 "enabled_modules": [
  97                         "restful",
  98                         "status",
  99                         "dashboard"
 100                 ],
 101                 "disabled_modules": [
 102                 ]
 103         }
 104
 105         $ ceph mgr services
 106         {
 107                 "dashboard": "http://myserver.com:7789/",
 108                 "restful": "https://myserver.com:8789/"
 109         }
 110
 111
 112 The first time the cluster starts, it uses the ``mgr_initial_modules``
 113 setting to override which modules to enable.  However, this setting
 114 is ignored through the rest of the lifetime of the cluster: only
 115 use it for bootstrapping.  For example, before starting your
 116 monitor daemons for the first time, you might add a section like
 117 this to your ``ceph.conf``:
 118
 119 ::
 120
 121     [mon]
 122         mgr initial modules = dashboard balancer
 123
 124 Calling module commands
 125 -----------------------
 126
 127 Where a module implements command line hooks, the commands will
 128 be accessible as ordinary Ceph commands::
 129
 130     ceph <command | help>
 131
 132 If you would like to see the list of commands handled by the
 133 manager (where normal ``ceph help`` would show all mon and mgr commands),
 134 you can send a command directly to the manager daemon::
 135
 136     ceph tell mgr help
 137
 138 Note that it is not necessary to address a particular mgr instance,
 139 simply ``mgr`` will pick the current active daemon.
 140
 141 Configuration
 142 -------------
 143
 144 ``mgr module path``
 145
 146 :Description: Path to load modules from
 147 :Type: String
 148 :Default: ``"<library dir>/mgr"``
 149
 150 ``mgr data``
 151
 152 :Description: Path to load daemon data (such as keyring)
 153 :Type: String
 154 :Default: ``"/var/lib/ceph/mgr/$cluster-$id"``
 155
 156 ``mgr tick period``
 157
 158 :Description: How many seconds between mgr beacons to monitors, and other
 159               periodic checks.
 160 :Type: Integer
 161 :Default: ``5``
 162
 163 ``mon mgr beacon grace``
 164
 165 :Description: How long after last beacon should a mgr be considered failed
 166 :Type: Integer
 167 :Default: ``30``
 168
 169 .. _Modifying User Capabilities: ../../rados/operations/user-management/#modify-user-capabilities