Adding upstream version 102.upstream/102

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 148 insertions, 82 deletions

diff --git a/man/dracut.cmdline.7.asc b/man/dracut.cmdline.7.asc
index fefa209..7c0051e 100644
--- a/man/dracut.cmdline.7.asc
+++ b/man/dracut.cmdline.7.asc
@@ -221,13 +221,11 @@ It should be attached to any report about dracut problems.
     drop to a shell at the end
 
 **rd.break=**__{cmdline|pre-udev|pre-trigger|initqueue|pre-mount|mount|pre-pivot|cleanup}__::
-    drop to a shell before the defined breakpoint starts
-
-**rd.udev.info**::
-    set udev to loglevel info
+    drop to a shell before the defined breakpoint starts.
+    This parameter can be specified multiple times.
 
-**rd.udev.debug**::
-    set udev to loglevel debug
+**rd.udev.log_level=**__{err|info|debug}__::
+    set udev log level. The default is 'err'.
 
 I18N
 ~~~~
@@ -972,19 +970,38 @@ root=virtiofs:host rw
 DASD
 ~~~~
 **rd.dasd=**....::
-    same syntax as the kernel module parameter (s390 only)
+    same syntax as the kernel module parameter (s390 only).
+    For more details on the syntax see the IBM book
+    "Linux on IBM Z and IBM LinuxONE - Device Drivers, Features, and Commands"
+    https://www.ibm.com/docs/en/linux-on-systems?topic=overview-device-drivers-features-commands.
+    This parameter can be specified multiple times.
++
+NOTE:
+    This parameter is no longer handled by dracut itself but with the exact
+    same syntax by
+    https://github.com/ibm-s390-linux/s390-tools/tree/master/zdev/dracut/95zdev.
 
 ZFCP
 ~~~~
 **rd.zfcp=**__<zfcp adaptor device bus ID>__,__<WWPN>__,__<FCPLUN>__::
     rd.zfcp can be specified multiple times on the kernel command
     line.
++
+NOTE:
+    This parameter is no longer handled by dracut itself but with the exact
+    same syntax by
+    https://github.com/ibm-s390-linux/s390-tools/tree/master/zdev/dracut/95zdev.
 
 **rd.zfcp=**__<zfcp adaptor device bus ID>__::
     If NPIV is enabled and the 'allow_lun_scan' parameter to the zfcp
-    module is set to 'Y' then the zfcp adaptor will be initiating a
+    module is set to 'Y' then the zfcp driver will be initiating a
     scan internally and the <WWPN> and <FCPLUN> parameters can be omitted.
 +
+NOTE:
+    This parameter is no longer handled by dracut itself but with the exact
+    same syntax by
+    https://github.com/ibm-s390-linux/s390-tools/tree/master/zdev/dracut/95zdev.
++
 [listing]
 .Example
 --
@@ -998,9 +1015,12 @@ rd.zfcp=0.0.4000
 ZNET
 ~~~~
 **rd.znet=**__<nettype>__,__<subchannels>__,__<options>__::
-    The whole parameter is appended to /etc/ccw.conf, which is used on
-    RHEL/Fedora with ccw_init, which is called from udev for certain
-    devices on z-series.
+    Activates a channel-attached network interface on s390 architecture.
+    <nettype> is one of: qeth, lcs, ctc.
+    <subchannels> is a comma-separated list of ccw device bus-IDs.
+    The list consists of 3 entries with nettype qeth, and 2 for other nettype.
+    <options> is a comma-separated list of <name>=<value> pairs,
+    where <name> refers to a device sysfs attribute to which <value> gets written.
     rd.znet can be specified multiple times on the kernel command line.
 
 **rd.znet_ifname=**__<ifname>__:__<subchannels>__::
@@ -1020,51 +1040,88 @@ Booting live images
 Dracut offers multiple options for live booted images:
 
 =====================
