crushtool man page

crushtool — CRUSH map manipulation tool




crushtool is a utility that lets you create, compile, decompile and test CRUSH map files.

CRUSH is a pseudo-random data distribution algorithm that efficiently maps input values (which, in the context of Ceph, correspond to Placement Groups) across a heterogeneous, hierarchically structured device map. The algorithm was originally described in detail in the following paper (although it has evolved some since then):

The tool has four modes of operation.

--compile|-c map.txt

will compile a plaintext map.txt into a binary map file.

--decompile|-d map





will perform a dry run of a CRUSH mapping for a range of input values [--min-x,--max-x] (default [0,1023]) which can be thought of as simulated Placement Groups. See below for a more detailed explanation.



Running Tests with --test


Note: Each Placement Group (PG) has an integer ID which can be obtained from ceph pg dump (for example PG 2.2f means pool id 2, PG id 32). The pool and PG IDs are combined by a function to get a value which is given to CRUSH to map it to OSDs. crushtool does not know about PGs or pools; it only runs simulations by mapping values in the range [--min-x,--max-x].


Displays a summary of the distribution. For instance:


shows that rule 1 which is named metadata successfully mapped 1024 values to result size == 5 devices when trying to map them to num_rep 5 replicas. When it fails to provide the required mapping, presumably because the number of tries must be increased, a breakdown of the failures is displayed. For instance:


shows that although num_rep 10 replicas were required, 4 out of 1024 values ( 4/1024 ) were mapped to result size == 8 devices only.


Displays the mapping of each value in the range [--min-x,--max-x]. For instance:

CRUSH rule 1 x 24 [11,6]

shows that value 24 is mapped to devices [11,6] by rule 1.


Displays which value failed to be mapped to the required number of devices. For instance:

bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9]



Displays the expected and actual utilization for each device, for each number of replicas. For instance:

device 0: stored : 951      expected : 853.333
device 1: stored : 963      expected : 853.333

shows that device 0 stored 951 values and was expected to store 853. Implies --show-statistics.





0:     95224
1:      3745
2:      2225






Device ID, Absolute Weight
--output-name NAME




bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9]


$ crushtool -i mymap --test


Building a Map with --build


Each layer consists of:

bucket ( uniform | list | tree | straw ) size







       node straw 4 \
       rack straw 20 \
       row straw 2 \
       root straw 0
# id        weight  type name       reweight
-87 320     root root
-85 160             row row0
-81 80                      rack rack0
-1  4                               node node0
0   1                                       osd.0   1
1   1                                       osd.1   1
2   1                                       osd.2   1
3   1                                       osd.3   1
-2  4                               node node1
4   1                                       osd.4   1
5   1                                       osd.5   1

CRUSH rules are created so the generated crushmap can be tested. They are the same rules as the ones created by default when creating a new Ceph cluster. They can be further edited with:

# decompile
crushtool -d crushmap -o map.txt

# edit
emacs map.txt

# recompile
crushtool -c map.txt -o crushmap


The reclassify function allows users to transition from older maps that maintain parallel hierarchies for OSDs of different types to a modern CRUSH map that makes use of the device class feature.  For more information, see

Example Output from --test

See for sample crushtool --test commands and output produced thereby.



See Also

ceph(8), osdmaptool(8),


John Wilkins, Sage Weil, Loic Dachary

Referenced By

monmaptool(8), osdmaptool(8).

Jan 09, 2020 dev Ceph