doc: add crushdiff(8) man page

Signed-off-by: Mykola Golub <mykola.golub@clyso.com>

diff --git a/ceph.spec.in b/ceph.spec.in
index 5fe197417a2a30398e3fb0c51a4410f15512faa6..7ca560fe81ba1f9134b657c24b8e4eb67129fff1 100644 (file)
--- a/ceph.spec.in
+++ b/ceph.spec.in
@@ -1603,6 +1603,7 @@ exit 0
 %{_mandir}/man8/ceph-syn.8*
 %{_mandir}/man8/ceph-post-file.8*
 %{_mandir}/man8/ceph.8*
+%{_mandir}/man8/crushdiff.8*
 %{_mandir}/man8/mount.ceph.8*
 %{_mandir}/man8/rados.8*
 %{_mandir}/man8/radosgw-admin.8*

diff --git a/debian/ceph-common.install b/debian/ceph-common.install
index 2ec671b357cf0926732b532375ced5da52fc3575..c3bc9dbaa4ee74a3f3c8b300b3f9ab3addc8d11c 100755 (executable)
--- a/debian/ceph-common.install
+++ b/debian/ceph-common.install
@@ -33,6 +33,7 @@ usr/share/man/man8/ceph-rbdnamer.8
 usr/share/man/man8/ceph-syn.8
 usr/share/man/man8/ceph-post-file.8
 usr/share/man/man8/ceph.8
+usr/share/man/man8/crushdiff.8
 usr/share/man/man8/mount.ceph.8
 usr/share/man/man8/rados.8
 usr/share/man/man8/radosgw-admin.8

diff --git a/doc/man/8/CMakeLists.txt b/doc/man/8/CMakeLists.txt
index c3eb4101bf95263369cedba9a3b61cf06f784d4e..4675cc11dd23205b48744719827d46c137fc9db3 100644 (file)
--- a/doc/man/8/CMakeLists.txt
+++ b/doc/man/8/CMakeLists.txt
@@ -24,6 +24,7 @@ set(osd_srcs
   ceph-volume.rst
   ceph-volume-systemd.rst
   ceph-osd.rst
+  crushdiff.rst
   osdmaptool.rst
   ceph-bluestore-tool.rst)
 

diff --git a/doc/man/8/crushdiff.rst b/doc/man/8/crushdiff.rst
new file mode 100644 (file)
index 0000000..44ba4f5
--- /dev/null
+++ b/doc/man/8/crushdiff.rst
@@ -0,0 +1,118 @@
+:orphan:
+
+.. _crushdiff:
+
+=======================================
+ crushdiff -- ceph crush map test tool
+=======================================
+
+.. program:: crushdiff
+
+Synopsis
+========
+
+| **crushdiff** [ --osdmap *osdmap* ] [ --pg-dump *pg-dump* ]
+  [ --compiled ] [ --verbose ] *command* *crushmap*
+
+
+Description
+===========
+
+**crushdiff** is a utility that lets you test the effect of a crushmap
+change: number of pgs, objects, bytes moved. This is a wrapper around
+:doc:`osdmaptool <osdmaptool>`\(8), relying on its **--test-map-pgs-dump**
+option to get the list of changed pgs. Additionally it uses pg stats
+to calculate the numbers of objects and bytes moved.
+
+By default, **crushdiff** will use the cluster current osdmap and pg
+stats, which requires access to the cluster. Though one can use the
+**--osdmap** and **--pg-dump** options to test against previously
+obtained data.
+
+Options
+=======
+
+.. option:: --compiled
+
+   The input/output crushmap is compiled. If the options is not
+   specified the expected/returned crushmap is in txt (decompiled)
+   format.
+
+.. option:: --pg-dump <pg-dump>
+
+   JSON output of **ceph pg dump**. If not specified **crushdiff**
+   will try to get data running the command itself.
+
+.. option:: --osdmap <osdmap>
+
+   The cluster osdmap, obtained with **ceph osd getmap** command. If
+   not specified **crushdiff** will try to get data running the
+   command itself.
+
+.. option:: --verbose
+
+   Produce diagnostic output.
+
+Commands
+========
+
+:command:`compare` *crushmap*
+  Compare the crushmap from *crushmap* file with the crushmap from
+  the cluster osdmap. The output will show the expected number of pgs,
+  objects, bytes moved when the new crushmap is installed.
+
+:command:`export` *crushmap*
+  Export crushmap to *crushmap* file from the cluster osdmap.
+
+:command:`import` *crushmap*
+  Import crushmap from *crushmap* file to the cluster osdmap.
+
+Example
+=======
+
+Get the current crushmap::
+
+        crushdiff export cm.txt
+
+Edit the map::
+
+        $EDITOR cm.txt
+
+Check the result::
+
+        crushdiff compare cm.txt
+
+        79/416 (18.99%) pgs affected
+        281/1392 (20.19%) objects affected
+        80/1248 (6.41%) pg shards to move
+        281/4176 (6.73%) pg object shards to move
+        730.52Mi/10.55Gi (6.76%) bytes to move
+
+When running with **--verbose** option the output will also contain
+detailed information about the affected pgs, like below::
+
+        4.3    [0, 2, 1] -> [1, 4, 2]
+        4.b    [0, 1, 3] -> [2, 1, 3]
+        4.c    [4, 0, 1] -> [4, 1, 2]
+
+i.e. a pg number, and its old and the new osd active sets.
+
+If the result is satisfactory install the updated map::
+
+        crushdiff import cm.txt
+
+
+Availability
+============
+
+**crushdiff** is part of Ceph, a massively scalable, open-source, distributed storage system.  Please
+refer to the Ceph documentation at https://docs.ceph.com for more
+information.
+
+
+See also
+========
+
+:doc:`ceph <ceph>`\(8),
+:doc:`crushtool <crushtool>`\(8),
+:doc:`osdmaptool <osdmaptool>`\(8),

diff --git a/doc/man_index.rst b/doc/man_index.rst
index d89cac2d31055bd7b9d7bb9ad317c433feca24a2..1f786ac8a74317c56aa7ab856943cd89c070c748 100644 (file)
--- a/doc/man_index.rst
+++ b/doc/man_index.rst
@@ -26,6 +26,7 @@
    man/8/cephfs-top
    man/8/cephfs-mirror
    man/8/cephfs-shell
+   man/8/crushdiff
    man/8/crushtool
    man/8/librados-config
    man/8/monmaptool

diff --git a/doc/rados/man/index.rst b/doc/rados/man/index.rst
index 8311bfd5a30c338d1253bb07dc80b6e89e23ddb3..bac56aa4602d2f3946b8fe39753e9e29e1b43c81 100644 (file)
--- a/doc/rados/man/index.rst
+++ b/doc/rados/man/index.rst
@@ -18,6 +18,7 @@
    ../../man/8/ceph-kvstore-tool.rst
    ../../man/8/ceph-run.rst
    ../../man/8/ceph-syn.rst
+   ../../man/8/crushdiff.rst
    ../../man/8/crushtool.rst
    ../../man/8/librados-config.rst
    ../../man/8/monmaptool.rst