ceph/doc/man/8/crushdiff.rst

   1 :orphan:
   2
   3 .. _crushdiff:
   4
   5 =======================================
   6  crushdiff -- ceph crush map test tool
   7 =======================================
   8
   9 .. program:: crushdiff
  10
  11 Synopsis
  12 ========
  13
  14 | **crushdiff** [ --osdmap *osdmap* ] [ --pg-dump *pg-dump* ]
  15   [ --compiled ] [ --verbose ] *command* *crushmap*
  16
  17
  18 Description
  19 ===========
  20
  21 **crushdiff** is a utility that lets you test the effect of a crushmap
  22 change: number of pgs, objects, bytes moved. This is a wrapper around
  23 :doc:`osdmaptool <osdmaptool>`\(8), relying on its **--test-map-pgs-dump**
  24 option to get the list of changed pgs. Additionally it uses pg stats
  25 to calculate the numbers of objects and bytes moved.
  26
  27 By default, **crushdiff** will use the cluster current osdmap and pg
  28 stats, which requires access to the cluster. Though one can use the
  29 **--osdmap** and **--pg-dump** options to test against previously
  30 obtained data.
  31
  32 Options
  33 =======
  34
  35 .. option:: --compiled
  36
  37    The input/output crushmap is compiled. If the options is not
  38    specified the expected/returned crushmap is in txt (decompiled)
  39    format.
  40
  41 .. option:: --pg-dump <pg-dump>
  42
  43    JSON output of **ceph pg dump**. If not specified **crushdiff**
  44    will try to get data running the command itself.
  45
  46 .. option:: --osdmap <osdmap>
  47
  48    The cluster osdmap, obtained with **ceph osd getmap** command. If
  49    not specified **crushdiff** will try to get data running the
  50    command itself.
  51
  52 .. option:: --verbose
  53
  54    Produce diagnostic output.
  55
  56 Commands
  57 ========
  58
  59 :command:`compare` *crushmap*
  60   Compare the crushmap from *crushmap* file with the crushmap from
  61   the cluster osdmap. The output will show the expected number of pgs,
  62   objects, bytes moved when the new crushmap is installed.
  63
  64 :command:`export` *crushmap*
  65   Export crushmap to *crushmap* file from the cluster osdmap.
  66
  67 :command:`import` *crushmap*
  68   Import crushmap from *crushmap* file to the cluster osdmap.
  69
  70 Example
  71 =======
  72
  73 Get the current crushmap::
  74
  75         crushdiff export cm.txt
  76
  77 Edit the map::
  78
  79         $EDITOR cm.txt
  80
  81 Check the result::
  82
  83         crushdiff compare cm.txt
  84
  85         79/416 (18.99%) pgs affected
  86         281/1392 (20.19%) objects affected
  87         80/1248 (6.41%) pg shards to move
  88         281/4176 (6.73%) pg object shards to move
  89         730.52Mi/10.55Gi (6.76%) bytes to move
  90
  91 When running with **--verbose** option the output will also contain
  92 detailed information about the affected pgs, like below::
  93
  94         4.3     [0, 2, 1] -> [1, 4, 2]
  95         4.b     [0, 1, 3] -> [2, 1, 3]
  96         4.c     [4, 0, 1] -> [4, 1, 2]
  97
  98 i.e. a pg number, and its old and the new osd active sets.
  99
 100 If the result is satisfactory install the updated map::
 101
 102         crushdiff import cm.txt
 103
 104
 105 Availability
 106 ============
 107
 108 **crushdiff** is part of Ceph, a massively scalable, open-source, distributed storage system.  Please
 109 refer to the Ceph documentation at https://docs.ceph.com for more
 110 information.
 111
 112
 113 See also
 114 ========
 115
 116 :doc:`ceph <ceph>`\(8),
 117 :doc:`crushtool <crushtool>`\(8),
 118 :doc:`osdmaptool <osdmaptool>`\(8),