diff options
Diffstat (limited to 'man/lvmautoactivation.7_main')
-rw-r--r-- | man/lvmautoactivation.7_main | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/man/lvmautoactivation.7_main b/man/lvmautoactivation.7_main new file mode 100644 index 0000000..0f77345 --- /dev/null +++ b/man/lvmautoactivation.7_main @@ -0,0 +1,302 @@ +.TH "LVMAUTOACTIVATION" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" +. +.SH NAME +. +lvmautoactivation \(em LVM autoactivation +. +.SH DESCRIPTION +. +Autoactivation is the activation of LVs performed automatically by the +system in response to LVM devices being attached to the machine. When all +PVs in a VG have been attached, the VG is complete, and LVs in the VG are +activated. +.P +Autoactivation of VGs, or specific LVs, can be prevented using vgchange or +lvchange --setautoactivation n. The lvm.conf auto_activation_volume_list +is another way to limit autoactivation. +. +.SS event autoactivation +.P +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 are activated at a fixed point during system startup +by a systemd service, and not in response to events. +.P +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. +.P +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 +which lead to autoactivation: +.P +.B 69-dm-lvm-metad.rules +. +.IP \[bu] 2 +device /dev/name with major:minor X:Y is attached to the machine +. +.IP \[bu] 2 +systemd/udev runs blkid to identify /dev/name as an LVM PV +. +.IP \[bu] 2 +udev rule 69-dm-lvm-metad.rules is run for /dev/name +. +.IP \[bu] 2 +the lvm udev rule runs the systemd service lvm2-pvscan@X:Yservice +. +.IP \[bu] 2 +the lvm2-pvscan service runs: +.br +pvscan --cache -aay --major X --minor Y +. +.IP \[bu] 2 +pvscan reads the device, records that the PV is online +(see pvs_online), and checks if the VG is complete. +. +.IP \[bu] 2 +if the VG is complete, pvscan creates the vgs_online temp file, +and activates the VG. +. +.IP \[bu] 2 +the activation command output can be seen from +systemctl status lvm2-pvscan* +.P +.B 69-dm-lvm.rules +. +.IP \[bu] 2 +device /dev/name with major:minor X:Y is attached to the machine +. +.IP \[bu] 2 +systemd/udev runs blkid to identify /dev/name as an LVM PV +. +.IP \[bu] 2 +udev rule 69-dm-lvm.rules is run for /dev/name +. +.IP \[bu] 2 +the lvm udev rule runs: +.br +pvscan --cache --listvg --checkcomplete --vgonline +.br +--autoactivation event --udevoutput --journal=output /dev/name +. +.IP \[bu] 2 +pvscan reads the device, records that the PV is online +(see pvs_online), and checks if the VG is complete. +. +.IP \[bu] 2 +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' +. +.IP \[bu] 2 +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>. +. +.IP \[bu] 2 +the lvm-activate-<vgname> service runs +.br +vgchange -aay --autoactivation event <vgname> +. +.IP \[bu] 2 +the activation command output can be seen from +journalctl -u lvm-activate-<vgname> +.P +. +.SS pvscan options +.P +.B --cache +.br +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. +.P +.B -aay +.br +Activate the VG from the pvscan command +(includes implicit --checkcomplete and --vgonline.) +.P +.B --checkcomplete +.br +Check if the VG is complete, i.e. all PVs are present on +the system, by checking /run/lvm/pvs_online/<pvid> files. +.P +.B --vgonline +.br +Create /run/lvm/vgs_online/<vgname> if the VG is complete +(used to ensure only one command performs activation.) +.P +.B --autoactivation event +.br +Inform the command it is used for event based autoactivation. +.P +.B --listvg +.br +Print the name of the VG using the device. +.P +.B --udevoutput +.br +Only print output that can be imported to the udev rule, +using the udev environment key format, i.e. NAME='value'. +.P +.B --journal=output +.br +Send standard command output to the journal (when stdout +is reserved for udev output.) +.P +.SS run files +.P +Autoactivation commands use a number of temp files in /run/lvm (with the +expectation that /run is cleared between boots.) +.P +.B pvs_online +.br +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. +.P +.B pvs_lookup +.br +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. +.P +.B vgs_online +.br +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. +. +.SS static autoactivation +.P +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. +. +.SS lvm.conf filter +.P +Device symlinks from /dev/disk/ can be used in the lvm.conf 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. +.P +Common symlinks, e.g. 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. +. +.SH EXAMPLES +.P +VG "vg" contains two PVs: +.nf +$ pvs -o name,vgname,uuid /dev/sdb /dev/sdc + PV VG PV UUID + /dev/sdb vg 1uKpaT-lFOZ-NLHX-j4jI-OBi1-QpdE-HZ5hZY + /dev/sdc vg 5J3tM8-aIPe-2vbd-DBe7-bvRq-TGj0-DaKV2G +.fi +.P +use of --cache: +.nf +$ pvscan --cache /dev/sdb + pvscan[12922] PV /dev/sdb online. +$ pvscan --cache /dev/sdc + pvscan[12923] PV /dev/sdc online. + +$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY +8:16 +vg:vg +dev:/dev/sdb +$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G +8:32 +vg:vg +dev:/dev/sdc +.fi +.P +use of -aay: +.nf +$ pvscan --cache -aay /dev/sdb + pvscan[12935] PV /dev/sdb online, VG vg incomplete (need 1). +$ pvscan --cache -aay /dev/sdc + pvscan[12936] PV /dev/sdc online, VG vg is complete. + pvscan[12936] VG vg run autoactivation. + 1 logical volume(s) in volume group "vg" now active + +$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY +8:16 +vg:vg +dev:/dev/sdb +$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G +8:32 +vg:vg +dev:/dev/sdc +$ ls /run/lvm/vgs_online/vg +/run/lvm/vgs_online/vg +.fi +.P +use of --listvg: +.nf +$ pvscan --cache --listvg /dev/sdb + VG vg +$ pvscan --cache --listvg /dev/sdc + VG vg + +$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY +8:16 +vg:vg +dev:/dev/sdb +$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G +8:32 +vg:vg +dev:/dev/sdc +.fi +.P +use of --checkcomplete: +.nf +$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdb + pvscan[12996] PV /dev/sdb online, VG vg incomplete (need 1). + VG vg incomplete +$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdc + pvscan[12997] PV /dev/sdc online, VG vg is complete. + VG vg complete +.fi +.P +use of --udevoutput: +.nf +$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdb +LVM_VG_NAME_INCOMPLETE='vg' +$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdc +LVM_VG_NAME_COMPLETE='vg' +.fi +.P +use of --listlvs: +.nf +$ lvs -o name,devices vg + LV Devices + lvol0 /dev/sdb(0) + lvol1 /dev/sdc(0) + lvol2 /dev/sdb(1),/dev/sdc(1) + +$ pvscan --cache --listlvs --checkcomplete /dev/sdb + pvscan[13288] PV /dev/sdb online, VG vg incomplete (need 1). + VG vg incomplete + LV vg/lvol0 complete + LV vg/lvol2 incomplete +$ pvscan --cache --listlvs --checkcomplete /dev/sdc + pvscan[13289] PV /dev/sdc online, VG vg is complete. + VG vg complete + LV vg/lvol1 complete + LV vg/lvol2 complete +.fi + |