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


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

Setup
-----

Create an authentication key for your daemon::

    ceph auth get-or-create mgr.$name mon '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

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 beacon period``

:Description: How many seconds between mgr beacons to monitors
:Type: Integer
:Default: ``5``

``mon mgr beacon grace``

:Description: How long after last beacon should a mgr be considered failed
:Type: Integer
:Default: ``30``
Commit	Line	Data
7c673cae FG	1
	2	ceph-mgr administrator's guide
	3	==============================
	4
	5	Setup
	6	-----
	7
	8	Create an authentication key for your daemon::
	9
	10	ceph auth get-or-create mgr.$name mon 'allow *'
	11
	12	Place that key into ``mgr data`` path, which for a cluster "ceph"
	13	and mgr $name "foo" would be ``/var/lib/ceph/mgr/ceph-foo``.
	14
	15	Start the ceph-mgr daemon::
	16
	17	ceph-mgr -i $name
	18
	19	Check that the mgr has come up by looking at the output
	20	of ``ceph status``, which should now include a mgr status line::
	21
	22	mgr active: $name
	23
	24	High availability
	25	-----------------
	26
	27	In general, you should set up a ceph-mgr on each of the hosts
	28	running a ceph-mon daemon to achieve the same level of availability.
	29
	30	By default, whichever ceph-mgr instance comes up first will be made
	31	active by the monitors, and the others will be standbys. There is
	32	no requirement for quorum among the ceph-mgr daemons.
	33
	34	If the active daemon fails to send a beacon to the monitors for
	35	more than ``mon mgr beacon grace`` (default 30s), then it will be replaced
	36	by a standby.
	37
	38	If you want to pre-empt failover, you can explicitly mark a ceph-mgr
	39	daemon as failed using ``ceph mgr fail <mgr name>``.
	40
	41	Calling module commands
	42	-----------------------
	43
	44	Where a module implements command line hooks, using the Ceph CLI's
	45	``tell`` command to call them like this::
	46
	47	ceph tell mgr <command \| help>
	48
	49	Note that it is not necessary to address a particular mgr instance,
	50	simply ``mgr`` will pick the current active daemon.
	51
	52	Use the ``help`` command to get a list of available commands from all
	53	modules.
	54
	55	Configuration
	56	-------------
	57
	58	OPTION(mgr_module_path, OPT_STR, CEPH_PKGLIBDIR "/mgr") // where to load python modules from
	59
	60	``mgr module path``
	61
	62	:Description: Path to load modules from
	63	:Type: String
	64	:Default: ``"<library dir>/mgr"``
65
66	``mgr modules``
67
68	:Description: List of python modules to load
69	:Type: String
70	:Default: ``"rest"`` (Load the REST API module only)
71
72	``mgr data``
73
74	:Description: Path to load daemon data (such as keyring)
75	:Type: String
76	:Default: ``"/var/lib/ceph/mgr/$cluster-$id"``
77
78	``mgr beacon period``
79
80	:Description: How many seconds between mgr beacons to monitors
81	:Type: Integer
82	:Default: ``5``
83
84	``mon mgr beacon grace``
85
86	:Description: How long after last beacon should a mgr be considered failed
87	:Type: Integer
88	:Default: ``30``
89