From 888e026aa929544b3a93817432d2f1cba65d7a13 Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Jul 30 2024 06:58:13 +0000
Subject: systemd: Add section on testing the dracut backport


---

diff --git a/docs/internal/systemd.md b/docs/internal/systemd.md
index c1cdc67..546e05d 100644
--- a/docs/internal/systemd.md
+++ b/docs/internal/systemd.md
@@ -175,16 +175,18 @@ sudo mkosi qemu
 ```
 
 If the boot succeeds and we end up in a root shell, great! Otherwise, we'll need
-to debug. If the boot failed this is likely due to SELinux denials. We can start
-by booting with SELinux in permissive mode:
+to debug. If the boot failed this is either due to SELinux denials or because
+dracut hasn't been updated to accomodate changes in newer systemd releases. We
+can start by booting with SELinux in permissive mode:
 
 ```shell
 sudo mkosi --kernel-command-line-extra=enforcing=0 qemu
 ```
 
-This should get you into a root shell. Regardless of whether we're in enforcing
-or permissive mode, the first thing to check is whether there's any SELinux
-denials:
+If this still doesn't get you into a root shell, the problem might lie with
+dracut, see the next section for more details. Otherwise, regardless of whether
+we're in enforcing or permissive mode, the first thing to check is whether
+there's any SELinux denials:
 
 ```shell
 journalctl -t audit -g AVC
@@ -270,6 +272,65 @@ SELinux denials in the virtual machine. Now it's a matter of waiting and working
 with the policy maintainers to fix the denials, and backport the newer version
 of selinux-policy once it is released in Fedora Rawhide (see above steps).
 
+## Testing the dracut backport with the systemd-releng repository
+
+Because new systemd releases often require changes in dracut as well, we also
+maintain a backport of dracut from Fedora Rawhide. Every time a change in a new
+release of systemd requires a corresponding change in dracut, a newer release of
+dracut should be backported first before doing a new release of systemd in the
+Hyperscale SIG.
+
+To backport a new version of dracut from Fedora Rawhide, you can run the
+following steps:
+
+```shell
+git clone https://git.centos.org/rpms/dracut.git
+cd dracut
+git remote add fedora https://src.fedoraproject.org/rpms/dracut
+git fetch rawhide
+git checkout rawhide
+fedpkg sources
+git checkout c<centos-release>s-sig-hyperscale
+git merge fedora/rawhide
+```
+
+We can then build the new dracut rpms with mock:
+
+```shell
+mock -r centos-stream-hyperscale-<centos-release>-x86_64 --sources . --spec dracut.spec
+```
+
+And finally test whether the image built with mkosi boots with the new version
+of dracut as follows:
+
+```shell
+cd <path-to-systemd-releng>
+sudo mkosi \
+  --profile=hyperscale \
+  --release=<centos-release> \
+  --volatile-package-directory=<path-to-systemd-rpms-dir> \
+  --volatile-package-directory=/var/lib/mock/centos-stream-hyperscale-<centos-release>-x86_64/result \
+  --force \
+  qemu
+```
+
+If everything works as expected, we can build and tag the new dracut version in
+CBS:
+
+```shell
+cd <path-to-dracut>
+<path-to-centos-git-common>/lookaside_upload_sig -f <source.tar.gz> -n dracut
+git checkout c<centos-release>s-sig-hyperscale
+git push
+cbs build hyperscale<centos-release>s-packages-main-el<centos-release>s git+https://git.centos.org/rpms/dracut.git#(git rev-parse HEAD)
+cbs tag-build hyperscale<centos-release>s-packages-main-release dracut-<version+release>.hs.el<centos-release>
+```
+
+If there are still issues with booting, you'll need to debug the issue and
+resolve it together with upstream. Be sure to also extend this section with any
+useful debugging information to make the process easier for the next
+contributor.
+
 ## Testing upgrades from stock CentOS Stream with the systemd-releng repository
 
 To test upgrades from stock CentOS Stream to CentOS Stream + Hyperscale, you