add monitor documentation

Signed-off-by: Alfredo Deza <alfredo.deza@inktank.com>

diff --git a/docs/source/contents.rst b/docs/source/contents.rst
index d48d66a07925a4aa106e0363e8ac3ad284d922a2..afd3624e15058e62d30c1ec6c617c19956990df6 100644 (file)
--- a/docs/source/contents.rst
+++ b/docs/source/contents.rst
@@ -8,3 +8,4 @@ Content Index
    changelog.rst
    install.rst
    pkg.rst
+   mon.rst

diff --git a/docs/source/mon.rst b/docs/source/mon.rst
new file mode 100644 (file)
index 0000000..9d74f55
--- /dev/null
+++ b/docs/source/mon.rst
@@ -0,0 +1,75 @@
+.. _mon:
+
+``mon``
+=======
+The ``mon`` subcommand provides an interface to interact with a cluster's
+monitors. The tool makes a few assumptions that are needed to implement the
+most common scenarios. Monitors are usually very particular in what they need
+to work correctly.
+
+``create-initial``
+------------------
+Will deploy for monitors defined in ``mon initial members``, wait until
+they form quorum and then ``gatherkeys``, reporting the monitor status along
+the process. If monitors don't form quorum the command will eventually
+time out.
+
+This is the *preferred* way of initially deploying monitors since it will
+compound a few of the steps needed together while looking for possible issues
+along the way.
+
+::
+
+    ceph-deploy mon create-initial
+
+
+``create``
+----------
+Deploy monitors by specifying directly like::
+
+    ceph-deploy mon create node1 node2 node3
+
+If no hosts are passed it will default to use the `mon initial members`
+defined in the configuration.
+
+Please note that if this is an initial monitor deployment, the preferred way
+is to use ``create-initial``.
+
+
+``add``
+-------
+Add a monitor to an existing cluster::
+
+    ceph-deploy mon add node1
+
+Since monitor hosts can have different network interfaces, this command allows
+you to specify the interface IP in a few different ways.
+
+**``--address``**: this will explicitly override any configured address for
+that host. Usage::
+
+    ceph-deploy mon add node1 --address 192.168.1.10
+
+
+**ceph.conf**: If a section for the node that is being added exists and it
+defines a ``mon addr`` key. For example::
+
+    [mon.node1]
+    mon addr = 192.168.1.10
+
+**resolving/dns**: if the monitor address is not defined in the configuration file
+nor overridden in the command-line it will fall-back to resolving the address
+of the provided host.
+
+.. warning:: If the monitor host has multiple addresses you should specify
+             the address directly to ensure the right IP is used.
+
+.. versionadded:: 1.3.6
+
+
+``destroy``
+-----------
+Completely remove monitors on a remote host. Requires hostname(s) as
+arguments::
+
+    ceph-deploy mon destroy node1