Check LVM Volume Group Metadata Safely with vgck

You will use vgck to read the metadata of an LVM volume group, select a group or tag explicitly, and rehearse a metadata repair without allowing it to write. The installed command is from LVM2 2.03.16(2), dated 18 May 2022, in package lvm2 2.03.16-3ubuntu3.2.

Allow about fifteen minutes for a routine check. You need a shell, an existing volume group name, and enough privilege for LVM to read the devices and acquire its locks. The read-only inspection is normally an administrative command and may need sudo on a production host.

1. Confirm the installed command

Start with the binary and version. These commands only inspect the local installation:

$ command -v vgck
/usr/sbin/vgck
$ vgck --version
LVM version:     2.03.16(2) (2022-05-18)
Library version: 1.02.185 (2022-05-18)

The exact path can differ. The version matters because LVM tools share common options, while details of reports and device discovery can change between releases.

2. Identify the volume group you intend to check

Set a placeholder to the exact volume group name. Do not include angle brackets in the command, and do not guess a name from a mount point:

VG_NAME='example-vg'
printf 'checking volume group: %s\n' "$VG_NAME"

If you need to discover names, use an existing read-only LVM inventory command such as vgs or inspect the host's documented storage inventory. The argument to vgck can be a volume group name or a tag. A tag may select more than one group, so prefer an explicit name when you are investigating one group.

Keep the name quoted in scripts. This makes the intended argument boundary clear and avoids accidental word splitting if a value comes from another command or configuration source.

3. Run the ordinary consistency check

Run the check for the chosen group:

$ sudo vgck "$VG_NAME"

There may be little or no standard output when the check succeeds. That is not a request to add --updatemetadata. Treat the exit status as the first result:

sudo vgck "$VG_NAME"
status=$?
printf 'vgck exit status: %s\n' "$status"
test "$status" -eq 0

An exit status of zero means this invocation completed successfully. It is not a guarantee that every physical device is healthy, that a filesystem is usable, or that the group can be activated in every situation. Preserve the command's diagnostics if the status is non-zero; they identify the next investigation.

4. Ask for a machine-readable report

The installed manual documents basic and json report formats. JSON is useful when a check is collected by a script, but the report describes the host's current state, so do not hard-code example fields without inspecting this command's output:

$ sudo vgck --reportformat json "$VG_NAME"

For a human investigation, the default basic format is usually easier to scan. For automation, save the output and validate it with a JSON parser rather than matching a few words with grep. Keep stderr separate if your collector needs to distinguish report data from warnings.

sudo vgck --reportformat json "$VG_NAME" > vgck-report.json
status=$?
if test "$status" -ne 0; then
    printf 'vgck failed with status %s; inspect diagnostics before using the report\n' "$status" >&2
    exit "$status"
fi
python3 -m json.tool vgck-report.json > /dev/null

The final parser command is only a syntax check for the saved output. It does not prove that the metadata is correct. If your host does not have Python, use another JSON parser already approved for that system.

5. Rehearse a metadata update without writing

When the diagnostics indicate a metadata problem, first run the same repair form in test mode. The --updatemetadata option requires a volume group argument, and --test disables metadata writing:

$ sudo vgck --test --updatemetadata "$VG_NAME"
$ printf 'test-mode exit status: %s\n' "$?"
test-mode exit status: 0

Test mode can still read devices, take locks, and produce unusual messages in multi-stage operations because later stages may expect a change that was deliberately not made. A successful test is a rehearsal, not evidence that the real update is risk-free.

Do not use --yes during this rehearsal. That option automatically answers prompts with yes. It is intended for controlled automation and the manual warns to use it with extreme caution.

6. Apply a metadata update only with a recovery plan

Only an administrator who has reviewed the diagnostics and the affected storage should perform the write:

$ sudo vgck --updatemetadata "$VG_NAME"

This can update metadata that was left behind on a previously missing physical volume, clear outdated metadata when a removed volume returns, or replace damaged metadata text on a physical volume. It is not a general repair for severe damage such as damaged headers; the installed manual directs those cases to pvck.

Before this step, take the LVM metadata backup required by your operating procedure and make sure the affected devices are stable. Keep a maintenance window if the group is active. Do not interrupt the command, remove devices, or run competing LVM commands while it is writing.

There is no generic undo command for a metadata rewrite. If the result is wrong, stop further changes and use the known-good metadata backup and your tested vgcfgrestore recovery procedure. Restore operations can themselves alter metadata, so confirm the target group and devices twice before proceeding.

7. Diagnose the common traps

• Permission or device-mapper errors: rerun the read-only check with the privilege required by the host and confirm that the expected devices are visible. Do not disable locking merely to make a command return; the manual warns that concurrent commands can then produce incorrect results.
• A group appears incomplete: check whether the command was restricted with --devices or a devices file. The manual says devices excluded by that setting appear to be missing.
• JSON is mixed with diagnostics: separate standard output and standard error, and parse only the saved report stream.
• The command reports no problem but activation still fails: vgck checks LVM metadata consistency. It does not replace checks of physical devices, filesystems, kernel device-mapper state, or the service using the volume.