Mirroring Module and Interface
------------------------------
-Mirroring module provides interface for managing directory snapshot mirroring. The module
-is implemented as a Ceph Manager plugin. Mirroring module does not manage spawning (and
-terminating) the mirror daemons. Right now the preferred way would be to start/stop
-mirror daemons via `systemctl(1)`. Going forward, deploying mirror daemons would be
-managed by `cephadm` (Tracker: http://tracker.ceph.com/issues/47261).
+The mirroring module provides an interface for managing directory snapshot
+mirroring. The module is implemented as a Ceph Manager plugin. The mirroring
+module does not manage the spawning of (and terminating of) the mirror
+daemons. `systemctl(1)` is the preferred way to start and stop mirror daemons.
+In the future, mirror daemons will be deployed and managed by `cephadm`
+(Tracker: http://tracker.ceph.com/issues/47261).
+
+The manager module is responsible for assigning directories to mirror daemons
+for synchronization. Multiple mirror daemons can be spawned to achieve
+concurrency in directory snapshot synchronization. When mirror daemons are
+spawned (or terminated), the mirroring module discovers the modified set of
+mirror daemons and rebalances the directory assignment amongst the new set
+thus providing high-availability.
+
+.. note:: Configurations that have multiple mirror daemons are currently
+ untested. Only a single mirror daemon is recommended.
+
+The mirroring module is disabled by default. To enable mirroring, run the
+following command:
-The manager module is responsible for assigning directories to mirror daemons for
-synchronization. Multiple mirror daemons can be spawned to achieve concurrency in
-directory snapshot synchronization. When mirror daemons are spawned (or terminated)
-, the mirroring module discovers the modified set of mirror daemons and rebalances
-the directory assignment amongst the new set thus providing high-availability.
+.. prompt:: bash $
+
+ ceph mgr module enable mirroring
-.. note:: Multiple mirror daemons is currently untested. Only a single mirror daemon
- is recommended.
+The mirroring module provides a family of commands for controlling the
+mirroring of directory snapshots. To add or remove directories, mirroring
+must be enabled for a given file system. To enable mirroring, run a command of the following form:
-Mirroring module is disabled by default. To enable mirroring use::
+.. prompt:: bash $
- $ ceph mgr module enable mirroring
+ ceph fs snapshot mirror enable <fs_name>
-Mirroring module provides a family of commands to control mirroring of directory
-snapshots. To add or remove directories, mirroring needs to be enabled for a given
-file system. To enable mirroring use::
+.. note:: The mirroring-module commands use the ``fs snapshot mirror`` prefix
+ as distinct from the monitor commands, which use the ``fs mirror`` prefix.
+ Make sure to use module (that is, ``fs snapshot mirror``) commands.
- $ ceph fs snapshot mirror enable <fs_name>
+To disable mirroring, run a command of the following form:
-.. note:: Mirroring module commands use `fs snapshot mirror` prefix as compared to
- the monitor commands which `fs mirror` prefix. Make sure to use module
- commands.
+.. prompt:: bash $
-To disable mirroring, use::
+ ceph fs snapshot mirror disable <fs_name>
- $ ceph fs snapshot mirror disable <fs_name>
+After mirroring has been enabled, add a peer to which directory snapshots will
+be mirrored. Peers follow the ``<client>@<cluster>`` specification and get
+assigned a unique-id (UUID) when added. See the `Creating Users` section for
+information on how to create Ceph users for mirroring.
-Once mirroring is enabled, add a peer to which directory snapshots are to be mirrored.
-Peers follow `<client>@<cluster>` specification and get assigned a unique-id (UUID)
-when added. See `Creating Users` section on how to create Ceph users for mirroring.
+To add a peer, run a command of the following form:
-To add a peer use::
+.. prompt:: bash $
- $ ceph fs snapshot mirror peer_add <fs_name> <remote_cluster_spec> [<remote_fs_name>] [<remote_mon_host>] [<cephx_key>]
+ ceph fs snapshot mirror peer_add <fs_name> <remote_cluster_spec> [<remote_fs_name>] [<remote_mon_host>] [<cephx_key>]
-`<remote_fs_name>` is optional, and default to `<fs_name>` (on the remote cluster).
+``<remote_fs_name>`` is optional, and defaults to ``<fs_name>`` (on the remote
+cluster).
-This requires the remote cluster ceph configuration and user keyring to be available in
-the primary cluster. See `Bootstrap Peers` section to avoid this. `peer_add` additionally
-supports passing the remote cluster monitor address and the user key. However, bootstrapping
-a peer is the recommended way to add a peer.
+This requires that the remote-cluster Ceph configuration and the user keyring
+are available in the primary cluster. See the `Bootstrap Peers` section for
+more information. The ``peer_add`` subcommand also supports passing the remote
+cluster's monitor address and user key. However, bootstrapping a peer is the
+recommended way to add a peer.
.. note:: Only a single peer is supported right now.
-To remove a peer use::
+To remove a peer, run a command of the following form:
+
+.. prompt:: bash $
+
+ ceph fs snapshot mirror peer_remove <fs_name> <peer_uuid>
+
+.. note:: See the `Mirror Daemon Status` section on how to figure out Peer
+ UUID.
- $ ceph fs snapshot mirror peer_remove <fs_name> <peer_uuid>
+To list the file system mirror peers, run a command of the following form:
-.. note:: See `Mirror Daemon Status` section on how to figure out Peer UUID.
+.. prompt:: bash $
-To list file system mirror peers use::
+ ceph fs snapshot mirror peer_list <fs_name>
- $ ceph fs snapshot mirror peer_list <fs_name>
+To configure a directory for mirroring, run a command of the following form:
-To configure a directory for mirroring, use::
+.. prompt:: bash $
-
$ ceph fs snapshot mirror add <fs_name> <path>
+ ceph fs snapshot mirror add <fs_name> <path>
-To stop a mirroring directory snapshots use::
+To stop a directory from mirroring snapshots, run a command of the following
+form:
- $ ceph fs snapshot mirror remove <fs_name> <path>
+.. prompt:: bash $
-Only absolute directory paths are allowed. Also, paths are normalized by the mirroring
-module, therefore, `/a/b/../b` is equivalent to `/a/b`::
+ ceph fs snapshot mirror remove <fs_name> <path>
+
+Only absolute directory paths are allowed. Also, paths are normalized by the
+mirroring module. This means that ``/a/b/../b`` is equivalent to ``/a/b``:
+
+.. prompt:: bash $
+
+ mkdir -p /d0/d1/d2
+ ceph fs snapshot mirror add cephfs /d0/d1/d2 {}
+ ceph fs snapshot mirror add cephfs /d0/d1/../d1/d2
+::
- $ mkdir -p /d0/d1/d2
- $ ceph fs snapshot mirror add cephfs /d0/d1/d2
- {}
- $ ceph fs snapshot mirror add cephfs /d0/d1/../d1/d2
Error EEXIST: directory /d0/d1/d2 is already tracked
-Once a directory is added for mirroring, its subdirectory or ancestor directories are
-disallowed to be added for mirroring::
+After a directory is added for mirroring, its subdirectory or ancestor
+directories are not allowed to be added for mirroring:
+
+.. prompt:: bash $
+
+ ceph fs snapshot mirror add cephfs /d0/d1
+::
+
+ Error EINVAL: /d0/d1 is a ancestor of tracked path /d0/d1/d2
+
+.. prompt:: bash $
+
+ ceph fs snapshot mirror add cephfs /d0/d1/d2/d3
+::
- $ ceph fs snapshot mirror add cephfs /d0/d1
- Error EINVAL: /d0/d1 is a ancestor of tracked path /d0/d1/d2
- $ ceph fs snapshot mirror add cephfs /d0/d1/d2/d3
- Error EINVAL: /d0/d1/d2/d3 is a subtree of tracked path /d0/d1/d2
+ Error EINVAL: /d0/d1/d2/d3 is a subtree of tracked path /d0/d1/d2
-Commands to check directory mapping (to mirror daemons) and directory distribution are
-detailed in `Mirror Daemon Status` section.
+Commands for checking directory mapping (to mirror daemons) and directory
+distribution are detailed in the `Mirror Daemon Status` section.
Bootstrap Peers
---------------
projects / ceph.git / commitdiff