doc: complete documentation for ceph fs administration commands

Fixes: http://tracker.ceph.com/issues/24580
Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>

diff --git a/doc/cephfs/administration.rst b/doc/cephfs/administration.rst
index 289e668bccf2a18339149d18ce29f332788cc738..210d0b41a275a6bf709c105ab3c2f4c20e30c5ca 100644 (file)
--- a/doc/cephfs/administration.rst
+++ b/doc/cephfs/administration.rst
@@ -14,34 +14,65 @@ creation of multiple filesystems use ``ceph fs flag set enable_multiple true``.
 
     fs new <filesystem name> <metadata pool name> <data pool name>
 
+This command creates a new file system. The file system name and metadata pool
+name are self-explanatory. The specified data pool is the default data pool and
+cannot be changed once set. Each file system has its own set of MDS daemons
+assigned to ranks so ensure that you have sufficient standby daemons available
+to accommodate the new file system.
+
 ::
 
     fs ls
 
+List all file systems by name.
+
 ::
 
-    fs rm <filesystem name> [--yes-i-really-mean-it]
+    fs dump [epoch]
+
+This dumps the FSMap at the given epoch (default: current) which includes all
+file system settings, MDS daemons and the ranks they hold, and the list of
+standby MDS daemons.
+
 
 ::
 
-    fs reset <filesystem name>
+    fs rm <filesystem name> [--yes-i-really-mean-it]
+
+Destroy a CephFS file system. This wipes information about the state of the
+file system from the FSMap. The metadata pool and data pools are untouched and
+must be destroyed separately.
 
 ::
 
     fs get <filesystem name>
 
+Get information about the named file system, including settings and ranks. This
+is a subset of the same information from the ``fs dump`` command.
+
 ::
 
     fs set <filesystem name> <var> <val>
 
+Change a setting on a file system. These settings are specific to the named
+file system and do not affect other file systems.
+
 ::
 
     fs add_data_pool <filesystem name> <pool name/id>
 
+Add a data pool to the file system. This pool can be used for file layouts
+as an alternate location to store file data.
+
 ::
 
     fs rm_data_pool <filesystem name> <pool name/id>
 
+This command removes the specified pool from the list of data pools for the
+file system.  If any files have layouts for the removed data pool, the file
+data will become unavailable. The default data pool (when creating the file
+system) cannot be removed.
+
 
 Settings
 --------
@@ -82,13 +113,13 @@ Taking a CephFS cluster down is done by setting the down flag:
  
 :: 
  
-    mds set <fs_name> down true
+    fs set <fs_name> down true
  
 To bring the cluster back online:
  
 :: 
 
-    mds set <fs_name> down false
+    fs set <fs_name> down false
 
 This will also restore the previous value of max_mds. MDS daemons are brought
 down in a way such that journals are flushed to the metadata pool and all
@@ -157,28 +188,28 @@ daemons. Use ``ceph tell mds.* help`` to learn available commands.
 
     mds metadata <gid/name/role>
 
-::
-
-    mds repaired <role>
+Get metadata about the given MDS known to the Monitors.
 
 ::
 
-    mds stat
+    mds repaired <role>
 
+Mark the file system rank as repaired. Unlike the name suggests, this command
+does not change a MDS; it manipulates the file system rank which has been
+marked damaged.
 
 
 Global settings
 ---------------
 
-::
-
-    fs dump
 
 ::
 
     fs flag set <flag name> <flag val> [<confirmation string>]
 
-"flag name" must be one of ['enable_multiple']
+Sets a global CephFS flag (i.e. not specific to a particular file system).
+Currently, the only flag setting is 'enable_multiple' which allows having
+multiple CephFS file systems.
 
 Some flags require you to confirm your intentions with "--yes-i-really-mean-it"
 or a similar string they will prompt you with. Consider these actions carefully
@@ -197,37 +228,29 @@ filesystem.
 
     mds compat rm_compat
 
+Removes an compatibility feature flag.
+
 ::
 
     mds compat rm_incompat
 
+Removes an incompatibility feature flag.
+
 ::
 
     mds compat show
 
-::
-
-    mds set_state
+Show MDS compatibility flags.
 
 ::
 
     mds rmfailed
 
-Legacy
-------
-
-These legacy commands are obsolete and no longer usable post-Luminous.
+This removes a rank from the failed set.
 
 ::
 
-    mds add_data_pool # replaced by "fs add_data_pool"
-    mds cluster_down  # replaced by "fs set cluster_down"
-    mds cluster_up  # replaced by "fs set cluster_up"
-    mds dump  # replaced by "fs get"
-    mds getmap # replaced by "fs dump"
-    mds newfs # replaced by "fs new"
-    mds remove_data_pool # replaced by "fs rm_data_pool"
-    mds set # replaced by "fs set"
-    mds set_max_mds # replaced by "fs set max_mds"
-    mds stop  # obsolete
+    fs reset <filesystem name>
 
+This command resets the file system state to defaults, except for the name and
+pools. Non-zero ranks are saved in the stopped set.

diff --git a/src/mon/MonCommands.h b/src/mon/MonCommands.h
index f5ce691fe2c8ef9a6f192b262bd816a0eb849ce8..2c5451185ea324ce49545f56a8f40a6a67f4312a 100644 (file)
--- a/src/mon/MonCommands.h
+++ b/src/mon/MonCommands.h
@@ -282,7 +282,7 @@ COMMAND("versions",
  * MDS commands (MDSMonitor.cc)
  */
 
-COMMAND("mds stat", "show MDS status", "mds", "r")
+COMMAND_WITH_FLAG("mds stat", "show MDS status", "mds", "r", FLAG(HIDDEN))
 COMMAND_WITH_FLAG("mds dump "
        "name=epoch,type=CephInt,req=false,range=0", \
        "dump legacy MDS cluster info, optionally from epoch",
@@ -325,10 +325,10 @@ COMMAND_WITH_FLAG("mds set " \
 // arbitrary limit 0-20 below; worth standing on head to make it
 // relate to actual state definitions?
 // #include "include/ceph_fs.h"
-COMMAND("mds set_state " \
+COMMAND_WITH_FLAG("mds set_state " \
        "name=gid,type=CephInt,range=0 " \
        "name=state,type=CephInt,range=0|20", \
-       "set mds state of <gid> to <numeric-state>", "mds", "rw")
+       "set mds state of <gid> to <numeric-state>", "mds", "rw", FLAG(HIDDEN))
 COMMAND("mds fail name=role_or_gid,type=CephString", \
        "Mark MDS failed: trigger a failover if a standby is available",
         "mds", "rw")
@@ -337,9 +337,9 @@ COMMAND("mds repaired name=role,type=CephString", \
 COMMAND("mds rm " \
        "name=gid,type=CephInt,range=0", \
        "remove nonactive mds", "mds", "rw")
-COMMAND("mds rmfailed name=role,type=CephString " \
+COMMAND_WITH_FLAG("mds rmfailed name=role,type=CephString " \
         "name=yes_i_really_mean_it,type=CephBool,req=false", \
-       "remove failed mds", "mds", "rw")
+       "remove failed rank", "mds", "rw", FLAG(HIDDEN))
 COMMAND_WITH_FLAG("mds cluster_down", "take MDS cluster down", "mds", "rw", FLAG(OBSOLETE))
 COMMAND_WITH_FLAG("mds cluster_up", "bring MDS cluster up", "mds", "rw", FLAG(OBSOLETE))
 COMMAND("mds compat rm_compat " \