Difference between revisions of "Dracut"

From ArchWiki
Jump to navigation Jump to search
(There's nothing settled yet, to early to say we're replacing)
(→‎Generate a new initramfs on kernel upgrade: replace deprecated "Type = File" with "Type = Path", https://git.archlinux.org/pacman.git/commit/?id=39c20ad4f1d5f6e915b5be8976b6a94885ca3b0c)
 
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Lowercase title}}
 
{{Lowercase title}}
 
[[Category:Boot process]]
 
[[Category:Boot process]]
{{Note|Read the mailing list announcment for a possible [https://lists.archlinux.org/pipermail/arch-dev-public/2019-May/029570.html Mkinitcpio replacement with Dracut].}}
+
[[ja:Dracut]]
 +
{{Related articles start}}
 +
{{Related|mkinitcpio}}
 +
{{Related articles end}}
 +
{{Note|Read the mailing list announcement for a possible [https://lists.archlinux.org/pipermail/arch-dev-public/2019-May/029570.html Mkinitcpio replacement with Dracut].}}
  
[https://dracut.wiki.kernel.org/ 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. This might replace [[mkinitcpio]] in Arch Linux in the near future.
+
[https://dracut.wiki.kernel.org/ 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. Upon installing {{Pkg|linux}}, you can choose between [[mkinitcpio]] and dracut. dracut is used by Fedora, RHEL, Gentoo, and Debian, among others.
 +
 
 +
You can read the full project documentation for dracut [https://mirrors.edge.kernel.org/pub/linux/utils/boot/dracut/dracut.html in the kernel documentation].
 +
 
 +
== Installation ==
 +
 
 +
dracut can be [[install]]ed with the {{Pkg|dracut}} package.
 +
 
 +
{{Tip|If dracut works on your machine '''after you test it''', you can remove {{Pkg|mkinitcpio}}.}}
 +
 
 +
== Configuration ==
 +
 
 +
If you wish to always execute dracut with a certain set of flags, you can save a specified configuration in a {{ic|.conf}} file in {{ic|/etc/dracut.conf.d/}}. For example:
 +
 
 +
{{hc|/etc/dracut.conf.d/myflags.conf|2=
 +
hostonly="yes"
 +
compress="lz4"
 +
add_drivers+=" i915 "
 +
omit_dracutmodules+=" network iscsi "
 +
}}
 +
 
 +
You can see more configuration options with {{man|5|dracut.conf}}. Fuller descriptions of each option can be found with {{man|8|dracut}}.
 +
 
 +
=== Kernel command line options ===
 +
 
 +
You can force dracut to use kernel command line parameters in the initramfs environment. Be aware that you should [[#Spaces in kernel parameters|use the UUID naming scheme]] for specifying block devices.
 +
 
 +
It is not necessary to specify the root block device for dracut. From {{man|7|dracut.cmdline}}:
 +
 
 +
: The root device used by the kernel is specified in the boot configuration file on the kernel command line, as always.
 +
 
 +
However, it may be useful to set some parameters early, and you can enable additional features like prompting for additional command like parameters. See {{man|7|dracut.cmdline}} for all options. Here are some example configuration options:
 +
 
 +
* Resume from a swap partition: {{ic|1=resume=UUID=80895b78-7312-45bc-afe5-58eb4b579422}}
 +
* Prompt for additional kernel command line parameters: {{ic|1=rd.cmdline=ask}}
 +
* Print informational output even if "quiet" is set: {{ic|1=rd.info}}
 +
 
 +
Kernel command line options should be placed line-by-line similar to the {{ic|/etc/dracut.conf.d/}} style, in a {{ic|*.conf}} file in {{ic|/etc/cmdline.d/}}. For example, your kernel command line options file could look like:
 +
 
 +
{{hc|/etc/cmdline.d/myflags.conf|2=
 +
resume=UUID=80895b78-7312-45bc-afe5-58eb4b579422
 +
rd.cmdline=ask
 +
rd.info
 +
}}
 +
 
 +
== Usage ==
 +
 
 +
dracut is easy to use and typically does not require user configuration, even when using non-standard setups, like [[dm-crypt/Encrypting an entire system#LVM on LUKS|LVM on LUKS]].
 +
 
 +
To generate an initramfs for the running kernel:
 +
 
 +
# dracut /boot/initramfs-linux.img
 +
 
 +
To generate a fallback initramfs run:
 +
 
 +
# dracut -N /boot/initramfs-linux-fallback.img
 +
 
 +
{{ic|/boot/initramfs-linux.img}} refers to the output image file. If you are using the non-regular kernel, consider changing the file name. For example, for the {{Pkg|linux-lts}} kernel, the output file should be named {{ic|/boot/initramfs-linux-lts.img}}. However, you can name these files whatever you wish as long as your [[boot loader]] configuration uses the same file names.
 +
 
 +
=== Additional flags ===
 +
 
 +
The {{ic|--hostonly}} flag creates an image that only contains the files needed to boot the local host system, instead of creating a generic image with more files. Using this flag reduces the size of the generated image, but you will not be able to use it on other computers or switch to a different root file system without generating a new image.
 +
 
 +
The {{ic|--force}} flag overwrites the image file if it is already present.
 +
 
 +
More flags can be found with {{man|8|dracut}}.
 +
 
 +
== Tips and tricks ==
 +
 
 +
{{Expansion|Add instructions for creating a [[unified kernel image]] using the {{ic|--uefi}} option.}}
 +
 
 +
=== View information about generated image ===
 +
 
 +
You can view information about a generated initramfs image, which you may wish to view in a pager:
 +
 
 +
# lsinitrd ''/path/to/initramfs_image'' | less
 +
 
 +
This command will list the arguments passed to dracut when the image was created, the list of included dracut modules, and the list of all included files.
 +
 
 +
=== Change compression program ===
 +
 
 +
To reduce the amount of time spent compressing the final image, you may change the compression program used.
 +
 
 +
{{Warning|Make sure your kernel has your chosen decompression support compiled in, otherwise you will not be able to boot. You must also have the chosen compression program package installed. Note that Linux does not support zstd compressed initramfs.}}
 +
 
 +
Simply add any one of the following lines (not multiple) [[#Configuration|to your dracut configuration]]:
 +
 
 +
compress="cat"
 +
compress="gzip"
 +
compress="bzip2"
 +
compress="lzma"
 +
compress="xz"
 +
compress="lzo"
 +
compress="lz4"
 +
 
 +
{{Pkg|gzip}} is the default compression program used. {{ic|1=compress="cat"}} will make the initramfs with no compression.
 +
 
 +
You can also use a non-officially-supported compression program:
 +
 
 +
compress="''program''"
 +
 
 +
=== Generate a new initramfs on kernel upgrade ===
 +
 
 +
It is possible to automatically generate new initramfs images upon each kernel upgrade. The instructions here are for the default {{Pkg|linux}} kernel, but it should be easy to add extra hooks for other kernels.
 +
 
 +
As the command to figure out the kernel version is somewhat complex, it will not work by itself in a [[pacman hook]]. So create a script anywhere on your system. For this example it will be created in {{ic|/usr/local/bin/}}.
 +
 
 +
The script will also copy the new {{ic|vmlinuz}} kernel file to {{ic|/boot/}}, since the kernel packages do not place files in {{ic|/boot/}} anymore.[https://lists.archlinux.org/pipermail/arch-general/2019-October/047056.html]
 +
 
 +
{{hc|/usr/local/bin/dracut-install.sh|<nowiki>
 +
#!/usr/bin/env bash
 +
 
 +
args=('--no-hostonly-cmdline')
 +
 
 +
while read -r line; do
 +
if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
 +
read -r pkgbase < "/${line}"
 +
kver="${line#'usr/lib/modules/'}"
 +
kver="${kver%'/pkgbase'}"
 +
 
 +
install -Dm0644 "/${line%'/pkgbase'}/vmlinuz" "/boot/vmlinuz-${pkgbase}"
 +
dracut "${args[@]}" --force "/boot/initramfs-${pkgbase}.img" --kver "$kver"
 +
dracut --no-hostonly --force "/boot/initramfs-${pkgbase}-fallback.img" --kver "$kver"
 +
fi
 +
done
 +
</nowiki>}}
 +
 
 +
{{hc|/usr/local/bin/dracut-remove.sh|<nowiki>
 +
#!/usr/bin/env bash
 +
 
 +
while read -r line; do
 +
if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
 +
read -r pkgbase < "/${line}"
 +
rm -f "/boot/vmlinuz-${pkgbase}" "/boot/initramfs-${pkgbase}.img" "/boot/initramfs-${pkgbase}-fallback.img"
 +
fi
 +
done
 +
</nowiki>}}
 +
 
 +
You need to make the scripts [[executable]]. If you wish to add or remove flags, you should [[#Configuration|add them to your dracut configuration]].
 +
 
 +
The next step is creating [[pacman hook]]s:
 +
 
 +
{{hc|/etc/pacman.d/hooks/90-dracut-install.hook|<nowiki>
 +
[Trigger]
 +
Type = Path
 +
Operation = Install
 +
Operation = Upgrade
 +
Target = usr/lib/modules/*/pkgbase
 +
 
 +
[Action]
 +
Description = Updating linux initcpios (with dracut!)...
 +
When = PostTransaction
 +
Exec = /usr/local/bin/dracut-install.sh
 +
NeedsTargets
 +
</nowiki>}}
 +
 
 +
{{hc|/etc/pacman.d/hooks/60-dracut-remove.hook|<nowiki>
 +
[Trigger]
 +
Type = Path
 +
Operation = Remove
 +
Target = usr/lib/modules/*/pkgbase
 +
 
 +
[Action]
 +
Description = Removing linux initcpios...
 +
When = PreTransaction
 +
Exec = /usr/local/bin/dracut-remove.sh
 +
NeedsTargets
 +
</nowiki>}}
 +
 
 +
You should stop [[mkinitcpio]] from creating and removing initramfs images as well, either by removing {{Pkg|mkinitcpio}} or with the following commands:
 +
 
 +
# ln -sf /dev/null /etc/pacman.d/hooks/90-mkinitcpio-install.hook
 +
# ln -sf /dev/null /etc/pacman.d/hooks/60-mkinitcpio-remove.hook
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== Spaces in kernel parameters ===
 +
 
 +
dracut does not support quoted values with spaces in the {{ic|1=root=}} and {{ic|1=resume=}} [[kernel parameters]]. For example {{ic|1=root="PARTLABEL=Arch Linux"}}. See [https://github.com/dracutdevs/dracut/issues/720 dracut issue 720].
 +
 
 +
You will need to specify the parameters using a different block device naming scheme like [[UUID]].
 +
 
 +
== See also ==
 +
 
 +
* [[Wikipedia:dracut (software)]]
 +
* [[Gentoo:Dracut]]

Latest revision as of 10:32, 18 February 2020

Note: Read the mailing list announcement for a possible Mkinitcpio replacement with Dracut.

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. Upon installing linux, you can choose between mkinitcpio and dracut. dracut is used by Fedora, RHEL, Gentoo, and Debian, among others.

You can read the full project documentation for dracut in the kernel documentation.

Installation

dracut can be installed with the dracut package.

Tip: If dracut works on your machine after you test it, you can remove mkinitcpio.

Configuration

If you wish to always execute dracut with a certain set of flags, you can save a specified configuration in a .conf file in /etc/dracut.conf.d/. For example:

/etc/dracut.conf.d/myflags.conf
hostonly="yes"
compress="lz4"
add_drivers+=" i915 "
omit_dracutmodules+=" network iscsi "

You can see more configuration options with dracut.conf(5). Fuller descriptions of each option can be found with dracut(8).

Kernel command line options

You can force dracut to use kernel command line parameters in the initramfs environment. Be aware that you should use the UUID naming scheme for specifying block devices.

It is not necessary to specify the root block device for dracut. From dracut.cmdline(7):

The root device used by the kernel is specified in the boot configuration file on the kernel command line, as always.

However, it may be useful to set some parameters early, and you can enable additional features like prompting for additional command like parameters. See dracut.cmdline(7) for all options. Here are some example configuration options:

  • Resume from a swap partition: resume=UUID=80895b78-7312-45bc-afe5-58eb4b579422
  • Prompt for additional kernel command line parameters: rd.cmdline=ask
  • Print informational output even if "quiet" is set: rd.info

Kernel command line options should be placed line-by-line similar to the /etc/dracut.conf.d/ style, in a *.conf file in /etc/cmdline.d/. For example, your kernel command line options file could look like:

/etc/cmdline.d/myflags.conf
resume=UUID=80895b78-7312-45bc-afe5-58eb4b579422
rd.cmdline=ask
rd.info

Usage

dracut is easy to use and typically does not require user configuration, even when using non-standard setups, like LVM on LUKS.

To generate an initramfs for the running kernel:

# dracut /boot/initramfs-linux.img

To generate a fallback initramfs run:

# dracut -N /boot/initramfs-linux-fallback.img

/boot/initramfs-linux.img refers to the output image file. If you are using the non-regular kernel, consider changing the file name. For example, for the linux-lts kernel, the output file should be named /boot/initramfs-linux-lts.img. However, you can name these files whatever you wish as long as your boot loader configuration uses the same file names.

Additional flags

The --hostonly flag creates an image that only contains the files needed to boot the local host system, instead of creating a generic image with more files. Using this flag reduces the size of the generated image, but you will not be able to use it on other computers or switch to a different root file system without generating a new image.

The --force flag overwrites the image file if it is already present.

More flags can be found with dracut(8).

Tips and tricks

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Add instructions for creating a unified kernel image using the --uefi option. (Discuss in Talk:Dracut#)

View information about generated image

You can view information about a generated initramfs image, which you may wish to view in a pager:

# lsinitrd /path/to/initramfs_image | less

This command will list the arguments passed to dracut when the image was created, the list of included dracut modules, and the list of all included files.

Change compression program

To reduce the amount of time spent compressing the final image, you may change the compression program used.

Warning: Make sure your kernel has your chosen decompression support compiled in, otherwise you will not be able to boot. You must also have the chosen compression program package installed. Note that Linux does not support zstd compressed initramfs.

Simply add any one of the following lines (not multiple) to your dracut configuration:

compress="cat"
compress="gzip"
compress="bzip2"
compress="lzma"
compress="xz"
compress="lzo"
compress="lz4"

gzip is the default compression program used. compress="cat" will make the initramfs with no compression.

You can also use a non-officially-supported compression program:

compress="program"

Generate a new initramfs on kernel upgrade

It is possible to automatically generate new initramfs images upon each kernel upgrade. The instructions here are for the default linux kernel, but it should be easy to add extra hooks for other kernels.

As the command to figure out the kernel version is somewhat complex, it will not work by itself in a pacman hook. So create a script anywhere on your system. For this example it will be created in /usr/local/bin/.

The script will also copy the new vmlinuz kernel file to /boot/, since the kernel packages do not place files in /boot/ anymore.[1]

/usr/local/bin/dracut-install.sh
#!/usr/bin/env bash

args=('--no-hostonly-cmdline')

while read -r line; do
	if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
		read -r pkgbase < "/${line}"
		kver="${line#'usr/lib/modules/'}"
		kver="${kver%'/pkgbase'}"

		install -Dm0644 "/${line%'/pkgbase'}/vmlinuz" "/boot/vmlinuz-${pkgbase}"
		dracut "${args[@]}" --force "/boot/initramfs-${pkgbase}.img" --kver "$kver"
		dracut --no-hostonly --force "/boot/initramfs-${pkgbase}-fallback.img" --kver "$kver"
	fi
done
/usr/local/bin/dracut-remove.sh
#!/usr/bin/env bash

while read -r line; do
	if [[ "$line" == 'usr/lib/modules/'+([^/])'/pkgbase' ]]; then
		read -r pkgbase < "/${line}"
		rm -f "/boot/vmlinuz-${pkgbase}" "/boot/initramfs-${pkgbase}.img" "/boot/initramfs-${pkgbase}-fallback.img"
	fi
done

You need to make the scripts executable. If you wish to add or remove flags, you should add them to your dracut configuration.

The next step is creating pacman hooks:

/etc/pacman.d/hooks/90-dracut-install.hook
[Trigger]
Type = Path
Operation = Install
Operation = Upgrade
Target = usr/lib/modules/*/pkgbase

[Action]
Description = Updating linux initcpios (with dracut!)...
When = PostTransaction
Exec = /usr/local/bin/dracut-install.sh
NeedsTargets
/etc/pacman.d/hooks/60-dracut-remove.hook
[Trigger]
Type = Path
Operation = Remove
Target = usr/lib/modules/*/pkgbase

[Action]
Description = Removing linux initcpios...
When = PreTransaction
Exec = /usr/local/bin/dracut-remove.sh
NeedsTargets

You should stop mkinitcpio from creating and removing initramfs images as well, either by removing mkinitcpio or with the following commands:

# ln -sf /dev/null /etc/pacman.d/hooks/90-mkinitcpio-install.hook
# ln -sf /dev/null /etc/pacman.d/hooks/60-mkinitcpio-remove.hook

Troubleshooting

Spaces in kernel parameters

dracut does not support quoted values with spaces in the root= and resume= kernel parameters. For example root="PARTLABEL=Arch Linux". See dracut issue 720.

You will need to specify the parameters using a different block device naming scheme like UUID.

See also