lvmautoactivation(7)

event autoactivation

LVM autoactivation is "event based", in which complete VGs are activated in response to uevents which occur during system startup or at any time after the system has started. An old form of autoactivation was "static", in which complete VGs were activated at a fixed point during system startup by a systemd service, and not in response to events.

Event based autoactivation is driven by udev, udev rules, and systemd. When a device is attached to a machine, a uevent is generated by the kernel to notify userspace of the new device. systemd-udev runs udev rules to process the new device. Udev rules use blkid to identify the device as an LVM PV and then execute the lvm-specific udev rule for the device, which triggers autoactivation.

There are two variations of event based autoactivation that may be used on a system, depending on the LVM udev rule that is installed (found in /lib/udev/rules.d/). The following summarizes the steps in each rule that lead to autoactivation:

69-dm-lvm-metad.rules

•

device /dev/name with major:minor X:Y is attached to the machine

•

systemd/udev runs blkid to identify /dev/name as an LVM PV

•

udev rule 69-dm-lvm-metad.rules is run for /dev/name

•

the lvm udev rule runs the systemd service lvm2-pvscan@X:Y.service

•

the lvm2-pvscan service runs:
pvscan --cache -aay --major X --minor Y

•

pvscan reads the device, records that the PV is online (see pvs_online), and checks if the VG is complete.

•

if the VG is complete, pvscan creates the vgs_online temp file, and activates the VG.

•

the activation command output can be seen from systemctl status lvm2-pvscan*

69-dm-lvm.rules

•

device /dev/name with major:minor X:Y is attached to the machine

•

systemd/udev runs blkid to identify /dev/name as an LVM PV

•

udev rule 69-dm-lvm.rules is run for /dev/name

•

the lvm udev rule runs:
pvscan --cache --listvg --checkcomplete --vgonline --autoactivation event --udevoutput --journal=output /dev/name

•

pvscan reads the device, records that the PV is online (see pvs_online), and checks if the VG is complete.

•

if the VG is complete, pvscan creates the vgs_online temp file, and prints the name of the VG for the udev rule to import: LVM_VG_NAME_COMPLETE='vgname'

•

if the lvm udev rule sees LVM_VG_NAME_COMPLETE from pvscan, it activates the VG using a transient systemd service named lvm-activate-<vgname>.

•

the lvm-activate-<vgname> service runs
vgchange -aay --autoactivation event <vgname>

•

the activation command output can be seen from journalctl -u lvm-activate-<vgname>

pvscan options

--cache

Read the <device> arg (and only that device), and record that the PV is online by creating the /run/lvm/pvs_online/<pvid> file containing the name of the VG and the device for the PV.

-aay

Activate the VG from the pvscan command (includes implicit --checkcomplete and --vgonline.)

--checkcomplete

Check if the VG is complete, i.e. all PVs are present on the system, by checking /run/lvm/pvs_online/<pvid> files.

--vgonline

Create /run/lvm/vgs_online/<vgname> if the VG is complete (used to ensure only one command performs activation.)

--autoactivation event

Inform the command it is used for event based autoactivation.

--listvg

Print the name of the VG using the device.

--udevoutput

Only print output that can be imported to the udev rule, using the udev environment key format, i.e. NAME='value'.

--journal=output

Send standard command output to the journal (when stdout is reserved for udev output.)

PVs on LVs

An active LV can be used as a PV for another VG. This is sometimes called a layered or nested VG. For example, an LV in an outer VG can contain a PV and an inner VG. The outer LV must be active before commands can find or use the inner PV.

By default, LVM does not scan LVs for PVs. This avoids finding LVM metadata inside guest or VM disk images stored on an LV. Do not enable scanning for all LVs unless every such LV is intended to be used as an LVM PV by the host.

To allow commands to find intentionally layered PVs, set devices/scan_lvs to 1 in lvm.conf(5). When this setting is enabled, restrict the LVs that LVM scans to the intended storage LVs. Use the LVM devices file described in lvmdevices(8), or, when the devices file is disabled, use the lvm.conf filter. The devices file must include the outer LV device as well as any other devices needed by the command.

