[ceph.git] / ceph / doc / mgr / administrator.rst


ceph-mgr administrator's guide
==============================

Manual setup
------------

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::

    ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow *' mds 'allow *'

Place that key into ``mgr data`` path, which for a cluster "ceph"
and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo``.

Start the ceph-mgr daemon::

    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`_.

High availability
-----------------

In general, you should set up a ceph-mgr on each of the hosts
running a ceph-mon daemon to achieve the same level of availability. 

By default, whichever ceph-mgr instance comes up first will be made
active by the monitors, and the others will be standbys.  There is
no requirement for quorum among the ceph-mgr daemons.

If the active daemon fails to send a beacon to the monitors for
more than ``mon mgr beacon grace`` (default 30s), then it will be replaced
by a standby.

If you want to pre-empt failover, you can explicitly mark a ceph-mgr
daemon as failed using ``ceph mgr fail <mgr name>``.

Calling module commands
-----------------------

Where a module implements command line hooks, using the Ceph CLI's
``tell`` command to call them like this::

    ceph tell mgr <command | help>

Note that it is not necessary to address a particular mgr instance,
simply ``mgr`` will pick the current active daemon.

Use the ``help`` command to get a list of available commands from all
modules.

Configuration
-------------

OPTION(mgr_module_path, OPT_STR, CEPH_PKGLIBDIR "/mgr") // where to load python modules from

``mgr module path``

:Description: Path to load modules from
:Type: String
:Default: ``"<library dir>/mgr"``

``mgr modules``

:Description: List of python modules to load
:Type: String
:Default: ``"rest"`` (Load the REST API module only)

``mgr data``

:Description: Path to load daemon data (such as keyring)
:Type: String
:Default: ``"/var/lib/ceph/mgr/$cluster-$id"``

``mgr tick period``

:Description: How many seconds between mgr beacons to monitors, and other
              periodic checks.
:Type: Integer
:Default: ``5``

``mon mgr beacon grace``

:Description: How long after last beacon should a mgr be considered failed
:Type: Integer
:Default: ``30``

.. _Modifying User Capabilities: ../rados/operations/user-management#modify-user-capabilities
Commit	Line	Data
7c673cae FG	1
	2	ceph-mgr administrator's guide
	3	==============================
	4
31f18b77 FG	5	Manual setup
31f18b77 FG	6	------------
7c673cae	7
31f18b77 FG	8	Usually, you would set up a ceph-mgr daemon using a tool such
	9	as ceph-ansible. These instructions describe how to set up
	10	a ceph-mgr daemon manually.
7c673cae	11
31f18b77 FG	12	First, create an authentication key for your daemon::
	13
	14	ceph auth get-or-create mgr.$name mon 'allow profile mgr' osd 'allow ' mds 'allow '
7c673cae FG	15
	16	Place that key into ``mgr data`` path, which for a cluster "ceph"
	17	and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo``.
	18
	19	Start the ceph-mgr daemon::
	20
	21	ceph-mgr -i $name
	22
	23	Check that the mgr has come up by looking at the output
	24	of ``ceph status``, which should now include a mgr status line::
	25
	26	mgr active: $name
	27
31f18b77 FG	28	Client authentication
	29	---------------------
	30	The manager is a new daemon which requires new CephX capabilities. If you upgrade
	31	a cluster from an old version of Ceph, or use the default install/deploy tools,
	32	your admin client should get this capability automatically. If you use tooling from
	33	elsewhere, you may get EACCES errors when invoking certain ceph cluster commands.
	34	To fix that, add a "mgr allow *" stanza to your client's cephx capabilities by
	35	`Modifying User Capabilities`_.
	36
7c673cae FG	37	High availability
	38	-----------------
	39
	40	In general, you should set up a ceph-mgr on each of the hosts
	41	running a ceph-mon daemon to achieve the same level of availability.
	42
	43	By default, whichever ceph-mgr instance comes up first will be made
	44	active by the monitors, and the others will be standbys. There is
	45	no requirement for quorum among the ceph-mgr daemons.
	46
	47	If the active daemon fails to send a beacon to the monitors for
	48	more than ``mon mgr beacon grace`` (default 30s), then it will be replaced
	49	by a standby.
	50
	51	If you want to pre-empt failover, you can explicitly mark a ceph-mgr
	52	daemon as failed using ``ceph mgr fail <mgr name>``.
	53
	54	Calling module commands
	55	-----------------------
	56
	57	Where a module implements command line hooks, using the Ceph CLI's
	58	``tell`` command to call them like this::
	59
	60	ceph tell mgr <command \| help>
	61
	62	Note that it is not necessary to address a particular mgr instance,
	63	simply ``mgr`` will pick the current active daemon.
	64
	65	Use the ``help`` command to get a list of available commands from all
	66	modules.
	67
	68	Configuration
	69	-------------
	70
	71	OPTION(mgr_module_path, OPT_STR, CEPH_PKGLIBDIR "/mgr") // where to load python modules from
	72
	73	``mgr module path``
	74
	75	:Description: Path to load modules from
	76	:Type: String
	77	:Default: ``"<library dir>/mgr"``
	78
	79	``mgr modules``
	80
	81	:Description: List of python modules to load
	82	:Type: String
	83	:Default: ``"rest"`` (Load the REST API module only)
	84
	85	``mgr data``
	86
	87	:Description: Path to load daemon data (such as keyring)
	88	:Type: String
	89	:Default: ``"/var/lib/ceph/mgr/$cluster-$id"``
	90
31f18b77	91	``mgr tick period``
7c673cae	92
31f18b77 FG	93	:Description: How many seconds between mgr beacons to monitors, and other
31f18b77 FG	94	periodic checks.
7c673cae FG	95	:Type: Integer
	96	:Default: ``5``
	97
	98	``mon mgr beacon grace``
	99
	100	:Description: How long after last beacon should a mgr be considered failed
	101	:Type: Integer
	102	:Default: ``30``
	103
31f18b77	104	.. _Modifying User Capabilities: ../rados/operations/user-management#modify-user-capabilities