[RFC PATCH v3 09/10] Use lighttpd as a example how to add a dracut module

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---
.../dracut-example-lighttpd_0.1.bb | 26 ++++++++++
.../dracut-example-lighttpd/files/install.sh | 21 ++++++++
.../files/lighttpd.conf | 52 +++++++++++++++++++
.../files/lighttpd.service | 13 +++++
.../files/sysuser-lighttpd.conf | 3 ++
.../recipes-initramfs/images/isar-dracut.bb | 3 ++
6 files changed, 118 insertions(+)
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/dracut-example-lighttpd_0.1.bb
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/install.sh
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.conf
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.service
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/sysuser-lighttpd.conf

diff --git a/meta-isar/recipes-initramfs/dracut-example-lighttpd/dracut-example-lighttpd_0.1.bb b/meta-isar/recipes-initramfs/dracut-example-lighttpd/dracut-example-lighttpd_0.1.bb
new file mode 100644
index 00000000..7895e689
--- /dev/null
+++ b/meta-isar/recipes-initramfs/dracut-example-lighttpd/dracut-example-lighttpd_0.1.bb
@@ -0,0 +1,26 @@
+#
+# Copyright (c) Siemens AG, 2025
+#
+# Authors:
+# Quirin Gylstorff <quirin.g...@siemens.com>
+#
+# SPDX-License-Identifier: MIT
+#
+require recipes-initramfs/dracut-module/dracut-module.inc
+
+DEBIAN_DEPENDS:append = ",lighttpd"
+SRC_URI += "file://install.sh \
+ file://lighttpd.conf \
+ file://lighttpd.service \
+ file://sysuser-lighttpd.conf \
+ "
+DRACUT_REQUIRED_BINARIES = "lighttpd"
+DRACUT_MODULE_DEPENDENCIES = "systemd-network-management"
+
+do_install[cleandirs] += "${D}/usr/lib/sysusers.d/"
+do_install:append() {
+ install -m 666 ${WORKDIR}/lighttpd.conf ${DRACUT_MODULE_PATH}
+ install -m 666 ${WORKDIR}/lighttpd.service ${DRACUT_MODULE_PATH}
+ install -m 666 ${WORKDIR}/sysuser-lighttpd.conf ${D}/usr/lib/sysusers.d/lighttpd.conf
+}
+
diff --git a/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/install.sh b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/install.sh
new file mode 100644
index 00000000..e7e50ad4
--- /dev/null
+++ b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/install.sh
@@ -0,0 +1,21 @@
+install() {
+ inst_binary /usr/sbin/lighttpd
+ inst_binary /usr/sbin/lighttpd-angel
+ inst_binary /usr/sbin/lighttpd-disable-mod
+ inst_binary /usr/sbin/lighttpd-enable-mod
+ inst_multiple -o /usr/lib/lighttpd/*.so
+ inst_multiple -o /usr/share/lighttpd/*
+ inst_simple "${moddir}/lighttpd.service" "$systemdsystemunitdir/lighttpd.service"
+ mkdir -p -m 0700 "$initdir/etc/lighttpd/"
+ mkdir -p -m 0700 "$initdir/var/cache/lighttpd/compress"
+ mkdir -p -m 0700 "$initdir/var/cache/lighttpd/uploads"
+ mkdir -p -m 0700 "$initdir/var/log/lighttpd/"
+ mkdir -p -m 0755 "$initdir/var/www/html"
+ /usr/bin/install -m 0644 /usr/share/lighttpd/index.html "$initdir/var/www/html/index.html"
+ touch "$moddir"/error.log
+ /usr/bin/install -m 0644 "$moddir"/error.log "$initdir/var/log/lighttpd/error.log"
+ chown -R www-data:www-data "$initdir/var/log/lighttpd/"
+ inst_simple "${moddir}/lighttpd.conf" /etc/lighttpd/lighttpd.conf
+ inst_sysusers lighttpd.conf
+ systemctl -q --root "$initdir" enable lighttpd
+}
diff --git a/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.conf b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.conf
new file mode 100644
index 00000000..3a1bb351
--- /dev/null
+++ b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.conf
@@ -0,0 +1,52 @@
+server.modules = (
+ "mod_indexfile",
+ "mod_access",
+ "mod_alias",
+ "mod_redirect",
+)
+
+server.document-root = "/var/www/html"
+server.upload-dirs = ( "/var/cache/lighttpd/uploads" )
+server.errorlog = "/var/log/lighttpd/error.log"
+server.pid-file = "/run/lighttpd.pid"
+server.username = "www-data"
+server.groupname = "www-data"
+server.port = 80
+
+# features
+#https://redmine.lighttpd.net/projects/lighttpd/wiki/Server_feature-flagsDetails
+server.feature-flags += ("server.h2proto" => "enable")
+server.feature-flags += ("server.h2c" => "enable")
+server.feature-flags += ("server.graceful-shutdown-timeout" => 5)
+#server.feature-flags += ("server.graceful-restart-bg" => "enable")
+
+# strict parsing and normalization of URL for consistency and security
+# https://redmine.lighttpd.net/projects/lighttpd/wiki/Server_http-parseoptsDetails
+# (might need to explicitly set "url-path-2f-decode" = "disable"
+# if a specific application is encoding URLs inside url-path)
+server.http-parseopts = (
+ "header-strict" => "enable",# default
+ "host-strict" => "enable",# default
+ "host-normalize" => "enable",# default
+ "url-normalize-unreserved"=> "enable",# recommended highly
+ "url-normalize-required" => "enable",# recommended
+ "url-ctrls-reject" => "enable",# recommended
+ "url-path-2f-decode" => "enable",# recommended highly (unless breaks app)
+ #"url-path-2f-reject" => "enable",
+ "url-path-dotseg-remove" => "enable",# recommended highly (unless breaks app)
+ #"url-path-dotseg-reject" => "enable",
+ #"url-query-20-plus" => "enable",# consistency in query string
+)
+
+index-file.names = ( "index.php", "index.html" )
+url.access-deny = ( "~", ".inc" )
+static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
+
+# default listening port for IPv6 falls back to the IPv4 port
+include "/etc/lighttpd/conf-enabled/*.conf"
+
+#server.compat-module-load = "disable"
+server.modules += (
+ "mod_dirlisting",
+ "mod_staticfile",
+)
diff --git a/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.service b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.service
new file mode 100644
index 00000000..da8c9033
--- /dev/null
+++ b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.service
@@ -0,0 +1,13 @@
+[Unit]
+Description=Lighttpd Daemon
+DefaultDependencies=no
+
+[Service]
+Type=simple
+PIDFile=/run/lighttpd.pid
+ExecStartPre=/usr/sbin/lighttpd -tt -f /etc/lighttpd/lighttpd.conf
+ExecStart=/usr/sbin/lighttpd -D -f /etc/lighttpd/lighttpd.conf
+ExecReload=/bin/kill -USR1 $MAINPID
+Restart=on-failure
+[Install]
+WantedBy=sysinit.target
diff --git a/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/sysuser-lighttpd.conf b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/sysuser-lighttpd.conf
new file mode 100644
index 00000000..6507ccf3
--- /dev/null
+++ b/meta-isar/recipes-initramfs/dracut-example-lighttpd/files/sysuser-lighttpd.conf
@@ -0,0 +1,3 @@
+g www-data - -
+u www-data - - /var/www /usr/sbin/nologin
+
diff --git a/meta-isar/recipes-initramfs/images/isar-dracut.bb b/meta-isar/recipes-initramfs/images/isar-dracut.bb
index 226fdeaa..95739b12 100644
--- a/meta-isar/recipes-initramfs/images/isar-dracut.bb
+++ b/meta-isar/recipes-initramfs/images/isar-dracut.bb
@@ -14,4 +14,7 @@ INITRAMFS_PREINSTALL += " \

# Recipes that should be installed into the initramfs build rootfs.
INITRAMFS_INSTALL += " \
+ dracut-example-lighttpd \
"
+
+DRACUT_EXTRA_MODULES += "example-lighttpd"
--
2.51.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

.../recipes-initramfs/images/isar-dracut.bb | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
create mode 100644 meta-isar/recipes-initramfs/images/isar-dracut.bb

diff --git a/meta-isar/recipes-initramfs/images/isar-dracut.bb b/meta-isar/recipes-initramfs/images/isar-dracut.bb
new file mode 100644
index 00000000..226fdeaa
--- /dev/null
+++ b/meta-isar/recipes-initramfs/images/isar-dracut.bb
@@ -0,0 +1,17 @@
+# Example of a custom initramfs image recipe. The image will be deployed to
+#
+# build/tmp/deploy/images/${MACHINE}/isar-initramfs-${DISTRO}-${MACHINE}.initrd.img
+#
+# This software is a part of ISAR.
+
+inherit initrd-dracut
+
+# Debian packages that should be installed into the system for building the
+# initramfs. E.g. the cryptsetup package which contains initramfs scripts for
+# decrypting a root filesystem.
+INITRAMFS_PREINSTALL += " \
+ "
+
+# Recipes that should be installed into the initramfs build rootfs.
+INITRAMFS_INSTALL += " \
+ "
--
2.51.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

doc/user_manual.md | 51 ++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 47 insertions(+), 4 deletions(-)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 67f91973..a4707f0a 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -1680,10 +1680,11 @@ SRC_URI += "docker://debian;digest=sha256:f528891ab1aa484bf7233dbcc84f3c806c3e42
## Customize the initramfs

Isar supports the customization of initramfs images by providing an
-infrastructure for quickly creating hooks and by allowing to replace the
-Debian-generated image with a separately built one.
+infrastructure for quickly creating hooks in case of `initramfs-tools`
+or modules for `dracut` by allowing to replace the Debian-generated
+image with a separately built one.

-### Creating initramfs hooks
+### Creating initramfs-tools hooks

To create an initramfs hook that adds tools or modules to the image and may
also run custom scripts during boot, use the include file
@@ -1720,6 +1721,33 @@ initramfs.

See `initramfs-example` for an exemplary hook recipe.

+### Creating dracut modules
+
+To create a custom dracut module that adds tools, kernel-modules or services
+to the initrd, use the include file `recipes-initramfs/dracut-module/dracut-module.inc`.
+It is controlled by following variables:
+
+- `DRACUT_REQUIRED_BINARIES` defines the binaries required by the module.
+- `DRACUT_MODULE_DEPENDENCIES` defines dependencies to other dracut modules.
+- `DRACUT_MODULE_NO` defines the module number which prefixes the module name
+to define the execution order.The default is `50`.
+- `DRACUT_MODULE_NAME` the name of the module which is used to install the
+module in the initrd or as a dependency to other modules. It defaults to
+`${PN}` without the prefix `dracut-`.
+- `DRACUT_MODULE_PATH` contains the path to the installed module. It is set
+to `${D}/usr/lib/dracut/modules.d/${DRACUT_MODULE_NO}${DRACUT_MODULE_NAME}/`
+
+The `install()` function is added by storing the file `install.sh` in the
+files directory of the dracut module.
+
+Other files can by added to the module by coping them to the Module folder
+with:
+```bash
+install -m 666 ${WORKDIR}/lighttpd.service ${DRACUT_MODULE_PATH}
+```
+
+See `dracut-example-lighttpd` for an exemplary hook recipe.
+
### Creating an initramfs image aside the rootfs

To avoid shipping all tools and binaries needed to generate an initramfs, isar
@@ -1733,4 +1761,19 @@ self-built packages and `INITRAMFS_PREINSTALL` for prebuilt ones, analogously
to the respective `IMAGE_*` variables. Note that the kernel is automatically
added to `INITRAMFS_INSTALL` if `KERNEL_NAME` is set.

-See `isar-initramfs` for an example recipe.
+See `isar-initramfs` or `isar-dracut` for an example recipes.
+
+#### dracut config
+
+A dracut initramfs can be configured by the command line or a configuration file.
+The use configuration files is preferred:
+ - Debian provides dracut-config-* packages
+ - It is easier to upstream and to maintain.
+
+The configuration file can be chosen with the variable `DRACUT_CONFIG_PATH`. This variable
+contains the absolut path to the used configuration in the root file system.
+
+Still there are some use cases like debugging to add modules via the command line.
+For this the recipe meta/classes/initrd-dracut.bbclass provides the following options:
+ - `DRACUT_EXTRA_DRIVERS` add extra drivers to the dracut initrd
+ - `DRACUT_EXTRA_MODULES` add extra modules to the dracut initrd
--
2.51.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

Debian intends to change the default initrd generator from
initramfs-tools to dracut[1],[2].

This is a first draft to support multiple initrd generator in
ISAR. I tested it with bookworm and trixie.

Currently missing is the possibility to generate custom dracut initrd.
This will be added in a future revision of this patch set.

[1]: https://salsa.debian.org/kernel-team/meetings/-/wikis/20250730
[2]: https://meetbot.debian.net/debian-kernel/2025/debian-kernel.2025-08-06-19.00.log.html

Changes v3:
- drop initramfs patch
- add examples
- add user_manual section

Changes v2:
- extract the initramfs-cmd from the cmdline
- increase version of enable-fsck
- add function to print an error in case a invalid package is installed

Quirin Gylstorff (10):
add dracut to custom kernel builds
rootfs: Allow to overwrite the initramfs generation cmds
rootfs Add dracut to initramfs generator
initramfs: allow to set the generator command
Add class to generate custom dracut initramfs
rootfs: add flag to use dracut if it is not part of the package list
Add example dracut initramfs
Add dracut module helper
Use lighttpd as a example how to add a dracut module
user_manual: Add dracut for initramfs generation

doc/user_manual.md | 51 ++++++++++++++++--

.../dracut-example-lighttpd_0.1.bb | 26 ++++++++++
.../dracut-example-lighttpd/files/install.sh | 21 ++++++++
.../files/lighttpd.conf | 52 +++++++++++++++++++
.../files/lighttpd.service | 13 +++++
.../files/sysuser-lighttpd.conf | 3 ++

.../recipes-initramfs/images/isar-dracut.bb | 20 +++++++
meta/classes/initramfs.bbclass | 19 ++++++-
meta/classes/initrd-dracut.bbclass | 49 +++++++++++++++++
meta/classes/rootfs.bbclass | 17 ++++--
.../dracut-module/dracut-module.inc | 41 +++++++++++++++
.../dracut-module/files/module-setup.sh.tmpl | 20 +++++++
meta/recipes-kernel/linux/linux-custom.inc | 2 +-
13 files changed, 324 insertions(+), 10 deletions(-)

create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/dracut-example-lighttpd_0.1.bb
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/install.sh
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.conf
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/lighttpd.service
create mode 100644 meta-isar/recipes-initramfs/dracut-example-lighttpd/files/sysuser-lighttpd.conf

create mode 100644 meta-isar/recipes-initramfs/images/isar-dracut.bb
create mode 100644 meta/classes/initrd-dracut.bbclass
create mode 100644 meta/recipes-initramfs/dracut-module/dracut-module.inc
create mode 100644 meta/recipes-initramfs/dracut-module/files/module-setup.sh.tmpl

--
2.51.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

This adds a helper similar to initramfs-hook to generate a dracut
module.

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

.../dracut-module/dracut-module.inc | 41 +++++++++++++++++++
.../dracut-module/files/module-setup.sh.tmpl | 20 +++++++++
2 files changed, 61 insertions(+)

create mode 100644 meta/recipes-initramfs/dracut-module/dracut-module.inc
create mode 100644 meta/recipes-initramfs/dracut-module/files/module-setup.sh.tmpl

diff --git a/meta/recipes-initramfs/dracut-module/dracut-module.inc b/meta/recipes-initramfs/dracut-module/dracut-module.inc
new file mode 100644
index 00000000..54071105
--- /dev/null
+++ b/meta/recipes-initramfs/dracut-module/dracut-module.inc
@@ -0,0 +1,41 @@

+#
+# Copyright (c) Siemens AG, 2025
+#
+# Authors:
+# Quirin Gylstorff <quirin.g...@siemens.com>
+#
+# SPDX-License-Identifier: MIT
+#
+

+inherit dpkg-raw
+
+FILESPATH:append := ":${FILE_DIRNAME}/files"
+
+DPKG_ARCH = "all"
+
+DRACUT_MODULE_SETUP = "module-setup.sh"
+SRC_URI += "file://${DRACUT_MODULE_SETUP}.tmpl"
+
+DRACUT_REQUIRED_BINARIES = ""
+DRACUT_MODULE_DEPENDENCIES = ""
+DRACUT_MODULE_NO ??= "50"
+DRACUT_MODULE_NAME ?= "${@ d.getVar('PN')[7:] if d.getVar('PN').startswith('dracut-') else d.getVAR('PN')}"
+
+TEMPLATE_FILES:append = " \
+ ${DRACUT_MODULE_SETUP}.tmpl \
+ "
+
+TEMPLATE_VARS:append = " \
+ DRACUT_REQUIRED_BINARIES \
+ DRACUT_MODULE_DEPENDENCIES \
+ "
+DEBIAN_DEPENDS = "dracut-core"
+DRACUT_MODULE_PATH = "${D}/usr/lib/dracut/modules.d/${DRACUT_MODULE_NO}${DRACUT_MODULE_NAME}/"
+do_install[cleandirs] += "${DRACUT_MODULE_PATH}"
+do_install:append() {
+ install -m 770 ${WORKDIR}/${DRACUT_MODULE_SETUP} ${DRACUT_MODULE_PATH}
+ if [ -f ${WORKDIR}/install.sh ]; then
+ cat ${WORKDIR}/install.sh >> ${DRACUT_MODULE_PATH}/${DRACUT_MODULE_SETUP}
+ fi
+}
+
diff --git a/meta/recipes-initramfs/dracut-module/files/module-setup.sh.tmpl b/meta/recipes-initramfs/dracut-module/files/module-setup.sh.tmpl
new file mode 100644
index 00000000..46477cf4
--- /dev/null
+++ b/meta/recipes-initramfs/dracut-module/files/module-setup.sh.tmpl
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# called by dracut
+check() {
+
+ # If the binary(s) requirements are not fulfilled the module can't be installed.
+ require_binaries \
+ ${DRACUT_REQUIRED_BINARIES} \
+ || return 1
+
+ return 0
+
+}
+# Module dependency requirements.
+depends() {
+ echo "${DRACUT_MODULE_DEPENDENCIES}"
+ return 0
+
+}
+
--
2.51.0

[Quirin Gylstorff]

From: Quirin Gylstorff <quirin.g...@siemens.com>

This is intend for version where dracut is the default initramfs where
dracut is part of the dependency tree and not explicit requested.

Signed-off-by: Quirin Gylstorff <quirin.g...@siemens.com>
---

meta/classes/rootfs.bbclass | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/meta/classes/rootfs.bbclass b/meta/classes/rootfs.bbclass
index a9f174d9..a27c2a99 100644
--- a/meta/classes/rootfs.bbclass
+++ b/meta/classes/rootfs.bbclass
@@ -6,9 +6,10 @@ inherit deb-dl-dir
ROOTFS_ARCH ?= "${DISTRO_ARCH}"
ROOTFS_DISTRO ?= "${DISTRO}"

+ROOTFS_USE_DRACUT ??= ""
def initramfs_generator_cmdline(d):
rootfs_packages = d.getVar('ROOTFS_PACKAGES') or ''
- if 'dracut' in rootfs_packages:
+ if 'dracut' in rootfs_packages or bb.utils.to_boolean(d.getVar('ROOTFS_USE_DRACUT')):
return "dracut --force /initrd.img \"$kernel_version\""
return "update-initramfs -u -v -k \"$kernel_version\""

--
2.51.0