doc/mon: clean up `mds fail`/`mds deactivate` descriptions

Fixes: http://tracker.ceph.com/issues/20424
Signed-off-by: John Spray <john.spray@redhat.com>

diff --git a/doc/cephfs/administration.rst b/doc/cephfs/administration.rst
index 23bd5fc6a991ed222b42b1b7117166eba01b7be8..f4976cfa2dfc7d5527527db3308108a8f6706870 100644 (file)
--- a/doc/cephfs/administration.rst
+++ b/doc/cephfs/administration.rst
@@ -81,17 +81,29 @@ These commands act on specific mds daemons or ranks.
 
 ::
 
-    mds fail <gid/name/role
+    mds fail <gid/name/role>
 
-This command deactivates an MDS causing it to flush its entire journal to
-backing RADOS objects and close all open client sessions. Deactivating an MDS
-is primarily intended for bringing down a rank after reducing the number of
-active MDS (max_mds).
+Mark an MDS daemon as failed.  This is equivalent to what the cluster
+would do if an MDS daemon had failed to send a message to the mon
+for ``mds_beacon_grace`` second.  If the daemon was active and a suitable
+standby is available, using ``mds fail`` will force a failover to the standby.
+
+If the MDS daemon was in reality still running, then using ``mds fail``
+will cause the daemon to restart.  If it was active and a standby was
+available, then the "failed" daemon will return as a standby.
 
 ::
 
     mds deactivate <role>
 
+Deactivate an MDS, causing it to flush its entire journal to
+backing RADOS objects and close all open client sessions. Deactivating an MDS
+is primarily intended for bringing down a rank after reducing the number of
+active MDS (max_mds).
+
+Use ``mds deactivate`` in conjunction with adjustments to ``max_mds`` to
+shrink an MDS cluster.  See :doc:`/cephfs/multimds`
+
 ::
 
     tell mds.<daemon name>

diff --git a/src/mon/MonCommands.h b/src/mon/MonCommands.h
index e5e3cd98befb01b8551e7790a73fe266dda0e76f..973b6eabc7bd0943d0b5ad053769aef3f20c4491 100644 (file)
--- a/src/mon/MonCommands.h
+++ b/src/mon/MonCommands.h
@@ -301,7 +301,8 @@ COMMAND("mds compat show", "show mds compatibility settings", \
        "mds", "r", "cli,rest")
 COMMAND_WITH_FLAG("mds stop name=who,type=CephString", "stop mds", \
        "mds", "rw", "cli,rest", FLAG(DEPRECATED))
-COMMAND("mds deactivate name=who,type=CephString", "stop mds", \
+COMMAND("mds deactivate name=who,type=CephString",
+        "clean up specified MDS rank (use with `set max_mds` to shrink cluster)", \
        "mds", "rw", "cli,rest")
 COMMAND_WITH_FLAG("mds set_max_mds " \
        "name=maxmds,type=CephInt,range=0", \
@@ -320,7 +321,8 @@ COMMAND("mds set_state " \
        "name=state,type=CephInt,range=0|20", \
        "set mds state of <gid> to <numeric-state>", "mds", "rw", "cli,rest")
 COMMAND("mds fail name=who,type=CephString", \
-       "force mds to status failed", "mds", "rw", "cli,rest")
+       "Mark MDS failed: trigger a failover if a standby is available",
+        "mds", "rw", "cli,rest")
 COMMAND("mds repaired name=rank,type=CephString", \
        "mark a damaged MDS rank as no longer damaged", "mds", "rw", "cli,rest")
 COMMAND("mds rm " \