From 25dbe3dd825a629ff7f67cb43342cc345071d3f7 Mon Sep 17 00:00:00 2001 From: David Teigland Date: Wed, 24 Nov 2021 16:03:39 -0600 Subject: [PATCH 15/54] man: lvmautoactivation new topical man page describing autoactivation --- man/Makefile.in | 2 +- man/lvm.8_main | 1 + man/lvmautoactivation.7_main | 280 +++++++++++++++++++++++++++++++++++ man/pvscan.8_des | 63 ++++---- 4 files changed, 309 insertions(+), 37 deletions(-) create mode 100644 man/lvmautoactivation.7_main diff --git a/man/Makefile.in b/man/Makefile.in index 40248d640..ba6f2046f 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -33,7 +33,7 @@ CMIRRORDMAN = cmirrord.8 LVMDBUSDMAN = lvmdbusd.8 MAN5=lvm.conf.5 -MAN7=lvmsystemid.7 lvmreport.7 lvmraid.7 +MAN7=lvmsystemid.7 lvmreport.7 lvmraid.7 lvmautoactivation.7 MAN8=lvm.8 lvmdump.8 lvm-fullreport.8 lvm-lvpoll.8 \ lvcreate.8 lvchange.8 lvmconfig.8 lvconvert.8 lvdisplay.8 \ diff --git a/man/lvm.8_main b/man/lvm.8_main index 6f86d0353..a008a3bc0 100644 --- a/man/lvm.8_main +++ b/man/lvm.8_main @@ -579,6 +579,7 @@ Prepends source file name and code line number with libdm debugging. .BR lvmraid (7), .BR lvmthin (7), .BR lvmcache (7), +.BR lvmautoactivation (7), .P .BR dmsetup (8), .BR dmstats (8), diff --git a/man/lvmautoactivation.7_main b/man/lvmautoactivation.7_main new file mode 100644 index 000000000..87c15a3d1 --- /dev/null +++ b/man/lvmautoactivation.7_main @@ -0,0 +1,280 @@ +.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. +.P +The most common form of 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. Another form of +autoactivation is "service based" in which complete VGs are activated at a +fixed point during system startup by a systemd service, and are not +activated in response to uevents. This can be controlled with the +lvm.conf setting event_activation. +.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 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-. +. +.IP \[bu] 2 +the lvm-activate- service runs +.br +vgchange -aay --autoactivation event +. +.IP \[bu] 2 +the activation command output can be seen from +systemctl status lvm-activate- +.P +. +.SS pvscan options +.P +.B --cache +.br +Read the arg (and only that device), and record that +the PV is online by creating the /run/lvm/pvs_online/ +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/ files. +.P +.B --vgonline +.br +Create /run/lvm/vgs_online/ 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 Temp 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. +. +.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 + diff --git a/man/pvscan.8_des b/man/pvscan.8_des index b20b987da..4c5929955 100644 --- a/man/pvscan.8_des +++ b/man/pvscan.8_des @@ -4,56 +4,47 @@ like or .BR pvdisplay (8). .P -When the --cache and -aay options are used, pvscan records which PVs are -available on the system, and activates LVs in completed VGs. A VG is -complete when pvscan sees that the final PV in the VG has appeared. This -is used by event-based system startup (systemd, udev) to activate LVs. -.P -The four main variations of this are: +When --cache is used, pvscan updates runtime lvm state on the system, or +with -aay performs autoactivation. .P .B pvscan --cache .I device .P -If device is present, lvm adds a record that the PV on device is online. +If device is present, lvm records that the PV on device is online. If device is not present, lvm removes the online record for the PV. -In most cases, the pvscan will only read the named devices. +pvscan only reads the named device. .P -.B pvscan --cache -aay -.IR device ... +.B pvscan --cache .P -This begins by performing the same steps as above. Afterward, if the VG -for the specified PV is complete, then pvscan will activate LVs in the VG -(the same as vgchange -aay vgname would do.) +Updates the runtime state for all lvm devices. .P -.B pvscan --cache +.B pvscan --cache -aay +.I device .P -This first clears all existing PV online records, then scans all devices -on the system, adding PV online records for any PVs that are found. +Performs the --cache steps for the device, then checks if the VG using the +device is complete. If so, LVs in the VG are autoactivated, the same as +vgchange -aay vgname would do. (A device name may be replaced with major +and minor numbers.) .P .B pvscan --cache -aay .P -This begins by performing the same steps as pvscan --cache. Afterward, it -activates LVs in any complete VGs. +Performs the --cache steps for all devices, then autoactivates any complete VGs. .P -To prevent devices from being scanned by pvscan --cache, add them -to -.BR lvm.conf (5) -.B devices/global_filter. -For more information, see: -.br -.B lvmconfig --withcomments devices/global_filter +.B pvscan --cache --listvg|--listlvs +.I device +.P +Performs the --cache steps for the device, then prints the name of the VG +using the device, or the names of LVs using the device. --checkcomplete +is usually included to check if all PVs for the VG or LVs are online. +When this command is called by a udev rule, the output must conform to +udev rule specifications (see --udevoutput.) The udev rule will use the +results to perform autoactivation. .P -Auto-activation of VGs or LVs can be enabled/disabled using: -.br +Autoactivation of VGs or LVs can be enabled/disabled using vgchange or +lvchange with --setautoactivation y|n, or by adding names to .BR lvm.conf (5) .B activation/auto_activation_volume_list .P -For more information, see: -.br -.B lvmconfig --withcomments activation/auto_activation_volume_list -.P -To disable auto-activation, explicitly set this list to an empty list, -i.e. auto_activation_volume_list = [ ]. -.P -When this setting is undefined (e.g. commented), then all LVs are -auto-activated. +See +.BR lvmautoactivation (7) +for more information about how pvscan is used for autoactivation. -- 2.34.3