From f7d79339e8da664d82f32e276a38744f050be9be Mon Sep 17 00:00:00 2001 From: Joe Thornber Date: Mon, 18 Sep 2017 16:10:56 +0100 Subject: [PATCH] [man pages] Various updates. --- Makefile.in | 8 +++-- caching/cache_metadata_size.cc | 5 +-- era/era_invalidate.cc | 1 + man8/cache_check.8 | 4 +++ man8/cache_dump.8 | 3 ++ man8/cache_metadata_size.8 | 43 +++++++++++++++++++++++ man8/cache_restore.8 | 19 +++++++--- man8/cache_writeback.8 | 9 ++++- man8/era_dump.8 | 5 ++- man8/era_invalidate.8 | 6 ++++ man8/era_restore.8 | 64 ++++++++++++++++++++++++++++++++++ man8/thin_delta.8 | 2 +- man8/thin_dump.8 | 3 ++ man8/thin_ls.8 | 3 -- thin-provisioning/commands.cc | 2 +- thin-provisioning/thin_dump.cc | 1 + 16 files changed, 162 insertions(+), 16 deletions(-) create mode 100644 man8/cache_metadata_size.8 create mode 100644 man8/era_restore.8 diff --git a/Makefile.in b/Makefile.in index b4eeebb..e2f38d7 100644 --- a/Makefile.in +++ b/Makefile.in @@ -107,10 +107,10 @@ SOURCE=\ thin-provisioning/thin_repair.cc \ thin-provisioning/thin_restore.cc \ thin-provisioning/thin_rmap.cc \ + thin-provisioning/thin_trim.cc \ thin-provisioning/xml_format.cc DEVTOOLS_SOURCE=\ - thin-provisioning/thin_trim.cc \ thin-provisioning/thin_ll_dump.cc \ thin-provisioning/thin_ll_restore.cc \ thin-provisioning/thin_show_duplicates.cc \ @@ -250,6 +250,7 @@ install: bin/pdata_tools ln -s -f pdata_tools $(BINDIR)/thin_restore ln -s -f pdata_tools $(BINDIR)/thin_rmap ln -s -f pdata_tools $(BINDIR)/thin_metadata_size + ln -s -f pdata_tools $(BINDIR)/thin_trim ln -s -f pdata_tools $(BINDIR)/era_check ln -s -f pdata_tools $(BINDIR)/era_dump ln -s -f pdata_tools $(BINDIR)/era_invalidate @@ -257,6 +258,7 @@ install: bin/pdata_tools $(INSTALL_DIR) $(MANPATH)/man8 $(INSTALL_DATA) man8/cache_check.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/cache_dump.8 $(MANPATH)/man8 + $(INSTALL_DATA) man8/cache_metadata_size.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/cache_repair.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/cache_restore.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/cache_writeback.8 $(MANPATH)/man8 @@ -270,15 +272,15 @@ install: bin/pdata_tools $(INSTALL_DATA) man8/thin_metadata_size.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/era_check.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/era_dump.8 $(MANPATH)/man8 + $(INSTALL_DATA) man8/era_restore.8 $(MANPATH)/man8 $(INSTALL_DATA) man8/era_invalidate.8 $(MANPATH)/man8 + $(INSTALL_DATA) man8/thin_trim.8 $(MANPATH)/man8 ifeq ("@DEVTOOLS@", "yes") ln -s -f pdata_tools $(BINDIR)/thin_show_duplicates - ln -s -f pdata_tools $(BINDIR)/thin_trim ln -s -f pdata_tools $(BINDIR)/thin_ll_dump ln -s -f pdata_tools $(BINDIR)/thin_show_duplicates ln -s -f pdata_tools $(BINDIR)/thin_generate_metadata ln -s -f pdata_tools $(BINDIR)/thin_scan - $(INSTALL_DATA) man8/thin_trim.8 $(MANPATH)/man8 endif # $(INSTALL_DATA) man8/era_restore.8 $(MANPATH)/man8 diff --git a/caching/cache_metadata_size.cc b/caching/cache_metadata_size.cc index 57cfe03..94e71f6 100644 --- a/caching/cache_metadata_size.cc +++ b/caching/cache_metadata_size.cc @@ -141,7 +141,8 @@ cache_metadata_size_cmd::usage(ostream &out) const << " {-V|--version}" << endl << " {--block-size }" << endl << " {--device-size }" << endl - << " {--nr-blocks }" << endl << endl + << " {--nr-blocks }" << endl + << " {--max-hint-width }" << endl << endl << "These all relate to the size of the fast device (eg, SSD), rather" << endl << "than the whole cached device." << endl; } @@ -164,7 +165,7 @@ cache_metadata_size_cmd::run(int argc, char **argv) cout << calc_size(nr_blocks, fs.max_hint_width) << " sectors" << endl; } catch (std::exception const &e) { - cerr << e.what(); + cerr << e.what() << "\n"; return 1; } diff --git a/era/era_invalidate.cc b/era/era_invalidate.cc index 76eaadd..e9a4ca1 100644 --- a/era/era_invalidate.cc +++ b/era/era_invalidate.cc @@ -199,6 +199,7 @@ era_invalidate_cmd::usage(std::ostream &out) const << " {-h|--help}\n" << " {-o }\n" << " {--metadata-snapshot}\n" + << " {--written-since}\n" << " {-V|--version}" << endl; } diff --git a/man8/cache_check.8 b/man8/cache_check.8 index 1d53c18..0a48944 100644 --- a/man8/cache_check.8 +++ b/man8/cache_check.8 @@ -40,6 +40,10 @@ 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: diff --git a/man8/cache_dump.8 b/man8/cache_dump.8 index 00a6cfc..0f55578 100644 --- a/man8/cache_dump.8 +++ b/man8/cache_dump.8 @@ -31,6 +31,9 @@ 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. diff --git a/man8/cache_metadata_size.8 b/man8/cache_metadata_size.8 new file mode 100644 index 0000000..af72ad1 --- /dev/null +++ b/man8/cache_metadata_size.8 @@ -0,0 +1,43 @@ +.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_restore.8 b/man8/cache_restore.8 index 9a1de2f..f3eb57e 100644 --- a/man8/cache_restore.8 +++ b/man8/cache_restore.8 @@ -33,10 +33,11 @@ Input file or device with metadata. 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{\-\-debug-override-metadata-version}\fP \fI\fP" -ONLY FOR DEBUGGING PURPOSES: -.br -override the version stored in 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. @@ -44,6 +45,16 @@ 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 diff --git a/man8/cache_writeback.8 b/man8/cache_writeback.8 index 525b63a..c01a071 100644 --- a/man8/cache_writeback.8 +++ b/man8/cache_writeback.8 @@ -32,11 +32,18 @@ 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\-\-skip\-metadata\-update\fP" +.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. diff --git a/man8/era_dump.8 b/man8/era_dump.8 index b1ad2b6..78a5162 100644 --- a/man8/era_dump.8 +++ b/man8/era_dump.8 @@ -25,7 +25,7 @@ in order to put it back onto a metadata This tool cannot be run on live metadata. -.IP "\fB\-r, \-\-repair\fP". +.IP "\fB\-\-repair\fP". Repair the metadata whilst dumping it. .IP "\fB\-h, \-\-help\fP". @@ -39,6 +39,9 @@ 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: diff --git a/man8/era_invalidate.8 b/man8/era_invalidate.8 index 9bc6994..62c221f 100644 --- a/man8/era_invalidate.8 +++ b/man8/era_invalidate.8 @@ -25,6 +25,12 @@ 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. diff --git a/man8/era_restore.8 b/man8/era_restore.8 new file mode 100644 index 0000000..a7b8ccc --- /dev/null +++ b/man8/era_restore.8 @@ -0,0 +1,64 @@ +.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/thin_delta.8 b/man8/thin_delta.8 index 565ad71..e845600 100644 --- a/man8/thin_delta.8 +++ b/man8/thin_delta.8 @@ -17,7 +17,7 @@ This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP opt .IP "\fB\-\-thin1, \-\-snap1\fP" The numeric identifier for the first thin volume to diff. -.IP "\fB\-\-thin1, \-\-snap1\fP" +.IP "\fB\-\-thin2, \-\-snap2\fP" The numeric identifier for the second thin volume to diff. .IP "\fB\-m, \-\-metadata\-snap\fP [block#]" diff --git a/man8/thin_dump.8 b/man8/thin_dump.8 index eb81c29..0d853e2 100644 --- a/man8/thin_dump.8 +++ b/man8/thin_dump.8 @@ -51,6 +51,9 @@ 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. diff --git a/man8/thin_ls.8 b/man8/thin_ls.8 index 47607c6..d6cb9bf 100644 --- a/man8/thin_ls.8 +++ b/man8/thin_ls.8 @@ -30,9 +30,6 @@ Don't output headers. 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\-\-verbose" -Provide extra information on the mappings. - .IP "\fB\-h, \-\-help\fP" Print help and exit. diff --git a/thin-provisioning/commands.cc b/thin-provisioning/commands.cc index 4f2af9d..b5f8495 100644 --- a/thin-provisioning/commands.cc +++ b/thin-provisioning/commands.cc @@ -16,12 +16,12 @@ thin_provisioning::register_thin_commands(base::application &app) app.add_cmd(command::ptr(new thin_restore_cmd())); app.add_cmd(command::ptr(new thin_repair_cmd())); app.add_cmd(command::ptr(new thin_rmap_cmd())); + app.add_cmd(command::ptr(new thin_trim_cmd())); #ifdef DEV_TOOLS app.add_cmd(command::ptr(new thin_ll_dump_cmd())); app.add_cmd(command::ptr(new thin_ll_restore_cmd())); app.add_cmd(command::ptr(new thin_scan_cmd())); - app.add_cmd(command::ptr(new thin_trim_cmd())); app.add_cmd(command::ptr(new thin_generate_metadata_cmd())); app.add_cmd(command::ptr(new thin_show_duplicates_cmd())); app.add_cmd(command::ptr(new thin_show_metadata_cmd())); diff --git a/thin-provisioning/thin_dump.cc b/thin-provisioning/thin_dump.cc index c6a964a..17ddee6 100644 --- a/thin-provisioning/thin_dump.cc +++ b/thin-provisioning/thin_dump.cc @@ -123,6 +123,7 @@ thin_dump_cmd::usage(std::ostream &out) const << " {-m|--metadata-snap} [block#]\n" << " {-o }\n" << " {--dev-id} \n" + << " {--skip-mappings}\n" << " {-V|--version}" << endl; }