LVMDEVICES(8)

📦

version 2.03.44 · 11 versions

✨ lvmdevices — Manage the devices file ✨

hiii bestie 🫶 you just opened LVMDEVICES(8) from the System Manager's Manual, and honestly? iconic. this whole page is about who gets to be in the devices file and who does not. let's go 💅

🎀 NAME 🎀

lvmdevices — Manage the devices file.

that's it, that's the whole job description 🦋

🌸 SYNOPSIS 🌸

lvmdevices option_args
       [ option_args ]

        --adddev PV
        --addid String
        --addpvid String
        --check
        --commandprofile String
        --config String
     -d|--debug ...
        --deldev String
        --delid String
        --delnotfound
        --delpvid String
        --deviceidtype String
        --devices PV
        --devicesfile String
        --driverloaded y|n
     -f|--force ...
     -h|--help
        --journal String
        --listids PV
        --lockopt String
        --longhelp
        --nohints
        --nolocking
        --profile String
     -q|--quiet ...
        --refresh
     -t|--test
        --update
     -v|--verbose ...
        --version
     -y|--yes

so you call lvmdevices with option_args, and optionally even more option_args 🙈 the full menu is up there, and the juicy details on each one are coming. not in this part tho. patience, bestie ✨

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ the LVM devices file is literally the list of devices that lvm commands will use. that's it. that's the list. it lives at /etc/lvm/devices/system.devices.

the lvmdevices(8) command is the one that manages that file — it's used to add, remove and list devices. three jobs, she does them all 👑

📋 Listing devices

run the lvmdevices command with no options or arguments and it shows you the entries in system.devices:

lvmdevices

every line starts with a current device name from the system, then its device ID from the devices file, then other device details that lvm uses. no cap.

if there's no device on the system matching that device ID, the line starts with Device none 💀 (and heads up: looking at the system.devices file directly does not tell you whether a device is actually present on the system. rude, i know.)

➕ Adding devices

to use a device with lvm, you add it to the devices file with one of these:

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

and there's more 👀 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. they just do it. no permission asked, but like, in a helpful way 💖

➖ Removing devices

removing a device from the devices file means lvm will straight up not see it or use it. it's giving ghosted, but on purpose. remove a device with one of these:

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

🆔 device IDs

so LVM identifies devices in the devices file using hardware-specific IDs, like the WWID or serial number. slay. and for virtual device types, subsystem-specific IDs get used instead, because those also aim to be unique and stable.

when there's no hardware or subsystem ID available? lvm falls back to using the device name as the device ID. and bestie… using device names as IDs is not optimal, because device names aren't stable and will often change after reboot 😭 when device names are used as IDs, lvm has to do extra device scanning to locate devices if the device name changes. extra work. for no reason. tragic.

when stable device IDs are used, lvm will not access devices outside of those listed in the devices file. but 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.

device IDs have two parts: an IDTYPE and an IDNAME. the IDTYPE says where the ID comes from, and the IDNAME is the actual identifier. there's a predefined set of IDTYPEs in the next section, and a devices file entry has to have one of those ID types. when you add a device to the devices file, lvm automatically picks the best IDTYPE for you — and you can override it with the --deviceidtype option, but that is not generally recommended. respectfully, don't. 🙈

to see all of the possible device IDs for a device, or the value of one specific type, use these:

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

🏷️ device ID types

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. the fallback queen 💅
nvme_uuid, nvme_nguid, nvme_eui64 are not generally used, but may appear for nvme devices that report invalid wwid values. rare breed ✨

📂 sysfs files

most of the device ID types read the device ID value from sysfs. those sysfs values can also be read directly from these 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

(and psst — some sysfs values get modified before being used as the device ID, e.g. spaces omitted or replaced with underscores. little glow-up pass 🎀)

📝 devices file contents

lvm writes some additional information to the devices file on top of the device IDs. lvm commands automatically update this info 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. it contains a HASH value that lvm uses to detect if the file has been modified since lvm last wrote it. and when lvm updates the devices file, the previous version gets moved to /etc/lvm/devices/backup/. so it keeps receipts 🫶

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.

🔄 device ID refresh

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 that saved machine ID to the current machine, which lets lvm detect when system.devices has been copied or restored onto a different machine. sneaky little file move. caught 👀

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 a 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.

and on top of the automated device ID refresh mode, refresh can be done manually too:

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. ✨

🗂️ custom devices files

you can keep multiple devices files in /etc/lvm/devices, which lets lvm be used with different sets of devices. so versatile. 💅

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 the 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.

and 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 that case, dmeventd.devices should list devices from all of the VGs that require dmeventd. all of them. no skipping 🫶

🚫 disabling and overriding

there are multiple ways 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.

