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

.. _mgr-administrator-guide:

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, the commands will
be accessible as ordinary Ceph commands::

    ceph <command | help>

If you would like to see the list of commands handled by the
manager (where normal ``ceph help`` would show all mon and mgr commands),
you can send a command directly to the manager daemon::

    ceph tell mgr help

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

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 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
b5b8bbf5	1	.. _mgr-administrator-guide:
7c673cae FG	2
	3	ceph-mgr administrator's guide
	4	==============================
	5
31f18b77 FG	6	Manual setup
31f18b77 FG	7	------------
7c673cae	8
31f18b77 FG	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.
7c673cae	12
31f18b77 FG	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 '
7c673cae FG	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
31f18b77 FG	29	Client authentication
31f18b77 FG	30	---------------------
224ce89b	31
31f18b77 FG	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.
224ce89b	36	To fix that, add a "mgr allow \*" stanza to your client's cephx capabilities by
31f18b77 FG	37	`Modifying User Capabilities`_.
31f18b77 FG	38
7c673cae FG	39	High availability
	40	-----------------
	41
	42	In general, you should set up a ceph-mgr on each of the hosts
b5b8bbf5	43	running a ceph-mon daemon to achieve the same level of availability.
7c673cae FG	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	Calling module commands
	57	-----------------------
	58
c07f9fc5 FG	59	Where a module implements command line hooks, the commands will
c07f9fc5 FG	60	be accessible as ordinary Ceph commands::
7c673cae	61
c07f9fc5 FG	62	ceph <command \| help>
	63
	64	If you would like to see the list of commands handled by the
	65	manager (where normal ``ceph help`` would show all mon and mgr commands),
	66	you can send a command directly to the manager daemon::
	67
	68	ceph tell mgr help
7c673cae FG	69
	70	Note that it is not necessary to address a particular mgr instance,
	71	simply ``mgr`` will pick the current active daemon.
	72
7c673cae FG	73	Configuration
	74	-------------
	75
	76	OPTION(mgr_module_path, OPT_STR, CEPH_PKGLIBDIR "/mgr") // where to load python modules from
	77
	78	``mgr module path``
	79
	80	:Description: Path to load modules from
	81	:Type: String
	82	:Default: ``"<library dir>/mgr"``
	83
7c673cae FG	84	``mgr data``
	85
	86	:Description: Path to load daemon data (such as keyring)
	87	:Type: String
	88	:Default: ``"/var/lib/ceph/mgr/$cluster-$id"``
	89
31f18b77	90	``mgr tick period``
7c673cae	91
31f18b77 FG	92	:Description: How many seconds between mgr beacons to monitors, and other
31f18b77 FG	93	periodic checks.
7c673cae FG	94	:Type: Integer
	95	:Default: ``5``
	96
	97	``mon mgr beacon grace``
	98
	99	:Description: How long after last beacon should a mgr be considered failed
	100	:Type: Integer
	101	:Default: ``30``
	102
224ce89b	103	.. _Modifying User Capabilities: ../../rados/operations/user-management/#modify-user-capabilities