dracut.8.asc

   1 DRACUT(8)
   2 =========
   3 :doctype: manpage
   4 :man source:   dracut
   5 :man manual:   dracut
   6 :man version:  {version}
   7
   8 NAME
   9 ----
  10 dracut - low-level tool for generating an initramfs/initrd image
  11
  12 SYNOPSIS
  13 --------
  14 *dracut* [__OPTION...__] [__<image>__ [__<kernel version>__]]
  15
  16 DESCRIPTION
  17 -----------
  18
  19 Create an initramfs <image> for the kernel with the version <kernel version>.
  20 If <kernel version> is omitted, then the version of the actual running
  21 kernel is used. If <image> is omitted or empty, then the default location
  22 /boot/initramfs-<kernel version>.img is used.
  23
  24 dracut creates an initial image used by the kernel for preloading the block
  25 device modules (such as IDE, SCSI or RAID) which are needed to access the root
  26 filesystem, mounting the root filesystem and booting into the real system.
  27
  28 At boot time, the kernel unpacks that archive into RAM disk, mounts and uses it
  29 as initial root file system. All finding of the root device happens in this
  30 early userspace.
  31
  32 Initramfs images are also called "initrd".
  33
  34 For a complete list of kernel command line options see *dracut.cmdline*(7).
  35
  36 If you are dropped to an emergency shell, while booting your initramfs,
  37 the file _/run/initramfs/rdsosreport.txt_ is created, which can be saved to a
  38 (to be mounted by hand) partition (usually /boot) or a USB stick.
  39 Additional debugging info can be produced by adding **rd.debug** to the kernel
  40 command line. _/run/initramfs/rdsosreport.txt_ contains all logs and the output
  41 of some tools. It should be attached to any report about dracut problems.
  42
  43 USAGE
  44 -----
  45
  46 include::dracut.usage.asc[]
  47
  48 OPTIONS
  49 -------
  50 **--kver** _<kernel version>_::
  51     set the kernel version. This enables to specify the kernel version, without
  52     specifying the location of the initramfs image. For example:
  53 ----
  54 # dracut --kver 3.5.0-0.rc7.git1.2.fc18.x86_64
  55 ----
  56
  57 **-f, --force**::
  58     overwrite existing initramfs file.
  59
  60 **-a, --add** _<list of dracut modules>_::
  61     add a space-separated list of dracut modules to the default set of modules.
  62     This parameter can be specified multiple times.
  63 +
  64 [NOTE]
  65 ===============================
  66 If [LIST] has multiple arguments, then you have to put these in quotes. For
  67 example:
  68 ----
  69 # dracut --add "module1 module2"  ...
  70 ----
  71 ===============================
  72
  73 **--force-add** _<list of dracut modules>_::
  74     force to add a space-separated list of dracut modules to the default set of
  75     modules, when -H is specified. This parameter can be specified multiple
  76     times.
  77 +
  78 [NOTE]
  79 ===============================
  80 If [LIST] has multiple arguments, then you have to put these in quotes. For
  81 example:
  82 ----
  83 # dracut --force-add "module1 module2"  ...
  84 ----
  85 ===============================
  86
  87 **-o, --omit** _<list of dracut modules>_::
  88     omit a space-separated list of dracut modules. This parameter can be
  89     specified multiple times.
  90 +
  91 [NOTE]
  92 ===============================
  93 If [LIST] has multiple arguments, then you have to put these in quotes. For
  94 example:
  95 ----
  96 # dracut --omit "module1 module2"  ...
  97 ----
  98 ===============================
  99
 100 **-m, --modules** _<list of dracut modules>_::
 101     specify a space-separated list of dracut modules to call when building the
 102     initramfs. Modules are located in _/usr/lib/dracut/modules.d_. This
 103     parameter can be specified multiple times.
 104     This option forces dracut to only include the specified dracut modules.
 105     In most cases the "--add" option is what you want to use.
 106 +
 107 [NOTE]
 108 ===============================
 109 If [LIST] has multiple arguments, then you have to put these in quotes. For
 110 example:
 111 ----
 112 # dracut --modules "module1 module2"  ...
 113 ----
 114 ===============================
 115
 116 **-d, --drivers** _<list of kernel modules>_::
 117     specify a space-separated list of kernel modules to exclusively include
 118     in the initramfs. The kernel modules have to be specified without the ".ko"
 119     suffix. This parameter can be specified multiple times.
 120 +
 121 [NOTE]
 122 ===============================
 123 If [LIST] has multiple arguments, then you have to put these in quotes. For
 124 example:
 125 ----
 126 # dracut --drivers "kmodule1 kmodule2"  ...
 127 ----
 128 ===============================
 129
 130 **--add-drivers** _<list of kernel modules>_::
 131     specify a space-separated list of kernel modules to add to the initramfs.
 132     The kernel modules have to be specified without the ".ko" suffix. This
 133     parameter can be specified multiple times.
 134 +
 135 [NOTE]
 136 ===============================
 137 If [LIST] has multiple arguments, then you have to put these in quotes. For
 138 example:
 139 ----
 140 # dracut --add-drivers "kmodule1 kmodule2"  ...
 141 ----
 142 ===============================
 143
 144 **--force-drivers** _<list of kernel modules>_::
 145     See add-drivers above. But in this case it is ensured that the drivers
 146     are tried to be loaded early via modprobe.
 147 +
 148 [NOTE]
 149 ===============================
 150 If [LIST] has multiple arguments, then you have to put these in quotes. For
 151 example:
 152 ----
 153 # dracut --force-drivers "kmodule1 kmodule2"  ...
 154 ----
 155 ===============================
 156
 157 **--omit-drivers** _<list of kernel modules>_::
 158     specify a space-separated list of kernel modules not to add to the
 159     initramfs.
 160     The kernel modules have to be specified without the ".ko" suffix. This
 161     parameter can be specified multiple times.
 162 +
 163 [NOTE]
 164 ===============================
 165 If [LIST] has multiple arguments, then you have to put these in quotes. For
 166 example:
 167 ----
 168 # dracut --omit-drivers "kmodule1 kmodule2"  ...
 169 ----
 170 ===============================
 171
 172 **--filesystems** _<list of filesystems>_::
 173     specify a space-separated list of kernel filesystem modules to exclusively
 174     include in the generic initramfs. This parameter can be specified multiple
 175     times.
 176 +
 177 [NOTE]
 178 ===============================
 179 If [LIST] has multiple arguments, then you have to put these in quotes. For
 180 example:
 181 ----
 182 # dracut --filesystems "filesystem1 filesystem2"  ...
 183 ----
 184 ===============================
 185
 186 **-k, --kmoddir** _<kernel directory>_::
 187     specify the directory, where to look for kernel modules
 188
 189 **--fwdir** _<dir>[:<dir>...]++_::
 190     specify additional directories, where to look for firmwares. This parameter
 191     can be specified multiple times.
 192
 193 **--kernel-cmdline <parameters>**::
 194     specify default kernel command line parameters
 195
 196
 197 **--kernel-only**::
 198     only install kernel drivers and firmware files
 199
 200 **--no-kernel**::
 201     do not install kernel drivers and firmware files
 202
 203 **--early-microcode**::
 204     Combine early microcode with ramdisk
 205
 206 **--no-early-microcode**::
 207     Do not combine early microcode with ramdisk
 208
 209 **--print-cmdline**::
 210     print the kernel command line for the current disk layout
 211
 212 **--mdadmconf**::
 213     include local _/etc/mdadm.conf_
 214
 215 **--nomdadmconf**::
 216     do not include local _/etc/mdadm.conf_
 217
 218 **--lvmconf**::
 219     include local _/etc/lvm/lvm.conf_
 220
 221 **--nolvmconf**::
 222     do not include local _/etc/lvm/lvm.conf_
 223
 224 **--fscks** [LIST]::
 225     add a space-separated list of fsck tools, in addition to _dracut.conf_'s
 226     specification; the installation is opportunistic (non-existing tools are
 227     ignored)
 228 +
 229 [NOTE]
 230 ===============================
 231 If [LIST] has multiple arguments, then you have to put these in quotes. For
 232 example:
 233 ----
 234 # dracut --fscks "fsck.foo barfsck"  ...
 235 ----
 236 ===============================
 237
 238 **--nofscks**::
 239     inhibit installation of any fsck tools
 240
 241 **--strip**::
 242     strip binaries in the initramfs (default)
 243
 244 **--nostrip**::
 245     do not strip binaries in the initramfs
 246
 247 **--hardlink**::
 248     hardlink files in the initramfs (default)
 249
 250 **--nohardlink**::
 251     do not hardlink files in the initramfs
 252
 253 **--prefix** _<dir>_::
 254     prefix initramfs files with the specified directory
 255
 256 **--noprefix**::
 257     do not prefix initramfs files (default)
 258
 259 **-h, --help**::
 260     display help text and exit.
 261
 262 **--debug**::
 263     output debug information of the build process
 264
 265 **-v, --verbose**::
 266     increase verbosity level (default is info(4))
 267
 268 **-q, --quiet**:: decrease verbosity level (default is info(4))
 269
 270 **-c, --conf** _<dracut configuration file>_::
 271     specify configuration file to use.
 272 +
 273 Default:
 274    _/etc/dracut.conf_
 275
 276 **--confdir** _<configuration directory>_::
 277     specify configuration directory to use.
 278 +
 279 Default:
 280    _/etc/dracut.conf.d_
 281
 282 **--tmpdir** _<temporary directory>_::
 283     specify temporary directory to use.
 284 +
 285 Default:
 286    _/var/tmp_
 287
 288 **-r, --sysroot** _<sysroot directory>_::
 289     specify the sysroot directory to collect files from.
 290     This is useful to create the initramfs image from
 291     a cross-compiled sysroot directory. For the extra helper
 292     variables, see *ENVIRONMENT* below.
 293 +
 294 Default:
 295     _empty_
 296
 297 **--sshkey** _<sshkey file>_:: ssh key file used with ssh-client module.
 298
 299 **--logfile** _<logfile>_:: logfile to use; overrides any setting from
 300     the configuration files.
 301 +
 302 Default:
 303     _/var/log/dracut.log_
 304
 305 **-l, --local**::
 306     activates the local mode. dracut will use modules from the current working
 307     directory instead of the system-wide installed modules in
 308     _/usr/lib/dracut/modules.d_.
 309     This is useful when running dracut from a git checkout.
 310
 311 **-H, --hostonly**::
 312     Host-Only mode: Install only what is needed for booting the local host
 313     instead of a generic host and generate host-specific configuration.
 314 +
 315 [WARNING]
 316 ====
 317 If chrooted to another root other than the real root device, use "--fstab" and
 318 provide a valid _/etc/fstab_.
 319 ====
 320
 321 **-N, --no-hostonly**::
 322     Disable Host-Only mode
 323
 324 **--hostonly-cmdline**:
 325     Store kernel command line arguments needed in the initramfs
 326
 327 **--no-hostonly-cmdline**:
 328     Do not store kernel command line arguments needed in the initramfs
 329
 330 **--no-hostonly-default-device**:
 331     Do not generate implicit host devices like root, swap, fstab, etc.
 332     Use "--mount" or "--add-device" to explicitly add devices as needed.
 333
 334 **--hostonly-i18n**:
 335     Install only needed keyboard and font files according to the host configuration (default).
 336
 337 **--no-hostonly-i18n**:
 338     Install all keyboard and font files available.
 339
 340 **--persistent-policy** _<policy>_::
 341     Use _<policy>_ to address disks and partitions.
 342     _<policy>_ can be any directory name found in /dev/disk.
 343     E.g. "by-uuid", "by-label"
 344
 345 **--fstab**::
 346     Use _/etc/fstab_ instead of _/proc/self/mountinfo_.
 347
 348 **--add-fstab** _<filename>_::
 349     Add entries of _<filename>_ to the initramfs /etc/fstab.
 350
 351 **--mount** "_<device>_ _<mountpoint>_ _<filesystem type>_ [_<filesystem options>_ [_<dump frequency>_ [_<fsck order>_]]]"::
 352     Mount _<device>_ on _<mountpoint>_ with _<filesystem type>_ in the
 353     initramfs. _<filesystem options>_, _<dump options>_ and _<fsck order>_ can
 354     be specified, see fstab manpage for the details.
 355     The default _<filesystem options>_ is "defaults".
 356     The default _<dump frequency>_ is "0".
 357     the default _<fsck order>_ is "2".
 358
 359 **--mount** "_<mountpoint>_"::
 360     Like above, but _<device>_, _<filesystem type>_ and _<filesystem options>_
 361     are determined by looking at the current mounts.
 362
 363 **--add-device** _<device>_ ::
 364     Bring up _<device>_ in initramfs, _<device>_ should be the device name.
 365     This can be useful in hostonly mode for resume support when your swap is on
 366     LVM or an encrypted partition.
 367     [NB --device can be used for compatibility with earlier releases]
 368
 369 **-i, --include** _<SOURCE>_ _<TARGET>_::
 370     include the files in the SOURCE directory into the
 371     TARGET directory in the final initramfs. If SOURCE is a file, it will be
 372     installed to TARGET in the final initramfs. This parameter can be specified
 373     multiple times.
 374
 375 **-I, --install** _<file list>_::
 376     install the space separated list of files into the initramfs.
 377 +
 378 [NOTE]
 379 ===============================
 380 If [LIST] has multiple arguments, then you have to put these in quotes. For
 381 example:
 382 ----
 383 # dracut --install "/bin/foo /sbin/bar"  ...
 384 ----
 385 ===============================
 386
 387 **--install-optional** _<file list>_::
 388     install the space separated list of files into the initramfs, if they exist.
 389
 390 **--gzip**::
 391     Compress the generated initramfs using gzip. This will be done by default,
 392     unless another compression option or --no-compress is passed. Equivalent to
 393     "--compress=gzip -9"
 394
 395 **--bzip2**::
 396     Compress the generated initramfs using bzip2.
 397 +
 398 [WARNING]
 399 ====
 400 Make sure your kernel has bzip2 decompression support compiled in, otherwise you
 401 will not be able to boot. Equivalent to "--compress=bzip2"
 402 ====
 403
 404 **--lzma**::
 405     Compress the generated initramfs using lzma.
 406 +
 407 [WARNING]
 408 ====
 409 Make sure your kernel has lzma decompression support compiled in, otherwise you
 410 will not be able to boot. Equivalent to "lzma --compress=lzma -9"
 411 ====
 412
 413 **--xz**::
 414     Compress the generated initramfs using xz.
 415 +
 416 [WARNING]
 417 ====
 418 Make sure your kernel has xz decompression support compiled in, otherwise you
 419 will not be able to boot. Equivalent to
 420 "lzma --compress=xz --check=crc32 --lzma2=dict=1MiB"
 421 ====
 422
 423 **--lzo**::
 424     Compress the generated initramfs using lzop.
 425 [WARNING]
 426 ====
 427 Make sure your kernel has lzo decompression support compiled in, otherwise you
 428 will not be able to boot.
 429 ====
 430
 431 **--lz4**::
 432     Compress the generated initramfs using lz4.
 433 [WARNING]
 434 ====
 435 Make sure your kernel has lz4 decompression support compiled in, otherwise you
 436 will not be able to boot.
 437 ====
 438
 439 **--zstd**::
 440     Compress the generated initramfs using Zstandard.
 441 [WARNING]
 442 ====
 443 Make sure your kernel has zstd decompression support compiled in, otherwise you
 444 will not be able to boot.
 445 ====
 446
 447 **--compress** _<compressor>_::
 448     Compress the generated initramfs using the passed compression program. If
 449     you pass it just the name of a compression program, it will call that
 450     program with known-working arguments. If you pass a quoted string with
 451     arguments, it will be called with exactly those arguments. Depending on what
 452     you pass, this may result in an initramfs that the kernel cannot decompress.
 453     The default value can also be set via the _INITRD_COMPRESS_ environment variable.
 454
 455 **--no-compress**::
 456     Do not compress the generated initramfs. This will override any other
 457     compression options.
 458
 459 **--reproducible**::
 460     Create reproducible images.
 461
 462 **--no-reproducible**::
 463     Do not create reproducible images.
 464
 465 **--list-modules**::
 466     List all available dracut modules.
 467
 468 **-M, --show-modules**::
 469     Print included module's name to standard output during build.
 470
 471 **--keep**::
 472     Keep the initramfs temporary directory for debugging purposes.
 473
 474 **--printsize**::
 475     Print out the module install size
 476
 477 **--profile**:
 478     Output profile information of the build process
 479
 480 **--ro-mnt**:
 481     Mount / and /usr read-only by default.
 482
 483 **-L, --stdlog** _<level>_::
 484     [0-6] Specify logging level (to standard error)
 485 ----
 486           0 - suppress any messages
 487           1 - only fatal errors
 488           2 - all errors
 489           3 - warnings
 490           4 - info
 491           5 - debug info (here starts lots of output)
 492           6 - trace info (and even more)
 493 ----
 494
 495 **--regenerate-all**::
 496     Regenerate all initramfs images at the default location with the kernel
 497     versions found on the system. Additional parameters are passed through.
 498
 499 **--loginstall _<DIR>_**::
 500     Log all files installed from the host to _<DIR>_.
 501
 502 **--uefi**::
 503     Instead of creating an initramfs image, dracut will create an UEFI executable,
 504     which can be executed by an UEFI BIOS. The default output filename is
 505     _<EFI>/EFI/Linux/linux-$kernel$-<MACHINE_ID>-<BUILD_ID>.efi_. <EFI> might be
 506     _/efi_, _/boot_ or _/boot/efi_ depending on where the ESP partition is mounted.
 507     The <BUILD_ID> is taken from BUILD_ID in _/usr/lib/os-release_ or if it exists
 508     _/etc/os-release_ and is left out, if BUILD_ID is non-existant or empty.
 509
 510 **--no-machineid**::
 511     affects the default output filename of **--uefi** and will discard the <MACHINE_ID>
 512     part.
 513
 514 **--uefi-stub _<FILE>_**::
 515     Specifies the UEFI stub loader, which will load the attached kernel, initramfs and
 516     kernel command line and boots the kernel. The default is
 517     _$prefix/lib/systemd/boot/efi/linux<EFI-MACHINE-TYPE-NAME>.efi.stub_
 518     or _$prefix/lib/gummiboot/linux<EFI-MACHINE-TYPE-NAME>.efi.stub_
 519
 520 **--uefi-splash-image _<FILE>_**::
 521     Specifies the UEFI stub loader's splash image. Requires bitmap (**.bmp**) image
 522     format.
 523
 524 **--kernel-image _<FILE>_**::
 525     Specifies the kernel image, which to include in the UEFI executable. The default is
 526     _/lib/modules/<KERNEL-VERSION>/vmlinuz_ or _/boot/vmlinuz-<KERNEL-VERSION>_
 527
 528 ENVIRONMENT
 529 -----------
 530
 531 _INITRD_COMPRESS_::
 532     sets the default compression program. See **--compress**.
 533
 534 _DRACUT_LDCONFIG_::
 535     sets the _ldconfig_ program path and options. Optional.
 536     Used for **--sysroot**.
 537 +
 538 Default:
 539     _ldconfig_
 540
 541 _DRACUT_LDD_::
 542     sets the _ldd_ program path and options. Optional.
 543     Used for **--sysroot**.
 544 +
 545 Default:
 546     _ldd_
 547
 548 _DRACUT_TESTBIN_::
 549     sets the initially tested binary for detecting library paths.
 550     Optional. Used for **--sysroot**. In the cross-compiled sysroot,
 551     the default value (_/bin/sh_) is unusable, as it is an absolute
 552     symlink and points outside the sysroot directory.
 553 +
 554 Default:
 555     _/bin/sh_
 556
 557 _DRACUT_INSTALL_::
 558     overrides path and options for executing _dracut-install_ internally.
 559     Optional. Can be used to debug _dracut-install_ while running the
 560     main dracut script.
 561 +
 562 Default:
 563     _dracut-install_
 564 +
 565 Example:
 566     DRACUT_INSTALL="valgrind dracut-install"
 567
 568 _DRACUT_COMPRESS_BZIP2_::
 569 _DRACUT_COMPRESS_BZIP2_::
 570 _DRACUT_COMPRESS_LBZIP2_::
 571 _DRACUT_COMPRESS_LZMA_::
 572 _DRACUT_COMPRESS_XZ_::
 573 _DRACUT_COMPRESS_GZIP_::
 574 _DRACUT_COMPRESS_PIGZ_::
 575 _DRACUT_COMPRESS_LZOP_::
 576 _DRACUT_COMPRESS_ZSTD_::
 577 _DRACUT_COMPRESS_LZ4_::
 578 _DRACUT_COMPRESS_CAT_::
 579     overrides for compression utilities to support using them from
 580     non-standard paths.
 581 +
 582 Default values are the default compression utility names to be found in **PATH**.
 583
 584 _DRACUT_ARCH_::
 585     overrides the value of **uname -m**. Used for **--sysroot**.
 586 +
 587 Default:
 588     _empty_ (the value of **uname -m** on the host system)
 589
 590 _SYSTEMD_VERSION_::
 591     overrides systemd version. Used for **--sysroot**.
 592
 593 _DRACUT_INSTALL_PATH_::
 594     overrides **PATH** environment for **dracut-install** to look for
 595     binaries relative to **--sysroot**. In a cross-compiled environment
 596     (e.g. Yocto), PATH points to natively built binaries that are not
 597     in the host's /bin, /usr/bin, etc. **dracut-install** still needs plain
 598     /bin and /usr/bin that are relative to the cross-compiled sysroot.
 599 +
 600 Default:
 601     _PATH_
 602
 603 _DRACUT_INSTALL_LOG_TARGET_::
 604     overrides **DRACUT_LOG_TARGET** for **dracut-install**. It allows
 605     running **dracut-install* to run with different log target that
 606     **dracut** runs with.
 607 +
 608 Default:
 609     _DRACUT_LOG_TARGET_
 610
 611 _DRACUT_INSTALL_LOG_LEVEL_::
 612     overrides **DRACUT_LOG_LEVEL** for **dracut-install**. It allows
 613     running **dracut-install* to run with different log level that
 614     **dracut** runs with.
 615 +
 616 Default:
 617     _DRACUT_LOG_LEVEL_
 618
 619 FILES
 620 -----
 621 _/var/log/dracut.log_::
 622     logfile of initramfs image creation
 623
 624 _/tmp/dracut.log_::
 625     logfile of initramfs image creation, if _/var/log/dracut.log_ is not
 626     writable
 627
 628 _/etc/dracut.conf_::
 629     see dracut.conf5
 630
 631 _/etc/dracut.conf.d/*.conf_::
 632     see dracut.conf5
 633
 634 _/usr/lib/dracut/dracut.conf.d/*.conf_::
 635     see dracut.conf5
 636
 637 Configuration in the initramfs
 638 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 639 _/etc/conf.d/_::
 640     Any files found in _/etc/conf.d/_ will be sourced in the initramfs to
 641     set initial values. Command line options will override these values
 642     set in the configuration files.
 643
 644 _/etc/cmdline_::
 645     Can contain additional command line options. Deprecated, better use
 646     /etc/cmdline.d/*.conf.
 647
 648 _/etc/cmdline.d/*.conf_::
 649     Can contain additional command line options.
 650
 651 AVAILABILITY
 652 ------------
 653 The dracut command is part of the dracut package and is available from
 654 link:$$https://dracut.wiki.kernel.org$$[https://dracut.wiki.kernel.org]
 655
 656 AUTHORS
 657 -------
 658 Harald Hoyer
 659
 660 Victor Lowther
 661
 662 Philippe Seewer
 663
 664 Warren Togami
 665
 666 Amadeusz Żołnowski
 667
 668 Jeremy Katz
 669
 670 David Dillow
 671
 672 Will Woods
 673
 674 SEE ALSO
 675 --------
 676 *dracut.cmdline*(7) *dracut.conf*(5) *lsinitrd*(1)