improve info about vgck updatemetadata

Add man page info about this option, and add log messages
pointing to this option.

3 files changed, 17 insertions, 2 deletions

diff --git a/lib/cache/lvmcache.c b/lib/cache/lvmcache.c
index 6cb5ff0d8..b1d05fb07 100644
--- a/lib/cache/lvmcache.c
+++ b/lib/cache/lvmcache.c
@@ -84,6 +84,7 @@ static DM_LIST_INIT(_unused_duplicates);
 static DM_LIST_INIT(_prev_unused_duplicate_devs);
 static int _vgs_locked = 0;
 static int _found_duplicate_vgnames = 0;
+static int _outdated_warning = 0;
 
 int lvmcache_init(struct cmd_context *cmd)
 {
@@ -1776,6 +1777,9 @@ int lvmcache_update_vg_from_read(struct volume_group *vg, unsigned precommitted)
 		log_warn("WARNING: outdated PV %s seqno %u has been removed in current VG %s seqno %u.",
 			 dev_name(info->dev), info->summary_seqno, vg->name, vginfo->seqno);
 
+		if (!_outdated_warning++)
+			log_warn("See vgck --updatemetadata to clear outdated metadata.");
+
 		_drop_vginfo(info, vginfo); /* remove from vginfo->infos */
 		dm_list_add(&vginfo->outdated_infos, &info->list);
 	}
diff --git a/lib/metadata/metadata.c b/lib/metadata/metadata.c
index 4b8dce902..c0d42066d 100644
--- a/lib/metadata/metadata.c
+++ b/lib/metadata/metadata.c
@@ -4875,8 +4875,10 @@ static struct volume_group *_vg_read(struct cmd_context *cmd,
 		}
 	}
 
-	if (found_old_metadata)
+	if (found_old_metadata) {
 		log_warn("WARNING: Inconsistent metadata found for VG %s.", vgname);
+		log_warn("See vgck --updatemetadata to correct inconsistency.");
+	}
 
 	vg = NULL;
 
diff --git a/tools/args.h b/tools/args.h
index d1f604b0c..5fae21abb 100644
--- a/tools/args.h
+++ b/tools/args.h
@@ -1428,7 +1428,16 @@ arg(thin_ARG, 'T', "thin", 0, 0, 0,
     "See \\fBlvmthin\\fP(7) for more information about LVM thin provisioning.\n")
 
 arg(updatemetadata_ARG, '\0', "updatemetadata", 0, 0, 0,
-    "Update VG metadata to correct problems.\n")
+    "Update VG metadata to correct problems.\n"
+    "If VG metadata was updated while a PV was missing, and the PV\n"
+    "reappears with an old version of metadata, then this option\n"
+    "(or any other command that writes metadata) will update the\n"
+    "metadata on the previously missing PV. If a PV was removed\n"
+    "from a VG while it was missing, and the PV reappears, using\n"
+    "this option will clear the outdated metadata from the previously\n"
+    "missing PV. If metadata text is damaged on one PV, using this\n"
+    "option will replace the damaged metadata text. For more severe\n"
+    "damage, e.g. with headers, see \\fBpvck\\fP(8).\n")
 
 arg(uuid_ARG, 'u', "uuid", 0, 0, 0,
     "#pvchange\n"