✨ to be continued ✨

--devices device — okay so if you name specific devices on the command line with --devices, the command straight up ignores the devices file and only touches the devices you named. That's it, that's the whole vibe. 💅
pvs -A — and if you hand pvs the -A or --allpvs option, it also refuses to use the devices file. Simple as.

So when the devices file is disabled, lvm commands fall back to the lvm.conf filter like it's their ex. 😭 But when the devices file is in use, lvm commands ignore the lvm.conf filter setting entirely — except vgimportdevices, which does apply the regex filter to the set of devices on the system when it's hunting for VGs to import into the devices file. Not me being the one exception to the rule bestie. 🫶

💫 VG metadata 💫

LVM commands that write VG metadata will include the device ID of each PV right there in the VG metadata. Obsessed. You can peep the device ID with these options:

pvs -o deviceidtype,deviceid

Quick note: the lvmdevices command does not update VG metadata, but any subsequent lvm commands that modify the metadata will include the device ID. So it's giving "I'll get there when I get there." ✨

🛠️ creating the devices file 🛠️

If the system.devices file doesn't exist yet, pvcreate or vgcreate will create it — but only if they see no existing VGs on the system. Meanwhile lvmdevices --adddev and vgimportdevices will always create a new devices file if it doesn't exist. They're the friend who starts the group chat, no hesitation, no cap. 👑

📖 USAGE 📖

Print devices in the devices file.

lvmdevices
       [ COMMON_OPTIONS ]

Check the devices file and report incorrect values.

lvmdevices --check
       [ --refresh ]
       [ COMMON_OPTIONS ]

Update the devices file to fix incorrect values.

lvmdevices --update
       [ -f|--force ... ]
       [ --delnotfound ]
       [ --refresh ]
       [ COMMON_OPTIONS ]

Add a device to the devices file.

lvmdevices --adddev PV
       [ --deviceidtype String ]
       [ COMMON_OPTIONS ]

Remove a device from the devices file.

lvmdevices --deldev String
       [ --deviceidtype String ]
       [ COMMON_OPTIONS ]

Find the device with the given PVID and add it to the devices file.

lvmdevices --addpvid String
       [ --deviceidtype String ]
       [ COMMON_OPTIONS ]

Remove the devices file entry for the given PVID.

lvmdevices --delpvid String
       [ COMMON_OPTIONS ]

Find the device with the given device_id and add it to the devices file.

lvmdevices --addid String --deviceidtype String
       [ COMMON_OPTIONS ]

Remove the devices file entry with the given device_id.

lvmdevices --delid String --deviceidtype String
       [ COMMON_OPTIONS ]

Print device_id types and values available for the device.

lvmdevices --listids PV
       [ --deviceidtype String ]
       [ COMMON_OPTIONS ]

Common options for lvm, aka the group chat everyone's in:

[ -d|--debug ... ]
[ -h|--help ]
[ -q|--quiet ... ]
[ -t|--test ]
[ -v|--verbose ... ]
[ -y|--yes ]
[ --commandprofile String ]
[ --config String ]
[ --devices PV ]
[ --devicesfile String ]
[ --driverloaded y|n ]
[ --journal String ]
[ --lockopt String ]
[ --longhelp ]
[ --nohints ]
[ --nolocking ]
[ --profile String ]
[ --version ]

✨ OPTIONS ✨

