man: crushtool, osdmaptool

diff --git a/debian/ceph.install b/debian/ceph.install
index 74ab184236426582f10aee5adbd852ed9b055c5b..bafceac02a67c2de9c96a7fc1e629dd8082ae691 100644 (file)
--- a/debian/ceph.install
+++ b/debian/ceph.install
@@ -21,3 +21,5 @@ usr/share/man/man8/cosd.8
 usr/share/man/man8/mkcephfs.8
 usr/share/man/man8/crun.8
 usr/share/man/man8/csyn.8
+usr/share/man/man8/crushtool.8
+usr/share/man/man8/osdmaptool.8

diff --git a/man/Makefile.am b/man/Makefile.am
index bb8e7a21a073b5a02c9ea47efddd0526b536ea23..ed0b54d995f1452438da41aefdaaf4f694571548 100644 (file)
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,4 +1,4 @@
 AUTOMAKE_OPTIONS = gnu
 
-man_MANS = cosd.8 cmds.8 cmon.8 mkcephfs.8 cfuse.8 csyn.8
-dist_man_MANS = cosd.8 cmds.8 cmon.8 mkcephfs.8 cfuse.8 csyn.8
\ No newline at end of file
+man_MANS = cosd.8 cmds.8 cmon.8 mkcephfs.8 cfuse.8 csyn.8 crushtool.8 osdmaptool.8
+dist_man_MANS = cosd.8 cmds.8 cmon.8 mkcephfs.8 cfuse.8 csyn.8 crushtool.8 osdmaptool.8
\ No newline at end of file

diff --git a/man/crushtool.8 b/man/crushtool.8
new file mode 100644 (file)
index 0000000..228fc0e
--- /dev/null
+++ b/man/crushtool.8
@@ -0,0 +1,73 @@
+.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) preceeding 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 preceeding 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)

diff --git a/man/osdmaptool.8 b/man/osdmaptool.8
new file mode 100644 (file)
index 0000000..914addb
--- /dev/null
+++ b/man/osdmaptool.8
@@ -0,0 +1,50 @@
+.TH OSDMAPTOOL 8
+.SH NAME
+osdmaptool \- ceph osd cluster map manipulation tool
+.SH SYNOPSIS
+.B osdmaptool
+\fImapfilename\fP
+[\fB\-\-print\fR]
+[\fB\-\-createsimple \fInumosd\fR [\fB\-\-pgbits \fIbitsperosd\fR]]
+[\fB\-\-clobber\fR]
+.SH DESCRIPTION
+.B osdmaptool
+is a utility that lets you create, view, and manipulate OSD cluster maps from the
+Ceph distributed file system.  Notably, it lets you extract the embedded CRUSH map
+or import a new CRUSH map.
+.SH OPTIONS
+.TP
+\fB\-\-print\fP
+will simply make the tool print a plaintext dump of the map, after any modifications are made.
+.TP
+\fB\-\-clobber\fP
+will allow
+.B osdmaptool
+to overwrite \fImapfilename\fP if changes are made.
+.TP
+\fB\-\-import-crush\fI mapfile\fP
+will load the CRUSH map from \fImapfile\fP and embed it in the OSD map.
+.TP
+\fB\-\-export-crush\fI mapfile\fP
+will extract the CRUSH map from the OSD map and write it to \fImapfile\fP.
+.TP
+\fB\-\-createsimple\fI numosd\fP [\fB\-\-pgbits \fIbitsperosd\fR]
+will create a relatively generic OSD map with the \fInumosd\fP devices.  If \fB\-\-pgbits\fP 
+is specified, the initial placement group counts will be set with \fIbitsperosd\fP bits per OSD.
+That is, the \fIpg_num\fP map attribute will be set to \fInumosd\fP shifted by \fIbitsperosd\fP.
+.SH EXAMPLE
+To create a simple map with 16 devices:
+.IP
+osdmaptool --createsimple 16 osdmap --clobber
+.PP
+To view the result:
+.IP
+osdmaptool --print osdmap
+.SH AVAILABILITY
+.B osdmaptool
+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 crushtool (8),
+.BR mkcephfs (8)