.TH CRUSHTOOL 8
.SH NAME
crushtool \- CRUSH map manipulation tool
.SH SYNOPSIS
.B crushtool
( \fB\-d\fI map\fP | \fB\-c\fI map.txt\fP | \fB\-\-build\fI numosds layer1 ...\fP )
[ \fB\-o\fI outfile\fP [ \fB\-\-clobber\fP ]]
.SH DESCRIPTION
.B crushtool
is a utility that lets you create, compile, and decompile CRUSH map files.
.PP
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):
.IP
http://www.ssrc.ucsc.edu/Papers/weil-sc06.pdf
.PP
The tool has three modes of operation.
.TP
\fB\-c\fI map.txt\fP
will compile a plaintext \fImap.txt\fP into a binary map file.
.TP
\fB\-d\fI map\fP
will take the compiled \fImap\fP and decompile it into a plaintext source file,
suitable for editing.
.TP
\fB\-\-build\fI numosds layer1 ...\fP
will create a relatively generic map with the given layer structure.  See below for examples.
.SH OPTIONS
.TP
\fB\-o\fI outfile\fP
will specify the output file.
.TP
\fB\-\-clobber\fP
will allow the tool to overwrite an existing \fIoutfile\fP (it will normally refuse).
.SH BUILDING A MAP
The build mode will generate relatively generic hierarchical maps.  The first argument simply
specifies the number of devices (leaves) in the CRUSH hierarchy.  Each layer describes how the 
layer (or raw devices) preceding it should be grouped.
.PP
Each \fIlayer\fP consists of
.IP
\fIname\fP ( uniform | list | tree | straw ) \fIsize\fP
.PP
The first element is the \fIname\fP for the elements in the layer (e.g. "rack").  Each element's
name will be append a number to the provided \fIname\fP.
.PP
The second component is the type of CRUSH bucket.  
.PP
The third component is the maximum size of the bucket.  If the size is \fI0\fP, a single bucket
will be generated that includes everything in the preceding layer.
.SH EXAMPLE
Suppose we have 128 devices, each grouped into shelves with 4 devices each, and 8 shelves per
rack.  We could create a three level hierarchy with:
.IP
crushtool --build 128 shelf uniform 4 rack straw 8 root straw 0 -o map
.PP
To adjust the default (generic) mapping rules, we can
.IP
crushtool -d map -o map.txt  # decompile
.IP
vi map.txt                   # edit
.IP
crushtool -c map.txt -o map  # recompile
.SH AVAILABILITY
.B crushtool
is part of the Ceph distributed file system.  Please refer to the Ceph wiki at
http://ceph.newdream.net/wiki for more information.
.SH SEE ALSO
.BR ceph (8),
.BR osdmaptool (8),
.BR mkcephfs (8)