--adddev PV — Adds a device to the devices file. Slay, now it's in the roster. 💖
--addid String — Finds the device with the given device_id and adds it to the devices file.
--addpvid String — Finds a device with the PVID and adds that device to the devices file.
--check — Checks the content of the devices file and reports incorrect device names or PVIDs for entries. It's the vibe check for your devices. 👀
--commandprofile String — The command profile to use for command configuration. Peep lvm.conf(5) if you want the tea about profiles.
--config String — Config settings for the command. These override lvm.conf(5) settings, so they're highkey in charge. The String arg uses the same format as lvm.conf(5), or it can use section/field syntax. Go read lvm.conf(5) for more about config.
-d|--debug ... — Set the debug level. Repeat from 1 to 6 times to make the messages sent to the log file and/or syslog (if configured) more and more detailed. Crank that dial. 🔊
--deldev String — Remove a device from the devices file. When used alone, --deldev specifies a device name. When used with --deviceidtype, --deldev specifies a device id.
--delid String — Remove the device with the specified device ID from the devices file.
--delnotfound — Remove devices file entries that have no matching device. Ghosting entries that don't exist anymore, honestly iconic. 💀
--delpvid String — Remove a device with the PVID from the devices file.
--deviceidtype String — The type of device ID to use for the device. If the type you name is available for the device, it overrides the default type lvm would've used. You're the main character now. 👑
--devices PV — Restricts which devices are visible and accessible to the command. Devices not on the list will appear to be missing — dramatic, but make it funct— I mean, functional. 💅 This option can be repeated, or it accepts a comma-separated list of devices. It overrides the devices file.
--devicesfile String — A file listing devices that LVM should use. The file must exist in /etc/lvm/devices/ and is managed with the lvmdevices(8) command. This overrides the lvm.conf(5) devices/devicesfile and devices/use_devicesfile settings.
--driverloaded y|n — If set to no, the command will not attempt to use device-mapper. For testing and debugging. Just vibes, no real drivers. 🙈
-f|--force ... — Override various checks, confirmations and protections. Use with extreme caution. Like bestie I'm serious, this is the "hold my iced coffee" option. 🔥
-h|--help — Display help text.
--journal String — Record information in the systemd journal. This info is in addition to whatever the lvm.conf log/journal setting already enables. command: record information about the command. output: record the default command output. debug: record full command debugging.
--listids PV — Print a list of device IDs available for the device. Window shopping for IDs fr fr. ✨
--lockopt String — Used to pass options for special cases to lvmlockd. See lvmlockd(8) for more info.
--longhelp — Display long help text.
--nohints — Do not use the hints file to locate devices for PVs. A command may read more devices to find PVs when hints aren't used. The command will still perform standard hint file invalidation where appropriate. No hints, we rawdogging it. 😭
--nolocking — Disable locking. Use with caution — concurrent commands may produce incorrect results. This is the "f around and find out" speedrun. 💀
--profile String — An alias for --commandprofile or --metadataprofile, depending on the command. It's giving "I go by either name." 🦋
-q|--quiet ... — Suppress output and log messages. Overrides --debug and --verbose. Repeat it once to also suppress any prompts with answer 'no'. Peace and quiet, periodt. 🤫
--refresh — Search for missing PVs on new devices, and update the devices file with new device IDs for the PVs if they're found on new devices. This is useful if PVs have been moved to new devices with new WWIDs, for example. The device ID type and name may both change for a PV. WARNING: if a PV is detached from the system, but a device containing a clone or snapshot of that PV is present, then refresh would replace the correct device ID with the clone/snapshot device ID, and lvm would begin using the wrong device for the PV. Use deldev/adddev to safely change a PV device ID in this scenario. 🚨 Not me warning you, but like, seriously. Don't let refresh catfish lvm with a clone. 😭
-t|--test — Run in test mode. Commands will not update metadata. This is implemented by disabling all metadata writing but nevertheless returning success to the calling function. This may lead to unusual error messages in multi-stage operations if a tool relies on reading back metadata it believes has changed but hasn't. Fake it till you make it, but the metadata never made it. 🙈
--update — Update the content of the devices file.
-v|--verbose ... — Set verbose level. Repeat from 1 to 4 times to get more and more detailed messages sent to stdout and stderr. Spill the tea, louder. 📢
--version — Display version information.
-y|--yes — Do not prompt for confirmation interactively but always assume the answer yes. Use with extreme caution. (For automatic no, see -qq.) It's giving yes-girl, but scary. 💅

🧮 VARIABLES 🧮

String — See the option description for info about the string content. It's a string bestie, it strings. ✨
Size[UNIT] — Size is an input number that accepts an optional unit. Input units are always treated as base two values, no matter the capitalization — e.g. 'k' and 'K' both refer to 1024. The default input unit is specified by letter, followed by |UNIT. UNIT represents the other possible input units: b|B is bytes, s|S is sectors of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB, p|P is PiB, e|E is EiB. (This should not be confused with the output control --units, where capital letters mean a multiple of 1000.) Okay so lowercase vs uppercase here is basically the same thing, but over in --units it's a whole different story. Iykyk. 💜

🌍 ENVIRONMENT VARIABLES 🌍

See lvm(8) for the info about environment variables used by lvm. For example, LVM_VG_NAME can generally be substituted for a required VG parameter. Sub in the name like it's a tag in the group chat. 🏷️

pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8), pvremove(8), pvresize(8), pvs(8), pvscan(8),

vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8), vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8), vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),

lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8), lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),

lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),

dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), lvmdbusd(8), fsadm(8),

lvmsystemid(7), lvmreport(7), lvmcache(7), lvmraid(7), lvmthin(7), lvmvdo(7), lvmautoactivation(7)

okay bestie that's the whole page! 💖 this cutie was brought to you by Red Hat, Inc., and it's LVM TOOLS 2.03.44(2) from 2026-10-27. take care of your devices file and it'll take care of you. mwah! 🌈💅✨

📦 where this page comes from

arch rolling: lvm2 2.03.44-1 · GPL-2.0-only AND LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms