From 2764df209e71b71a3a6a363d568044fa35b6a911 Mon Sep 17 00:00:00 2001 From: Sage Weil Date: Tue, 10 Mar 2009 20:38:47 -0700 Subject: [PATCH] man: crushtool, osdmaptool --- debian/ceph.install | 2 ++ man/Makefile.am | 4 +-- man/crushtool.8 | 73 +++++++++++++++++++++++++++++++++++++++++++++ man/osdmaptool.8 | 50 +++++++++++++++++++++++++++++++ 4 files changed, 127 insertions(+), 2 deletions(-) create mode 100644 man/crushtool.8 create mode 100644 man/osdmaptool.8 diff --git a/debian/ceph.install b/debian/ceph.install index 74ab1842364..bafceac02a6 100644 --- 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 bb8e7a21a07..ed0b54d995f 100644 --- 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 index 00000000000..228fc0e5c61 --- /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 index 00000000000..914addb96f5 --- /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)