From: Zac Dover Date: Tue, 13 May 2025 06:58:39 +0000 (+1000) Subject: doc/dev/cephfs-mirroring: edit file 2 of x X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=0c30240649e2768f105a3e32ba1fd0df95e2a1cb;p=ceph.git doc/dev/cephfs-mirroring: edit file 2 of x Add prompts (and perform necessary corrections to glaring grammatical errors) to doc/dev/cephfs-mirroring.rst, as requested by Jos Collin in https://github.com/ceph/ceph/pull/63237/files#r2085886075. This commit edits the second quarter of the doc/dev/cephfs-mirroring.rst file. This commit encompasses about one-hundred lines of RST. Signed-off-by: Zac Dover (cherry picked from commit 0768ef3fcab69392635d32ed6c4c7051b27afd37) --- diff --git a/doc/dev/cephfs-mirroring.rst b/doc/dev/cephfs-mirroring.rst index 7c6354fad3a65..a3a1106786336 100644 --- a/doc/dev/cephfs-mirroring.rst +++ b/doc/dev/cephfs-mirroring.rst @@ -96,93 +96,129 @@ file system mirroring and is the recommended control interface. 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 -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 +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 - $ ceph fs snapshot mirror disable +After mirroring has been enabled, add a peer to which directory snapshots will +be mirrored. Peers follow the ``@`` 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 `@` 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 [] [] [] + ceph fs snapshot mirror peer_add [] [] [] -`` is optional, and default to `` (on the remote cluster). +```` is optional, and defaults to ```` (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 + +.. note:: See the `Mirror Daemon Status` section on how to figure out Peer + UUID. - $ ceph fs snapshot mirror peer_remove +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 - $ ceph fs snapshot mirror peer_list +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 + ceph fs snapshot mirror add -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 +.. 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 + +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 ---------------