Find LVM Volume Groups Safely with vgscan

A volume group has gone missing from a report, and before you touch anything, vgscan is how you confirm whether LVM can even see it. It searches the LVM-visible block devices on a Linux host, checks the installed LVM version, and produces either human-readable or JSON output. The command is normally a read-only discovery operation. Allow about ten minutes for a single host, longer if you need to audit device visibility or investigate locking.

This guide describes the installed lvm2 command, version 2.03.16(2), from 18 May 2022. Other LVM2 releases can add options or alter report details, so check the local command before copying a script between distributions.

1. Check the installed command

Run the version and help queries as an ordinary user first. They do not scan disks or change LVM metadata:

$ vgscan --version
  LVM version:     2.03.16(2) (2022-05-18)
  Library version: 1.02.185 (2022-05-18)
$ vgscan --help
  vgscan - Search for all volume groups

The exact help output is longer than the excerpt above. Confirm that the options you plan to use are present, especially --reportformat, --devices and --devicesfile. If vgscan is missing, install or repair the distribution's lvm2 package through its normal package-management process. Do not download a replacement binary into a production path.

2. Run the basic scan

The basic command searches supported LVM block devices for volume-group metadata:

$ vgscan
  Found volume group "work" using metadata type lvm2

A host with no discoverable groups may print no group rows and still return success. Warnings about permissions, device-mapper, or locking are not the same thing as a discovered volume group. Always check the status:

$ vgscan
$ status=$?
$ printf 'vgscan exit status: %s\n' "$status"
vgscan exit status: 0

The sample group name is only an example. Do not treat a blank scan as proof that the storage is empty. LVM may be unable to see a device because it is absent, filtered, excluded by a devices file, not readable by the current user, or hidden by a multipath or virtualisation boundary.

3. Get machine-readable output

Use JSON when another program needs to consume the report. The option changes the report format; it does not make the scan broader:

$ vgscan --reportformat json
{
  "report": [
    {
      "vg": [
        {"vg_name":"work","vg_attr":"wz--n-","vg_size":"100.00g","vg_free":"20.00g"}
      ]
    }
  ]
}

Field names and whitespace can vary with the report requested and the installed release. Treat the output as JSON, not as a stable screen-scraping format. First save it to a new file, then parse it with a JSON-aware tool:

$ vgscan --reportformat json > /tmp/vgscan-report.json
$ jq . /tmp/vgscan-report.json > /dev/null
$ printf 'JSON is valid\n'
JSON is valid

The temporary file may contain warnings if your environment sends diagnostics to standard output. Check the command's output and exit status before feeding it to automation. Keep reports containing host or storage names out of world-readable locations.

4. Restrict which devices are visible

For a controlled diagnostic, pass one or more physical volume paths with --devices. Devices not listed appear to be missing to this command:

$ sudo vgscan --devices /dev/sdb1 --devices /dev/sdc1
  Found volume group "archive" using metadata type lvm2

Use sudo only when the device permissions or system configuration require it. The option accepts a comma-separated list as well, but repeating it keeps each path easy to review. Verify the paths before running the scan:

$ ls -l /dev/sdb1 /dev/sdc1
$ sudo vgscan --devices /dev/sdb1,/dev/sdc1

This is a visibility boundary, not a repair. If a group uses physical volumes outside the list, the report can describe an incomplete view. Do not use a restricted scan to decide that a volume group is safe to remove or import.

5. Understand devices files and hints

Some installations manage the allowed device set with an LVM devices file under /etc/lvm/devices/. The file is managed by lvmdevices(8). Select one explicitly with --devicesfile when you need to reproduce an existing host policy:

$ sudo vgscan --devicesfile lvm_system.devices

The named file must exist in /etc/lvm/devices/. Do not create or edit it as part of a routine scan. If a known physical volume is not found, compare the configured devices file and LVM filtering policy before changing anything.

LVM can also use a hints file to find physical volumes more quickly. --nohints disables those hints for this command and may make it read more devices. It does not bypass the devices policy. Use it as a diagnostic comparison, not as a default switch in every script:

$ sudo vgscan --nohints

6. Handle locking and device-mapper messages

On a normal host, a scan can use LVM locking while other LVM commands run. If locking fails, the command normally reports the problem instead of silently pretending the view is complete. --ignorelockingfailure permits read-only metadata operations to continue after a locking failure:

$ sudo vgscan --ignorelockingfailure

Use this only when you understand the concurrent activity. It is not a fix for a busy or misconfigured clustered LVM setup, and it should not be combined casually with other recovery work. Stop and investigate if the host is actively changing LVM metadata.

For a test that must not attempt device-mapper interaction, the installed command accepts --driverloaded n. Pairing it with --nolocking is useful for troubleshooting command-line behaviour, but it may not discover the same information as a production scan:

$ vgscan --driverloaded n --nolocking
  WARNING: Activation disabled. No device-mapper interaction will be attempted.
$ printf 'vgscan exit status: %s\n' "$?"
vgscan exit status: 0

Warning: --nolocking disables locking. Concurrent LVM commands can produce incorrect results. Do not use it to make a service-disrupting storage change appear safe. It is a diagnostic switch, not a recovery plan.

7. Use mknodes only when you need device nodes

--mknodes checks the LVM special files in /dev needed by active logical volumes, creating missing nodes and removing unused ones. This changes system state, unlike an ordinary discovery scan:

$ sudo vgscan --mknodes

Before using it, record the command's status and confirm that the host's device-management service is healthy. Do not run it as a harmless first troubleshooting step. There is no general undo command in vgscan; recovery means restoring the device-node state through the host's normal udev and LVM procedures, while leaving LVM metadata untouched.

Done means