Provided by: ceph_10.1.2-0ubuntu1_amd64 bug

NAME

       crushtool - CRUSH map manipulation tool

SYNOPSIS

       crushtool ( -d map | -c map.txt | --build --num_osds numosds
       layer1 ... | --test ) [ -o outfile ]

DESCRIPTION

       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
       (typically data objects) 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):
          http://www.ssrc.ucsc.edu/Papers/weil-sc06.pdf

       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 take the compiled map and decompile it into a plaintext source file,  suitable
              for editing.

       --build --num_osds {num-osds} layer1 ...
              will  create  map  with  the  given  layer  structure.  See  below  for  a detailed
              explanation.

       --test will perform a dry run of a CRUSH mapping for a range of input  object  names.  See
              below for a detailed explanation.

       Unlike  other  Ceph tools, crushtool does not accept generic options such as --debug-crush
       from the command line. They can,  however,  be  provided  via  the  CEPH_ARGS  environment
       variable. For instance, to silence all output from the CRUSH subsystem:

          CEPH_ARGS="--debug-crush 0" crushtool ...

RUNNING TESTS WITH --TEST

       The  test mode will use the input crush map ( as specified with -i map ) and perform a dry
       run of CRUSH mapping or random placement ( if --simulate is  set  ).  On  completion,  two
       kinds  of  reports  can  be  created.   1)  The  --show-...  option outputs human readable
       information on stderr.  2) The --output-csv option creates CSV files that  are  documented
       by the --help-output option.

       --show-statistics
              For each rule, displays the mapping of each object. For instance:

                 CRUSH rule 1 x 24 [11,6]

              shows  that  object  24  is  mapped  to devices [11,6] by rule 1. At the end of the
              mapping details, a summary of the distribution is displayed. For instance:

                 rule 1 (metadata) num_rep 5 result size == 5:    1024/1024

              shows that rule 1 which is named  metadata  successfully  mapped  1024  objects  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:

                 rule 1 (metadata) num_rep 10 result size == 8:   4/1024
                 rule 1 (metadata) num_rep 10 result size == 9:   93/1024
                 rule 1 (metadata) num_rep 10 result size == 10:  927/1024

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

       --show-bad-mappings
              Displays which object 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]

              shows  that  when  rule  1  was  required to map 7 devices, it could map only six :
              [8,10,2,11,6,9].

       --show-utilization
              Displays the expected and actual utilisation 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 objects and was expected to store 853.  Implies
              --show-statistics.

       --show-utilization-all
              Displays the same as --show-utilization but  does  not  suppress  output  when  the
              weight of a device is zero.  Implies --show-statistics.

       --show-choose-tries
              Displays how many attempts were needed to find a device mapping.  For instance:

                 0:     95224
                 1:      3745
                 2:      2225
                 ..

              shows  that  95224 mappings succeeded without retries, 3745 mappings succeeded with
              one  attempts,  etc.   There   are   as   many   rows   as   the   value   of   the
              --set-choose-total-tries option.

       --output-csv
              Creates  CSV  files (in the current directory) containing information documented by
              --help-output. The files  are  named  after  the  rule  used  when  collecting  the
              statistics. For instance, if the rule : 'metadata' is used, the CSV files will be:

                 metadata-absolute_weights.csv
                 metadata-device_utilization.csv
                 ...

              The first line of the file shortly explains the column layout. For instance:

                 metadata-absolute_weights.csv
                 Device ID, Absolute Weight
                 0,1
                 ...

       --output-name NAME
              Prepend  NAME  to  the  file  names  generated  when --output-csv is specified. For
              instance --output-name FOO will create files:

                 FOO-metadata-absolute_weights.csv
                 FOO-metadata-device_utilization.csv
                 ...

       The --set-... options can be used to modify the tunables of the input crush map. The input
       crush map is modified in memory. For example:

          $ crushtool -i mymap --test --show-bad-mappings
          bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9]

       could be fixed by increasing the choose-total-tries as follows:

          $ crushtool -i mymap --test
                 --show-bad-mappings --set-choose-total-tries 500

BUILDING A MAP WITH --BUILD

       The build mode will generate hierarchical maps. The first argument specifies the number of
       devices (leaves) in the CRUSH hierarchy. Each layer describes how the layer  (or  devices)
       preceding it should be grouped.

       Each layer consists of:

          bucket ( uniform | list | tree | straw ) size

       The bucket is the type of the buckets in the layer (e.g. "rack"). Each bucket name will be
       built by appending a unique number to the bucket string (e.g. "rack0", "rack1"...).

       The second component is the type of bucket: straw should be used most of the time.

       The third component is the maximum size of the bucket. A size of zero means  a  bucket  of
       infinite capacity.

EXAMPLE

       Suppose  we  have  two  rows  with two racks each and 20 nodes per rack. Suppose each node
       contains 4 storage devices for Ceph OSD Daemons. This configuration allows  us  to  deploy
       320 Ceph OSD Daemons. Lets assume a 42U rack with 2U nodes, leaving an extra 2U for a rack
       switch.

       To reflect our hierarchy  of  devices,  nodes,  racks  and  rows,  we  would  execute  the
       following:

          $ crushtool -o crushmap --build --num_osds 320 \
                 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  rulesets  are  created  so  the generated crushmap can be tested. They are the same
       rulesets as the one 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

AVAILABILITY

       crushtool  is part of Ceph, a massively scalable, open-source, distributed storage system.
       Please refer to the Ceph documentation at http://ceph.com/docs for more information.

SEE ALSO

       ceph(8), osdmaptool(8),

AUTHORS

       John Wilkins, Sage Weil, Loic Dachary

COPYRIGHT

       2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA