From: Antonio Alvarez Feijoo Date: Mon, 9 May 2022 10:41:39 +0000 (+0200) Subject: docs(dracut): format and add missing options X-Git-Tag: 057~16 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a6c497dc7a26c0585b4074b5d1e22f3dec8d32eb;p=thirdparty%2Fdracut.git docs(dracut): format and add missing options Set common format to each option, correct default compression options and add missing options: --rebuild --aggresive-strip --hostonly-mode --hostonly-nics --noimageifnotneeded --- diff --git a/man/dracut.8.asc b/man/dracut.8.asc index 59de9dd42..83b46938b 100644 --- a/man/dracut.8.asc +++ b/man/dracut.8.asc @@ -53,22 +53,28 @@ include::dracut.usage.asc[] OPTIONS ------- **--kver** __:: - set the kernel version. This enables to specify the kernel version, without + Set the kernel version. This enables to specify the kernel version, without specifying the location of the initramfs image. For example: ---- # dracut --kver 3.5.0-0.rc7.git1.2.fc18.x86_64 ---- **-f, --force**:: - overwrite existing initramfs file. + Overwrite existing initramfs file. + +__ **--rebuild**:: + Append the current arguments to those with which the input initramfs image + was built. This option helps in incrementally building the initramfs for + testing. If optional __ is not provided, the input initramfs + provided to rebuild will be used as output file. **-a, --add** __:: - add a space-separated list of dracut modules to the default set of modules. + Add a space-separated list of dracut modules to the default set of modules. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --add "module1 module2" ... @@ -76,13 +82,13 @@ example: =============================== **--force-add** __:: - force to add a space-separated list of dracut modules to the default set of + Force to add a space-separated list of dracut modules to the default set of modules, when -H is specified. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --force-add "module1 module2" ... @@ -90,12 +96,12 @@ example: =============================== **-o, --omit** __:: - omit a space-separated list of dracut modules. This parameter can be + Omit a space-separated list of dracut modules. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --omit "module1 module2" ... @@ -103,7 +109,7 @@ example: =============================== **-m, --modules** __:: - specify a space-separated list of dracut modules to call when building the + Specify a space-separated list of dracut modules to call when building the initramfs. Modules are located in _/usr/lib/dracut/modules.d_. This parameter can be specified multiple times. This option forces dracut to only include the specified dracut modules. @@ -111,7 +117,7 @@ example: + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --modules "module1 module2" ... @@ -119,13 +125,13 @@ example: =============================== **-d, --drivers** __:: - specify a space-separated list of kernel modules to exclusively include + Specify a space-separated list of kernel modules to exclusively include in the initramfs. The kernel modules have to be specified without the ".ko" suffix. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --drivers "kmodule1 kmodule2" ... @@ -133,13 +139,13 @@ example: =============================== **--add-drivers** __:: - specify a space-separated list of kernel modules to add to the initramfs. + Specify a space-separated list of kernel modules to add to the initramfs. The kernel modules have to be specified without the ".ko" suffix. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --add-drivers "kmodule1 kmodule2" ... @@ -152,7 +158,7 @@ example: + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --force-drivers "kmodule1 kmodule2" ... @@ -160,14 +166,14 @@ example: =============================== **--omit-drivers** __:: - specify a space-separated list of kernel modules not to add to the + Specify a space-separated list of kernel modules not to add to the initramfs. The kernel modules have to be specified without the ".ko" suffix. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --omit-drivers "kmodule1 kmodule2" ... @@ -175,13 +181,13 @@ example: =============================== **--filesystems** __:: - specify a space-separated list of kernel filesystem modules to exclusively + Specify a space-separated list of kernel filesystem modules to exclusively include in the generic initramfs. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --filesystems "filesystem1 filesystem2" ... @@ -189,20 +195,20 @@ example: =============================== **-k, --kmoddir** __:: - specify the directory, where to look for kernel modules + Specify the directory, where to look for kernel modules. **--fwdir** _[:...]++_:: - specify additional directories, where to look for firmwares. This parameter + Specify additional directories, where to look for firmwares. This parameter can be specified multiple times. **--libdirs** __:: - specify a space-separated list of directories to look for libraries to + Specify a space-separated list of directories to look for libraries to include in the generic initramfs. This parameter can be specified multiple times. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --libdirs "dir1 dir2" ... @@ -210,44 +216,43 @@ example: =============================== **--kernel-cmdline **:: - specify default kernel command line parameters - + Specify default kernel command line parameters. **--kernel-only**:: - only install kernel drivers and firmware files + Only install kernel drivers and firmware files. **--no-kernel**:: - do not install kernel drivers and firmware files + Do not install kernel drivers and firmware files. **--early-microcode**:: - Combine early microcode with ramdisk + Combine early microcode with ramdisk. **--no-early-microcode**:: - Do not combine early microcode with ramdisk + Do not combine early microcode with ramdisk. **--print-cmdline**:: - print the kernel command line for the current disk layout + Print the kernel command line for the current disk layout. **--mdadmconf**:: - include local _/etc/mdadm.conf_ + Include local _/etc/mdadm.conf_ file. **--nomdadmconf**:: - do not include local _/etc/mdadm.conf_ + Do not include local _/etc/mdadm.conf_ file. **--lvmconf**:: - include local _/etc/lvm/lvm.conf_ + Include local _/etc/lvm/lvm.conf_ file. **--nolvmconf**:: - do not include local _/etc/lvm/lvm.conf_ + Do not include local _/etc/lvm/lvm.conf_ file. -**--fscks** [LIST]:: - add a space-separated list of fsck tools, in addition to _dracut.conf_'s +**--fscks** __:: + Add a space-separated list of fsck tools, in addition to _dracut.conf_'s specification; the installation is opportunistic (non-existing tools are - ignored) + ignored). + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --fscks "fsck.foo barfsck" ... @@ -255,60 +260,65 @@ example: =============================== **--nofscks**:: - inhibit installation of any fsck tools + Inhibit installation of any fsck tools. **--strip**:: - strip binaries in the initramfs (default) + Strip binaries in the initramfs (default). + +**--aggresive-strip**:: + Strip more than just debug symbol and sections, for a smaller initramfs + build. The --strip option must also be specified. **--nostrip**:: - do not strip binaries in the initramfs + Do not strip binaries in the initramfs. **--hardlink**:: - hardlink files in the initramfs (default) + Hardlink files in the initramfs (default). **--nohardlink**:: - do not hardlink files in the initramfs + Do not hardlink files in the initramfs. **--prefix** __:: - prefix initramfs files with the specified directory + Prefix initramfs files with the specified directory. **--noprefix**:: - do not prefix initramfs files (default) + Do not prefix initramfs files (default). **-h, --help**:: - display help text and exit. + Display help text and exit. **--debug**:: - output debug information of the build process + Output debug information of the build process. **-v, --verbose**:: - increase verbosity level (default is info(4)) + Increase verbosity level (default is info(4)). **--version**:: - display version and exit + Display version and exit. -**-q, --quiet**:: decrease verbosity level (default is info(4)) +**-q, --quiet**:: + Decrease verbosity level (default is info(4)). **-c, --conf** __:: - specify configuration file to use. + Specify configuration file to use. + Default: _/etc/dracut.conf_ **--confdir** __:: - specify configuration directory to use. + Specify configuration directory to use. + Default: _/etc/dracut.conf.d_ **--tmpdir** __:: - specify temporary directory to use. + Specify temporary directory to use. + Default: _/var/tmp_ **-r, --sysroot** __:: - specify the sysroot directory to collect files from. + Specify the sysroot directory to collect files from. This is useful to create the initramfs image from a cross-compiled sysroot directory. For the extra helper variables, see *ENVIRONMENT* below. @@ -316,22 +326,23 @@ Default: Default: _empty_ -**--sshkey** __:: ssh key file used with ssh-client module. +**--sshkey** __:: + SSH key file used with ssh-client module. -**--logfile** __:: logfile to use; overrides any setting from - the configuration files. +**--logfile** __:: + Logfile to use; overrides any setting from the configuration files. + Default: _/var/log/dracut.log_ **-l, --local**:: - activates the local mode. dracut will use modules from the current working + Activates the local mode. dracut will use modules from the current working directory instead of the system-wide installed modules in _/usr/lib/dracut/modules.d_. This is useful when running dracut from a git checkout. **-H, --hostonly**:: - Host-Only mode: Install only what is needed for booting the local host + Host-only mode: Install only what is needed for booting the local host instead of a generic host and generate host-specific configuration. + [WARNING] @@ -341,24 +352,43 @@ provide a valid _/etc/fstab_. ==== **-N, --no-hostonly**:: - Disable Host-Only mode + Disable host-only mode. + +**--hostonly-mode __**:: + Specify the host-only mode to use. __ could be one of "sloppy" or + "strict". + In "sloppy" host-only mode, extra drivers and modules will be installed, so + minor hardware change won't make the image unbootable (e.g. changed + keyboard), and the image is still portable among similar hosts. + With "strict" mode enabled, anything not necessary for booting the local + host in its current state will not be included, and modules may do some + extra job to save more space. Minor change of hardware or environment could + make the image unbootable. ++ +Default: + _sloppy_ -**--hostonly-cmdline**: - Store kernel command line arguments needed in the initramfs +**--hostonly-cmdline**:: + Store kernel command line arguments needed in the initramfs. -**--no-hostonly-cmdline**: - Do not store kernel command line arguments needed in the initramfs +**--no-hostonly-cmdline**:: + Do not store kernel command line arguments needed in the initramfs. -**--no-hostonly-default-device**: +**--no-hostonly-default-device**:: Do not generate implicit host devices like root, swap, fstab, etc. Use "--mount" or "--add-device" to explicitly add devices as needed. -**--hostonly-i18n**: - Install only needed keyboard and font files according to the host configuration (default). +**--hostonly-i18n**:: + Install only needed keyboard and font files according to the host + configuration (default). -**--no-hostonly-i18n**: +**--no-hostonly-i18n**:: Install all keyboard and font files available. +**--hostonly-nics** __:: + Only enable listed NICs in the initramfs. The list can be empty, so other + modules can install only the necessary network drivers. + **--persistent-policy** __:: Use __ to address disks and partitions. __ can be any directory name found in /dev/disk. @@ -376,7 +406,7 @@ provide a valid _/etc/fstab_. be specified, see fstab manpage for the details. The default __ is "defaults". The default __ is "0". - the default __ is "2". + The default __ is "2". **--mount** "__":: Like above, but __, __ and __ @@ -384,22 +414,22 @@ provide a valid _/etc/fstab_. **--add-device** __ :: Bring up __ in initramfs, __ should be the device name. - This can be useful in hostonly mode for resume support when your swap is on + This can be useful in host-only mode for resume support when your swap is on LVM or an encrypted partition. [NB --device can be used for compatibility with earlier releases] **-i, --include** __ __:: - include the files in the SOURCE directory into the + Include the files in the SOURCE directory into the TARGET directory in the final initramfs. If SOURCE is a file, it will be installed to TARGET in the final initramfs. This parameter can be specified multiple times. **-I, --install** __:: - install the space separated list of files into the initramfs. + Install the space separated list of files into the initramfs. + [NOTE] =============================== -If [LIST] has multiple arguments, then you have to put these in quotes. For +If the list has multiple arguments, then you have to put these in quotes. For example: ---- # dracut --install "/bin/foo /sbin/bar" ... @@ -407,12 +437,12 @@ example: =============================== **--install-optional** __:: - install the space separated list of files into the initramfs, if they exist. + Install the space separated list of files into the initramfs, if they exist. **--gzip**:: Compress the generated initramfs using gzip. This will be done by default, unless another compression option or --no-compress is passed. Equivalent to - "--compress=gzip -9" + "--compress=gzip -9". **--bzip2**:: Compress the generated initramfs using bzip2. @@ -420,7 +450,7 @@ example: [WARNING] ==== Make sure your kernel has bzip2 decompression support compiled in, otherwise you -will not be able to boot. Equivalent to "--compress=bzip2" +will not be able to boot. Equivalent to "--compress=bzip2 -9". ==== **--lzma**:: @@ -429,7 +459,7 @@ will not be able to boot. Equivalent to "--compress=bzip2" [WARNING] ==== Make sure your kernel has lzma decompression support compiled in, otherwise you -will not be able to boot. Equivalent to "lzma --compress=lzma -9" +will not be able to boot. Equivalent to "--compress=lzma -9 -T0". ==== **--xz**:: @@ -439,31 +469,34 @@ will not be able to boot. Equivalent to "lzma --compress=lzma -9" ==== Make sure your kernel has xz decompression support compiled in, otherwise you will not be able to boot. Equivalent to -"lzma --compress=xz --check=crc32 --lzma2=dict=1MiB" +"--compress=xz --check=crc32 --lzma2=dict=1MiB -T0". ==== **--lzo**:: Compress the generated initramfs using lzop. ++ [WARNING] ==== Make sure your kernel has lzo decompression support compiled in, otherwise you -will not be able to boot. +will not be able to boot. Equivalent to "--compress=lzop -9". ==== **--lz4**:: Compress the generated initramfs using lz4. ++ [WARNING] ==== Make sure your kernel has lz4 decompression support compiled in, otherwise you -will not be able to boot. +will not be able to boot. Equivalent to "--compress=lz4 -l -9". ==== **--zstd**:: Compress the generated initramfs using Zstandard. ++ [WARNING] ==== Make sure your kernel has zstd decompression support compiled in, otherwise you -will not be able to boot. +will not be able to boot. Equivalent to "--compress=zstd -15 -q -T0". ==== **--compress** __:: @@ -472,7 +505,8 @@ will not be able to boot. program with known-working arguments. If you pass a quoted string with arguments, it will be called with exactly those arguments. Depending on what you pass, this may result in an initramfs that the kernel cannot decompress. - The default value can also be set via the _INITRD_COMPRESS_ environment variable. + The default value can also be set via the _INITRD_COMPRESS_ environment + variable. **--squash-compressor** __:: Compress the squashfs image using the passed compressor and compressor @@ -500,16 +534,16 @@ will not be able to boot. Keep the initramfs temporary directory for debugging purposes. **--printsize**:: - Print out the module install size + Print out the module install size. -**--profile**: - Output profile information of the build process +**--profile**:: + Output profile information of the build process. -**--ro-mnt**: +**--ro-mnt**:: Mount / and /usr read-only by default. **-L, --stdlog** __:: - [0-6] Specify logging level (to standard error) + [0-6] Specify logging level (to standard error). ---- 0 - suppress any messages 1 - only fatal errors @@ -524,36 +558,42 @@ will not be able to boot. Regenerate all initramfs images at the default location with the kernel versions found on the system. Additional parameters are passed through. -**--loginstall __**:: - Log all files installed from the host to __. +**--noimageifnotneeded**:: + Do not create an image in host-only mode, if no kernel driver is needed +and no /etc/cmdline/*.conf will be generated into the initramfs. + +**--loginstall __**:: + Log all files installed from the host to __. **--uefi**:: - Instead of creating an initramfs image, dracut will create an UEFI executable, - which can be executed by an UEFI BIOS. The default output filename is - _/EFI/Linux/linux-$kernel$--.efi_. might be - _/efi_, _/boot_ or _/boot/efi_ depending on where the ESP partition is mounted. - The is taken from BUILD_ID in _/usr/lib/os-release_ or if it exists - _/etc/os-release_ and is left out, if BUILD_ID is non-existant or empty. + Instead of creating an initramfs image, dracut will create an UEFI + executable, which can be executed by an UEFI BIOS. The default output + filename is _/EFI/Linux/linux-$kernel$--.efi_. + might be _/efi_, _/boot_ or _/boot/efi_ depending on where the ESP + partition is mounted. The is taken from BUILD_ID in + _/usr/lib/os-release_ or if it exists _/etc/os-release_ and is left out, + if BUILD_ID is non-existant or empty. **--no-uefi**:: Disables UEFI mode. **--no-machineid**:: - affects the default output filename of **--uefi** and will discard the - part. + Affects the default output filename of **--uefi** and will discard the + part. -**--uefi-stub __**:: - Specifies the UEFI stub loader, which will load the attached kernel, initramfs and - kernel command line and boots the kernel. The default is - _$prefix/lib/systemd/boot/efi/linux.efi.stub_ +**--uefi-stub __**:: + Specifies the UEFI stub loader, which will load the attached kernel, + initramfs and kernel command line and boots the kernel. The default is + _$prefix/lib/systemd/boot/efi/linux.efi.stub_. -**--uefi-splash-image __**:: - Specifies the UEFI stub loader's splash image. Requires bitmap (**.bmp**) image - format. +**--uefi-splash-image __**:: + Specifies the UEFI stub loader's splash image. Requires bitmap (**.bmp**) + image format. -**--kernel-image __**:: - Specifies the kernel image, which to include in the UEFI executable. The default is - _/lib/modules//vmlinuz_ or _/boot/vmlinuz-_ +**--kernel-image __**:: + Specifies the kernel image, which to include in the UEFI executable. The + default is _/lib/modules//vmlinuz_ or + _/boot/vmlinuz-_. **--enhanced-cpio**:: Attempt to use the dracut-cpio binary, which optimizes archive creation for @@ -562,7 +602,8 @@ will not be able to boot. optimal data alignment for extent sharing. To retain reflink data deduplication benefits, this should be used alongside the **--no-compress** and **--no-strip** parameters, with initramfs source files, **--tmpdir** - staging area and destination all on the same copy-on-write capable filesystem. + staging area and destination all on the same copy-on-write capable + filesystem. ENVIRONMENT -----------