diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-03 13:54:25 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-03 13:54:25 +0000 |
commit | 9cb1c4df7b9ce1a9ad1312621b0f2b16a94fba3a (patch) | |
tree | 2efb72864cc69e174c9c5ee33efb88a5f1553b48 /man/dracut.8.asc | |
parent | Initial commit. (diff) | |
download | dracut-9cb1c4df7b9ce1a9ad1312621b0f2b16a94fba3a.tar.xz dracut-9cb1c4df7b9ce1a9ad1312621b0f2b16a94fba3a.zip |
Adding upstream version 060+5.upstream/060+5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/dracut.8.asc')
-rw-r--r-- | man/dracut.8.asc | 771 |
1 files changed, 771 insertions, 0 deletions
diff --git a/man/dracut.8.asc b/man/dracut.8.asc new file mode 100644 index 0000000..ae4497e --- /dev/null +++ b/man/dracut.8.asc @@ -0,0 +1,771 @@ +DRACUT(8) +========= +:doctype: manpage +:man source: dracut +:man manual: dracut +:man version: {version} + +NAME +---- +dracut - low-level tool for generating an initramfs/initrd image + +SYNOPSIS +-------- +*dracut* [__OPTION...__] [__<image>__ [__<kernel version>__]] + +DESCRIPTION +----------- + +Create an initramfs <image> for the kernel with the version <kernel version>. +If <kernel version> is omitted, then the version of the actual running +kernel is used. If <image> is omitted or empty, depending on bootloader +specification, the default location can be +_/efi/<machine-id>/<kernel-version>/initrd_, +_/boot/<machine-id>/<kernel-version>/initrd_, +_/boot/efi/<machine-id>/<kernel-version>/initrd_, +_/lib/modules/<kernel-version>/initrd_ or +_/boot/initramfs-<kernel-version>.img_. + +dracut creates an initial image used by the kernel for preloading the block +device modules (such as IDE, SCSI or RAID) which are needed to access the root +filesystem, mounting the root filesystem and booting into the real system. + +At boot time, the kernel unpacks that archive into RAM disk, mounts and uses it +as initial root file system. All finding of the root device happens in this +early userspace. + +Initramfs images are also called "initrd". + +For a complete list of kernel command line options see *dracut.cmdline*(7). + +If you are dropped to an emergency shell, while booting your initramfs, +the file _/run/initramfs/rdsosreport.txt_ is created, which can be saved to a +(to be mounted by hand) partition (usually /boot) or a USB stick. +Additional debugging info can be produced by adding **rd.debug** to the kernel +command line. _/run/initramfs/rdsosreport.txt_ contains all logs and the output +of some tools. It should be attached to any report about dracut problems. + +USAGE +----- + +include::dracut.usage.asc[] + +OPTIONS +------- +**--kver** _<kernel version>_:: + 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. + +_<output 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 _<output file>_ is not provided, the input initramfs + provided to rebuild will be used as output file. + +**-a, --add** _<list of dracut modules>_:: + Add a space-separated list of dracut modules to the default set of modules. + This parameter can be specified multiple times. ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --add "module1 module2" ... +---- +=============================== + +**--force-add** _<list of dracut modules>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --force-add "module1 module2" ... +---- +=============================== + +**-o, --omit** _<list of dracut modules>_:: + Omit a space-separated list of dracut modules. This parameter can be + specified multiple times. ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --omit "module1 module2" ... +---- +=============================== + +**-m, --modules** _<list of dracut modules>_:: + 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. + In most cases the "--add" option is what you want to use. ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --modules "module1 module2" ... +---- +=============================== + +**-d, --drivers** _<list of kernel modules>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --drivers "kmodule1 kmodule2" ... +---- +=============================== + +**--add-drivers** _<list of kernel modules>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --add-drivers "kmodule1 kmodule2" ... +---- +=============================== + +**--force-drivers** _<list of kernel modules>_:: + See add-drivers above. But in this case it is ensured that the drivers + are tried to be loaded early via modprobe. ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --force-drivers "kmodule1 kmodule2" ... +---- +=============================== + +**--omit-drivers** _<list of kernel modules>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --omit-drivers "kmodule1 kmodule2" ... +---- +=============================== + +**--filesystems** _<list of filesystems>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --filesystems "filesystem1 filesystem2" ... +---- +=============================== + +**-k, --kmoddir** _<kernel directory>_:: + Specify the directory, where to look for kernel modules. + +**--fwdir** _<dir>[:<dir>...]++_:: + Specify additional directories, where to look for firmwares. This parameter + can be specified multiple times. + +**--libdirs** _<list of directories>_:: + 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 the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --libdirs "dir1 dir2" ... +---- +=============================== + +**--kernel-cmdline <parameters>**:: + Specify default kernel command line parameters. + +**--kernel-only**:: + Only install kernel drivers and firmware files. + +**--no-kernel**:: + Do not install kernel drivers and firmware files. + +**--early-microcode**:: + Combine early microcode with ramdisk. + +**--no-early-microcode**:: + Do not combine early microcode with ramdisk. + +**--print-cmdline**:: + Print the kernel command line for the current disk layout. + +**--mdadmconf**:: + Include local _/etc/mdadm.conf_ file. + +**--nomdadmconf**:: + Do not include local _/etc/mdadm.conf_ file. + +**--lvmconf**:: + Include local _/etc/lvm/lvm.conf_ file. + +**--nolvmconf**:: + Do not include local _/etc/lvm/lvm.conf_ file. + +**--fscks** _<list of fsck tools>_:: + Add a space-separated list of fsck tools, in addition to _dracut.conf_'s + specification; the installation is opportunistic (non-existing tools are + ignored). ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --fscks "fsck.foo barfsck" ... +---- +=============================== + +**--nofscks**:: + Inhibit installation of any fsck tools. + +**--strip**:: + Strip binaries in the initramfs (default). + +**--aggressive-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. + +**--hardlink**:: + Hardlink files in the initramfs (default). + +**--nohardlink**:: + Do not hardlink files in the initramfs. + +**--prefix** _<dir>_:: + Prefix initramfs files with the specified directory. + +**--noprefix**:: + Do not prefix initramfs files (default). + +**-h, --help**:: + Display help text and exit. + +**--debug**:: + Output debug information of the build process. + +**-v, --verbose**:: + Increase verbosity level (default is info(4)). + +**--version**:: + Display version and exit. + +**-q, --quiet**:: + Decrease verbosity level (default is info(4)). + +**-c, --conf** _<dracut configuration file>_:: + Specify configuration file to use. ++ +Default: + _/etc/dracut.conf_ + +**--confdir** _<configuration directory>_:: + Specify configuration directory to use. ++ +Default: + _/etc/dracut.conf.d_ + +**--tmpdir** _<temporary directory>_:: + Specify temporary directory to use. ++ +Default: + _/var/tmp_ + +**-r, --sysroot** _<sysroot directory>_:: + 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. ++ +Default: + _empty_ + +**--sshkey** _<sshkey file>_:: + SSH key file used with ssh-client module. + +**--logfile** _<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 + 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 + instead of a generic host and generate host-specific configuration. ++ +[WARNING] +==== +If chrooted to another root other than the real root device, use "--fstab" and +provide a valid _/etc/fstab_. +==== + +**-N, --no-hostonly**:: + Disable host-only mode. + +**--hostonly-mode _<mode>_**:: + Specify the host-only mode to use. _<mode>_ 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. + +**--no-hostonly-cmdline**:: + Do not store kernel command line arguments needed in the initramfs. + +**--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). + +**--no-hostonly-i18n**:: + Install all keyboard and font files available. + +**--hostonly-nics** _<list of 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** _<policy>_:: + Use _<policy>_ to address disks and partitions. + _<policy>_ can be any directory name found in /dev/disk (e.g. "by-uuid", + "by-label"), or "mapper" to use /dev/mapper device names (default). + +**--fstab**:: + Use _/etc/fstab_ instead of _/proc/self/mountinfo_. + +**--add-fstab** _<filename>_:: + Add entries of _<filename>_ to the initramfs /etc/fstab. + +**--mount** "_<device>_ _<mountpoint>_ _<filesystem type>_ [_<filesystem options>_ [_<dump frequency>_ [_<fsck order>_]]]":: + Mount _<device>_ on _<mountpoint>_ with _<filesystem type>_ in the + initramfs. _<filesystem options>_, _<dump options>_ and _<fsck order>_ can + be specified, see fstab manpage for the details. + The default _<filesystem options>_ is "defaults". + The default _<dump frequency>_ is "0". + The default _<fsck order>_ is "2". + +**--mount** "_<mountpoint>_":: + Like above, but _<device>_, _<filesystem type>_ and _<filesystem options>_ + are determined by looking at the current mounts. + +**--add-device** _<device>_ :: + Bring up _<device>_ in initramfs, _<device>_ should be the device name. + 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** _<SOURCE>_ _<TARGET>_:: + 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** _<file list>_:: + Install the space separated list of files into the initramfs. ++ +[NOTE] +=============================== +If the list has multiple arguments, then you have to put these in quotes. For +example: +---- +# dracut --install "/bin/foo /sbin/bar" ... +---- +=============================== + +**--install-optional** _<file list>_:: + 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". + +**--bzip2**:: + Compress the generated initramfs using bzip2. ++ +[WARNING] +==== +Make sure your kernel has bzip2 decompression support compiled in, otherwise you +will not be able to boot. Equivalent to "--compress=bzip2 -9". +==== + +**--lzma**:: + Compress the generated initramfs using lzma. ++ +[WARNING] +==== +Make sure your kernel has lzma decompression support compiled in, otherwise you +will not be able to boot. Equivalent to "--compress=lzma -9 -T0". +==== + +**--xz**:: + Compress the generated initramfs using xz. ++ +[WARNING] +==== +Make sure your kernel has xz decompression support compiled in, otherwise you +will not be able to boot. Equivalent to +"--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. 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. 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. Equivalent to "--compress=zstd -15 -q -T0". +==== + +**--compress** _<compressor>_:: + Compress the generated initramfs using the passed compression program. If + you pass it just the name of a compression program, it will call that + 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. + +**--squash-compressor** _<compressor>_:: + Compress the squashfs image using the passed compressor and compressor + specific options for mksquashfs. You can refer to mksquashfs manual for + supported compressors and compressor specific options. If squash module is + not called when building the initramfs, this option will not take effect. + +**--no-compress**:: + Do not compress the generated initramfs. This will override any other + compression options. + +**--reproducible**:: + Create reproducible images. + +**--no-reproducible**:: + Do not create reproducible images. + +**--list-modules**:: + List all available dracut modules. + +**-M, --show-modules**:: + Print included module's name to standard output during build. + +**--keep**:: + Keep the initramfs temporary directory for debugging purposes. + +**--printsize**:: + Print out the module install size. + +**--profile**:: + Output profile information of the build process. + +**--ro-mnt**:: + Mount / and /usr read-only by default. + +**-L, --stdlog** _<level>_:: + [0-6] Specify logging level (to standard error). +---- + 0 - suppress any messages + 1 - only fatal errors + 2 - all errors + 3 - warnings + 4 - info + 5 - debug info (here starts lots of output) + 6 - trace info (and even more) +---- + +**--regenerate-all**:: + Regenerate all initramfs images at the default location with the kernel + versions found on the system. Additional parameters are passed through. + +**-p, --parallel**:: + Try to execute tasks in parallel. Currently only supported with + **--regenerate-all** (build initramfs images for all kernel + versions simultaneously). + +**--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 _<directory>_**:: + Log all files installed from the host to _<directory>_. + +**--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>/EFI/Linux/linux-$kernel$-<MACHINE_ID>-<BUILD_ID>.efi_. + <EFI> might be _/efi_, _/boot_ or _/boot/efi_ depending on where the ESP + partition is mounted. The <BUILD_ID> 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-existent or empty. + +**--no-uefi**:: + Disables UEFI mode. + +**--no-machineid**:: + Affects the default output filename of **--uefi** and will discard the + <MACHINE_ID> part. + +**--uefi-stub _<file>_**:: + 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-MACHINE-TYPE-NAME>.efi.stub_. + +**--uefi-splash-image _<file>_**:: + Specifies the UEFI stub loader's splash image. Requires bitmap (**.bmp**) + image format. + +**--kernel-image _<file>_**:: + Specifies the kernel image, which to include in the UEFI executable. The + default is _/lib/modules/<KERNEL-VERSION>/vmlinuz_ or + _/boot/vmlinuz-<KERNEL-VERSION>_. + +**--sbat <parameters>**:: + Specifies the SBAT parameters, which to include in the UEFI executable. By default + the default SBAT string added is "sbat,1,SBAT Version,sbat,1, + https://github.com/rhboot/shim/blob/main/SBAT.md". + +**--enhanced-cpio**:: + Attempt to use the dracut-cpio binary, which optimizes archive creation for + copy-on-write filesystems by using the copy_file_range(2) syscall via Rust's + io::copy(). When specified, initramfs archives are also padded to ensure + optimal data alignment for extent sharing. To retain reflink data + deduplication benefits, this should be used alongside the **--no-compress** + and **--nostrip** parameters, with initramfs source files, **--tmpdir** + staging area and destination all on the same copy-on-write capable + filesystem. + +ENVIRONMENT +----------- + +_INITRD_COMPRESS_:: + sets the default compression program. See **--compress**. + +_DRACUT_LDCONFIG_:: + sets the _ldconfig_ program path and options. Optional. + Used for **--sysroot**. ++ +Default: + _ldconfig_ + +_DRACUT_LDD_:: + sets the _ldd_ program path and options. Optional. + Used for **--sysroot**. ++ +Default: + _ldd_ + +_DRACUT_TESTBIN_:: + sets the initially tested binary for detecting library paths. + Optional. Used for **--sysroot**. In the cross-compiled sysroot, + the default value (_/bin/sh_) is unusable, as it is an absolute + symlink and points outside the sysroot directory. ++ +Default: + _/bin/sh_ + +_DRACUT_INSTALL_:: + overrides path and options for executing _dracut-install_ internally. + Optional. Can be used to debug _dracut-install_ while running the + main dracut script. ++ +Default: + _dracut-install_ ++ +Example: + DRACUT_INSTALL="valgrind dracut-install" + +_DRACUT_COMPRESS_BZIP2_:: +_DRACUT_COMPRESS_LBZIP2_:: +_DRACUT_COMPRESS_LZMA_:: +_DRACUT_COMPRESS_XZ_:: +_DRACUT_COMPRESS_GZIP_:: +_DRACUT_COMPRESS_PIGZ_:: +_DRACUT_COMPRESS_LZOP_:: +_DRACUT_COMPRESS_ZSTD_:: +_DRACUT_COMPRESS_LZ4_:: +_DRACUT_COMPRESS_CAT_:: + overrides for compression utilities to support using them from + non-standard paths. ++ +Default values are the default compression utility names to be found in **PATH**. + +_DRACUT_ARCH_:: + overrides the value of **uname -m**. Used for **--sysroot**. ++ +Default: + _empty_ (the value of **uname -m** on the host system) + +_SYSTEMD_VERSION_:: + overrides systemd version. Used for **--sysroot**. + +_SYSTEMCTL_:: + overrides the systemctl binary. Used for **--sysroot**. + +_NM_VERSION_:: + overrides the NetworkManager version. Used for **--sysroot**. + +_DRACUT_INSTALL_PATH_:: + overrides **PATH** environment for **dracut-install** to look for + binaries relative to **--sysroot**. In a cross-compiled environment + (e.g. Yocto), PATH points to natively built binaries that are not + in the host's /bin, /usr/bin, etc. **dracut-install** still needs plain + /bin and /usr/bin that are relative to the cross-compiled sysroot. ++ +Default: + _PATH_ + +_DRACUT_INSTALL_LOG_TARGET_:: + overrides **DRACUT_LOG_TARGET** for **dracut-install**. It allows + running **dracut-install* to run with different log target that + **dracut** runs with. ++ +Default: + _DRACUT_LOG_TARGET_ + +_DRACUT_INSTALL_LOG_LEVEL_:: + overrides **DRACUT_LOG_LEVEL** for **dracut-install**. It allows + running **dracut-install* to run with different log level that + **dracut** runs with. ++ +Default: + _DRACUT_LOG_LEVEL_ + +FILES +----- +_/var/log/dracut.log_:: + logfile of initramfs image creation + +_/tmp/dracut.log_:: + logfile of initramfs image creation, if _/var/log/dracut.log_ is not + writable + +_/etc/dracut.conf_:: + see dracut.conf5 + +_/etc/dracut.conf.d/*.conf_:: + see dracut.conf5 + +_/usr/lib/dracut/dracut.conf.d/*.conf_:: + see dracut.conf5 + +Configuration in the initramfs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +_/etc/conf.d/_:: + Any files found in _/etc/conf.d/_ will be sourced in the initramfs to + set initial values. Command line options will override these values + set in the configuration files. + +_/etc/cmdline_:: + Can contain additional command line options. Deprecated, better use + /etc/cmdline.d/*.conf. + +_/etc/cmdline.d/*.conf_:: + Can contain additional command line options. + +AVAILABILITY +------------ +The dracut command is part of the dracut package and is available from +link:$$https://github.com/dracutdevs/dracut$$[https://github.com/dracutdevs/dracut] + +AUTHORS +------- +Harald Hoyer + +Victor Lowther + +Amadeusz Żołnowski + +Hannes Reinecke + +Daniel Molkentin + +Will Woods + +Philippe Seewer + +Warren Togami + +SEE ALSO +-------- +*dracut.cmdline*(7) *dracut.conf*(5) *lsinitrd*(1) |