-SquashFS with read-only filesystem image::: The system will boot with a
-read-only filesystem from the SquashFS and apply a writable Device-mapper
-snapshot or an OverlayFS overlay mount for the read-only base filesystem.  This
-method ensures a relatively fast boot and lower RAM usage. Users **must be
-careful** to avoid writing too many blocks to a snapshot volume.  Once the
-blocks of the snapshot overlay are exhausted, the root filesystem becomes
-read-only and may cause application failures.  The snapshot overlay file is
-marked 'Overflow', and a difficult recovery is required to repair and enlarge
-the overlay offline.  Non-persistent overlays are sparse files in RAM that only
-consume content space as required blocks are allocated.  They default to an
-apparent size of 32 GiB in RAM.  The size can be adjusted with the
-**rd.live.overlay.size=** kernel command line option.
-+
-The filesystem structure is traditionally expected to be:
-+
+SquashFS (read-only) base filesystem image:::
+Note -- There are 3 separate overlay types available:
+- Device-mapper snapshots (the original offering),
+- Device-mapper thin provisioning snapshots (see *_rd.live.overlay.thin_*,
+a later offering), and
+- OverlayFS based overlay mounts (a more recent offering).
+
++
+--
+Using one of these technologies, the system will provide a writable overlay for
+the base, read-only SquashFS root filesystem. These methods enable a relatively
+fast boot and lower RAM usage.
+
+With the original Device-mapper snapshot overlay, users **must be careful** to
+avoid writing too many blocks to the snapshot device.  Once the blocks of the
+snapshot overlay are exhausted, the whole root filesystem becomes read-only
+leading to application failures.  The snapshot overlay device is marked
+'Overflow', and a difficult recovery is required to repair and enlarge the
+overlay offline.
+
+When *_rd.live.overlay=_* is not specified for persistent overlay storage, or
+the specified file is not found or writable, a Device-mapper snapshot based
+non-persistent or temporary overlay is automatically created as a sparse file
+in RAM of the initramfs.  This file will only consume content space as required
+blocks are allocated. This snapshot based overlay defaults to an apparent size
+of 32 GiB in RAM, and can be adjusted with the *_rd.live.overlay.size=_* kernel
+command line option.  This file is hidden (and appears deleted) when the boot
+process switches out of the initramfs to the main root filesystem but its loop
+device remains connected to the Device-mapper snapshot.
+
+Even with large Device-mapper overlay files for write space, the available root
+filesystem capacity is limited by the total allocated size of the base root
+filesystem, which often provide only a small number of gigabytes of free space.
+
+This shortage could be remedied by building the root filesystem with more
+allocated free space, or the OverlayFS based overlay mount method can be used.
+
+When the *_rd.live.overlay.overlayfs_* option is specified or when
+*_rd.live.overlay=_* points to an appropriate directory with a sister at
+`/../ovlwork`, then an OverlayFS based overlay mount is employed.  Such a
+persistent OverlayFS overlay can extend the available root filesystem storage
+up to the capacity of the LiveOS disk device.
+
+For non-persistent OverlayFS overlays, the `/run/overlayfs` directory in the
+`/run` tmpfs is used for temporary storage.  This filesystem is typically sized
+to one half of the RAM total in the system. +
+The command: `mount -o remount,size=<nbytes> /run` will resize this virtual
+filesystem after booting.
+
+The internal SquashFS structure is traditionally expected to be:
+
 [listing]
---
+----
 squashfs.img          |  SquashFS from LiveCD .iso
    !(mount)
    /LiveOS
-       |- rootfs.img  |  Filesystem image to mount read-only
+       |- rootfs.img  |  Usually a ext4 filesystem image to mount read-only
             !(mount)
-            /bin      |  Live filesystem
+            /bin      |  Base Live root filesystem
             /boot     |
             /dev      |
             ...       |
---
-+
-For OverlayFS mount overlays, the filesystem structure may also be a direct
+----
+
+For OverlayFS mount overlays, the internal SquashFS structure may be a direct
 compression of the root filesystem:
-+
+
 [listing]
---
+----
 squashfs.img          |  SquashFS from LiveCD .iso
    !(mount)
