417 lines
13 KiB
Diff
417 lines
13 KiB
Diff
From 25dbe3dd825a629ff7f67cb43342cc345071d3f7 Mon Sep 17 00:00:00 2001
|
|
From: David Teigland <teigland@redhat.com>
|
|
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-<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
|
|
+systemctl status 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 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
|
|
|