diff --git a/HACKING b/HACKING deleted file mode 100644 index 3c3a52da..00000000 --- a/HACKING +++ /dev/null @@ -1,23 +0,0 @@ -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. - -dracut exists and will build an image. 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). 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" - -Note that dracut calls functional components in modules.d "modules" -while kernel modules are called "drivers". - -Requirements: -* udev -* nfs module: nfs daemon and rpc helper -* iscsi: iscsi diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 00000000..dbd2327d --- /dev/null +++ b/HACKING.md @@ -0,0 +1,248 @@ +# Dracut Developer Guidelines + +## git + +Currently dracut lives on github.com and kernel.org. + +* https://github.com/dracutdevs/dracut.git +* https://git.kernel.org/pub/scm/boot/dracut/dracut.git + +Pull requests should be filed preferably on github nowadays. + +### Commit Messages + +Commit messages should answer these questions: + +* What?: a short summary of what you changed in the subject line. +* Why?: what the intended outcome of the change is (arguably the most important piece of information that should go into a message). +* How?: if multiple approaches for achieving your goal were available, you also want to explain why you chose the used implementation strategy. + Note that you should not explain how your change achieves your goal in your commit message. + That should be obvious from the code itself. + If you cannot achieve that clarity with the used programming language, use comments within the code instead. + +The commit message is primarily the place for documenting the why. + +Commit message titles should follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +Format is `[optional scope]: `, where `type` is one of: + +* fix: A bug fix +* feat: A new feature +* perf: A code change that improves performance +* refactor: A code change that neither fixes a bug nor adds a feature +* style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +* test: Adding missing tests or correcting existing tests +* docs: Documentation only changes +* revert: Reverts a previous commit +* chore: Other changes that don't modify src or test files +* build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) +* ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) + +`scope` should be the module name (without numbers) or: + +* cli: for the dracut command line interface +* rt: for the dracut initramfs runtime logic +* functions: for general purpose dracut functions + +Commit messages are checked with [Commisery](https://github.com/tomtom-international/commisery). + +## Writing modules + +Some general rules for writing modules: + +* Use one of the inst family of functions to actually install files + on to the initramfs. 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 initramfs should be POSIX compliant. dracut + will try to use /bin/dash as /bin/sh for the initramfs 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. +* Hooks must have a .sh extension. +* Generator modules are described in more detail later on. +* We have some breakpoints for debugging your hooks. If you pass 'rdbreak' + as a kernel parameter, the initramfs will drop to a shell just before + switching to a new root. You can pass 'rdbreak=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. + +Most of the functionality that dracut implements are actually implemented +by dracut modules. dracut modules live in modules.d, and have the following +structure: + +``` +dracut_install_dir/modules.d/ + 00modname/ + module-setup.sh + check + +``` + +`00modname`: The name of the module prefixed by a two-digit numeric sort code. + The numeric code must be present and in the range of 00 - 99. + Modules with lower numbers are installed first. This is important + because the dracut install functions (which install files onto + the initrd) refuse to overwrite already installed files. This makes + it easy for an earlier module to override the functionality of a + later module, so that you can have a distro or system specific + module override or modify the functionality of a generic module + without having to patch the more generic module. + +`module-setup.sh`: + dracut sources this script to install the functionality that a + module implements onto the initrd. For the most part, this amounts + to copying files from the host system onto the initrd in a controlled + manner. + +`install()`: + This function of module-setup.sh is called to install all + non-kernel files. dracut supplies several install functions that are + specialized for different file types. Browse through dracut-functions + fore more details. dracut also provides a $moddir variable if you + need to install a file from the module directory, such as an initrd + hook, a udev rule, or a specialized executable. + +`installkernel()`: + This function of module-setup.sh is called to install all + kernel related files. + + +`check()`: + dracut calls this function to check and see if a module can be installed + on the initrd. + + When called without options, check should check to make sure that + any files it needs to install into the initrd from the host system + are present. It should exit with a 0 if they are, and a 1 if they are + not. + + When called with $hostonly set, it should perform the same check + that it would without it set, and it should also check to see if the + functionality the module implements is being used on the host system. + For example, if this module handles installing support for LUKS + encrypted volumes, it should return 0 if all the tools to handle + encrpted volumes are available and the host system has the root + partition on an encrypted volume, 1 otherwise. + +`depends()`: + This function should output a list of dracut modules + that it relies upon. An example would be the nfs and iscsi modules, + which rely on the network module to detect and configure network + interfaces. + +Any other files in the module will not be touched by dracut directly. + +You are encouraged to provide a README that describes what the module is for. + + +### Hooks + +init has the following hook points to inject scripts: + +`/lib/dracut/hooks/cmdline/*.sh` + scripts for command line parsing + +`/lib/dracut/hooks/pre-udev/*.sh` + scripts to run before udev is started + +`/lib/dracut/hooks/pre-trigger/*.sh` + scripts to run before the main udev trigger is pulled + +`/lib/dracut/hooks/initqueue/*.sh` + runs in parallel to the udev trigger + Udev events can add scripts here with /sbin/initqueue. + If /sbin/initqueue is called with the "--onetime" option, the script + will be removed after it was run. + If /lib/dracut/hooks/initqueue/work is created and udev >= 143 then + this loop can process the jobs in parallel to the udevtrigger. + If the udev queue is empty and no root device is found or no root + filesystem was mounted, the user will be dropped to a shell after + a timeout. + Scripts can remove themselves from the initqueue by "rm $job". + +`/lib/dracut/hooks/pre-mount/*.sh` + scripts to run before the root filesystem is mounted + Network filesystems like NFS that do not use device files are an + exception. Root can be mounted already at this point. + +`/lib/dracut/hooks/mount/*.sh` + scripts to mount the root filesystem + If the udev queue is empty and no root device is found or no root + filesystem was mounted, the user will be dropped to a shell after + a timeout. + +`/lib/dracut/hooks/pre-pivot/*.sh` + scripts to run before latter initramfs cleanups + +`/lib/dracut/hooks/cleanup/*.sh` + scripts to run before the real init is executed and the initramfs + disappears + All processes started before should be killed here. + + +## Testsuite + +For the testsuite to work, you will have to install at least the following software packages: +``` +dash \ +asciidoc \ +mdadm \ +lvm2 \ +dmraid \ +cryptsetup \ +nfs-utils \ +nbd \ +dhcp-server \ +scsi-target-utils \ +iscsi-initiator-utils \ +strace \ +syslinux \ +python-imgcreate \ +genisoimage \ +btrfs-progs \ +kmod-devel \ +gcc \ +bzip2 \ +xz \ +tar \ +wget \ +rpm-build \ +${NULL} +``` + +How to run the testsuite: + +``` +$ sudo make clean check +``` + +in verbose mode: +``` +$ sudo make V=1 clean check +``` + +only specific test: +``` +$ sudo make TESTS="01 20 40" clean check +``` +only runs the 01, 20 and 40 tests. + +debug a specific test case: +``` +$ cd TEST-01-BASIC +$ sudo make clean setup run +``` +... change some kernel parameters ... +``` +$ sudo make run +``` +to run the test without doing the setup diff --git a/README.md b/README.md index 2c08b7b3..251f7d35 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ dracut dracut is an event driven initramfs infrastructure. -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](.github/CODE_OF_CONDUCT.md) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](.github/CODE_OF_CONDUCT.md) [![Build Status](https://travis-ci.org/dracutdevs/dracut.svg?branch=master)](https://travis-ci.org/dracutdevs/dracut) [![Fedora-31](https://github.com/dracutdevs/dracut/workflows/Fedora-31/badge.svg?branch=master)](https://github.com/dracutdevs/dracut/actions?query=workflow%3AFedora-31) [![Fedora-32](https://github.com/dracutdevs/dracut/workflows/Fedora-32/badge.svg?branch=master)](https://github.com/dracutdevs/dracut/actions?query=workflow%3AFedora-32) @@ -29,32 +29,6 @@ specific functionality into the initramfs. They live in the modules.d 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 initramfs. 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 initramfs should be POSIX compliant. dracut - will try to use /bin/dash as /bin/sh for the initramfs 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. - * Hooks must have a .sh extension. - * Generator modules are described in more detail in README.modules. - * We have some breakpoints for debugging your hooks. If you pass 'rdbreak' - as a kernel parameter, the initramfs will drop to a shell just before - switching to a new root. You can pass 'rdbreak=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. - Currently dracut lives on github.com and kernel.org. The tarballs can be found here: @@ -62,15 +36,7 @@ The tarballs can be found here: ftp://ftp.kernel.org/pub/linux/utils/boot/dracut/ Git: - git://git.kernel.org/pub/scm/boot/dracut/dracut.git - http://git.kernel.org/pub/scm/boot/dracut/dracut.git - https://git.kernel.org/pub/scm/boot/dracut/dracut.git - - git@github.com:dracutdevs/dracut.git - -Git Web: - https://github.com/dracutdevs/dracut.git - + https://github.com/dracutdevs/dracut.git http://git.kernel.org/?p=boot/dracut/dracut.git Project Documentation: @@ -79,8 +45,8 @@ Project Documentation: Project Wiki: http://dracut.wiki.kernel.org -See the TODO file for things which still need to be done and HACKING for -some instructions on how to get started. There is also a mailing list +See the github issue tracker for things which still need to be done and HACKING.md +for some instructions on how to get started. There is also a mailing list that is being used for the discussion -- initramfs@vger.kernel.org. It is a typical vger list, send mail to majordomo@vger.kernel.org with body of 'subscribe initramfs email@host.com' diff --git a/README.modules b/README.modules deleted file mode 100644 index a50bed59..00000000 --- a/README.modules +++ /dev/null @@ -1,112 +0,0 @@ -Most of the functionality that dracut implements are actually implemented -by dracut modules. dracut modules live in modules.d, and have the following -structure: - -dracut_install_dir/modules.d/ - 00modname/ - module-setup.sh - check - - -00modname: The name of the module prefixed by a two-digit numeric sort code. - The numeric code must be present and in the range of 00 - 99. - Modules with lower numbers are installed first. This is important - because the dracut install functions (which install files onto - the initrd) refuse to overwrite already installed files. This makes - it easy for an earlier module to override the functionality of a - later module, so that you can have a distro or system specific - module override or modify the functionality of a generic module - without having to patch the more generic module. - -module-setup.sh: - dracut sources this script to install the functionality that a - module implements onto the initrd. For the most part, this amounts - to copying files from the host system onto the initrd in a controlled - manner. - -install(): - This function of module-setup.sh is called to install all - non-kernel files. dracut supplies several install functions that are - specialized for different file types. Browse through dracut-functions - fore more details. dracut also provides a $moddir variable if you - need to install a file from the module directory, such as an initrd - hook, a udev rule, or a specialized executable. - -installkernel(): - This function of module-setup.sh is called to install all - kernel related files. - - -check(): - dracut calls this function to check and see if a module can be installed - on the initrd. - - When called without options, check should check to make sure that - any files it needs to install into the initrd from the host system - are present. It should exit with a 0 if they are, and a 1 if they are - not. - - When called with $hostonly set, it should perform the same check - that it would without it set, and it should also check to see if the - functionality the module implements is being used on the host system. - For example, if this module handles installing support for LUKS - encrypted volumes, it should return 0 if all the tools to handle - encrpted volumes are available and the host system has the root - partition on an encrypted volume, 1 otherwise. - -depends(): - This function should output a list of dracut modules - that it relies upon. An example would be the nfs and iscsi modules, - which rely on the network module to detect and configure network - interfaces. - -Any other files in the module will not be touched by dracut directly. - -You are encouraged to provide a README that describes what the module is for. - - -HOOKS -===== - -init has the following hook points to inject scripts: - -/lib/dracut/hooks/cmdline/*.sh - scripts for command line parsing - -/lib/dracut/hooks/pre-udev/*.sh - scripts to run before udev is started - -/lib/dracut/hooks/pre-trigger/*.sh - scripts to run before the main udev trigger is pulled - -/lib/dracut/hooks/initqueue/*.sh - runs in parallel to the udev trigger - Udev events can add scripts here with /sbin/initqueue. - If /sbin/initqueue is called with the "--onetime" option, the script - will be removed after it was run. - If /lib/dracut/hooks/initqueue/work is created and udev >= 143 then - this loop can process the jobs in parallel to the udevtrigger. - If the udev queue is empty and no root device is found or no root - filesystem was mounted, the user will be dropped to a shell after - a timeout. - Scripts can remove themselves from the initqueue by "rm $job". - -/lib/dracut/hooks/pre-mount/*.sh - scripts to run before the root filesystem is mounted - Network filesystems like NFS that do not use device files are an - exception. Root can be mounted already at this point. - -/lib/dracut/hooks/mount/*.sh - scripts to mount the root filesystem - If the udev queue is empty and no root device is found or no root - filesystem was mounted, the user will be dropped to a shell after - a timeout. - -/lib/dracut/hooks/pre-pivot/*.sh - scripts to run before latter initramfs cleanups - -/lib/dracut/hooks/cleanup/*.sh - scripts to run before the real init is executed and the initramfs - disappears - All processes started before should be killed here. - diff --git a/README.testsuite b/README.testsuite deleted file mode 100644 index de6c7b8c..00000000 --- a/README.testsuite +++ /dev/null @@ -1,45 +0,0 @@ -For the testsuite to work, you will have to install at least the following software packages: -dash \ -asciidoc \ -mdadm \ -lvm2 \ -dmraid \ -cryptsetup \ -nfs-utils \ -nbd \ -dhcp-server \ -scsi-target-utils \ -iscsi-initiator-utils \ -strace \ -syslinux \ -python-imgcreate \ -genisoimage \ -btrfs-progs \ -kmod-devel \ -gcc \ -bzip2 \ -xz \ -tar \ -wget \ -rpm-build \ -${NULL} - -TEST-04-FULL-SYSTEMD: systemd >= 187 - -How to run the testsuite: - -$ sudo make clean check - -in verbose mode: -$ sudo make V=1 clean check - -only specific test: -$ sudo make TESTS="01 20 40" clean check -only runs the 01, 20 and 40 tests. - -debug a specific test case: -$ cd TEST-01-BASIC -$ sudo make clean setup run -... change some kernel parameters ... -$ sudo make run -to run the test without doing the setup diff --git a/dracut.spec b/dracut.spec index e89a9873..d1f46c67 100644 --- a/dracut.spec +++ b/dracut.spec @@ -280,7 +280,7 @@ echo 'dracut_rescue_image="yes"' > $RPM_BUILD_ROOT%{dracutlibdir}/dracut.conf.d/ %files %if %{with doc} -%doc README.md HACKING TODO AUTHORS NEWS dracut.html dracut.png dracut.svg +%doc README.md HACKING.md TODO AUTHORS NEWS dracut.html dracut.png dracut.svg %endif %{!?_licensedir:%global license %%doc} %license COPYING lgpl-2.1.txt