b6fb8c
From 25dbe3dd825a629ff7f67cb43342cc345071d3f7 Mon Sep 17 00:00:00 2001
b6fb8c
From: David Teigland <teigland@redhat.com>
b6fb8c
Date: Wed, 24 Nov 2021 16:03:39 -0600
38b7b2
Subject: [PATCH 15/54] man: lvmautoactivation
b6fb8c
b6fb8c
new topical man page describing autoactivation
b6fb8c
---
b6fb8c
 man/Makefile.in              |   2 +-
b6fb8c
 man/lvm.8_main               |   1 +
b6fb8c
 man/lvmautoactivation.7_main | 280 +++++++++++++++++++++++++++++++++++
b6fb8c
 man/pvscan.8_des             |  63 ++++----
b6fb8c
 4 files changed, 309 insertions(+), 37 deletions(-)
b6fb8c
 create mode 100644 man/lvmautoactivation.7_main
b6fb8c
b6fb8c
diff --git a/man/Makefile.in b/man/Makefile.in
b6fb8c
index 40248d640..ba6f2046f 100644
b6fb8c
--- a/man/Makefile.in
b6fb8c
+++ b/man/Makefile.in
b6fb8c
@@ -33,7 +33,7 @@ CMIRRORDMAN = cmirrord.8
b6fb8c
 LVMDBUSDMAN = lvmdbusd.8
b6fb8c
 
b6fb8c
 MAN5=lvm.conf.5
b6fb8c
-MAN7=lvmsystemid.7 lvmreport.7 lvmraid.7
b6fb8c
+MAN7=lvmsystemid.7 lvmreport.7 lvmraid.7 lvmautoactivation.7
b6fb8c
 
b6fb8c
 MAN8=lvm.8 lvmdump.8 lvm-fullreport.8 lvm-lvpoll.8 \
b6fb8c
      lvcreate.8 lvchange.8 lvmconfig.8 lvconvert.8 lvdisplay.8 \
b6fb8c
diff --git a/man/lvm.8_main b/man/lvm.8_main
b6fb8c
index 6f86d0353..a008a3bc0 100644
b6fb8c
--- a/man/lvm.8_main
b6fb8c
+++ b/man/lvm.8_main
b6fb8c
@@ -579,6 +579,7 @@ Prepends source file name and code line number with libdm debugging.
b6fb8c
 .BR lvmraid (7),
b6fb8c
 .BR lvmthin (7),
b6fb8c
 .BR lvmcache (7),
b6fb8c
+.BR lvmautoactivation (7),
b6fb8c
 .P
b6fb8c
 .BR dmsetup (8),
b6fb8c
 .BR dmstats (8),