For example, after configuring scan_lvs and the applicable devices-file or filter restriction, an outer LV can be prepared and used as follows:

# lvchange -ay outer_vg/storage_lv
# pvcreate /dev/outer_vg/storage_lv
# vgcreate inner_vg /dev/outer_vg/storage_lv
# vgchange -ay inner_vg
# pvs /dev/outer_vg/storage_lv
# vgs inner_vg

The setting enables explicit LVM commands to scan active LVs, but does not enable event-based autoactivation of an inner VG. The installed 69-dm-lvm.rules deliberately ignores a PV found on an LV, again to avoid host activation of guest VGs. To opt in to event-based autoactivation, add a custom udev rule that sets LVM_PVSCAN_ON_LVS=1 only for the selected storage LVs. The rule must sort before 69-dm-lvm.rules and must match the local naming or identification convention for those LVs.

For example, a file named /etc/udev/rules.d/68-lvm-pv-on-lv.rules can use LVM's udev properties to select an outer VG and LV:

ACTION=="add|change", ENV{DM_UUID}=="LVM-?*", \
ENV{DM_VG_NAME}=="outer_vg", ENV{DM_LV_NAME}=="storage_lv", \
ENV{LVM_PVSCAN_ON_LVS}="1"

Replace the VG and LV matches with a sufficiently narrow local rule. In particular, do not use a rule that sets this variable for every LV: it can cause the host to scan and activate VGs belonging to guest images. The properties used in the example are populated by the device-mapper udev rules that run before this rule.

After adding or changing the custom rule, reload udev rules and cause an event for the active outer LV, for example:

# udevadm control --reload
# udevadm trigger --action=change /dev/outer_vg/storage_lv
# udevadm settle

When udev recognizes the contained PV, its usual pvscan flow records the inner PV as online. If all PVs in the inner VG are present and eligible for autoactivation, the inner VG is activated. Check the result with vgs or lvs and inspect the transient lvm-activate-inner_vg unit journal if activation does not occur.

At boot, the outer VG and storage LV must first be eligible for and complete enough to be autoactivated. Activation of that LV then produces the event that lets the udev rule discover and activate the inner VG.

run files

Autoactivation commands use a number of temporary files in /run/lvm (with the expectation that it is cleared between boots).

pvs_online

pvscan --cache creates a file here for each PV that is attached. The file is named with the PVID and contains the VG name and device information. The existence of the file is used to determine when all PVs for a given VG are present. The device information in these files is also used to optimize locating devices for a VG when the VG is activated.

pvs_lookup

pvscan --cache creates a file here named for a VG (if one doesn't already exist.) The file contains a list of PVIDs in the VG. This is needed when a PV is processed which has no VG metadata, in which case the list of PVIDs from the lookup file is used to check if the VG is complete.

vgs_online

The first activation command (pvscan or vgchange) to create a file here, named for the VG, will activate the VG. This resolves a race when concurrent commands attempt to activate a VG at once.

static autoactivation

A static autoactivation method is no longer provided by lvm. Setting event_activation=0 still disables event based autoactivation. WARNING: disabling event activation without an alternative may prevent a system from booting. A custom systemd service could be written to run autoactivation during system startup, in which case disabling event autoactivation may be useful.

lvm.conf filter

Device symlinks from /dev/disk/ can be used in the lvm.conf(5) filter to guard against changes in kernel device names. The /dev/disk/by-path/ or /dev/disk/by-id/ prefixes should be included in the filter names; these prefixes help lvm detect that symlink names are used. Filters containing symlinks require special matching by commands run in the lvm udev rule.

Common symlinks, such as those beginning with wwn-, scsi-, pci-, or lvm-pv-uuid-, are recommended. Uncommon or custom symlinks created by custom udev rules may be less reliable. If a custom udev rule creates symlinks used in the lvm filter, then the udev rule should be started prior to the lvm rule.