lvmdevices - Man Page

Run the lvmdevices command with no options or arguments to display the entries in system.devices:
lvmdevices

Each line begins with a current device name from the system, followed by its device ID from the devices file, followed by other device details used by lvm. A line begins with "Device none" if no device on the system matches the device ID. (Viewing the system.devices file directly does not indicate if a device is present on the system.)

To use a device with lvm, add it to the devices file with one of the following commands.

Add a device by referencing its device path:
lvmdevices --adddev device

Add a device by referencing its PVID:
lvmdevices --addpvid PVID

Add a device by referencing its device ID:
lvmdevices --addid IDNAME --deviceidtype IDTYPE

Add all of the PVs in a VG:
vgimportdevices VG

Add all of the PVs in all visible VGs:
vgimportdevices -a

pvcreate, vgcreate, and vgextend also look outside of the existing devices file to find the target device, and automatically add it to the devices file.

Removing a device from the devices file will prevent lvm from seeing or using that device.  Remove a device with one of the following commands.

Remove a device by referencing its device path:
lvmdevices --deldev device

Remove a device by referencing its PVID:
lvmdevices --delpvid PVID

Remove a device by referencing its device ID:
lvmdevices --delid IDNAME --deviceidtype IDTYPE

LVM identifies devices in the devices file using hardware-specific IDs, such as the WWID or serial number.  Subsystem-specific IDs are used for virtual device types, which also aim to be unique and stable. When no hardware or subsystem ID is available, lvm falls back using the device name as the device ID.  Using device names as IDs is not optimal because they are not stable, and will often change after reboot.  When device names are used as IDs, lvm must perform extra device scanning to locate devices if the device name changes.

When stable device IDs are used, lvm will not access devices outside of those listed in the devices file.  When device names are used as IDs, lvm will scan devices outside the devices file to locate PVs on devices that changed names.  The config setting search_for_devnames can be used to control lvm's behavior in locating renamed devname entries.

A device ID has two parts: an IDTYPE and an IDNAME.

The IDTYPE specifies the origin of the ID, and the IDNAME is the actual identifier.  There is a predefined set of IDTYPEs listed in the next section.  A devices file entry must have one of these ID types.  When adding a device to the devices file, lvm automatically chooses the best IDTYPE, which can be overridden with the --deviceidtype option (this is not generally recommended.)

To display all of the possible device IDs for a device, or the value of one specific type, use the commands:

lvmdevices --listids device
lvmdevices --listids device --deviceidtype IDTYPE

The available device ID types are:

• sys_wwid uses the wwid reported by the wwid sysfs file. This is the first choice.
• wwid_naa uses the naa wwid decoded from the vpd_pg83 sysfs file.
• wwid_eui uses the eui wwid decoded from the vpd_pg83 sysfs file.
• wwid_t10 uses the t10 wwid decoded from the vpd_pg83 sysfs file.
• sys_serial uses the serial number reported by the serial sysfs file or the vpd_pg80 file. A serial number is used if no wwid is available.
• mpath_uuid is used for dm multipath devices, reported by sysfs.
• crypt_uuid is used for dm crypt devices, reported by sysfs.
• md_uuid is used for md devices, reported by sysfs.
• lvmlv_uuid is used if a PV is placed on top of an lvm LV, reported by sysfs.
• loop_file is used for loop devices, the backing file name reported by sysfs.
• devname the device name is used if no other type applies.
• nvme_uuid, nvme_nguid, nvme_eui64 are not generally used, but may appear for nvme devices that report invalid wwid values.

Most of the device ID types read the device ID value from sysfs. Those sysfs values can also be read directly from the following paths:

/sys/dev/block/major:minor/device/wwid
/sys/dev/block/major:minor/device/serial
/sys/dev/block/major:minor/wwid
/sys/dev/block/major:minor/device/vpd_pg83 (binary)
/sys/dev/block/major:minor/device/vpd_pg80 (binary)
/sys/dev/block/major:minor/dm/uuid (lvm reads via ioctl)
/sys/dev/block/major:minor/md/uuid
/sys/dev/block/major:minor/loop/backing_file

(Some sysfs values are modified before being used as the device ID, e.g. spaces omitted or replaced with underscores.)

LVM writes some additional information to the devices file in addition to the device IDs.  LVM commands automatically update this information if it changes.  This includes the last known device name, and the PV UUID (PVID) from the LVM disk header.

Check if the devices file content needs to be updated:
lvmdevices --check

