From dd8848f088875029feed8595594febbaf9ff86b7 Mon Sep 17 00:00:00 2001 From: Joe Thornber Date: Wed, 20 Sep 2017 11:15:00 +0100 Subject: [PATCH] [manpages] Rewrite man pages in a simpler text format. Makefile still needs work, but I wanted to commit to save progress. --- .gitignore | 4 + Makefile.in | 37 +++- bin/txt2man | 365 +++++++++++++++++++++++++++++++++++ man8/cache_check.8 | 68 ------- man8/cache_check.txt | 40 ++++ man8/cache_dump.8 | 64 ------ man8/cache_dump.txt | 41 ++++ man8/cache_metadata_size.8 | 43 ----- man8/cache_metadata_size.txt | 31 +++ man8/cache_repair.8 | 64 ------ man8/cache_repair.txt | 38 ++++ man8/cache_restore.8 | 78 -------- man8/cache_restore.txt | 47 +++++ man8/cache_writeback.8 | 60 ------ man8/cache_writeback.txt | 34 ++++ man8/era_check.8 | 59 ------ man8/era_check.txt | 33 ++++ man8/era_dump.8 | 61 ------ man8/era_dump.txt | 40 ++++ man8/era_invalidate.8 | 54 ------ man8/era_invalidate.txt | 37 ++++ man8/era_restore.8 | 64 ------ man8/era_restore.txt | 40 ++++ man8/thin_check.8 | 67 ------- man8/thin_check.txt | 43 +++++ man8/thin_delta.8 | 48 ----- man8/thin_delta.txt | 33 ++++ man8/thin_dump.8 | 94 --------- man8/thin_dump.txt | 68 +++++++ man8/thin_ls.8 | 48 ----- man8/thin_ls.txt | 36 ++++ man8/thin_metadata_size.8 | 79 -------- man8/thin_metadata_size.txt | 75 +++++++ man8/thin_repair.8 | 66 ------- man8/thin_repair.txt | 40 ++++ man8/thin_restore.8 | 67 ------- man8/thin_restore.txt | 42 ++++ man8/thin_rmap.8 | 50 ----- man8/thin_rmap.txt | 37 ++++ man8/thin_trim.8 | 37 ---- man8/thin_trim.txt | 23 +++ 41 files changed, 1182 insertions(+), 1173 deletions(-) create mode 100755 bin/txt2man delete mode 100644 man8/cache_check.8 create mode 100644 man8/cache_check.txt delete mode 100644 man8/cache_dump.8 create mode 100644 man8/cache_dump.txt delete mode 100644 man8/cache_metadata_size.8 create mode 100644 man8/cache_metadata_size.txt delete mode 100644 man8/cache_repair.8 create mode 100644 man8/cache_repair.txt delete mode 100644 man8/cache_restore.8 create mode 100644 man8/cache_restore.txt delete mode 100644 man8/cache_writeback.8 create mode 100644 man8/cache_writeback.txt delete mode 100644 man8/era_check.8 create mode 100644 man8/era_check.txt delete mode 100644 man8/era_dump.8 create mode 100644 man8/era_dump.txt delete mode 100644 man8/era_invalidate.8 create mode 100644 man8/era_invalidate.txt delete mode 100644 man8/era_restore.8 create mode 100644 man8/era_restore.txt delete mode 100644 man8/thin_check.8 create mode 100644 man8/thin_check.txt delete mode 100644 man8/thin_delta.8 create mode 100644 man8/thin_delta.txt delete mode 100644 man8/thin_dump.8 create mode 100644 man8/thin_dump.txt delete mode 100644 man8/thin_ls.8 create mode 100644 man8/thin_ls.txt delete mode 100644 man8/thin_metadata_size.8 create mode 100644 man8/thin_metadata_size.txt delete mode 100644 man8/thin_repair.8 create mode 100644 man8/thin_repair.txt delete mode 100644 man8/thin_restore.8 create mode 100644 man8/thin_restore.txt delete mode 100644 man8/thin_rmap.8 create mode 100644 man8/thin_rmap.txt delete mode 100644 man8/thin_trim.8 create mode 100644 man8/thin_trim.txt diff --git a/.gitignore b/.gitignore index 47e6166..8f5a52f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *~ +*.tmp *.swp *.swo *.o @@ -7,12 +8,15 @@ *.gmo *_t *.d +*.8 *.d.[0-9]* test.data cachegrind.* \#*\# core +googletest/ + bin/pdata_tools thin_check thin_dump diff --git a/Makefile.in b/Makefile.in index e2f38d7..3ec7925 100644 --- a/Makefile.in +++ b/Makefile.in @@ -193,7 +193,7 @@ else TEST_INCLUDES= endif -.SUFFIXES: .d +.SUFFIXES: .d .txt .8 %.o: %.cc @echo " [CXX] $<" @@ -203,6 +203,10 @@ endif sed 's,\([^ :]*\)\.o[ :]*,\1.o \1.gmo $* : Makefile ,g' < $*.$$$$ > $*.d; \ $(RM) $*.$$$$ +%.8: %.txt bin/txt2man + @echo " [txt2man] $<" + $(V) bin/txt2man -p -t $(basename $(notdir $<)) $< > $@ + #---------------------------------------------------------------- lib/libpdata.a: $(OBJECTS) $(EMITTERS) @@ -232,7 +236,36 @@ clean: distclean: clean $(RM) config.cache config.log config.status configure.h version.h Makefile unit-tests/Makefile -install: bin/pdata_tools +TOOLS:=\ + cache_check \ + cache_dump \ + cache_metadata_size \ + cache_repair \ + cache_restore \ + cache_writeback \ + thin_check \ + thin_delta \ + thin_dump \ + thin_ls \ + thin_repair \ + thin_restore \ + thin_rmap \ + thin_metadata_size \ + thin_trim \ + era_check \ + era_dump \ + era_invalidate \ + era_restore \ +ifeq ("@DEVTOOLS", "yes") + thin_show_duplicates \ + thin_ll_dump \ + thin_generate_metadata \ + thin_scan +endif + +MANPAGES:=$(patsubst %,man8/%.8,$(TOOLS)) + +install: bin/pdata_tools $(MANPAGES) $(INSTALL_DIR) $(BINDIR) $(INSTALL_PROGRAM) bin/pdata_tools $(BINDIR) $(STRIP) $(BINDIR)/pdata_tools diff --git a/bin/txt2man b/bin/txt2man new file mode 100755 index 0000000..71697ed --- /dev/null +++ b/bin/txt2man @@ -0,0 +1,365 @@ +#!/bin/sh +test "$HOME" = ~ || exec ksh $0 "$@" # try ksh if sh too old (not yet POSIX) + +# Copyright (C) 2001, 2002, 2003 Marc Vertes + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +# 02111-1307, USA. + +# txt2man-1.5 + +usage() +{ +cat << EOT +NAME + txt2man - convert flat ASCII text to man page format +SYNOPSIS + txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect] + [-v vol] [-I txt] [-B txt] [ifile] +DESCRIPTION + txt2man converts the input text into nroff/troff standard man(7) + macros used to format Unix manual pages. Nice pages can be generated + specially for commands (section 1 or 8) or for C functions reference + (sections 2, 3), with the ability to recognize and format command and + function names, flags, types and arguments. + + txt2man is also able to recognize and format sections, paragraphs, + lists (standard, numbered, description, nested), cross references and + literal display blocks. + + If input file ifile is omitted, standard input is used. Result is + displayed on standard output. + + Here is how text patterns are recognized and processed: + Sections These headers are defined by a line in upper case, starting + column 1. If there is one or more leading spaces, a + sub-section will be generated instead. + Paragraphs They must be separated by a blank line, and left aligned. + Tag list The item definition is separated from the item description + by at least 2 blank spaces, even before a new line, if + definition is too long. Definition will be emphasized + by default. + Bullet list + Bullet list items are defined by the first word being "-" + or "*" or "o". + Enumerated list + The first word must be a number followed by a dot. + Literal display blocks + This paragraph type is used to display unmodified text, + for example source code. It must be separated by a blank + line, and be indented. It is primarily used to format + unmodified source code. It will be printed using fixed font + whenever possible (troff). + Cross references + A cross reference (another man page) is defined by a word + followed by a number in parenthesis. + + Special sections: + NAME The function or command name and short description are set in + this section. + SYNOPSIS This section receives a special treatment to identify command + name, flags and arguments, and propagate corresponding + attributes later in the text. If a C like function is recognized + (word immediately followed by an open parenthesis), txt2man will + print function name in bold font, types in normal font, and + variables in italic font. The whole section will be printed using + a fixed font family (courier) whenever possible (troff). + + It is a good practice to embed documentation into source code, by using + comments or constant text variables. txt2man allows to do that, keeping + the document source readable, usable even without further formatting + (i.e. for online help) and easy to write. The result is high quality + and standard complying document. +OPTIONS + -h The option -h displays help. + -P pname Set pname as project name in header. Default to uname -s. + -p Probe title, section name and volume. + -t mytitle Set mytitle as title of generated man page. + -r rel Set rel as project name and release. + -s sect Set sect as section in heading, ususally a value from 1 to 8. + -v vol Set vol as volume name, i.e. "Unix user 's manual". + -I txt Italicize txt in output. Can be specified more than once. + -B txt Emphasize (bold) txt in output. Can be specified more than once. + -T Text result previewing using PAGER, usually more(1). + -X X11 result previewing using gxditview(1). +ENVIRONMENT + PAGER name of paging command, usually more(1), or less(1). If not set + falls back to more(1). +EXAMPLE + Try this command to format this text itself: + + $ txt2man -h 2>&1 | txt2man -T +HINTS + To obtain an overall good formating of output document, keep paragraphs + indented correctly. If you have unwanted bold sections, search for + multiple spaces between words, which are used to identify a tag list + (term followed by a description). Choose also carefully the name of + command line or function parameters, as they will be emphasized each + time they are encountered in the document. +SEE ALSO + man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1). +BUGS + - Automatic probe (-p option) works only if input is a regular file (i.e. + not stdin). +AUTHOR + Marc Vertes +EOT +} + +sys=$(uname -s) +rel= +volume= +section= +title=untitled +doprobe= +itxt= +btxt= +post=cat +while getopts :hpTXr:s:t:v:P:I:B: opt +do + case $opt in + r) rel=$OPTARG;; + t) title=$OPTARG;; + s) section=$OPTARG;; + v) volume=$OPTARG;; + P) sys=$OPTARG;; + p) doprobe=1;; + I) itxt="$OPTARG§$itxt";; + B) btxt=$OPTARG;; + T) post="groff -mandoc -Tlatin1 | ${PAGER:-more}";; + X) post="groff -mandoc -X";; + *) usage; exit;; + esac +done +shift $(($OPTIND - 1)) + +if test "$doprobe" +then + title=${1##*/}; title=${title%.txt} + section="8" + volume="System Manager's Manual" + # get release from path + #rel=$(pwd | sed 's:/.*[^0-9]/::g; s:/.*::g') + rel="Device Mapper Tools" +fi + +head=".\\\" Text automatically generated by txt2man +.TH $title $section \"$rel\" \"$volume\"" + +# All tabs converted to spaces +expand $* | +# gawk is needed because use of non standard regexp +gawk --re-interval -v head="$head" -v itxt="$itxt" -v btxt="$btxt" ' +BEGIN { + print head + avar[1] = btxt; avar[2] = itxt + for (k in avar) { + mark = (k == 1) ? "\\fB" : "\\fI" + split(avar[k], tt, "§") + for (i in tt) + if (tt[i] != "") + subwords["\\<" tt[i] "\\>"] = mark tt[i] "\\fP" + for (i in tt) + delete tt[i] + } + for (k in avar) + delete avar[k] +} +{ + # to avoid some side effects in regexp + sub(/\.\.\./, "\\.\\.\\.") + # remove spaces in empty lines + sub(/^ +$/,"") +} +/^[[:upper:][:space:]]+$/ { + # Section header + if ((in_bd + 0) == 1) { + in_bd = 0 + print ".fam T\n.fi" + } + if (section == "SYNOPSIS") { + print ".fam T\n.fi" + type["SYNOPSIS"] = "" + } + if ($0 ~/^[^[:space:]]/) + print ".SH " $0 + else + print ".SS" $0 + sub(/^ +/, "") + section = $0 + if (section == "SYNOPSIS") + print ".nf\n.fam C" + ls = 0 # line start index + pls = 0 # previous line start index + pnzls = 0 # previous non zero line start index + ni = 0 # indent level + ind[0] = 0 # indent offset table + prevblankline = 0 + next +} +{ + # Compute line start index, handle start of example display block + pls = ls + if (ls != 0) + pnzls = ls + match($0, /[^ ]/) + ls = RSTART + if (pls == 0 && pnzls > 0 && ls > pnzls && $1 !~ /^[0-9\-\*\o]\.*$/) { + # example display block + if (prevblankline == 1) { + print ".PP" + prevblankline = 0 + } + print ".nf\n.fam C" + in_bd = 1 + eoff = ls + } + if (ls > 0 && ind[0] == 0) + ind[0] = ls +} +(in_bd + 0) == 1 { + # In example display block + if (ls != 0 && ls < eoff) { + # End of litteral display block + in_bd = 0 + print ".fam T\n.fi" + } else { print; next } +} +section == "NAME" { + $1 = "\\fB" $1 + sub(/ \- /, " \\fP- ") +} +section == "SYNOPSIS" { + # Identify arguments of fcts and cmds + if (type["SYNOPSIS"] == "") { + if (index($0, "(") == 0 && index($0, ")") == 0 && + index($0, "#include") == 0) + type["SYNOPSIS"] = "cmd" + else + type["SYNOPSIS"] = "fct" + } + if (type["SYNOPSIS"] == "cmd") { + # Line is a command line + if ($1 !~ /^\[/) { + b = $1 + sub(/^\*/, "", b) + subwords["\\<" b "\\>"] = "\\fB" b "\\fP" + } + for (i = 2; i <= NF; i++) { + a = $i + gsub(/[\[\]\|]/, "", a) + if (a ~ /^[^\-]/) + subwords["\\<" a "\\>"] = "\\fI" a "\\fP" + } + } else { + # Line is a C function definition + if ($1 == "typedef") + subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP" + else if ($1 == "#define") + subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP" + for (i = 1; i <= NF; i++) { + if ($i ~ /[\,\)]/) { + a = $i + sub(/.*\(/, "", a) + gsub(/\W/, "", a) + if (a !~ /^void$/) + subwords["\\<" a "\\>"] = "\\fI" a "\\fP" + } + } + } +} +{ + # protect dots inside words + while ($0 ~ /\w\.\w/) + sub(/\./, "_dOt_") + # identify func calls and cross refs + for (i = 1; i <= NF; i++) { + b = $i + sub(/^\*/, "", b) + if ((a = index(b, ")(")) > 3) { + w = substr(b, 3, a - 3) + subwords["\\<" w "\\>"] = "\\fI" w "\\fP" + } + if ((a = index(b, "(")) > 1) { + w = substr(b, 1, a - 1) + subwords["\\<" w "\\("] = "\\fB" w "\\fP(" + } + } + # word attributes + for (i in subwords) + gsub(i, subwords[i]) + # shell options + gsub(/\B\-+\w+(\-\w+)*/, "\\fB&\\fP") + # unprotect dots inside words + gsub(/_dOt_/, ".") + + if (match($0, /[^ ] +/) > 0) { + # tag list item + adjust_indent() + tag = substr($0, 1, RSTART) + sub(/^ */, "", tag) + if (RSTART+RLENGTH < length()) + $0 = substr($0, RSTART + RLENGTH) + else + $0 = "" + print ".TP\n.B" + print tag + prevblankline = 0 + if (NF == 0) + next + } else if ($1 == "-"||$1 == "o"||$1 == "*") { + # bullet list item + adjust_indent() + print ".IP \\(bu 3" + prevblankline = 0 + $1 = "" + } else if ($1 ~ /^[0-9]+[\).]$/) { + # enum list item + adjust_indent() + print ".IP " $1 " 4" + prevblankline = 0 + $1 = "" + } else if (pls == 0) { + # new paragraph + adjust_indent() + } else if (NF == 0) { + # blank line + prevblankline = 1 + next + } else + prevblankline = 0 + # flush vertical space + if (prevblankline == 1) { + print ".PP" + prevblankline = 0 + } + if (section != "SYNOPSIS" || $0 ~ /^ {1,4}/) + sub(/ */,"") + print +} + +function adjust_indent() +{ + if (ls > ind[ni]) { + ind[++ni] = ls + print ".RS" + } else if (ls < ind[ni]) { + while (ls < ind[ni]) { + ni-- + print ".RE" + } + } +} +' | eval $post diff --git a/man8/cache_check.8 b/man8/cache_check.8 deleted file mode 100644 index 0a48944..0000000 --- a/man8/cache_check.8 +++ /dev/null @@ -1,68 +0,0 @@ -.TH CACHE_CHECK 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -cache_check \- repair cache metadata on device or file - -.SH SYNOPSIS -.B cache_check -.RB [ options ] -.I {device|file} - -.SH DESCRIPTION -.B cache_check -checks cache metadata created by -the device-mapper cache target on a -.I device -or -.I file. - -This tool cannot be run on live metadata. - -.SH OPTIONS -.IP "\fB\-q, \-\-quiet\fP" -Suppress output messages, return only exit code. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.IP "\fB\-\-super\-block\-only\fP" -Only check the superblock is present. - -.IP "\fB\-\-skip-mappings\fP" -Skip checking of the block mappings which make up the bulk of the -metadata. - -.IP "\fB\-\-skip-hints\fP" -Skip checking of the policy hint values metadata. - -.IP "\fB\-\-skip-discards\fP" -Skip checking of the discard bits in the metadata. - -.IP "\fB\-\-clear\-needs\-check\-flag\fP" -The kernel may set a flag to force the pool to be checked before it's next -activated. Set this switch to clear the flag if the check is successful. - -.SH EXAMPLE -Analyses and repairs cache metadata on logical volume -/dev/vg/metadata: -.sp -.B cache_check /dev/vg/metadata - -The device may not be actively used by the target -when running. - -.SH DIAGNOSTICS -.B cache_check -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B cache_dump(8) -.B cache_repair(8) -.B cache_restore(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/cache_check.txt b/man8/cache_check.txt new file mode 100644 index 0000000..b1bb320 --- /dev/null +++ b/man8/cache_check.txt @@ -0,0 +1,40 @@ +NAME + cache_check - validates cache metadata on a device or file. + +SYNOPSIS + cache_check [options] {device|file} + +DESCRIPTION + cache_check checks cache metadata created by the device-mapper cache target + on a device or file. + + This tool cannot be run on live metadata. + +OPTIONS + -q, --quiet Suppress output messages, return only exit code. + -h, --help Print help and exit. + -V, --version Output version information and exit. + --super-block-only Only check the superblock. + --skip-hints Skip checking of the policy hint values metadata. + --skip-discards Skip checking of the discard bits in the metadata. + --clear-needs-check-flag Clears the 'needs_check' flag in the superblock. + + The kernel may set a flag to force the pool to be checked before it's next + activated. Set this switch to clear the flag if the check is successful. + +EXAMPLE + Analyses and repairs cache metadata on logical volume /dev/vg/metadata: + + $ cache_check /dev/vg/metadata + + The device may not be actively used by the target when running. + +DIAGNOSTICS + cache_check returns an exit code of 0 for success or 1 for error. + +SEE ALSO + cache_dump(8), cache_repair(8), cache_restore(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/cache_dump.8 b/man8/cache_dump.8 deleted file mode 100644 index 0f55578..0000000 --- a/man8/cache_dump.8 +++ /dev/null @@ -1,64 +0,0 @@ -.TH CACHE_DUMP 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -cache_dump \- dump cache metadata from device or file to standard output - -.SH SYNOPSIS -.B cache_dump -.RB [options] -.I {device|file} - -.SH DESCRIPTION -.B cache_dump -dumps binary cache metadata created by -the device-mapper cache target on a -.I device -or -.I file -to standard output for -analysis or postprocessing in XML format. -XML formated metadata can be fed into cache_restore (see -.BR cache_restore(8) ) -in order to put it back onto a metadata -.I device -(to process by the device-mapper target) or -.I file. - -This tool cannot be run on live metadata. - -.IP "\fB\-r, \-\-repair\fP". -Repair the metadata whilst dumping it. - -.IP "\fB\-h, \-\-help\fP". -Print help and exit. - -.IP "\fB-o \\fP". -Specify an output file for the xml, rather than printing to stdout. - -.IP "\fB\-V, \-\-version\fP". -Output version information and exit. - -.SH EXAMPLES -Dumps the cache metadata on logical volume /dev/vg/metadata -to standard output in XML format: -.sp -.B cache_dump /dev/vg/metadata - -.SH EXAMPLES -Dumps the cache metadata on logical volume /dev/vg/metadata -whilst repairing it to standard output in XML format: -.sp -.B cache_dump --repair /dev/vg/metadata - -.SH DIAGNOSTICS -.B cache_dump -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B cache_check(8) -.B cache_repair(8) -.B cache_restore(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/cache_dump.txt b/man8/cache_dump.txt new file mode 100644 index 0000000..d915596 --- /dev/null +++ b/man8/cache_dump.txt @@ -0,0 +1,41 @@ +NAME + cache_dump - dump cache metadata from device or file to standard output. + +SYNOPSIS + cache_dump [options] {device|file} + +DESCRIPTION + cache_dump dumps binary cache metadata created by the device-mapper cache + target on a device or file to standard output for analysis or postprocessing + in XML format. XML formatted metadata can be fed into cache_restore in order + to put it back onto a metadata device (to process by the device-mapper + target), or file. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -r, --repair Repair the metadata whilst dumping it. + -o {xml file> Specify an output file for the xml, rather than printing to stdout. + +EXAMPLES + Dumps the cache metadata on logical volume /dev/vg/metadata to standard + output in XML format: + + $ cache_dump /dev/vg/metadata + + Dumps the cache metadata on logical volume /dev/vg/metadata whilst repairing + it to standard output in XML format: .sp + + $ cache_dump --repair /dev/vg/metadata + +DIAGNOSTICS + cache_dump returns an exit code of 0 for success or 1 for error. + +SEE ALSO + cache_check(8), cache_repair(8), cache_restore(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/cache_metadata_size.8 b/man8/cache_metadata_size.8 deleted file mode 100644 index af72ad1..0000000 --- a/man8/cache_metadata_size.8 +++ /dev/null @@ -1,43 +0,0 @@ -.TH CACHE_METADATA_SIZE 8 "Thin Provisioning Tools" "Red Hat, Inc." -.SH NAME -cache_metadata_size \- Estimate the size of the metadata device needed for a given configuration - -.SH SYNOPSIS -.B cache_metadata_size -.RB [ options ] - -.SH DESCRIPTION -.B cache_metadata_size -estimates the size of the metadata. Either \-\-nr\-blocks, or \-\-block\-size -and \-\-device\-size must be specified. - -.SH OPTIONS -.IP "\fB\-\-nr\-blocks\fP \" -Specify the number of cache blocks. - -.IP "\fB\-\-block-size\fP \" -Specify the size of each cache block in 512 byte sectors. - -.IP "\fB\-\-device\-size\fP \" -Specify total size of the fast device used in the cache. In 512 byte sectors. - -.IP "\fB\-\-max\-hint\-width\fP \" -Cache policies use a per block 'hint' to record extra info (for instance hit -counts). At the moment all policies use a 4 byte hint width. If you want to use -a different hint width specify it with this switch. - -.SH EXAMPLE -.B cache_metadata_size --nr-blocks 10240 -.sp -.B cache_metadata_size --block-size 128 --device-size 1024000 - -.SH SEE ALSO -.B cache_dump(8) -.B cache_repair(8) -.B cache_restore(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen - diff --git a/man8/cache_metadata_size.txt b/man8/cache_metadata_size.txt new file mode 100644 index 0000000..ac5a5a4 --- /dev/null +++ b/man8/cache_metadata_size.txt @@ -0,0 +1,31 @@ +NAME + cache_metadata_size - Estimate the size of the metadata device needed for a given configuration. + +SYNOPSIS + cache_metadata_size [options] + +DESCRIPTION + cache_metadata_size estimates the size of the metadata. Either --nr-blocks, + or --block-size and --device-size must be specified. + +OPTIONS + --nr-blocks {natural} Specify the number of cache blocks. + --block-size {sectors} Specify the size of each cache block in 512 byte sectors. + --device-size {sectors} Specify total size of the fast device used in the cache. In 512 byte sectors. + --max-hint-width {nr bytes} Specify hint width. + + Cache policies use a per block 'hint' to record extra info (for instance + hit counts). At the moment all policies use a 4 byte hint + width. If you want to use a different hint width specify it with this + switch. + +EXAMPLE + $ cache_metadata_size --nr-blocks 10240 + $ cache_metadata_size --block-size 128 --device-size 1024000 + +SEE ALSO + cache_dump(8), cache_repair(8), cache_restore(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/cache_repair.8 b/man8/cache_repair.8 deleted file mode 100644 index f701e77..0000000 --- a/man8/cache_repair.8 +++ /dev/null @@ -1,64 +0,0 @@ -.TH CACHE_REPAIR 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -cache_repair \- repair cache binary metadata from device/file to device/file - -.SH SYNOPSIS -.B cache_repair -.RB [ options ] -.RB -i -.I {device|file} -.RB -o -.I {device|file} - -.SH DESCRIPTION -.B cache_repair -reads binary cache metadata created by the -respective device-mapper target from one -.I device -or -.I file -, repairs it and writes it to another -.I device -or -.I file. -If written to a metadata -.I device -, the metadata can be processed -by the device-mapper target. - -This tool cannot be run on live metadata. - -.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP" -Input file or device with binary metadata. - -.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP" -Output file or device for repaired binary metadata. If a file is used -then it must be preallocated, and large enough to hold the metadata. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH EXAMPLE -Reads the binary cache metadata from file -.B metadata -, repairs it and writes it to logical volume /dev/vg/metadata -for further processing by the respective device-mapper target: -.sp -.B cache_repair -i metadata -o /dev/vg/metadata - -.SH DIAGNOSTICS -.B cache_repair -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B cache_dump(8) -.B cache_check(8) -.B cache_restore(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/cache_repair.txt b/man8/cache_repair.txt new file mode 100644 index 0000000..0d70429 --- /dev/null +++ b/man8/cache_repair.txt @@ -0,0 +1,38 @@ +NAME + cache_repair - repair cache binary metadata from device/file to device/file. + +SYNOPSIS + cache_repair [options] -i {device|file} -o {device|file} + +DESCRIPTION + cache_repair reads binary cache metadata created by the respective + device-mapper target from one device or file, repairs it and writes it to + another device or file. If written to a metadata device, the metadata can + be processed by the device-mapper target. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -i, --input {device|file} Input file or device containing binary metadata. + -o, --output {device|file} Output file or device for repaired binary metadata. + + If a file is then it must be preallocated, and large enough to hold the + metadata. + +EXAMPLE + Reads the binary cache metadata from file metadata, repairs it and writes it + to logical volume /dev/vg/metadata for further processing by the respective + device-mapper target: + + $ cache_repair -i metadata -o /dev/vg/metadata + +DIAGNOSTICS + cache_repair returns an exit code of 0 for success or 1 for error. + +SEE ALSO + cache_dump(8), cache_check(8), cache_restore(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen diff --git a/man8/cache_restore.8 b/man8/cache_restore.8 deleted file mode 100644 index f3eb57e..0000000 --- a/man8/cache_restore.8 +++ /dev/null @@ -1,78 +0,0 @@ -.TH CACHE_RESTORE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -cache_restore \- restore cache metadata file to device or file - -.SH SYNOPSIS -.B cache_restore -.RB [ options ] -.RB -i -.I {device|file} -.RB -o -.I {device|file} - -.SH DESCRIPTION -.B cache_restore -restores cache metadata created by the respective -device-mapper target dumped into an XML formatted (see -.BR cache_dump(8) ) -.I file -, which optionally can be preprocessed before the restore to another -.I device -or -.I file. -If restored to a metadata -.I device -, the metadata can be processed by the device-mapper target. - -This tool cannot be run on live metadata. - -.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP" -Input file or device with metadata. - -.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP" -Output file or device for repaired binary metadata. If a file is used -then it must be preallocated, and large enough to hold the metadata. - -.IP "\fB\-\-metadata\-version\fP \fI{1|2}\fP" -Choose metadata version. - -.IP "\fB\-q, \-\-quiet\fP" -Don't print any output. Check the exit code to test for success. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.IP "\fB\-\-debug-override-metadata-version\fP \fI\fP" -ONLY FOR DEBUGGING PURPOSES: -.br -override the version stored in the metadata. - -.IP "\fB\-\-omit\-clean\-shutdown\fP" -ONLY FOR DEBUGGING PURPOSES: -.br -Don't set the clean shutdown flag. - -.SH EXAMPLE -Restores the XML formatted cache metadata on file -.B metadata -to logical volume /dev/vg/metadata for further processing by the -respective device-mapper target: -.sp -.B cache_restore -i metadata -o /dev/vg/metadata - -.SH DIAGNOSTICS -.B cache_restore -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B cache_dump(8) -.B cache_check(8) -.B cache_repair(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/cache_restore.txt b/man8/cache_restore.txt new file mode 100644 index 0000000..d0a7076 --- /dev/null +++ b/man8/cache_restore.txt @@ -0,0 +1,47 @@ +NAME + cache_restore - restore cache metadata file to device or file. + +SYNOPSIS + cache_restore [options] -i {xml file} -o {device|file} + +DESCRIPTION + cache_restore restores cache metadata created by the respective device-mapper + target dumped into an XML formatted (see cache_dump(8)) file, which + optionally can be preprocessed before the restore to another device or file. + If restored to a metadata device, the metadata can be processed by the + device-mapper target. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -q, --quiet Don't print any output. Check the exit code to test for success. + -i, --input {xml file} Input xml. + -o, --output {device|file} Output file or device for restored binary metadata. + + If a file is used thin it must be preallocated, and large enough to hold + the metadata. + + --metadata-version {1|2} Choose a metadata version. + +DEBUGGING OPTIONS + --debug-override-metadata-version {integer} Override the version stored in the metadata. + --omit-clean-shutdown Don't set the clean shutdown flag. + +EXAMPLE + Restores the XML formatted cache metadata on file .B metadata to logical + volume /dev/vg/metadata for further processing by the respective + device-mapper target: + + $ cache_restore -i metadata -o /dev/vg/metadata + +DIAGNOSTICS + cache_restore returns an exit code of 0 for success or 1 for error. + +SEE ALSO + cache_dump(8), cache_check(8), cache_repair(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/cache_writeback.8 b/man8/cache_writeback.8 deleted file mode 100644 index c01a071..0000000 --- a/man8/cache_writeback.8 +++ /dev/null @@ -1,60 +0,0 @@ -.TH CACHE_WRITEBACK 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -cache_writeback \- writeback dirty blocks to the origin device. - -.SH SYNOPSIS -.B cache_writeback -.RB [ options ] -.RB --metadata-device -.I {device|file} -.RB --origin-device -.I {device|file} -.RB --fast-device -.I {device|file} - -.SH DESCRIPTION -.B cache_writeback - -An offline tool that writesback dirty data to the data device -(origin). Intended for use in recovery scenarios when the SSD is -giving IO errors. - -This tool cannot be run on a live cache. - -.SH OPTIONS - -.IP "\fB\\-\-metadata\-device\fP \fI{device|file}\fP" -Location of cache metadata. - -.IP "\fB\-\-origin\-device\fP \fI{device|file}\fP" -Slow device being cached. - -.IP "\fB\-\-fast\-device\fP \fI{device|file}\fP" -Fast device containing the data that needs to be written back. - -.IP "\fB\-\-no\-metadata\-update\fP" -Do not update the metadata to clear the dirty flags for written back -data. You may not want to do this if you're decommissioning the -cache. - -.IP "\fB\-\-buffer\-size\-meg \fI{size}\fP" -Specify the size for the metadata cache. Defaults to 16 Gig, a larger size may -improve performance. - -.IP "\fB\-\-list\-failed\-blocks\fP -List any blocks that failed the writeback process. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH SEE ALSO -.B cache_dump(8) -.B cache_check(8) -.B cache_repair(8) -.B cache_restore(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/cache_writeback.txt b/man8/cache_writeback.txt new file mode 100644 index 0000000..25ab0c9 --- /dev/null +++ b/man8/cache_writeback.txt @@ -0,0 +1,34 @@ +NAME + cache_writeback - writeback dirty blocks to the origin device. + +SYNOPSIS + cache_writeback [options] --metadata-device {device|file} --origin-device {device|file} --fast-device {device|file} + +DESCRIPTION + cache_writeback is an offline tool that writes back dirty data to the data + device (origin). Intended for use in recovery scenarios when the SSD is + giving IO errors. + + This tool cannot be run on a live cache. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + --metadata-device {device|file} Location of cache metadata. + --origin-device {device|file} Slow device being cached. + --fast-device {device|file} Fast device containing the data that needs to be written back. + --no-metadata-update Do not update the metadata to clear the dirty flags. + + You may want to use this flag if you're decommissioning the cache. + + --buffer-size-meg {size} Specify the size for the metadata cache. + + Defaults to 16 Gig, a larger size may improve performance. + + --list-failed-blocks List any blocks that failed the writeback process. + +SEE ALSO + cache_dump(8), cache_check(8), cache_repair(8), cache_restore(8) + +AUTHOR + Joe Thornber diff --git a/man8/era_check.8 b/man8/era_check.8 deleted file mode 100644 index 43b3ee0..0000000 --- a/man8/era_check.8 +++ /dev/null @@ -1,59 +0,0 @@ -.TH ERA_CHECK 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -era_check \- validate era metadata on device or file - -.SH SYNOPSIS -.B era_check -.RB [ options ] -.I {device|file} - -.SH DESCRIPTION -.B era_check -checks era metadata created by -the device-mapper era target on a -.I device -or -.I file. - -This tool cannot be run on live metadata. - -.SH OPTIONS -.IP "\fB\-q, \-\-quiet\fP" -Suppress output messages, return only exit code. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.IP "\fB\-\-super\-block\-only\fP" -Only check the superblock is present. - -.B era_check -will return a non-zero exit code if it finds a fatal -error. If any errors are discovered use -.B era_repair -to correct. - -.SH EXAMPLE -Analyse thin provisioning metadata on logical volume -/dev/vg/metadata: -.sp -.B era_check /dev/vg/metadata - -The device may not be actively used by the target -when running. - -.SH DIAGNOSTICS -.B era_check -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B era_dump(8) -.B era_repair(8) -.B era_restore(8) -.B era_invalidate(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/era_check.txt b/man8/era_check.txt new file mode 100644 index 0000000..8be23c2 --- /dev/null +++ b/man8/era_check.txt @@ -0,0 +1,33 @@ +NAME + era_check - validate era metadata on device or file. + +SYNOPSIS + era_check [options] {device|file} + +DESCRIPTION + era_check checks era metadata created by the device-mapper era target on a + device or file. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -q, --quiet Suppress output messages, return only exit code. + --super-block-only Only check the superblock is present. + +EXAMPLE + Analyse thin provisioning metadata on logical volume /dev/vg/metadata: + + $ era_check /dev/vg/metadata + + The device may not be actively used by the target when running. + +DIAGNOSTICS + era_check returns an exit code of 0 for success or 1 for error. + +SEE ALSO + era_dump(8), era_repair(8), era_restore(8), era_invalidate(8) + +AUTHOR + Joe Thornber diff --git a/man8/era_dump.8 b/man8/era_dump.8 deleted file mode 100644 index 78a5162..0000000 --- a/man8/era_dump.8 +++ /dev/null @@ -1,61 +0,0 @@ -.TH ERA_DUMP 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -era_dump \- dump era metadata from device or file to standard output - -.SH SYNOPSIS -.B era_dump -.RB [options] -.I {device|file} - -.SH DESCRIPTION -.B era_dump -dumps binary era metadata created by the device-mapper -era target on a -.I device -or -.I file -to standard output for -analysis or postprocessing in XML format. -XML formated metadata can be fed into era_restore (see -.BR era_restore(8) ) -in order to put it back onto a metadata -.I device -(to process by the device-mapper target) or -.I file. - -This tool cannot be run on live metadata. - -.IP "\fB\-\-repair\fP". -Repair the metadata whilst dumping it. - -.IP "\fB\-h, \-\-help\fP". -Print help and exit. - -.IP "\fB\-V, \-\-version\fP". -Output version information and exit. - -.IP "\fB\-\-logical\fP". -Fold any unprocessed write sets into the final era array. You -probably want to do this if you're intending to process the results as -it simplifies the XML. - -.IP "\fB-o \fI{xml file}\fP" -Specify a file for the output rather than writing to stdout. - -.SH EXAMPLES -Dumps era metadata on logical volume /dev/vg/metadata -to standard output in XML format: -.sp -.B era_dump /dev/vg/metadata - -.SH DIAGNOSTICS -.B era_dump -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B era_check(8) -.B era_repair(8) -.B era_restore(8) -.B era_invalidate(8) -.SH AUTHOR -Joe Thornber diff --git a/man8/era_dump.txt b/man8/era_dump.txt new file mode 100644 index 0000000..61dd066 --- /dev/null +++ b/man8/era_dump.txt @@ -0,0 +1,40 @@ +NAME + era_dump - dump era metadata from device or file to standard output. + +SYNOPSIS + era_dump [options] {device|file} + +DESCRIPTION + era_dump dumps binary era metadata created by the device-mapper era target on + a device or file to standard output for analysis or postprocessing in + XML format. XML formated metadata can be fed into era_restore (see + era_restore(8)) in order to put it back onto a metadata device (to process by + the device-mapper target) or file. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + --repair Repair the metadata whilst dumping it. + --logical Fold any unprocessed write sets into the final era array. + + You probably want to do this if you're intending to process the results as + it simplifies the XML. + + -o {xml file} Specify a file for the output rather than writeing to stdout. + +EXAMPLES + Dumps era metadata on logical volume /dev/vg/metadata to standard output in + XML format: + + $ era_dump /dev/vg/metadata + +DIAGNOSTICS + era_dump returns an exit code of 0 for success or 1 for error. + +SEE ALSO + era_check(8), era_repair(8), era_restore(8), era_invalidate(8) + +AUTHOR + Joe Thornber diff --git a/man8/era_invalidate.8 b/man8/era_invalidate.8 deleted file mode 100644 index 62c221f..0000000 --- a/man8/era_invalidate.8 +++ /dev/null @@ -1,54 +0,0 @@ -.TH ERA_INVALIDATE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -era_invalidate \- Provide a list of blocks that have changed since a particular era. - -.SH SYNOPSIS -.B era_invalidate -.RB [ options ] -.I {device|file} - -.SH DESCRIPTION -.B era_invalidate -Examines era metadata and lists blocks that may have changed since a given era. - -This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP option is used. - -.SH OPTIONS -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.IP "\fB\-o \fP" -Write output to a file rather than -.B stdout -. - -.IP "\fB\-\-metadata\-snapshot\fP" -Use the metadata snapshot rather than the current superblock. - -.IP "\fB\-\-written-since {era}\fP" -Blocks written since the given era will be listed. - -.SH EXAMPLE -List the blocks that may have been written since the beginning of era -13 on the metadata device /dev/vg/metadata. -.sp -.B era_invalidate --written-since 13 /dev/vg/metadata - -The device may not be actively used by the target -when running. - -.SH DIAGNOSTICS -.B era_invalidate -returns an exit code of 0 for success or 1 for error (eg, metadata corruption). - -.SH SEE ALSO -.B era_check(8), -.B era_dump(8), -.B era_repair(8), -.B era_restore(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/era_invalidate.txt b/man8/era_invalidate.txt new file mode 100644 index 0000000..569d1fc --- /dev/null +++ b/man8/era_invalidate.txt @@ -0,0 +1,37 @@ +NAME + era_invalidate - Provide a list of blocks that have changed since a particular era. + +SYNOPSIS + era_invalidate [options] {device|file} + +DESCRIPTION + era_invalidate examines era metadata and lists blocks that may have changed + since a given era. + + This tool cannot be run on live metadata unless the --metadata-snap option is + used. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -o {output file} Write output to a file rather than stdout. + --metadata-snapshot Use the metadata snapshot rather than the current superblock. + --written-since Blocks written since the given era will be listed. + +EXAMPLE + List the blocks that may have been written since the beginning of era 13 on the + metadata device /dev/vg/metadata: + + $ era_invalidate --written-since 13 /dev/vg/metadata + + The device may not be actively used by the target when running. + +DIAGNOSTICS + era_invalidate returns an exit code of 0 for success or 1 for error (eg, + metadata corruption). + +SEE ALSO + era_check(8), era_dump(8), era_repair(8), era_restore(8) + +AUTHOR + Joe Thornber diff --git a/man8/era_restore.8 b/man8/era_restore.8 deleted file mode 100644 index a7b8ccc..0000000 --- a/man8/era_restore.8 +++ /dev/null @@ -1,64 +0,0 @@ -.TH ERA_RESTORE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -era_restore \- restore era metadata file to device or file - -.SH SYNOPSIS -.B era_restore -.RB [ options ] -.RB -i -.I {device|file} -.RB -o -.I {device|file} - -.SH DESCRIPTION -.B era_restore -restores era metadata created by the respective -device-mapper target dumped into an XML formatted (see -.BR era_dump(8) ) -.I file -, which optionally can be preprocessed before the restore to another -.I device -or -.I file. -If restored to a metadata -.I device -, the metadata can be processed by the device-mapper target. - -This tool cannot be run on live metadata. - -.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP" -Input file or device with metadata. - -.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP" -Output file or device for repaired binary metadata. If a file is used -then it must be preallocated, and large enough to hold the metadata. - -.IP "\fB\-q, \-\-quiet\fP" -Don't print any output. Check the exit code to test for success. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH EXAMPLE -Restores the XML formatted era metadata on file -.B metadata -to logical volume /dev/vg/metadata for further processing by the -respective device-mapper target: -.sp -.B era_restore -i metadata -o /dev/vg/metadata - -.SH DIAGNOSTICS -.B era_restore -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B era_dump(8) -.B era_check(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/era_restore.txt b/man8/era_restore.txt new file mode 100644 index 0000000..9b37a4a --- /dev/null +++ b/man8/era_restore.txt @@ -0,0 +1,40 @@ +NAME + era_restore - restore era metadata file to device or file. + +SYNOPSIS + era_restore [options] -i {xml file} -o {device|file} + +DESCRIPTION + era_restore restores era metadata created by the respective device-mapper + target dumped into an XML formatted (see .BR era_dump(8)) file, which + optionally can be preprocessed before the restore to another device or + file. If restored to a metadata device, the metadata can be processed by + the device-mapper target. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -q, --quiet Don't print any output. Check the exit code to test for success. + -i, --input {xml file} Specify input file containing xml metadata. + -o, --output {device|file} Output device or file for restored binary metadata. + + If a file is used, then it must be preallocated, and large enough to hold + the metadata. + +EXAMPLE + Restores the XML formatted era metadata on file metadata to logical volume + /dev/vg/metadata for further processing by the respective device-mapper + target: + + $ era_restore -i metadata -o /dev/vg/metadata + +DIAGNOSTICS + era_restore returns an exit code of 0 for success or 1 for error. + +SEE ALSO + era_dump(8), era_check(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen diff --git a/man8/thin_check.8 b/man8/thin_check.8 deleted file mode 100644 index f5b6496..0000000 --- a/man8/thin_check.8 +++ /dev/null @@ -1,67 +0,0 @@ -.TH THIN_CHECK 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_check \- validate thin provisioning metadata on device or file - -.SH SYNOPSIS -.B thin_check -.RB [ options ] -.I {device|file} - -.SH DESCRIPTION -.B thin_check -checks thin provisioning metadata created by -the device-mapper thin provisioning target on a -.I device -or -.I file. - -This tool cannot be run on live metadata. - -.SH OPTIONS -.IP "\fB\-q, \-\-quiet\fP" -Suppress output messages, return only exit code. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.IP "\fB\-\-super\-block\-only\fP" -Only check the superblock is present. - -.IP "\fB\-\-skip-mappings\fP" -Skip checking of the block mappings which make up the bulk of the -metadata. - -.IP "\fB\-\-ignore\-non\-fatal\-errors\fP" -.B thin_check -will only return a non-zero exit code if it finds a fatal -error. An example of a non fatal error is an incorrect data block -reference count causing a block to be considered allocated when it in -fact isn't. Ignoring errors for a long time is not advised, you -really should be using thin_repair to fix them. - -.SH EXAMPLE -Analyses thin provisioning metadata on logical volume -/dev/vg/metadata: -.sp -.B thin_check /dev/vg/metadata - -The device must not be actively used by the target when running. - -.SH DIAGNOSTICS -.B thin_check -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_check.txt b/man8/thin_check.txt new file mode 100644 index 0000000..4944785 --- /dev/null +++ b/man8/thin_check.txt @@ -0,0 +1,43 @@ +NAME + thin_check - validates thin provisioning metadata on a device or file + +SYNOPSIS + thin_check [options] {device|file} + +DESCRIPTION + thin_check checks thin provisioning metadata created by the device-mapper + thin provisioning target on a device or file. + + The tool cannot be run on live metadata. + +OPTIONS + -q, --quiet Suppress output messages, return only exit code. + -h, --help Print help and exit. + -V, --version Output version information and exit. + --super-block-only Only check the superblock. + + --skip-mappings Skip checking of the block mappings which make up the bulk of the metadata. + + --ignore-non-fatal-errors Will only return a non-zero exit code if it finds a fatal error. + + An example of a nonfatal error is an incorrect data block reference count + causing a block to be considered allocated when it in fact isn't. Ignoring + errors for a long time is not advised, you really should be using + thin_repair to fix them. + +EXAMPLE + Analyses thin provisioning metadata on logical volume /dev/vg/metadata: + + $ thin_check /dev/vg/metadata + + The device must not be actively used by the target when running. + +DIAGNOSTICS + thin_check returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_dump(8), thin_repair(8), thin_restore(8), thin_rmap(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/thin_delta.8 b/man8/thin_delta.8 deleted file mode 100644 index e845600..0000000 --- a/man8/thin_delta.8 +++ /dev/null @@ -1,48 +0,0 @@ -.TH THIN_DELTA 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_delta \- Print the differences in the mappings between two thin devices. - -.SH SYNOPSIS -.B thin_delta -.RB [ options ] -.I {device|file} - -.SH DESCRIPTION -.B thin_delta -allows you to compare the mappings in two thin volumes (snapshots allow common blocks between thin volumes). - -This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP option is used. - -.SH OPTIONS -.IP "\fB\-\-thin1, \-\-snap1\fP" -The numeric identifier for the first thin volume to diff. - -.IP "\fB\-\-thin2, \-\-snap2\fP" -The numeric identifier for the second thin volume to diff. - -.IP "\fB\-m, \-\-metadata\-snap\fP [block#]" - -If you want to get information out of a live pool then you will need -to take a metadata snapshot and use this switch. In order for the -information to be meaningful you need to ensure the thin volumes -you're examining are not changing (eg, do not activate those thins). - -.IP "\fB\-\-verbose" -Provide extra information on the mappings. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_trim(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/thin_delta.txt b/man8/thin_delta.txt new file mode 100644 index 0000000..26cac46 --- /dev/null +++ b/man8/thin_delta.txt @@ -0,0 +1,33 @@ +NAME + thin_delta - Print the differences in the mappings between two thin devices. + +SYNOPSIS + thin_delta [options] {device|file} + +DESCRIPTION + thin_delta allows you to compare the mappings in two thin volumes (snapshots + allow common blocks between thin volumes). + + This tool cannot be run on live metadata unless the --metadata-snap option is + used. + +OPTIONS + --thin1, --snap1 {natural} The numeric identifier for the first thin volume to diff. + --thin2, --snap2 {natural} The numeric identifier for the second thin volume to diff. + --metadata-snap [block nr] Use a metadata snapshot. + + If you want to get information out of a live pool then you will need to + take a metadata snapshot and use this switch. In order for the information + to be meaningful, you need to ensure the thin volumes you're examining are + not changing (ie, do not activate those thins). + + --verbose Provide extra information on the mappings. + -h, --help Print help and exit. + -V, --version Output version information and exit. + +SEE ALSO + thin_dump(8), thin_repair(8), thin_restore(8), thin_rmap(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/thin_dump.8 b/man8/thin_dump.8 deleted file mode 100644 index 0d853e2..0000000 --- a/man8/thin_dump.8 +++ /dev/null @@ -1,94 +0,0 @@ -.TH THIN_DUMP 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_dump \- dump thin provisioning metadata from device or file to standard output - -.SH SYNOPSIS -.B thin_dump -.RB [options] -.I {device|file} - -.SH DESCRIPTION -.B thin_dump -dumps binary thin provisioning metadata (optionally from alternate block; -see option \-\-metadata-snap) created by the device-mapper -thin provisioning target on a -.I device -or -.I file -to standard output for -analysis or postprocessing in either XML or human readable format. -XML formated metadata can be fed into thin_restore (see -.BR thin_restore(8) ) -in order to put it back onto a metadata -.I device -(to process by the device-mapper target) or -.I file. - -This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP option is used. - -.IP "\fB\-f, \-\-format\fP \fI{xml|human_readable|custom}\fP". - -Print output in XML or human readable format. Custom formats are -supported via shared library plugins. They should be specified as in -this example: -.sp -.B thin_dump --format custom=mylib.so /dev/sda - -.IP "\fB\-r, \-\-repair\fP". -Repair the metadata whilst dumping it. - -.IP "\fB\-m, \-\-metadata\-snap\fP [block#]". -Dump metadata snapshot created by device-mapper thin provisioning target. -If block is not provided, access the default metadata snapshot created by -the thin provisioning device-mapper target, else try the one at block#. -See the thin provisioning target documentation on how to create or release -a metadata snapshot and retrieve the block number from the kernel. - -.IP "\fB\-\-dev\-id\fP ". -Dump the specified device. This option may be specified multiple -times to select more than one thin device. - -.IP "\fB\-\-skip\-mappings". -Do not dump the mappings. - -.IP "\fB-o \fI{xml file}\fP" -Specify a file for the output rather than writing to stdout. - -.IP "\fB\-h, \-\-help\fP". -Print help and exit. - -.IP "\fB\-V, \-\-version\fP". -Output version information and exit. - -.SH EXAMPLES -Dumps the thin provisioning metadata on logical volume /dev/vg/metadata -to standard output in human readable format: -.sp -.B thin_dump -f human_readable /dev/vg/metadata - -Dumps the thin provisioning metadata on logical volume /dev/vg/metadata -to standard output in XML format: -.sp -.B thin_dump /dev/vg/metadata - -Dumps the thin provisioning metadata snapshot on logical volume /dev/vg/metadata -to standard output in human readable format (not processable by -.B thin_restore(8) -): -.sp -.B thin_dump --format human_readable --metadata-snap /dev/vg/metadata - -.SH DIAGNOSTICS -.B thin_dump -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_check(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_metadata_size(8) -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_dump.txt b/man8/thin_dump.txt new file mode 100644 index 0000000..106a53e --- /dev/null +++ b/man8/thin_dump.txt @@ -0,0 +1,68 @@ +NAME + thin_dump - dump thin provisioning metadata from device or file to standard output. + +SYNOPSIS + thin_dump [options] {device|file} + +DESCRIPTION + thin_dump dumps binary thin provisioning metadata (optionally from alternate + block; see option --metadata-snap) created by the + device-mapper thin provisioning target on a device or file to standard + output for analysis or postprocessing in either XML or human readable format. + XML formated metadata can be fed into thin_restore (see thin_restore(8)) + in order to put it back onto a metadata device (to process by the + device-mapper target) or file. + + This tool cannot be run on live metadata unless the --metadata-snap + option is used. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -f, --format {xml|human_readable|custom} Choose output format. + + Custom formats are supported via shared library plugins. They should be + specified as in this example: + + $ thin_dump --format custom=mylib.so /dev/sda + + -r, --repair Repair the metadata whilst dumping it. + -m, --metadata-snap {block nr} Dump metadata snapshot. + + If block is not provided, access the default metadata snapshot created by + the thin provisioning device-mapper target, else try the one at block nr. + See the thin provisioning target documentation on how to create or release + a metadata snapshot and retrieve the block number from the kernel. + + --dev-id {natural} Dump the specified device. + + This option may be specified multiple times to select more than one thin + device. + + --skip-mappings Do not dump the mappings. + -o {xml file} Specify a file for the output rather than writing to stdout. + +EXAMPLES + Dumps the thin provisioning metadata on logical volume /dev/vg/metadata to + standard output in human readable format: + + $ thin_dump -f human_readable /dev/vg/metadata + + Dumps the thin provisioning metadata on logical volume /dev/vg/metadata to + standard output in XML format: + + $ thin_dump /dev/vg/metadata + + Dumps the thin provisioning metadata snapshot on logical volume /dev/vg/metadata + to standard output in human readable format (not processable by thin_restore(8)): + + $ thin_dump --format human_readable --metadata-snap /dev/vg/metadata + +DIAGNOSTICS + thin_dump returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_check(8) .B thin_repair(8) .B thin_restore(8) .B thin_rmap(8) .B thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen diff --git a/man8/thin_ls.8 b/man8/thin_ls.8 deleted file mode 100644 index dc3aef2..0000000 --- a/man8/thin_ls.8 +++ /dev/null @@ -1,48 +0,0 @@ -.TH THIN_LS 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_ls \- List thin volumes within a pool. - -.SH SYNOPSIS -.B thin_ls -.RB [ options ] -.I {metadata device} - -.SH DESCRIPTION -.B thin_ls -Displays infomation about thin volumes in a pool. Pass the metadata device on the command line, not the -pool device. - -This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP option is used. - -.SH OPTIONS - -.IP "\fB\-o, \-\-format\fP" -Give a comma separated list of the fields to be output. Valid fields are: -DEV, MAPPED_BLOCKS, EXCLUSIVE_BLOCKS, SHARED_BLOCKS, MAPPED_SECTORS, -EXCLUSIVE_SECTORS, SHARED_SECTORS, MAPPED_BYTES, EXCLUSIVE_BYTES, -SHARED_BYTES, MAPPED, EXCLUSIVE, SHARED, TRANSACTION, CREATE_TIME, SNAP_TIME - -.IP "\fB\-\-no\-headers\fP" -Don't output headers. - -.IP "\fB\-m, \-\-metadata\-snap\fP" - -If you want to get information out of a live pool then you will need -to take a metadata snapshot and use this switch. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_trim(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/thin_ls.txt b/man8/thin_ls.txt new file mode 100644 index 0000000..907b4a0 --- /dev/null +++ b/man8/thin_ls.txt @@ -0,0 +1,36 @@ +NAME + thin_ls - List thin volumes within a pool. + +SYNOPSIS + thin_ls [options] {device|file} + +DESCRIPTION + thin_ls displays infomation about thin volumes in a pool. Pass the metadata + device on the command line, not the pool device. + + This tool cannot be run on live metadata unless the --metadata-snap + option is used. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -o, --format Give a comma separated list of fields to be output. + + Valid fields are: + DEV, MAPPED_BLOCKS, EXCLUSIVE_BLOCKS, SHARED_BLOCKS, MAPPED_SECTORS, + EXCLUSIVE_SECTORS, SHARED_SECTORS, MAPPED_BYTES, EXCLUSIVE_BYTES, + SHARED_BYTES, MAPPED, EXCLUSIVE, SHARED, TRANSACTION, CREATE_TIME, + SNAP_TIME + + --no-headers Don't output headers. + -m, --metadata-snap Use metadata snapshot. + + If you want to get information out of a live pool then you will need to + take a metadata snapshot and use this switch. + +SEE ALSO + thin_dump(8), thin_repair(8), thin_restore(8), thin_rmap(8), thin_trim(8), + thin_metadata_size(8) + +AUTHOR + Joe Thornber diff --git a/man8/thin_metadata_size.8 b/man8/thin_metadata_size.8 deleted file mode 100644 index d38a0cc..0000000 --- a/man8/thin_metadata_size.8 +++ /dev/null @@ -1,79 +0,0 @@ -.TH THIN_METADATA_SIZE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_metadata_size \- thin provisioning metadata device/file size calculator. - -.SH SYNOPSIS -.B thin_metadata_size -.RB [ options ] - -.SH DESCRIPTION -.B thin_metadata_size -calculates the size of the thin provisioning metadata based on the block size -of the thin provisioned devices, the size of the thin provisioning pool and -the maximum number of all thin prisioned devices and snapshots. -Because thin provisioning pools are holding widely variable contents, -this tool is needed to provide sensible initial default size. - -.IP "\fB\-b, \-\-block-size\fP \fIBLOCKSIZE[bskKmMgGtTpPeEzZyY]\fP" -Block size of thin provisioned devices in units of bytes, sectors, kibibytes, kilobytes, ... respectively. -Default is in sectors without a block size unit specifier. -Size/number option arguments can be followed by unit specifiers in short one character -and long form (eg. -b1m or -b1mebibytes). - -.IP "\fB\-s, \-\-pool-size\fP \fIPOOLSIZE[bskKmMgGtTpPeEzZyY]\fP" -Thin provisioning pool size in units of bytes, sectors, kibibytes, kilobytes, ... respectively. -Default is in sectors without a pool size unit specifier. - -.IP "\fB\-m, \-\-max-thins\fP \fI#[bskKmMgGtTpPeEzZyY]\fP" -Maximum sum of all thin provisioned devices and snapshots. -Unit identifier supported to allow for convenient entry of large quantities, eg. 1000000 = 1M. -Default is absolute quantity without a number unit specifier. - -.IP "\fB\-u, \-\-unit\fP \fI{bskKmMgGtTpPeEzZyY}\fP" -Output unit specifier in units of bytes, sectors, kibibytes, kilobytes, ... respectively. -Default is in sectors without an output unit specifier. - -.IP "\fB\-n, \-\-numeric-only [short|long]\fP" -Limit output to just the size number with the optional unit specifier character/string. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH EXAMPLES -Calculates the thin provisioning metadata device size for block size 64 kibibytes, -pool size 1 tebibytes and maximum number of thin provisioned devices and snapshots of 1000 -in units of sectors with long output: -.sp -.B thin_metadata_size -b64k -s1t -m1000 - -Or (using the long options instead) for block size 1 gibibyte, pool size 1 petabyte and maximum number of thin provisioned devices -and snapshots of 1 million with numeric-only output in units of gigabytes: -.sp -.B thin_metadata_size --block-size=1g --pool-size=1P --max-thins=1M --unit=G --numeric-only - -Same as before (1g, 1P, 1M, numeric-only) but with unit specifier character appended: -.sp -.B thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G --numeric-only=short - -Or with unit specifier string appended: -.sp -.B thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G -nlong - -.SH DIAGNOSTICS -.B thin_metadata_size -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_check(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_metadata_size.txt b/man8/thin_metadata_size.txt new file mode 100644 index 0000000..ae2166d --- /dev/null +++ b/man8/thin_metadata_size.txt @@ -0,0 +1,75 @@ +NAME + thin_metadata_size - thin provisioning metadata device/file size calculator. + +SYNOPSIS + thin_metadata_size [options] + +DESCRIPTION + thin_metadata_size calculates the size of the thin provisioning metadata + based on the block size of the thin provisioned devices, the size of the thin + provisioning pool and the maximum number of all thin provisioned devices and + snapshots. Because thin provisioning pools are holding widely variable + contents, this tool is needed to provide sensible initial default size. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -b, --block-size {BLOCKSIZE[bskKmMgGtTpPeEzZyY]} Set block size. + + Block size of thin provisioned devices in units of bytes, sectors, + kibibytes, kilobytes, ... respectively. Default is in sectors without a + block size unit specifier. Size/number option arguments can be followed by + unit specifiers in short one character and long form (eg. -b1m or + -b1mebibytes). + + -s, --pool-size {POOLSIZE[bskKmMgGtTpPeEzZyY]} Set pool size. + + Thin provisioning pool size in units of bytes, sectors, kibibytes, + kilobytes, ... respectively. Default is in sectors without a pool size + unit specifier. + + -m, --max-thins {count[bskKmMgGtTpPeEzZyY]} Set max thins. + + Maximum sum of all thin provisioned devices and snapshots. Unit identifier + supported to allow for convenient entry of large quantities, eg. 1000000 = + 1M. Default is absolute quantity without a number unit specifier. + + -u, --unit {bskKmMgGtTpPeEzZyY} + + Output unit specifier in units of bytes, sectors, kibibytes, kilobytes, ... + respectively. Default is in sectors without an output unit specifier. + + -n, --numeric-only {short|long} Limit output to just the size number. + +EXAMPLES + Calculates the thin provisioning metadata device size for block size 64 + kibibytes, pool size 1 tebibytes and maximum number of thin provisioned + devices and snapshots of 1000 in units of sectors with long output: + + $ thin_metadata_size -b64k -s1t -m1000 + + Or (using the long options instead) for block size 1 gibibyte, pool size 1 + petabyte and maximum number of thin provisioned devices and snapshots of 1 + million with numeric-only output in units of gigabytes: + + $ thin_metadata_size --block-size=1g --pool-size=1P --max-thins=1M --unit=G --numeric-only + + Same as before (1g, 1P, 1M, numeric-only) but with unit specifier character + appended: + + $ thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G --numeric-only=short + + Or with unit specifier string appended: + + $ thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G -nlong + +DIAGNOSTICS + + thin_metadata_size returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_dump(8), thin_check(8), thin_repair(8), thin_restore(8), thin_rmap(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/thin_repair.8 b/man8/thin_repair.8 deleted file mode 100644 index 8e063fc..0000000 --- a/man8/thin_repair.8 +++ /dev/null @@ -1,66 +0,0 @@ -.TH THIN_REPAIR 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_repair \- repair thin provisioning binary metadata from device/file to device/file - -.SH SYNOPSIS -.B thin_repair -.RB [ options ] -.RB -i -.I {device|file} -.RB -o -.I {device|file} - -.SH DESCRIPTION -.B thin_repair -reads binary thin provisioning metadata created by the -respective device-mapper target from one -.I device -or -.I file -, repairs it and writes it to another -.I device -or -.I file. -If written to a metadata -.I device -, the metadata can be processed -by the device-mapper target. - -This tool cannot be run on live metadata. - -.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP" -Input file or device with binary metadata. - -.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP" -Output file or device for repaired binary metadata. If a file is used -then it must be preallocated, and large enough to hold the metadata. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH EXAMPLE -Reads the binary thin provisioning metadata from file -.B metadata -, repairs it and writes it to logical volume /dev/vg/metadata -for further processing by the respective device-mapper target: -.sp -.B thin_repair -i metadata -o /dev/vg/metadata - -.SH DIAGNOSTICS -.B thin_repair -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_check(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_repair.txt b/man8/thin_repair.txt new file mode 100644 index 0000000..640af06 --- /dev/null +++ b/man8/thin_repair.txt @@ -0,0 +1,40 @@ +NAME + thin_repair - repair thin provisioning binary metadata. + +SYNOPSIS + thin_repair [options] -i {device|file} -o {device|file} + +DESCRIPTION + thin_repair reads binary thin provisioning metadata created by the respective + device-mapper target from one device or file, repairs it and writes it + to different device or file. If written to a metadata device, the metadata + can be processed by the device-mapper target. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -i, --input {device|file} Input file or device with binary data. + -o, --output {device|file} Output file or device for binary data. + + If a file is used for output, then it must be preallocated, and large + enough to hold the metadata. + +EXAMPLE + + Reads the binary thin provisioning metadata from file metadata, repairs + it and writes it to logical volume /dev/vg/metadata for further processing by + the respective device-mapper target: + + $ thin_repair -i metadata -o /dev/vg/metadata + +DIAGNOSTICS + thin_repair returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_dump(8), thin_check(8), thin_restore(8), thin_rmap(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/thin_restore.8 b/man8/thin_restore.8 deleted file mode 100644 index 02dd33c..0000000 --- a/man8/thin_restore.8 +++ /dev/null @@ -1,67 +0,0 @@ -.TH THIN_RESTORE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_restore \- restore thin provisioning metadata file to device or file - -.SH SYNOPSIS -.B thin_restore -.RB [ options ] -.RB -i -.I {device|file} -.RB -o -.I {device|file} - -.SH DESCRIPTION -.B thin_restore -restores thin provisioning metadata created by the -respective device-mapper target dumped into an XML formatted (see -.BR thin_dump(8) ) -.I file -, which optionally can be preprocessed before the restore to another -.I device -or -.I file. -If restored to a metadata -.I device -, the metadata can be processed by the device-mapper target. - -This tool cannot be run on live metadata. - -.IP "\fB\-q, \-\-quiet\fP" -Suppress output messages, return only exit code. - -.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP" -Input file or device with metadata. - -.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP" -Output file or device for repaired binary metadata. If a file is used -then it must be preallocated, and large enough to hold the metadata. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH EXAMPLE -Restores the XML formatted thin provisioning metadata on file -.B metadata -to logical volume /dev/vg/metadata for further processing by the -respective device-mapper target: -.sp -.B thin_restore -i metadata -o /dev/vg/metadata - -.SH DIAGNOSTICS -.B thin_restore -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_check(8) -.B thin_repair(8) -.B thin_rmap(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_restore.txt b/man8/thin_restore.txt new file mode 100644 index 0000000..782bc64 --- /dev/null +++ b/man8/thin_restore.txt @@ -0,0 +1,42 @@ +NAME + thin_restore - restore thin provisioning metadata file to device or file. + +SYNOPSIS + thin_restore [options] -i {xml file} -o {device|file} + +DESCRIPTION + thin_restore restores thin provisioning metadata created by the respective + device-mapper target dumped into an XML formatted (see thin_dump(8)) file, + which optionally can be preprocessed before the restore to another device or + file. If restored to a metadata device, the metadata can be processed by the + device-mapper target. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + -q, --quiet Suppress output messages, return only exit code. + -i, --input {xml file} Input file containing XML metadata. + -o, --output {device|file} Output file or device for restored binary metadata. + + If a file is used for output, then it must be preallocated, and large + enough to hold the metadata. + +EXAMPLE + + Restores the XML formatted thin provisioning metadata on file metadata to + logical volume /dev/vg/metadata for further processing by the respective + device-mapper target: + + $ thin_restore -i metadata -o /dev/vg/metadata + +DIAGNOSTICS + + thin_restore returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_dump(8), thin_check(8), thin_repair(8), thin_rmap(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen diff --git a/man8/thin_rmap.8 b/man8/thin_rmap.8 deleted file mode 100644 index 75dfb38..0000000 --- a/man8/thin_rmap.8 +++ /dev/null @@ -1,50 +0,0 @@ -.TH THIN_RMAP(g 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_rmap \- output reverse map of a thin provisioned region of blocks from metadata device or file - -.SH SYNOPSIS -.B thin_rmap -.RB [options] -.I {device|file} - -.SH DESCRIPTION -.B thin_rmap -outputs the reverse mapping stored in the metadata on a -.I device -or -.I file -between a region of thin provisioned pool blocks -and the associated thin provisioned devices. - -This tool cannot be run on live metadata. - -.IP "\fB\\-\-region\fP \fI\fP". -output reverse map - -.IP "\fB\-h, \-\-help\fP". -Print help and exit. - -.IP "\fB\-V, \-\-version\fP". -Output version information and exit. - -.SH EXAMPLES -output reverse map for pool blocks 5..45 (denotes blocks 5 to 44 inclusive, but not block 45) - -.sp -.B thin_rmap --region 5..45 /dev/pool-metadata - -.SH DIAGNOSTICS -.B thin_rmap -returns an exit code of 0 for success or 1 for error. - -.SH SEE ALSO -.B thin_check(8) -.B thin_dump(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber -.br -Heinz Mauelshagen diff --git a/man8/thin_rmap.txt b/man8/thin_rmap.txt new file mode 100644 index 0000000..ab9c30a --- /dev/null +++ b/man8/thin_rmap.txt @@ -0,0 +1,37 @@ +NAME + thin_rmap - output reverse map of a thin provisioned region of blocks from + metadata device or file. + +SYNOPSIS + thin_rmap [options] {device|file} + +DESCRIPTION + thin_rmap outputs the reverse mapping stored in the metadata on a device or + file between a region of thin provisioned pool blocks and the associated thin + provisioned devices. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + --region {block range} Specify range of blocks on the data device. + + At least one region must be specified. Multiple regions may be specified. + + The range takes the format ... For example, + "5..45" specifies data blocks 5 to 44 inclusive, but not 45. + +EXAMPLES + + $ thin_rmap --region 5..45 /dev/pool-metadata + +DIAGNOSTICS + thin_rmap returns an exit code of 0 for success or 1 for error. + +SEE ALSO + thin_check(8), thin_dump(8), thin_repair(8), thin_restore(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber , Heinz Mauelshagen + diff --git a/man8/thin_trim.8 b/man8/thin_trim.8 deleted file mode 100644 index 6a02e79..0000000 --- a/man8/thin_trim.8 +++ /dev/null @@ -1,37 +0,0 @@ -.TH THIN_TRIM 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*- -.SH NAME -thin_trim \- Issue discard requests for free pool space (offline tool). - -.SH SYNOPSIS -.B thin_trim -.RB [ options ] -.B --metadata-dev -.I {device|file} -.B --data-dev -.I {device|file} - -.SH DESCRIPTION -.B thin_trim -sends discard requests to the pool device for unprovisioned areas. - -This tool cannot be run on live metadata. - -.SH OPTIONS -.IP "\fB\-\-pool-inactive\fP" -Indicates you are aware the pool should be inactive. Suppresses a warning message and prompt. - -.IP "\fB\-h, \-\-help\fP" -Print help and exit. - -.IP "\fB\-V, \-\-version\fP" -Output version information and exit. - -.SH SEE ALSO -.B thin_dump(8) -.B thin_repair(8) -.B thin_restore(8) -.B thin_rmap(8) -.B thin_metadata_size(8) - -.SH AUTHOR -Joe Thornber diff --git a/man8/thin_trim.txt b/man8/thin_trim.txt new file mode 100644 index 0000000..054ebab --- /dev/null +++ b/man8/thin_trim.txt @@ -0,0 +1,23 @@ +NAME + thin_trim - Issue discard requests for free pool space (offline tool). + +SYNOPSIS + thin_trim [options] --metadata-dev {device|file} --data-dev {device|file} + +DESCRIPTION + thin_trim sends discard requests to the pool device for unprovisioned areas. + + This tool cannot be run on live metadata. + +OPTIONS + -h, --help Print help and exit. + -V, --version Print version information and exit. + --pool-inactive Indicates you are aware the pool should be inactive. + + Suppresses a warning message and prompt. + +SEE ALSO + thin_dump(8), thin_repair(8), thin_restore(8), thin_rmap(8), thin_metadata_size(8) + +AUTHOR + Joe Thornber