man: refine lvm.conf and man page documentation for autoactivation feature

WHATS_NEW

@@ -1,5 +1,6 @@
 Version 2.02.99 - 
 ===================================
+  Refine lvm.conf and man page documentation for autoactivation feature.
   Add support for thin volumes in vgsplit.
   Also filter partitions on mpath components if multipath_component_detection=1.
   Add lvresize support for online thin pool metadata volume resize.

doc/example.conf.in

@@ -646,9 +646,29 @@ activation {
     # volume_list = [ "vg1", "vg2/lvol1", "@tag1", "@*" ]
 
     # If auto_activation_volume_list is defined, each LV that is to be
-    # activated with the autoactivation option (--activate ay/-a ay)
-    # is first checked against the list.  If it does not match, the LV
-    # is not activated.  This list is checked as well as volume_list.
+    # activated with the autoactivation option (--activate ay/-a ay) is
+    # first checked against the list. There are two scenarios in which
+    # the autoactivation option is used:
+    #
+    #   - automatic activation of volumes based on incoming PVs. If all the
+    #     PVs making up a VG are present in the system, the autoactivation
+    #     is triggered. This requires lvmetad (global/use_lvmetad=1) and udev
+    #     to be running. In this case, "pvscan --cache -aay" is called
+    #     automatically without any user intervention while processing
+    #     udev events. Please, make sure you define auto_activation_list
+    #     properly so only the volumes you want and expect are autoactivated.
+    #
+    #   - direct activation on command line with the autoactivation option.
+    #     In this case, the user calls "vgchange --activate ay/-a ay" or
+    #     "lvchange --activate ay/-a ay" directly.
+    #
+    # If the VG/LV being processed does not match the list, the VG/LV is not
+    # activated. If auto_activation_volume_list is not set, then all volumes
+    # are activated by default.
+    #
+    # N.B. The "activation/volume_list" is still honoured in all cases so even
+    # if the VG/LV passes the auto_activation_volume_list, it still needs to
+    # pass the volume_list for it to be activated in the end.
     #
     #   "vgname" and "vgname/lvname" are matched exactly.
     #   "@tag" matches any tag set in the LV or VG.

man/lvchange.8.in

@@ -65,8 +65,9 @@ libdevmapper to activate (\-ay) or deactivate (\-an) the
 logical volumes. If autoactivation option is used (\-aay),
 the logical volume is activated only if it matches an item in
 the activation/auto_activation_volume_list set in lvm.conf.
-Autoactivation is not yet supported for logical volumes that
-are part of partial or clustered volume groups.
+If this list is not set, then all volumes are considered for
+autoactivation. The autoactivation is not yet supported for
+logical volumes that are part of partial or clustered volume groups.
 .IP
 If clustered locking is enabled, -aey will activate exclusively
 on one node and -aly will activate only on the local node.

man/pvscan.8.in

@@ -47,8 +47,9 @@ Show UUIDs (Uniform Unique Identifiers) in addition to device special names.
 Together with the information already cached in lvmetad, automatically activate
 any logical volumes that become activatable after the scan done on one or more devices.
 The logical volume to autoactivate is matched against the
-activation/auto_activation_volume_list set in lvm.conf. Autoactivation is not yet
-supported on logical volumes that are part of partial or clustered volume groups.
+activation/auto_activation_volume_list set in lvm.conf. If this list is not set, then
+all volumes are considered for autoactivation. The autoactivation is not yet
+supported for logical volumes that are part of partial or clustered volume groups.
 .TP
 .BR \-\-cache " [" \-\-major " " \fImajor " " \-\-minor " " \fIminor " | " \fIDevicePath " ]..."
 Scan one or more devices and instruct the lvmetad daemon to update its cached

man/vgchange.8.in

@@ -70,8 +70,9 @@ group for input/output.
 In other words, makes the logical volumes known/unknown to the kernel.
 If autoactivation option is used (\-aay), each logical volume in
 the volume group is activated only if it matches an item in the
-activation/auto_activation_volume_list set in lvm.conf.
-Autoactivation is not yet supported for partial or clustered
+activation/auto_activation_volume_list set in lvm.conf. If this
+list is not set, then all volumes are considered for autoactivation.
+The autoactivation is not yet supported for partial or clustered
 volume groups.
 .IP
 If clustered locking is enabled, add 'e' to activate/deactivate