Update devices file fields that are outdated:
lvmdevices --update

The devices file is meant to be edited by lvm commands, not by the user. The devices file contains a HASH value which lvm uses to detect if the file has been modified since lvm last wrote it. When lvm updates the devices file, the previous version is moved to /etc/lvm/devices/backup/.

The following fields can be found in the devices file:
VERSION: incremented for each file update.
PRODUCT_UUID: a unique machine ID used to detect if the system.devices file has been moved to a new machine, and may require updating. When not available, HOSTNAME is used.

Device entry fields:
IDTYPE: indicates the source of the device ID value in IDNAME.
IDNAME: the unique device ID value.
DEVNAME: the most recent device name associated with the device ID.
PVID: the LVM PV UUID from the LVM disk header.
PART: the partition number if a PV exists on a partition.

When lvm writes system.devices, it includes a local machine ID in the system.devices file (as PRODUCT_UUID or HOSTNAME.)  When lvm reads system.devices, it compares this saved machine ID to the current machine, which allows lvm to detect when system.devices has been copied or restored onto a different machine.  When a machine change is detected, lvm enables a "device ID refresh" mode (configured by lvm.conf device_ids_refresh and device_ids_refresh_checks.)

In refresh mode, a device in system.devices that is not found by its device ID will be located using its PVID.  LVM will scan all devices on the system to search for the missing PVIDs in system.devices.  If a PVID is found on a new device, the system.devices entry is updated with a new device ID matching the new device on which the PVID was found.  The refresh mode can be configured to run once, when the machine change is first detected, or can be enabled for period of time following the first refresh, or can be disabled entirely.

device_ids_refresh = 0
Disables refresh mode.

device_ids_refresh = 1
Enables one attempt to refresh device IDs when a machine change is first detected.

device_ids_refresh = seconds
The refresh mode is enabled for this number of seconds following the initial refresh attempt, or until all PVs in system.devices are found.  During this period, a REFRESH_UNTIL line appears in system.devices.  Accepted values are 10-600 seconds.

In addition to the automated device ID refresh mode, refresh can be performed manually:

Check if system.devices would be updated with new device IDs:
lvmdevices --check --refresh

Update system.devices with new device IDs if PVs are found on new devices:
lvmdevices --update --refresh

The machine ID used in system.devices will be either the DMI product_uuid from /sys/devices/virtual/dmi/id/product_uuid, or the hostname from uname(2). See lvm.conf(5) device_ids_refresh_checks to configure this.

Multiple devices files can be kept in /etc/lvm/devices, which allows lvm to be used with different sets of devices.  For example, a given application may not need to access the system's devices, and the system may not need to access the application's devices.  In this case, system.devices could list only the system's devices and <application>.devices file could list only the application's devices.  The option --devicesfile <filename> is used to select the devices file to use with the command.  Without the option set, the default system.devices file is used.

If the special devices file /etc/lvm/devices/dmeventd.devices exists, then dmeventd uses dmeventd.devices instead of system.devices. Using dmeventd.devices is necessary if VGs from separate devices files require the services of dmeventd.  In this case, dmeventd.devices should list devices from all of the VGs that require dmeventd.

There are multiple ways that the devices file feature can be disabled or overridden:

• no system.devices
  If the system.devices file does not exist, then the devices file feature is disabled.
• use_devicesfile=0
  If lvm.conf use_devicesfile is set to 0, then the devices file feature is disabled, even if the system.devices file exists.
• --devicesfile ""
  If an empty devices file name is specified on the command line, then that command will not use a devices file.
• --devices device
  If specific devices are named on the command line with --devices, then the command will not use a devices file, and will only access the named devices.
• pvs -A
  If given the -A or --allpvs option, the pvs(8) command will not use a devices file.

When the devices file is disabled, lvm commands revert to using the lvm.conf filter. When the devices file is used, lvm commands ignore the lvm.conf filter setting, except for vgimportdevices which does apply the regex filter to the set of devices on the system when looking for VGs to import to the devices file.

LVM commands that write VG metadata will include the device ID of each PV in the VG metadata.  The device ID can be displayed with the options:

pvs -o deviceidtype,deviceid

(Note that the lvmdevices command does not update VG metadata, but subsequent lvm commands modifying the metadata will include the device ID.)

If the system.devices file does not yet exist, the pvcreate or vgcreate commands will create it only if they see no existing VGs on the system. lvmdevices --adddev and vgimportdevices will always create a new devices file if it does not yet exist.