From 7631c5b826b5a3eddfcd22db9b80574b249794c1 Mon Sep 17 00:00:00 2001
From: David Teigland <teigland@redhat.com>
Date: Mon, 6 Dec 2021 13:20:32 -0600
Subject: [PATCH 21/54] man: add section about static autoactivation

---
 man/lvmautoactivation.7_main | 48 ++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/man/lvmautoactivation.7_main b/man/lvmautoactivation.7_main
index 87c15a3d1..bf885991d 100644
--- a/man/lvmautoactivation.7_main
+++ b/man/lvmautoactivation.7_main
@@ -14,14 +14,16 @@ activated.
 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
 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.
+autoactivation is "static" in which complete VGs are activated at a fixed
+point during system startup by a systemd service, and not in response to
+events.  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
@@ -30,8 +32,8 @@ 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
+There are two variations of event baed 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
@@ -149,7 +151,7 @@ using the udev environment key format, i.e. NAME='value'.
 Send standard command output to the journal (when stdout
 is reserved for udev output.)
 .P
-.SS Temp files
+.SS run files
 .P
 Autoactivation commands use a number of temp files in /run/lvm (with the
 expectation that /run is cleared between boots.)
@@ -175,6 +177,38 @@ 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
+When event autoactivation is disabled by setting lvm.conf
+event_activation=0, autoactivation is performed at one or more static
+points during system startup. At these points, a vgchange -aay command is
+run to activate complete VGs from devices that are present on the system
+at that time. pvscan commands (and lvm2-pvscan services) do not perform
+autoactivation in this mode.  pvscan commands may still be run from
+uevents but will do nothing when they read the event_activation=0 setting.
+.P
+The static vgchange -aay commands are run by three systemd services at
+three points during startup: lvm2-activation-early, lvm2-activation, and
+lvm2-activation-net. These static activation services are "generated
+services", so the service files are created at run time by the
+lvm2-activation-generator command (run by systemd).
+lvm2-activation-generator creates the services if lvm.conf
+event_activation=0.
+.P
+The limitation of this method is that devices may not be attached to the
+system (or set up) at a reliable point in time during startup, and they
+may not be present when the services run vgchange.  In this case, the VGs
+will not be autoactivated.  So, the timing of device attachment/setup
+determines whether static autoactivation will produce the same results as
+event autoactivation.  For this reason, static autoactivation is not
+recommended.
+.P
+Sometimes, static autoactivation is mistakenly expected to disable all
+autoactivation of particular VGs. This may appear to be effective if those
+VGs are slow to be attached or set up. But, the only correct and reliable
+way to disable autoactivation is using vgchange/lvchange
+--setautoactivation n, or lvm.conf auto_activation_volume_list.
+.
 .SH EXAMPLES
 .P
 VG "vg" contains two PVs:
-- 
2.34.3