+.. _cephfs-administration:
CephFS Administrative commands
==============================
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
--------
Taking the cluster down
-----------------------
-Taking a CephFS cluster down is done by reducing the number of ranks to 1,
-setting the cluster_down flag, and then failing the last rank. For example:
+Taking a CephFS cluster down is done by setting the down flag:
+
+::
+
+ fs set <fs_name> down true
+
+To bring the cluster back online:
+
+::
+
+ 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
+client I/O is stopped.
+
+
+Taking the cluster down rapidly for deletion or disaster recovery
+-----------------------------------------------------------------
+
+To allow rapidly deleting a file system (for testing) or to quickly bring the
+file system and MDS daemons down, use the ``fs fail`` command:
+
+::
+
+ fs fail <fs_name>
+
+This command sets a file system flag to prevent standbys from
+activating on the file system (the ``joinable`` flag).
+
+This process can also be done manually by doing the following:
+
+::
+
+ fs set <fs_name> joinable false
+
+Then the operator can fail all of the ranks which causes the MDS daemons to
+respawn as standbys. The file system will be left in a degraded state.
+
+::
+
+ # For all ranks, 0-N:
+ mds fail <fs_name>:<n>
+
+Once all ranks are inactive, the file system may also be deleted or left in
+this state for other purposes (perhaps disaster recovery).
+
+To bring the cluster back up, simply set the joinable flag:
::
- ceph fs set <fs_name> max_mds 1
- ceph mds deactivate <fs_name>:1 # rank 2 of 2
- ceph status # wait for rank 1 to finish stopping
- ceph fs set <fs_name> cluster_down true
- ceph mds fail <fs_name>:0
-Setting the ``cluster_down`` flag prevents standbys from taking over the failed
-rank.
+ fs set <fs_name> joinable true
+
Daemons
-------
-These commands act on specific mds daemons or ranks.
+Most commands manipulating MDSs take a ``<role>`` argument which can take one
+of three forms:
+
+::
+
+ <fs_name>:<rank>
+ <fs_id>:<rank>
+ <rank>
+
+Commands to manipulate MDS daemons:
::
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). Once the rank is deactivated, the MDS daemon will rejoin the
-cluster as a standby.
-``<role>`` can take one of three forms:
::
- <fs_name>:<rank>
- <fs_id>:<rank>
- <rank>
-
-Use ``mds deactivate`` in conjunction with adjustments to ``max_mds`` to
-shrink an MDS cluster. See :doc:`/cephfs/multimds`
+ tell mds.<daemon name> command ...
-::
-
- tell mds.<daemon name>
+Send a command to the MDS daemon(s). Use ``mds.*`` to send a command to all
+daemons. Use ``ceph tell mds.* help`` to learn available commands.
::
mds metadata <gid/name/role>
+Get metadata about the given MDS known to the Monitors.
+
::
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
mds compat rm_compat
+Removes an compatibility feature flag.
+
::
mds compat rm_incompat
-::
-
- mds compat show
+Removes an incompatibility feature flag.
::
- mds getmap
-
-::
+ mds compat show
- mds set_state
+Show MDS compatibility flags.
::
mds rmfailed
-Legacy
-------
-
-The ``ceph mds set`` command is the deprecated version of ``ceph fs set``,
-from before there was more than one filesystem per cluster. It operates
-on whichever filesystem is marked as the default (see ``ceph fs
-set-default``.)
+This removes a rank from the failed set.
::
- mds stat
- mds dump # replaced by "fs get"
- mds stop # replaced by "mds deactivate"
- mds set_max_mds # replaced by "fs set max_mds"
- mds set # replaced by "fs set"
- mds cluster_down # replaced by "fs set cluster_down"
- mds cluster_up # replaced by "fs set cluster_up"
- mds newfs # replaced by "fs new"
- mds add_data_pool # replaced by "fs add_data_pool"
- mds remove_data_pool #replaced by "fs remove_data_pool"
+ 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.