-   /bin               |  Live filesystem
+   /bin               |  Base Live root filesystem
    /boot              |
    /dev               |
    ...                |
---
-+
+----
+
 Dracut uses one of the overlay methods of live booting by default.  No
-additional command line options are required other than **root=live:<URL>** to
-specify the location of your squashed filesystem.
-+
+additional command line options are required other than
+**root=**live:__<path to blockdevice>__ or **root=**live:__<URL>__ to specify
+the location of your squashed root filesystem.
+
 - The compressed SquashFS image can be copied during boot to RAM at
 `/run/initramfs/squashed.img` by using the **rd.live.ram=1** option.
 - A device with a persistent overlay can be booted read-only by using the
@@ -1072,7 +1129,8 @@ specify the location of your squashed filesystem.
 either cause a temporary, writable overlay to be stacked over a read-only
 snapshot of the root filesystem or the OverlayFS mount will use an additional
 lower layer with the root filesystem.
-+
+--
+
 Uncompressed live filesystem image:::
 When the live system was installed with the '--skipcompress' option of the
 __livecd-iso-to-disk__ installation script for Live USB devices, the root
@@ -1161,29 +1219,36 @@ Copy the complete image to RAM and use this for booting. This is useful
 when the image resides on, e.g., a DVD which needs to be ejected later on.
 
 **rd.live.overlay={**__<devspec>__[:__{<pathspec>|auto}__]|__none__}::
-Manage the usage of a permanent overlay.
+Manage the usage of a persistent overlay.
 +
 --
-* _<devspec>_ specifies the path to a device with a mountable filesystem.
-* _<pathspec>_ is the path to a file within that filesystem, which shall be
-used to persist the changes made to the device specified by the
-**root=live:__<url>__** option.
-+
-The default _pathspec_, when _auto_ or no _:<pathspec>_ is given, is
-`/<rd.live.dir>/overlay-<label>-<uuid>`, where _<label>_ is the
-device LABEL, and _<uuid>_ is the device UUID.
-* _none_ (the word itself) specifies that no overlay will be used, such as when
-an uncompressed, writable live root filesystem is available.
-+
-If a persistent overlay __is detected__ at the standard LiveOS path, the
-overlay & overlay type detected, whether Device-mapper or OverlayFS, will be
-used.
+* *_<devspec>_* specifies the path to a device with a mountable filesystem.
+* *_<pathspec>_* is a path within the *_<devspec>_* filesystem to either
+** a file (that is loop mounted for a Device-mapper overlay) or
+** a directory (that is symbolically linked to `/run/overlayfs` for a OverlayFS
+mount overlay). (A required sister directory `/<pathspec>/../ovlwork` is
+automatically made.)
+* *_none_* (the word itself) specifies that no overlay will be used, such as
+when an uncompressed, writable live root filesystem is available.
+
+The above method shall be used to persist the changes made to the root
+filesystem specified within the +
+**root=**live:__<path to blockdevice>__ or **root=**live:__<url>__ device.
+
+The default *_pathspec_*, when *:auto* or
+no **:__<pathspec>__** is given, is `/<rd.live.dir>/overlay-<label>-<uuid>`,
+where _<label>_ and _<uuid>_ are the LABEL and UUID of the filesystem specified
+by the **root=**live:__<path|url>__ device.
+
+If a persistent overlay __is detected__ at the standard LiveOS path,
+and *_rd.live.overlay.overlayfs_* is not set to 1, the overlay type (either
+Device-mapper or OverlayFS) will be detected and it will be used.
 --
 +
 [listing]
 .Examples
 --
-rd.live.overlay=/dev/sdb1:persistent-overlay.img
+rd.live.overlay=/dev/sdb1:/persistent-overlay.img
 rd.live.overlay=UUID=99440c1f-8daa-41bf-b965-b7240a8996f4
 --
 
@@ -1196,15 +1261,16 @@ Specifies a non-persistent Device-mapper overlay size in MiB.  The default is
 _32768_.
 
 **rd.live.overlay.readonly=**1::