b6fb8c
diff --git a/man/lvmautoactivation.7_main b/man/lvmautoactivation.7_main
b6fb8c
new file mode 100644
b6fb8c
index 000000000..87c15a3d1
b6fb8c
--- /dev/null
b6fb8c
+++ b/man/lvmautoactivation.7_main
b6fb8c
@@ -0,0 +1,280 @@
b6fb8c
+.TH "LVMAUTOACTIVATION" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""
b6fb8c
+.
b6fb8c
+.SH NAME
b6fb8c
+.
b6fb8c
+lvmautoactivation \(em LVM autoactivation
b6fb8c
+.
b6fb8c
+.SH DESCRIPTION
b6fb8c
+.
b6fb8c
+Autoactivation is the activation of LVs performed automatically by the
b6fb8c
+system in response to LVM devices being attached to the machine.  When all
b6fb8c
+PVs in a VG have been attached, the VG is complete, and LVs in the VG are
b6fb8c
+activated.
b6fb8c
+.P
b6fb8c
+Autoactivation of VGs, or specific LVs, can be prevented using vgchange or
b6fb8c
+lvchange --setautoactivation n.  The lvm.conf auto_activation_volume_list
b6fb8c
+is another way to limit autoactivation.
b6fb8c
+.P
b6fb8c
+The most common form of autoactivation is "event based", in which complete
b6fb8c
+VGs are activated in response to uevents which occur during system startup
b6fb8c
+or at any time after the system has started.  Another form of
b6fb8c
+autoactivation is "service based" in which complete VGs are activated at a
b6fb8c
+fixed point during system startup by a systemd service, and are not
b6fb8c
+activated in response to uevents.  This can be controlled with the
b6fb8c
+lvm.conf setting event_activation.
b6fb8c
+.P
b6fb8c
+Event based autoactivation is driven by udev, udev rules, and systemd.
b6fb8c
+When a device is attached to a machine, a uevent is generated by the
b6fb8c
+kernel to notify userspace of the new device.  systemd-udev runs udev
b6fb8c
+rules to process the new device.  Udev rules use blkid to identify the
b6fb8c
+device as an LVM PV and then execute the lvm-specific udev rule for the
b6fb8c
+device, which triggers autoactivation.
b6fb8c
+.P
b6fb8c
+There are two variations of event based autoactivation that may be used a
b6fb8c
+system, depending on the LVM udev rule that is installed (found in
b6fb8c
+/lib/udev/rules.d/.)  The following summarizes the steps in each rule
b6fb8c
+which lead to autoactivation:
b6fb8c
+.P
b6fb8c
+.B 69-dm-lvm-metad.rules
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+device /dev/name with major:minor X:Y is attached to the machine
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+systemd/udev runs blkid to identify /dev/name as an LVM PV
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+udev rule 69-dm-lvm-metad.rules is run for /dev/name
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the lvm udev rule runs the systemd service lvm2-pvscan@X:Yservice
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the lvm2-pvscan service runs:
b6fb8c
+.br
b6fb8c
+pvscan --cache -aay --major X --minor Y
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+pvscan reads the device, records that the PV is online
b6fb8c
+(see pvs_online), and checks if the VG is complete.
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+if the VG is complete, pvscan creates the vgs_online temp file,
b6fb8c
+and activates the VG.
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the activation command output can be seen from
b6fb8c
+systemctl status lvm2-pvscan*
b6fb8c
+.P
b6fb8c
+.B 69-dm-lvm.rules
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+device /dev/name with major:minor X:Y is attached to the machine
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+systemd/udev runs blkid to identify /dev/name as an LVM PV
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+udev rule 69-dm-lvm.rules is run for /dev/name
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the lvm udev rule runs:
b6fb8c
+.br
b6fb8c
+pvscan --cache --listvg --checkcomplete --vgonline
b6fb8c
+.br
b6fb8c
+--autoactivation event --udevoutput --journal=output /dev/name
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+pvscan reads the device, records that the PV is online
b6fb8c
+(see pvs_online), and checks if the VG is complete.
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+if the VG is complete, pvscan creates the vgs_online temp file,
b6fb8c
+and prints the name of the VG for the udev rule to import:
b6fb8c
+LVM_VG_NAME_COMPLETE='vgname'
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+if the lvm udev rule sees LVM_VG_NAME_COMPLETE from pvscan,
b6fb8c
+it activates the VG using a transient systemd service named
b6fb8c
+lvm-activate-<vgname>.
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the lvm-activate-<vgname> service runs
b6fb8c
+.br
b6fb8c
+vgchange -aay --autoactivation event <vgname>
b6fb8c
+.
b6fb8c
+.IP \[bu] 2
b6fb8c
+the activation command output can be seen from
b6fb8c
+systemctl status lvm-activate-<vgname>
b6fb8c
+.P
b6fb8c
+.
b6fb8c
+.SS pvscan options
b6fb8c
+.P
b6fb8c
+.B --cache
b6fb8c
+.br
b6fb8c
+Read the <device> arg (and only that device), and record that
b6fb8c
+the PV is online by creating the /run/lvm/pvs_online/<pvid>
b6fb8c
+file containing the name of the VG and the device for the PV.
b6fb8c
+.P
b6fb8c
+.B -aay
b6fb8c
+.br
b6fb8c
+Activate the VG from the pvscan command
b6fb8c
+(includes implicit --checkcomplete and --vgonline.)
b6fb8c
+.P
b6fb8c
+.B --checkcomplete
b6fb8c
+.br
b6fb8c
+Check if the VG is complete, i.e. all PVs are present on
b6fb8c
+the system, by checking /run/lvm/pvs_online/<pvid> files.
b6fb8c
+.P
b6fb8c
+.B --vgonline
b6fb8c
+.br
b6fb8c
+Create /run/lvm/vgs_online/<vgname> if the VG is complete
b6fb8c
+(used to ensure only one command performs activation.)
b6fb8c
+.P
b6fb8c
+.B --autoactivation event
b6fb8c
+.br
b6fb8c
+Inform the command it is used for event based autoactivation.
b6fb8c
+.P
b6fb8c
+.B --listvg
b6fb8c
+.br
b6fb8c
+Print the name of the VG using the device.
b6fb8c
+.P
b6fb8c
+.B --udevoutput
b6fb8c
+.br
b6fb8c
+Only print output that can be imported to the udev rule,
b6fb8c
+using the udev environment key format, i.e. NAME='value'.
b6fb8c
+.P
b6fb8c
+.B --journal=output
b6fb8c
+.br
b6fb8c
+Send standard command output to the journal (when stdout
b6fb8c
+is reserved for udev output.)
b6fb8c
+.P
b6fb8c
+.SS Temp files
b6fb8c
+.P
b6fb8c
+Autoactivation commands use a number of temp files in /run/lvm (with the
b6fb8c
+expectation that /run is cleared between boots.)
b6fb8c
+.P
b6fb8c
+.B pvs_online
b6fb8c
+.br
b6fb8c
+pvscan --cache creates a file here for each PV that is attached.  The file
b6fb8c
+is named with the PVID and contains the VG name and device information.
b6fb8c
+The existence of the file is used to determine when all PVs for a given VG
b6fb8c
+are present.  The device information in these files is also used to
b6fb8c
+optimize locating devices for a VG when the VG is activated.
b6fb8c
+.P
b6fb8c
+.B pvs_lookup
b6fb8c
+.br
b6fb8c
+pvscan --cache creates a file here named for a VG (if one doesn't already
b6fb8c
+exist.)  The file contains a list of PVIDs in the VG.  This is needed when
b6fb8c
+a PV is processed which has no VG metadata, in which case the list of
b6fb8c
+PVIDs from the lookup file is used to check if the VG is complete.
b6fb8c
+.P
b6fb8c
+.B vgs_online
b6fb8c
+.br
b6fb8c
+The first activation command (pvscan or vgchange) to create a file here,
b6fb8c
+named for the VG, will activate the VG.  This resolves a race when
b6fb8c
+concurrent commands attempt to activate a VG at once.
b6fb8c
+.
b6fb8c
+.SH EXAMPLES
b6fb8c
+.P
b6fb8c
+VG "vg" contains two PVs:
b6fb8c
+.nf
b6fb8c
+$ pvs -o name,vgname,uuid /dev/sdb /dev/sdc
b6fb8c
+  PV         VG PV UUID                               
b6fb8c
+  /dev/sdb   vg 1uKpaT-lFOZ-NLHX-j4jI-OBi1-QpdE-HZ5hZY
b6fb8c
+  /dev/sdc   vg 5J3tM8-aIPe-2vbd-DBe7-bvRq-TGj0-DaKV2G
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of --cache:
b6fb8c
+.nf
b6fb8c
+$ pvscan --cache /dev/sdb
b6fb8c
+  pvscan[12922] PV /dev/sdb online.
b6fb8c
+$ pvscan --cache /dev/sdc
b6fb8c
+  pvscan[12923] PV /dev/sdc online.
b6fb8c
+
b6fb8c
+$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY 
b6fb8c
+8:16
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdb
b6fb8c
+$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G 
b6fb8c
+8:32
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdc
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of -aay:
b6fb8c
+.nf
b6fb8c
+$ pvscan --cache -aay /dev/sdb
b6fb8c
+  pvscan[12935] PV /dev/sdb online, VG vg incomplete (need 1).
b6fb8c
+$ pvscan --cache -aay /dev/sdc
b6fb8c
+  pvscan[12936] PV /dev/sdc online, VG vg is complete.
b6fb8c
+  pvscan[12936] VG vg run autoactivation.
b6fb8c
+  1 logical volume(s) in volume group "vg" now active
b6fb8c
+
b6fb8c
+$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY 
b6fb8c
+8:16
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdb
b6fb8c
+$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G 
b6fb8c
+8:32
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdc
b6fb8c
+$ ls /run/lvm/vgs_online/vg 
b6fb8c
+/run/lvm/vgs_online/vg
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of --listvg:
b6fb8c
+.nf
b6fb8c
+$ pvscan --cache --listvg /dev/sdb
b6fb8c
+  VG vg
b6fb8c
+$ pvscan --cache --listvg /dev/sdc
b6fb8c
+  VG vg
b6fb8c
+
b6fb8c
+$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY 
b6fb8c
+8:16
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdb
b6fb8c
+$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G 
b6fb8c
+8:32
b6fb8c
+vg:vg
b6fb8c
+dev:/dev/sdc
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of --checkcomplete:
b6fb8c
+.nf
b6fb8c
+$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdb
b6fb8c
+  pvscan[12996] PV /dev/sdb online, VG vg incomplete (need 1).
b6fb8c
+  VG vg incomplete
b6fb8c
+$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdc
b6fb8c
+  pvscan[12997] PV /dev/sdc online, VG vg is complete.
b6fb8c
+  VG vg complete
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of --udevoutput:
b6fb8c
+.nf
b6fb8c
+$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdb
b6fb8c
+LVM_VG_NAME_INCOMPLETE='vg'
b6fb8c
+$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdc
b6fb8c
+LVM_VG_NAME_COMPLETE='vg'
b6fb8c
+.fi
b6fb8c
+.P
b6fb8c
+use of --listlvs:
b6fb8c
+.nf
b6fb8c
+$ lvs -o name,devices vg
b6fb8c
+  LV    Devices                
b6fb8c
+  lvol0 /dev/sdb(0)            
b6fb8c
+  lvol1 /dev/sdc(0)            
b6fb8c
+  lvol2 /dev/sdb(1),/dev/sdc(1)
b6fb8c
+
b6fb8c
+$ pvscan --cache --listlvs --checkcomplete /dev/sdb
b6fb8c
+  pvscan[13288] PV /dev/sdb online, VG vg incomplete (need 1).
b6fb8c
+  VG vg incomplete
b6fb8c
+  LV vg/lvol0 complete
b6fb8c
+  LV vg/lvol2 incomplete
b6fb8c
+$ pvscan --cache --listlvs --checkcomplete /dev/sdc
b6fb8c
+  pvscan[13289] PV /dev/sdc online, VG vg is complete.
b6fb8c
+  VG vg complete
b6fb8c
+  LV vg/lvol1 complete
b6fb8c
+  LV vg/lvol2 complete
b6fb8c
+.fi
b6fb8c
+
b6fb8c
diff --git a/man/pvscan.8_des b/man/pvscan.8_des
b6fb8c
index b20b987da..4c5929955 100644
b6fb8c
--- a/man/pvscan.8_des
b6fb8c
+++ b/man/pvscan.8_des
b6fb8c
@@ -4,56 +4,47 @@ like
b6fb8c
 or
b6fb8c
 .BR pvdisplay (8).
b6fb8c
 .P
b6fb8c
-When the --cache and -aay options are used, pvscan records which PVs are
b6fb8c
-available on the system, and activates LVs in completed VGs.  A VG is
b6fb8c
-complete when pvscan sees that the final PV in the VG has appeared.  This
b6fb8c
-is used by event-based system startup (systemd, udev) to activate LVs.
b6fb8c
-.P
b6fb8c
-The four main variations of this are:
b6fb8c
+When --cache is used, pvscan updates runtime lvm state on the system, or
b6fb8c
+with -aay performs autoactivation.
b6fb8c
 .P
b6fb8c
 .B pvscan --cache
b6fb8c
 .I device
b6fb8c
 .P
b6fb8c
-If device is present, lvm adds a record that the PV on device is online.
b6fb8c
+If device is present, lvm records that the PV on device is online.
b6fb8c
 If device is not present, lvm removes the online record for the PV.
b6fb8c
-In most cases, the pvscan will only read the named devices.
b6fb8c
+pvscan only reads the named device.
b6fb8c
 .P
b6fb8c
-.B pvscan --cache -aay
b6fb8c
-.IR device ...
b6fb8c
+.B pvscan --cache
b6fb8c
 .P
b6fb8c
-This begins by performing the same steps as above.  Afterward, if the VG
b6fb8c
-for the specified PV is complete, then pvscan will activate LVs in the VG
b6fb8c
-(the same as vgchange -aay vgname would do.)
b6fb8c
+Updates the runtime state for all lvm devices.
b6fb8c
 .P
b6fb8c
-.B pvscan --cache
b6fb8c
+.B pvscan --cache -aay
b6fb8c
+.I device
b6fb8c
 .P
b6fb8c
-This first clears all existing PV online records, then scans all devices
b6fb8c
-on the system, adding PV online records for any PVs that are found.
b6fb8c
+Performs the --cache steps for the device, then checks if the VG using the
b6fb8c
+device is complete.  If so, LVs in the VG are autoactivated, the same as
b6fb8c
+vgchange -aay vgname would do.  (A device name may be replaced with major
b6fb8c
+and minor numbers.)
b6fb8c
 .P
b6fb8c
 .B pvscan --cache -aay
b6fb8c
 .P
b6fb8c
-This begins by performing the same steps as pvscan --cache.  Afterward, it
b6fb8c
-activates LVs in any complete VGs.
b6fb8c
+Performs the --cache steps for all devices, then autoactivates any complete VGs.
b6fb8c
 .P
b6fb8c
-To prevent devices from being scanned by pvscan --cache, add them
b6fb8c
-to
b6fb8c
-.BR lvm.conf (5)
b6fb8c
-.B devices/global_filter.
b6fb8c
-For more information, see:
b6fb8c
-.br
b6fb8c
-.B lvmconfig --withcomments devices/global_filter
b6fb8c
+.B pvscan --cache --listvg|--listlvs
b6fb8c
+.I device
b6fb8c
+.P
b6fb8c
+Performs the --cache steps for the device, then prints the name of the VG
b6fb8c
+using the device, or the names of LVs using the device.  --checkcomplete
b6fb8c
+is usually included to check if all PVs for the VG or LVs are online.
b6fb8c
+When this command is called by a udev rule, the output must conform to
b6fb8c
+udev rule specifications (see --udevoutput.)  The udev rule will use the
b6fb8c
+results to perform autoactivation.
b6fb8c
 .P
b6fb8c
-Auto-activation of VGs or LVs can be enabled/disabled using:
b6fb8c
-.br
b6fb8c
+Autoactivation of VGs or LVs can be enabled/disabled using vgchange or
b6fb8c
+lvchange with --setautoactivation y|n, or by adding names to
b6fb8c
 .BR lvm.conf (5)
b6fb8c
 .B activation/auto_activation_volume_list
b6fb8c
 .P
b6fb8c
-For more information, see:
b6fb8c
-.br
b6fb8c
-.B lvmconfig --withcomments activation/auto_activation_volume_list
b6fb8c
-.P
b6fb8c
-To disable auto-activation, explicitly set this list to an empty list,
b6fb8c
-i.e. auto_activation_volume_list = [ ].
b6fb8c
-.P
b6fb8c
-When this setting is undefined (e.g. commented), then all LVs are
b6fb8c
-auto-activated.
b6fb8c
+See
b6fb8c
+.BR lvmautoactivation (7)
b6fb8c
+for more information about how pvscan is used for autoactivation.
b6fb8c
-- 
38b7b2
2.34.3
b6fb8c