README.md

   1 dracut
   2 ====
   3
   4 dracut is an event driven initramfs infrastructure.
   5
   6 [![Build Status](https://travis-ci.org/dracutdevs/dracut.svg?branch=master)](https://travis-ci.org/dracutdevs/dracut)
   7 ![Fedora-30](https://github.com/dracutdevs/dracut/workflows/Fedora-30/badge.svg?branch=master)
   8 ![Fedora-31](https://github.com/dracutdevs/dracut/workflows/Fedora-31/badge.svg?branch=master)
   9
  10 dracut (the tool) is used to create an initramfs image by copying tools
  11 and files from an installed system and combining it with the
  12 dracut framework, usually found in /usr/lib/dracut/modules.d.
  13
  14 Unlike existing initramfs's, this is an attempt at having as little as
  15 possible hard-coded into the initramfs as possible.  The initramfs has
  16 (basically) one purpose in life -- getting the rootfs mounted so that
  17 we can transition to the real rootfs.  This is all driven off of
  18 device availability.  Therefore, instead of scripts hard-coded to do
  19 various things, we depend on udev to create device nodes for us and
  20 then when we have the rootfs's device node, we mount and carry on.
  21 This helps to keep the time required in the initramfs as little as
  22 possible so that things like a 5 second boot aren't made impossible as
  23 a result of the very existence of an initramfs.  It's likely that
  24 we'll grow some hooks for running arbitrary commands in the flow of
  25 the script, but it's worth trying to resist the urge as much as we can
  26 as hooks are guaranteed to be the path to slow-down.
  27
  28 Most of the initramfs generation functionality in dracut is provided by a bunch
  29 of generator modules that are sourced by the main dracut script to install
  30 specific functionality into the initramfs.  They live in the modules.d
  31 subdirectory, and use functionality provided by dracut-functions to do their
  32 work.
  33
  34 Some general rules for writing modules:
  35  * Use one of the inst family of functions to actually install files
  36    on to the initramfs.  They handle mangling the pathnames and (for binaries,
  37    scripts, and kernel modules) installing dependencies as appropriate so
  38    you do not have to.
  39  * Scripts that end up on the initramfs should be POSIX compliant. dracut
  40    will try to use /bin/dash as /bin/sh for the initramfs if it is available,
  41    so you should install it on your system -- dash aims for strict POSIX
  42    compliance to the extent possible.
  43  * Hooks MUST be POSIX compliant -- they are sourced by the init script,
  44    and having a bashism break your user's ability to boot really sucks.
  45  * Generator modules should have a two digit numeric prefix -- they run in
  46    ascending sort order. Anything in the 90-99 range is stuff that dracut
  47    relies on, so try not to break those hooks.
  48  * Hooks must have a .sh extension.
  49  * Generator modules are described in more detail in README.modules.
  50  * We have some breakpoints for debugging your hooks.  If you pass 'rdbreak'
  51    as a kernel parameter, the initramfs will drop to a shell just before
  52    switching to a new root. You can pass 'rdbreak=hookpoint', and the initramfs
  53    will break just before hooks in that hookpoint run.
  54
  55 Also, there is an attempt to keep things as distribution-agnostic as
  56 possible.  Every distribution has their own tool here and it's not
  57 something which is really interesting to have separate across them.
  58 So contributions to help decrease the distro-dependencies are welcome.
  59
  60 Currently dracut lives on github.com and kernel.org.
  61
  62 The tarballs can be found here:
  63         http://www.kernel.org/pub/linux/utils/boot/dracut/
  64         ftp://ftp.kernel.org/pub/linux/utils/boot/dracut/
  65
  66 Git:
  67         git://git.kernel.org/pub/scm/boot/dracut/dracut.git
  68         http://git.kernel.org/pub/scm/boot/dracut/dracut.git
  69         https://git.kernel.org/pub/scm/boot/dracut/dracut.git
  70
  71         git@github.com:dracutdevs/dracut.git
  72
  73 Git Web:
  74         https://github.com/dracutdevs/dracut.git
  75
  76         http://git.kernel.org/?p=boot/dracut/dracut.git
  77
  78 Project Documentation:
  79         http://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html
  80
  81 Project Wiki:
  82         http://dracut.wiki.kernel.org
  83
  84 See the TODO file for things which still need to be done and HACKING for
  85 some instructions on how to get started.  There is also a mailing list
  86 that is being used for the discussion -- initramfs@vger.kernel.org.
  87 It is a typical vger list, send mail to majordomo@vger.kernel.org with body
  88 of 'subscribe initramfs email@host.com'
  89
  90
  91 Licensed under the GPLv2