-This is used to boot with a normally read-write persistent overlay in a
-read-only mode.  With this option, either an additional, non-persistent,
-writable snapshot overlay will be stacked over a read-only snapshot,
-`/dev/mapper/live‑ro`, of the base filesystem with the persistent overlay, or a
-read-only loop device, in the case of a writable __rootfs.img__, or an OverlayFS
-mount will use the persistent overlay directory linked at `/run/overlayfs‑r` as
-an additional lower layer along with the base root filesystem and apply a
-transient, writable upper directory overlay, in order to complete the booted
-root filesystem.
+This is used to boot in a read-only mode with a normally read-write persistent
+overlay.  With this option,
+* Device-mapper overlays will have an additional, non-persistent, writable
+snapshot overlay stacked over a read-only snapshot (`/dev/mapper/live‑ro`)
+of the base root filesystem and the persistent overlay, or
+* for writable `rootfs.img` images, the above over a read-only loop device, or
+* an OverlayFS mount will link the persistent overlay directory at
+`/run/overlayfs‑r` as an additional read-only lower layer stacked over the base
+root filesystem, and `/run/overlayfs` becomes the temporary, writable, upper
+directory overlay, to complete the bootable root filesystem.
 
 **rd.live.overlay.reset=**1::
 Specifies that a persistent overlay should be reset on boot.  All previous root
@@ -1222,18 +1288,15 @@ Enables the use of the *OverlayFS* kernel module, if available, to provide a
 copy-on-write union directory for the root filesystem.  OverlayFS overlays are
 directories of the files that have changed on the read-only base (lower)
 filesystem.  The root filesystem is provided through a special overlay type
-mount that merges the lower and upper directories.  If an OverlayFS upper
-directory is not present on the boot device, a tmpfs directory will be created
-at `/run/overlayfs` to provide temporary storage.  Persistent storage can be
-provided on vfat or msdos formatted devices by supplying the OverlayFS upper
-directory within an embedded filesystem that supports the creation of trusted.*
-extended attributes and provides a valid d_type in readdir responses, such as
-with ext4 and xfs.  On non-vfat-formatted devices, a persistent OverlayFS
-overlay can extend the available root filesystem storage up to the capacity of
-the LiveOS disk device.
-+
-If a persistent overlay is detected at the standard LiveOS path, the overlay &
-overlay type detected, whether OverlayFS or Device-mapper, will be used.
+mount that merges at least two directories, designated the lower and the upper.
+If an OverlayFS upper directory is not present on the boot device, a tmpfs
+directory will be created at `/run/overlayfs` to provide temporary storage.
+Persistent storage can be provided on vfat or msdos formatted devices by
+supplying the OverlayFS upper directory within an embedded filesystem that
+supports the creation of trusted.* extended attributes and provides a valid
+d_type in readdir responses, such as with btrfs, ext4, f2fs, & xfs.  On
+non-vfat-formatted devices, a persistent OverlayFS overlay can extend the
+available root filesystem storage up to the capacity of the LiveOS disk device.
 +
 The **rd.live.overlay.readonly** option, which allows a persistent overlayfs to
 be mounted read-only through a higher level transient overlay directory, has
@@ -1326,8 +1389,7 @@ ecryptfskey=/etc/keys/ecryptfs-trusted.blob
 
 Deprecated, renamed Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Here is a list of options, which were used in dracut prior to version 008, and
-their new replacement.
+Here is a list of options and their new replacement.
 
 rdbreak:: rd.break
 
@@ -1428,9 +1490,13 @@ rdshell:: rd.shell
 
 rd_NO_SPLASH:: rd.splash
 
-rdudevdebug:: rd.udev.debug
+rdudevdebug:: rd.udev.udev_log=debug
+
+rdudevinfo:: rd.udev.udev_log=info
+
+rd.udev.debug:: rd.udev.udev_log=debug
 
-rdudevinfo:: rd.udev.info
+rd.udev.info:: rd.udev.udev_log=info
 
 rd_NO_ZFCPCONF:: rd.zfcp.conf=0