From Fedora Project Wiki

m (moved User:Johannbg/QA/Dracut to Dracut: Ready for general public)
No edit summary
 
(26 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<!--{{header|dracut}}-->
<!--{{header|dracut}}-->


'''Dracut''' is a new initramfs infrastructure.
'''Dracut''' is an initramfs infrastructure.  The project wiki is at https://github.com/dracutdevs/dracut/wiki (background information about the project's goals and aims can be found at [[Initrdrewrite]]). Unlike previous initramfs systems, Dracut aims to have as little as possible hard-coded into the initramfs.  


Information about the initial goals and aims can be found at [https://fedoraproject.org/wiki/Initrdrewrite Initrdrewrite]
{{admon/warning|This wiki can be incomplete. Please use the dracut.cmdline.7 (alias dracut.kernel.7) man page or point your browser at /usr/share/doc/dracut-*/dracut.html}}


Unlike existing initramfs's, this is an attempt at having as little as possible hard-coded into the initramfs as possible. The initramfs has (basically) one purpose in life -- getting the rootfs mounted so that we can transition to the real rootfs. This is all driven off of device availability. Therefore, instead of scripts hard-coded to do various things, we depend on udev to create device nodes for us and then when we have the rootfs's device node, we mount and carry on. This helps to keep the time required in the initramfs as little as possible so that things like a 5 second boot aren't made impossible as a result of the very existence of an initramfs. It's likely that we'll grow some hooks for running arbitrary commands in the flow of the script, but it's worth trying to resist the urge as much as we can as hooks are guaranteed to be the path to slow-down.
 
== New Kernel Command Line Parameters ==
 
Read the [http://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html#dracut.kernel dracut.kernel.7 man page].
 
== Quick Debugging Tips ==
 
* add "rdshell" to the kernel command line and you are dropped to a shell
* add "rdshell rdinitdebug" to the kernel command line and dracut commands are printed
* you can inspect /init.log and run journalctl from the shell
* mount /boot manually and copy over /init.log or the /run/log/journal files
 
[[How_to_debug_Dracut_problems|Read More... ]]
 
== Technical details ==
 
With Dracut, the initramfs has one purpose in life - getting the rootfs mounted so that we can transition to the real rootfs. This is all driven by device availability. Therefore, instead of scripts hard-coded to do various things, we depend on udev to create device nodes for us and then when we have the rootfs's device node, we mount and carry on. This helps to keep the time required in the initramfs as short as possible so that things like a five second boot aren't made impossible as a result of the very existence of an initramfs. It's likely that we'll grow some hooks for running arbitrary commands in the flow of the script, but it's worth trying to resist the urge as much as we can as hooks are guaranteed to be the path to slow-down.


Most of the initrd generation functionality in dracut is provided by a bunch of generator modules that are sourced by the main dracut script to install specific functionality into the initrd. They live in the modules subdirectory, and use functionality provided by dracut-functions to do their work. Some general rules for writing modules:
Most of the initrd generation functionality in dracut is provided by a bunch of generator modules that are sourced by the main dracut script to install specific functionality into the initrd. They live in the modules subdirectory, and use functionality provided by dracut-functions to do their work. Some general rules for writing modules:


* Use one of the inst family of functions to actually install files on to the initrd. They handle mangling the pathnames and (for binaries, scripts, and kernel modules) installing dependencies as appropriate so you do not have to.
* Use one of the inst family of functions to actually install files on to the initrd. They handle mangling the pathnames and (for binaries, scripts, and kernel modules) installing dependencies as appropriate so you do not have to.
* Scripts that end up on the initrd should be POSIX compliant. dracut will try to use /bin/dash as /bin/sh for the initrd if it is available, so you should install it on your system -- dash aims for strict POSIX compliance to the extent possible.
* Scripts that end up on the initrd should be POSIX compliant. Dracut will try to use /bin/dash as /bin/sh for the initrd if it is available, so you should install it on your system -- dash aims for strict POSIX compliance to the extent possible.
* Hooks MUST be POSIX compliant -- they are sourced by the init script, and having a bashism break your user's ability to boot really sucks.
* Hooks MUST be POSIX compliant -- they are sourced by the init script, and having a bashism break your user's ability to boot really sucks.
* Generator modules should have a two digit numeric prefix -- they run in ascending sort order. Anything in the 90-99 range is stuff that dracut relies on, so try not to break those hooks.
* Generator modules should have a two digit numeric prefix -- they run in ascending sort order. Anything in the 90-99 range is stuff that dracut relies on, so try not to break those hooks.
Line 16: Line 32:
* We have some breakpoints for debugging your hooks. If you pass 'break' as a kernel parameter, the initramfs will drop to a shell just before switching to a new root. You can pass 'break=hookpoint', and the initramfs will break just before hooks in that hookpoint run.  
* We have some breakpoints for debugging your hooks. If you pass 'break' as a kernel parameter, the initramfs will drop to a shell just before switching to a new root. You can pass 'break=hookpoint', and the initramfs will break just before hooks in that hookpoint run.  


Also, there is an attempt to keep things as distribution-agnostic as possible. Every distribution has their own tool here and it's not something which is really interesting to have separate across them. So contributions to help decrease the distro-dependencies are welcome.  
Also, there is an attempt to keep things as distribution-agnostic as possible. Every distribution has their own tool here and it's not something which is really interesting to have separate across them. So contributions to help decrease the distro dependencies are welcome.  


== Communicate ==
== Communicate ==


*[irc://irc.freenode.net/dracut Talk to other Dracut's members] on our IRC channel
*[irc://irc.freenode.net/dracut Talk to other Dracut users and developers] on our IRC channel
*[http://news.gmane.org/gmane.linux.kernel.initramfs/ Newsgroup] for the mailing list [mailto:majordomo@vger.kernel.org?body=subscribe%20initramfs Subscribe]
*[http://news.gmane.org/gmane.linux.kernel.initramfs/ Newsgroup] for the mailing list
*[mailto:majordomo@vger.kernel.org?body=subscribe%20initramfs Subscribe] to the mailing list


Please read [[Communicate/MailingListGuidelines|the mailing list guidelines]] before communicating on the list. See also [[How to use IRC]] if the IRC links don't work, or if you need more information.
Please read [[Communicate/MailingListGuidelines|the mailing list guidelines]] before communicating on the list. See also [[How to use IRC]] if the IRC links don't work, or if you need more information.


== Participating ==
== Using Dracut ==


Right now, most of the testing is done using a qemu/kvm guest and generating the initramfs on another box but the support is all present to build for the "running" machine.
See the dracut.8 man page: {{command|man dracut}}
For the former, you can boot the guest using qemu's -kernel and -initrd options.


Dracut exists and will build an image.
The command {{command|dracut}} exists and will build an image. It is command-line equivalent to most mkinitrd implementations and should be pretty straightforward to use.   
It is command-line equivalent to most mkinitrd implementations and should be pretty straight-forward to use.   


To use, just run dracut with an output file name and, optionally, a kernel version (it defaults to using the current).
To use, just run {{command|dracut}} with an output file name and, optionally, a kernel version (it defaults to using the current). The appropriate modules will be copied over and things should be good to go. If you'd like to customize the list of modules copied in, edit {{filename|/etc/dracut.conf}} and set <pre>dracutmodules="foo bar baz"</pre>
The appropriate modules will be copied over and things should be good to go. If you'd
like to customize the list of modules copied in, edit '''/etc/dracut.conf''' and set
<pre>dracutmodules="foo bar baz"</pre>


{{admon/note|Dracut calls functional components in modules.d "modules" while kernel modules are called "drivers".}}  
{{admon/note|Dracut calls functional components in modules.d ''modules'' while kernel modules are called ''drivers''.}}  


See also [https://sourceforge.net/apps/trac/dracut/wiki/TODO TODO].
See also [https://sourceforge.net/apps/trac/dracut/wiki/TODO TODO].
Right now, most of the testing is done using a qemu/kvm guest and generating the initramfs on another box but the support is all present to build for the "running" machine. For the former, you can boot the guest using qemu's -kernel and -initrd options.


== Getting started ==  
== Getting started ==  


To install on Fedora 11 and onwards do.  
To install on Fedora 11 and onwards run {{command|yum install dracut}}.


<pre>yum install dracut</pre>
To build from source start by downloading the latest tarball from [http://harald.fedorapeople.org/downloads/dracut/ here] then do:
<pre>
tar xf dracut-$version.tar.bz2
cd dracut-$version
make
su
make install sbindir=/sbin sysconfdir=/etc
</pre>


To build from source start by downloading the latest tar ball from here [http://harald.fedorapeople.org/downloads/dracut/ Dracut Latest] then do..
To generate a initramfs image, run:
<pre>
dracut <imagename> <kernel version>
</pre>


<pre>tar xzf dracut-$version.tar.bz2</pre>
To overwrite an existing image, run:
<pre>cd dracut-$version</pre>
<pre>
<pre>make install sbindir=/sbin sysconfdir=/etc</pre>
dracut -f <imagename> <kernel version>
</pre>


To generate a initramfs image, run..
To view the generated kernel command line use dracuts helper tool.
<pre>dracut-gencmdline</pre>


<pre> dracut <imagename> <kernel version> </pre>
Try to boot from that image by modifying {{filename|/etc/grub.conf}}. Be sure to have a fallback entry.


To overwrite an existing image do..
Additional Dracut kernel command line parameters can be found on the [[Dracut/Options|options]] page and in the man page.


<pre>dracut -f <imagename> <kernel version></pre>
When you have become familiar with Dracut take some time to look at the [[Dracut/Testing|Test Matrix]] and see if you can contribute to testing.
 
Try to boot from that image by modifying /etc/grub.conf. Be sure to have a
fallback entry.
 
Additional Dracut Kernel Command Line parameters can be found on the [[User:Johannbg/QA/Dracut/Options| options]] page and in the man page.
 
When you have gotten familiar with Dracut take your time to look at the [[User:Johannbg/QA/Dracut/Testing| Test Matrix]]


== Getting the Source ==
== Getting the Source ==


The primary methods of distributing the Dracut source are source RPMs in the [http://download.fedora.redhat.com/pub/fedora/linux/development/source/SRPMS/ Fedora development tree] and git. To access the current source code in in non-rpm format, you'll need to install git.
The primary methods of distributing the Dracut source are source RPMs in the [http://download.fedora.redhat.com/pub/fedora/linux/development/source/SRPMS/ Fedora development tree] and git. To access the current source code in in non-rpm format, you'll need to install git: {{command|yum install git}}.
 
yum install git


Note that several related packages will be installed as well.  After the git source code management tool has been installed, then you use anonymous git access to the Dracut repository.
Note that several related packages will be installed as well.  After the git source code management tool has been installed, then you use anonymous git access to the Dracut repository.
<pre>
git clone git://git.kernel.org/pub/scm/boot/dracut/dracut.git
</pre>
Once you've committed changes locally, you can push them with {{command|git push}}.


git clone git://dracut.git.sourceforge.net/gitroot/dracut #FIXME
If you would just like to browse the Dracut git repository via the web, then you can use [http://git.kernel.org/?p=boot/dracut/dracut.git Dracut gitweb].
 
If you have committer access to Dracut, then you will want to use the git+ssh access url. #FIXME
 
git clone git+ssh://dracut.git.sourceforge.net/gitroot/dracut #FIXME
 
git clone git://dracut.git.sourceforge.net/gitroot/dracut #FIXME
 
Once you've committed changes locally, you can push them with
 
git push
 
If you would just like to browse the Dracut git repository via the web, then please use one of the following [http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut Dracut git URLs] .
 
[http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut;a=summary Summary] [http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut;a=shortlog Shortlog] [http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut;a=log Log] [http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut;a=commit Commit] [http://dracut.git.sourceforge.net/git/gitweb.cgi?p=dracut;a=commitdiff CommitDiff]


== Reporting Problems ==
== Reporting Problems ==


Before filing a bug, please read up on [[User:Johannbg/QA/Dracut/Debugging| Debugging]], which will tell you how to fill out useful bug reports that will help us quickly solve your problem. Also take a lookt at [https://admin.fedoraproject.org/pkgdb/packages/bugs/dracut Dracut] or try searching [http://bugzilla.redhat.com Bugzilla]for other reports about your problem, as some bugs are often filed by several people.
Before [https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=dracut  filing a bug], please read up on [[Dracut/Debugging|debugging]], which will tell you how to fill out useful bug reports that will help us quickly solve your problem. Also take a look at [http://bugz.fedoraproject.org/dracut Dracut bugs] or try searching [http://bugzilla.redhat.com Bugzilla]for other reports about your problem, as some bugs are often filed by several people.


== Dracut Team ==
== Dracut Team ==
Line 101: Line 108:
In alphabetical order, the following people are the Dracut team and are responsible for the majority of commits.
In alphabetical order, the following people are the Dracut team and are responsible for the majority of commits.


*'''Andreas Thienemann'''  
*'''[[User:ixs|Andreas Thienemann]]'''  
*'''Bill Nottingham'''
*'''[[User:notting|Bill Nottingham]]'''
*'''Dave Jones'''
*'''[[DaveJones|Dave Jones]]'''
*'''David Dillow'''
*'''David Dillow'''
*'''Harald Hoyer'''
*'''[[User:Harald|Harald Hoyer]]'''
*'''Jeremy Katz'''
*'''[[User:katzj|Jeremy Katz]]'''
*'''Peter Jones'''
*'''[[PeterJones|Peter Jones]]'''
*'''Seewer Philippe'''
*'''Seewer Philippe'''
*'''Victor Lowther'''
*'''Victor Lowther'''
*'''Warren Togami'''
*'''[[User:Wtogami|Warren Togami]]'''

Latest revision as of 10:39, 25 July 2023


Dracut is an initramfs infrastructure. The project wiki is at https://github.com/dracutdevs/dracut/wiki (background information about the project's goals and aims can be found at Initrdrewrite). Unlike previous initramfs systems, Dracut aims to have as little as possible hard-coded into the initramfs.

This wiki can be incomplete. Please use the dracut.cmdline.7 (alias dracut.kernel.7) man page or point your browser at /usr/share/doc/dracut-*/dracut.html


New Kernel Command Line Parameters

Read the dracut.kernel.7 man page.

Quick Debugging Tips

  • add "rdshell" to the kernel command line and you are dropped to a shell
  • add "rdshell rdinitdebug" to the kernel command line and dracut commands are printed
  • you can inspect /init.log and run journalctl from the shell
  • mount /boot manually and copy over /init.log or the /run/log/journal files

Read More...

Technical details

With Dracut, the initramfs has one purpose in life - getting the rootfs mounted so that we can transition to the real rootfs. This is all driven by device availability. Therefore, instead of scripts hard-coded to do various things, we depend on udev to create device nodes for us and then when we have the rootfs's device node, we mount and carry on. This helps to keep the time required in the initramfs as short as possible so that things like a five second boot aren't made impossible as a result of the very existence of an initramfs. It's likely that we'll grow some hooks for running arbitrary commands in the flow of the script, but it's worth trying to resist the urge as much as we can as hooks are guaranteed to be the path to slow-down.

Most of the initrd generation functionality in dracut is provided by a bunch of generator modules that are sourced by the main dracut script to install specific functionality into the initrd. They live in the modules subdirectory, and use functionality provided by dracut-functions to do their work. Some general rules for writing modules:

  • Use one of the inst family of functions to actually install files on to the initrd. They handle mangling the pathnames and (for binaries, scripts, and kernel modules) installing dependencies as appropriate so you do not have to.
  • Scripts that end up on the initrd should be POSIX compliant. Dracut will try to use /bin/dash as /bin/sh for the initrd if it is available, so you should install it on your system -- dash aims for strict POSIX compliance to the extent possible.
  • Hooks MUST be POSIX compliant -- they are sourced by the init script, and having a bashism break your user's ability to boot really sucks.
  • Generator modules should have a two digit numeric prefix -- they run in ascending sort order. Anything in the 90-99 range is stuff that dracut relies on, so try not to break those hooks.
  • Generator modules and hooks must have a .sh extension.
  • We have some breakpoints for debugging your hooks. If you pass 'break' as a kernel parameter, the initramfs will drop to a shell just before switching to a new root. You can pass 'break=hookpoint', and the initramfs will break just before hooks in that hookpoint run.

Also, there is an attempt to keep things as distribution-agnostic as possible. Every distribution has their own tool here and it's not something which is really interesting to have separate across them. So contributions to help decrease the distro dependencies are welcome.

Communicate

Please read the mailing list guidelines before communicating on the list. See also How to use IRC if the IRC links don't work, or if you need more information.

Using Dracut

See the dracut.8 man page: man dracut

The command dracut exists and will build an image. It is command-line equivalent to most mkinitrd implementations and should be pretty straightforward to use.

To use, just run dracut with an output file name and, optionally, a kernel version (it defaults to using the current). The appropriate modules will be copied over and things should be good to go. If you'd like to customize the list of modules copied in, edit /etc/dracut.conf and set

dracutmodules="foo bar baz"
Dracut calls functional components in modules.d modules while kernel modules are called drivers.

See also TODO.

Right now, most of the testing is done using a qemu/kvm guest and generating the initramfs on another box but the support is all present to build for the "running" machine. For the former, you can boot the guest using qemu's -kernel and -initrd options.

Getting started

To install on Fedora 11 and onwards run yum install dracut.

To build from source start by downloading the latest tarball from here then do:

tar xf dracut-$version.tar.bz2
cd dracut-$version
make
su
make install sbindir=/sbin sysconfdir=/etc

To generate a initramfs image, run:

dracut <imagename> <kernel version>

To overwrite an existing image, run:

dracut -f <imagename> <kernel version>

To view the generated kernel command line use dracuts helper tool.

dracut-gencmdline

Try to boot from that image by modifying /etc/grub.conf. Be sure to have a fallback entry.

Additional Dracut kernel command line parameters can be found on the options page and in the man page.

When you have become familiar with Dracut take some time to look at the Test Matrix and see if you can contribute to testing.

Getting the Source

The primary methods of distributing the Dracut source are source RPMs in the Fedora development tree and git. To access the current source code in in non-rpm format, you'll need to install git: yum install git.

Note that several related packages will be installed as well. After the git source code management tool has been installed, then you use anonymous git access to the Dracut repository.

git clone git://git.kernel.org/pub/scm/boot/dracut/dracut.git

Once you've committed changes locally, you can push them with git push.

If you would just like to browse the Dracut git repository via the web, then you can use Dracut gitweb.

Reporting Problems

Before filing a bug, please read up on debugging, which will tell you how to fill out useful bug reports that will help us quickly solve your problem. Also take a look at Dracut bugs or try searching Bugzillafor other reports about your problem, as some bugs are often filed by several people.

Dracut Team

In alphabetical order, the following people are the Dracut team and are responsible for the majority of commits.