pvck: repair headers and metadata

To write a new/repaired pv_header and label_header:

  pvck --repairtype pv_header --file <file> <device>

This uses the metadata input file to find the PV UUID,
device size, and data offset.

To write new/repaired metadata text and mda_header:

  pvck --repairtype metadata --file <file> <device>

This requires a good pv_header which points to one or two
metadata areas.  Any metadata areas referenced by the
pv_header are updated with the specified metadata and
a new mda_header. "--settings mda_num=1|2" can be used
to select one mda to repair.

To combine all header and metadata repairs:

  pvck --repair --file <file> <device>

It's best to use a raw metadata file as input, that was
extracted from another PV in the same VG (or from another
metadata area on the same PV.)  pvck will also accept a
metadata backup file, but that will produce metadata that
is not identical to other metadata copies on other PVs
and other areas.  So, when using a backup file, consider
using it to update metadata on all PVs/areas.

To get a raw metadata file to use for the repair, see
pvck --dump metadata|metadata_search.

List all instances of metadata from the metadata area:
  pvck --dump metadata_search <device>

Save one instance of metadata at the given offset to
the specified file (this file can be used for repair):

  pvck --dump metadata_search --file <file>
    --settings "metadata_offset=<off>" <device>

1 files changed, 81 insertions, 6 deletions

diff --git a/man/pvck.8_des b/man/pvck.8_des
index fb826d30e..2169d730f 100644
--- a/man/pvck.8_des
+++ b/man/pvck.8_des
@@ -1,8 +1,83 @@
-pvck checks LVM metadata on PVs.
+pvck checks and repairs LVM metadata on PVs.
 
-Use the --dump option to extract metadata from PVs for debugging.
-With dump, set --pvmetadatacopies 2 to extract metadata from a
-second metadata area at the end of the device. Use the --file
-option to save the raw metadata to a specified file. (The raw
-metadata is not usable with vgcfgbackup and vgcfgrestore.)
+.SS Dump
+
+.B headers
+.br
+Print header values and warn if any values are incorrect.  Checks the
+label_header, pv_header, mda_header(s), and metadata text.
+
+.B metadata
+.br
+Print or save the current metadata text, using headers to locate the
+metadata.  If headers are damaged, the metadata may not be found.  Use
+--settings "mda_num=2" to look in mda2 (the second mda at the end of the
+device (if used).  The metadata text is printed to stdout.  With --file,
+the metadata text is saved to a file.
+
+.B metadata_all
+.br
+List or save all versions of metadata found in the metadata area, using
+headers to locate the metadata.  If headers are damaged, the metadata may
+not be found.  Use --settings "mda_num=2" as above.  All metadata versions
+are listed (add -v to include descriptions and dates in the listing.)
+With -file, all versions are written to a file.
+
+.B metadata_search
+.br
+Search for all versions of metadata in the common locations.  This does
+not use headers, so it can find metadata even when headers are damaged.
+Use --settings "mda_num=2" as above.  All metadata versions are listed
+(add -v to include descriptions and dates in the listing.)  With --file,
+all versions are written to a file.  To save one copy of metadata, use
+--settings "metadata_offset=<offset>", where the offset is taken from the
+dump listing.
+
+.B metadata_area
+.br
+Save the entire text metadata area to a file without processing.
+
+.SS Repair
+
+.B --repair
+.br
+Repair headers and metadata on a PV.  This uses a metadata input file that
+was extracted by --dump, or a backup file (from /etc/lvm/backup).  When
+possible, use metadata saved by --dump from another PV in the same VG (or
+from a second metadata area on the PV).
+
+There are cases where the PV UUID needs to be specified for the PV being
+repaired.  It is specified using --settings "pv_uuid=<UUID>".  In
+particular, if the device name for the PV being repaired does not match
+the previous device name of the PV, then LVM may not be able to determine
+the correct PV UUID.  When headers are damaged on more than one PV in a
+VG, it is important for the user to determine the correct PV UUID and
+specify it in --settings.  Otherwise, the wrong PV UUID could be used if
+device names have been swapped since the metadata was last written.
+
+If a PV had no metadata areas and the pv_header is damaged, then the
+repair will not know to create no metadata areas during repair.  It will
+by default repair metadata in mda1.  To repair with no metadata areas, use
+--settings "mda_offset=0 mda_size=0".
+
+There are cases where repair should be run on all PVs in the VG (using the
+same metadata file):  if all PVs in the VG are damaged, if using an old
+metadata version, or if a backup file is used instead of raw metadata.
+
+Using --repair is equivalent to running --repairtype pv_header followed by
+--repairtype metadata.
+
+.B --repairtype pv_header
+.br
+Repairs the header sector, containing the pv_header and label_header.
+
+.B --repairtype metadata
+.br
+Repairs the mda_header and metadata text.  It requires the headers to be
+correct (having been undamaged or already repaired).
+
+.B --repairtype label_header
+.br
+Repairs label_header fields, leaving the pv_header (in the same sector)
+unchanged.  (repairtype pv_header should usually be used instead.)