desultory · truffle0 · Jul 11, 2025 · Jul 12, 2025 · Feb 9, 2025 · Feb 9, 2025
diff --git a/docs/bootloader_config.md b/docs/bootloader_config.md
@@ -24,6 +24,9 @@ The `build_dir`can be embedded into the Linux kernel with:
 CONFIG_INITRAMFS_SOURCE="/tmp/initramfs"
 ```
 
+Take care to set `make_nodes = true` to create `/dev/console` in the build dir (instead of in the cpio when packing it).
+The console device node file is required in builtin initrds.
+
 A CPIO file can be embedded into the Linux kernel with: 
 
 ```

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -41,7 +41,7 @@ Modules write to a shared config dict that is accessible by other modules.
 * `build_dir` (initramfs_build) If relative, it will be placed under `tmpdir`, defines the build directory.
 * `random_build_dir` (false) Adds a uuid to the end of the build dir name when true.
 * `build_logging` (false) Enables additional logging during the build process.
-* `make_nodes` (false) Create real device nodes in the build dir. 
+* `make_nodes` (false) Create real device nodes in the build dir. Otherwise they are created in the CPIO archive. 
 * `find_libgcc` (true) Automatically locates libgcc using ldconfig -p and adds it to the initramfs.
 * `musl_libc` (false) Disable ldconfig -p usage for libgcc detection, skip ld.so.cache regeneration.
 * `out_dir` (initramfs_out) If relative, it will be placed under `tmpdir`, defines the output directory.
@@ -151,6 +151,12 @@ Defines /dev/ttyS1 as a `vt100` terminal with a `115200` baud rate.
 
 `primary_console` (tty0) Used to set which console will be initialized with agetty on boot.
 
+#### base.keymap
+
+This module can be used to set keymaps in the initramfs.
+
+The only available parameter is `keymap_file`, which should point to a valid keymap file.
+
 #### base.debug
 
 This module contains debug programs such as `cp`, `mv`, `rm`, `grep`, `dmesg`, `find`, and an editor,
@@ -178,6 +184,7 @@ The following parameters can be used to change the kernel module pulling and ini
 * `kmod_ignore` - Kernel modules to ignore. Modules which depend on ignored modules will also be ignored.
 * `kmod_ignore_softdeps` (false) Ignore softdeps when checking kernel module dependencies.
 * `no_kmod` (false) Disable kernel modules entirely.
+* `kmod_no_normalize` - A list of kernel module names to not normalize (replace dashes with underscores).
 
 ##### ugrd.kmod.input
 
@@ -227,19 +234,27 @@ Additional modules include:
 #### ugrd.fs.mounts
 
 * `autodetect_root` (true) Set the root mount parameter based on the current root label or uuid.
-* `autodetect_root_dm` (true) Attempt to automatically configure virtual block devices such as LUKS/LVM/MDRAID.
-* `autodetect_root_luks` (true) Attempt to automatically configure LUKS mounts for the root device.
-* `autodetect_root_lvm` (true) Attempt to automatically configure LVM mounts for the root device.
-* `autodetect_root_mdraid` (true) Attempt to automatically configure MDRAID mounts for the root device.
+* `autodetect_dm` (true) Attempt to automatically configure virtual block devices such as LUKS/LVM/MDRAID.
+* `autodetect_luks` (true) Attempt to automatically configure LUKS mounts for the root device.
+* `autodetect_lvm` (true) Attempt to automatically configure LVM mounts for the root device.
+* `autodetect_mdraid` (true) Attempt to automatically configure MDRAID mounts for the root device.
 * `autodetect_init_mount'` (true) Automatically detect the mountpoint for the init binary, and add it to `late_mounts`.
 * `run_dirs` A list of directories to create under `/run/` at runtime
 
-> `autodetect_root` is required for `autodetect_root_<type>` to work.
+> `autodetect_root` is required for `autodetect_<type>` to work.
 
 `mounts`: A dictionary containing entries for mounts, with their associated config.
 
+Mounts defined here are mounted before `init_main` is run. This cannot be used for mounts backed by LUKS, LVM, or MDRAID devices, because the backend will not be available when these mounts are attempted.
+
+> `mounts` can be automatically populated by configuring paths as list items in `auto_mounts`.
+
 `mounts.root` is predefined to have a destination of `/target_rootfs` and defines the root filesystem mount, used by `switch_root`.
 
+`late_mounts`: A dictionary containing entries for mounts that should be mounted after `init_main` is run.
+
+>  `late_mounts` can be automatically populated by configuring paths as list items in `auto_late_mounts`.
+
 Each mount has the following available parameters:
 
 * `type` (auto) Mount filesystem type.
@@ -278,6 +293,8 @@ label = "extra"
 
 Paths added to `auto_mounts` will be auto-configured to mount before `init_main` is run.
 
+Paths added to `auto_late_mounts` will be auto-configured to mount after `init_main` is run.  
+
 #### ugrd.fs.fakeudev
 
 This module is used to create fake udev entries for DM devices.
@@ -289,7 +306,6 @@ This module can be enabled by adding `ugrd.fs.fakeudev` to the `modules` list.
 
 This module handles CPIO creation.
 
-* `mknod_cpio` (true) Only create device nodes within the CPIO.
 * `cpio_compression` (xz) Sets the compression method for the CPIO file, passed to PyCPIO.
 * `cpio_rotate` (true) Rotates old CPIO files, keeping `old_count` number of old files.
 
@@ -308,6 +324,7 @@ Importing this module will run `btrfs device scan` and pull btrfs modules.
 * `autodetect_root_subvol` (true) Autodetect the root subvolume, unless `root_subvol` or `subvol_selector` is set. Depends on `hostonly`.
 * `root_subvol` - Set the desired root subvolume.
 * `_base_mount_path` (/root_base) Sets where the subvolume selector mounts the base filesytem to scan for subvolumes.
+* `btrfs_userspace` (true) Add btrfs binary to be able to mount multi-device btrfs partitions.
 
 #### ugrd.fs.resume
 

diff --git a/docs/dev_manual.md b/docs/dev_manual.md
@@ -10,6 +10,8 @@ Python functions can be added imported into `init` and `build` runlevels to exec
 
 Within modules, all config values are imported, then processed according to the order of the `custom_parameters` list.
 
+> If config values have validation which may fail if other config is not loaded, those values can be added to the `_late_args' list to be processed last.
+
 `_module_name` can be set within a module for logging purposes, it is verified to be accurate when imported but optional.
 
 ## Imports

diff --git a/examples/example.toml b/examples/example.toml
@@ -1,3 +1,9 @@
+##############################################################################
+##                                                                          ##
+##    there are docs at https://github.com/desultory/ugrd/tree/main/docs    ##
+##                                                                          ##
+##############################################################################
+
 # This config will decrypt the LUKS volume with uuid "fdf442da-0574-4531-98c7-55227a041f1d", mapping it to "/dev/mapper/root"
 # Note: In most cases, the uuid of the LUKS volume will be detected from the root mount. It's set as an example here.
 # It will attempt to mount the btrfs volume with label "rootfs" to /target_rootfs
@@ -21,10 +27,13 @@ modules = [
 #kmod_ignore_sound = false
 #kmod_ignore_network = false
 
-# The initramfs will be built in /tmp/initramfs if "build_dir" is not specified not specified
+# The initramfs will be built in /tmp/initramfs if "build_dir" is not specified
 #out_dir = "/usr/src/initramfs"
 #out_dir = "/boot"
 
+# create device nodes in build dir, requires root
+#make_nodes = true
+
 # By default, xz compression is used. This can be disabled or set to zstd if the zstandard python module is installed
 #cpio_compression = "zstd"  # Use zstd compression
 #cpio_compression = false  # No compression

diff --git a/examples/vm_keymap.toml → examples/keymap.toml b/examples/vm_keymap.toml → examples/keymap.toml
diff --git a/examples/luks.toml b/examples/luks.toml
@@ -7,7 +7,7 @@ modules = [
 ]
 
 # Device mapper autodetection is enabled by default
-# autodetect_root_luks = true
+# autodetect_luks = true
 
 # Information about the LUKS volume can be manually specified
 #[cryptsetup.root]

diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ugrd"
-version = "2.0.1"
+version = "2.1.0"
 authors = [
   { name="Desultory", email="[email protected]" },
 ]
@@ -19,7 +19,7 @@ classifiers = [
 
 dependencies = [
     "zenlib >= 3.0.2",
-    "pycpio >= 1.5.2"
+    "pycpio >= 1.5.5"
 ]
 
 [project.optional-dependencies]

diff --git a/readme.md b/readme.md
@@ -17,7 +17,7 @@ Generated images are as static and secure as possible, only including components
 
 The final build environment is left in the specified `build_dir`, where it can be examined or repacked.
 
-Unless validation is disabled, µgRD attemts to validate most configuration against the host system, raising exceptions or logging warnings warnings if the configuration is invalid.
+Unless validation is disabled, µgRD attempts to validate most configuration against the host system, raising exceptions or logging warnings warnings if the configuration is invalid.
 
 ## Project goal and features
 
@@ -26,15 +26,19 @@ The original goal of this project was to create an initramfs suitable for decryp
 ### Auto-detection
 
 * Root mount, using `/proc/mounts`. `root=` and `rootflags=` can be used but are not required
-* MDRAID auto-configuration for the root mount
-* LUKS auto-configuration and validation for the root mount
+* MDRAID auto-configuration
+* LVM auto-configuration
+* LUKS auto-configuration and validation
   - LUKS under LVM support
   - LUKS under MDRAID support
-* LVM based root volumes are auto-mounted
-* BTRFS root subvolumes are automatically detected to `root_subvol`
-    - `subvol_selector` can be used to select a subvolume at boot time
-* `/usr` auto-mounting if the init system requires it
-* Auto-detection of kernel modules required by the storage device used by the root filesystem
+  - Detached header support
+  - YubiKey (OpenPGP smartcard) support
+  - Recovery using a passphrase using `try_nokey`
+  - DM-Integrity support
+* BTRFS root subvolumes are automatically detected or can be manually set with `root_subvol`
+    - `subvol_selector` can be used to interactively select a subvolume at boot time
+* `/usr`, `/var`, and `/etc` auto-mounting if the init system requires it
+* Auto-detection of kernel modules required by storage devices and filesystems
 * Init system/target auto-detection
 
 ### Validation
@@ -61,7 +65,7 @@ The original goal of this project was to create an initramfs suitable for decryp
   - Device nodes are created within the CPIO only, so true root privileges are not required
   - Hardlinks are automatically created for files with matching SHA256 hashes
   - Automatic xz compression
-* "merged usr" symlinks are creatd by default and can be disabled by setting `merge_usr = false`
+* "merged usr" symlinks are created by default and can be disabled by setting `merge_usr = false`
 * ZSH and BASH autocompletion for the `ugrd` command
 * Basic hibernation/resume support with `ugrd.fs.resume`
 * Similar usage/arguments as Dracut

diff --git a/src/ugrd/base/banner.py b/src/ugrd/base/banner.py
@@ -1,10 +1,10 @@
 __author__ = "desultory"
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 
 def print_banner(self) -> list[str]:
     """Prints the banner. Prints the kernel version if set"""
     banner = [self.banner]
     if kver := self.get("kernel_version"):
-        banner.append(f"einfo 'Kernel version: {kver}'")
+        banner.append(f"einfo 'Built for kernel version: {kver}'")
     return banner
diff --git a/src/ugrd/base/core.py b/src/ugrd/base/core.py
@@ -1,5 +1,5 @@
 __author__ = "desultory"
-__version__ = "4.7.0"
+__version__ = "4.7.1"
 
 from os import environ, makedev, mknod, uname
 from pathlib import Path
@@ -303,9 +303,7 @@ def deploy_nodes(self) -> None:
             self.logger.info("Created device node '%s' at path: %s" % (node, node_path))
         except PermissionError as e:
             self.logger.error("Unable to create device node %s at path: %s" % (node, node_path))
-            self.logger.info(
-                "`mknod_cpio` in `ugrd.base` can be used to generate device nodes within the initramfs archive if they cannot be created on the host system."
-            )
+            self.logger.info("When `make_nodes` is disabled, device nodes are synthetically created in the resulting CPIO archive.")
             raise e
 
 

diff --git a/src/ugrd/base/core.toml b/src/ugrd/base/core.toml
@@ -63,8 +63,8 @@ hostonly = "bool"  # If true, the initramfs will be built specifically for the h
 validate = "bool"  # If true, the configuration of the initramfs will be validated against the host
 timeout = "int"  # The timeout for _run commands, defaults to 15 seconds
 _custom_init_file = "str"  # Add the _custom_init_file propety, used to set where the custom init file is located
-tmpdir = "Path"  # The base directory for builds
-build_dir = "Path"  # The directory where the initramfs is built
+tmpdir = "Path"  # The base directory for builds, defaults to /tmp. the build and output directories are created inside this directory
+build_dir = "Path"  # The directory where the initramfs is built, inside the tmpdir unless an absolute path is given
 random_build_dir = "bool"  # If true, a random build directory will be used
 build_logging = "bool" # If true, additional build information will be logged to the console
 _build_log_level = "int"  # The level of logging to use for the build log, set to 10 by default and incremeted by if build_log is true (min 20)
@@ -78,17 +78,17 @@ zstd_dependencies = "NoDupFlatList"  # ZStandard compressed dependencies propert
 gz_dependencies = "NoDupFlatList"  # GZipped dependencies property, used to define the gzipped dependencies (will be extracted)
 library_paths = "NoDupFlatList"  # library_paths property, used to define the library paths to add to LD_LIBRARY_PATH
 find_libgcc = "bool"  # If true, the initramfs will search for libgcc_s.so.1 and add it to the initramfs
-musl_libc = "bool"  # If true, disables find_libgcc and regen_ld_so_cache
+musl_libc = "bool"  # If true, disables find_libgcc and regen_ld_so_cache (not needed for musl libc based systems)
 libraries = "NoDupFlatList"  # Additional libraries, by name, added to the initramfs
 binaries = "NoDupFlatList"  # Binaries which should be included in the intiramfs, dependencies resolved with lddtree
 binary_search_paths = "NoDupFlatList"  # Binary paths, used to define the paths to search for binaries
 copies = "dict"  # Copies dict, defines the files to be copied to the initramfs
 nodes = "dict"  # Nodes dict, defines the device nodes to be created
 paths = "NoDupFlatList"  # Paths to be created in the initramfs
 masks = "dict"  # Imports to be masked in the initramfs
-make_nodes = "bool"  # If true, actual device nodes will be created in the build dir
-out_dir = "Path"  # The directory where the initramfs is packed/output. If no packer is used, this is the final output directory.
+make_nodes = "bool"  # If true, actual device nodes will be created in the build dir instead of only being created in the cpio archive
+out_dir = "Path"  # The directory where the initramfs is packed/output
 out_file = "str"  # The name of the output file, if absolute, overrides out dir with the path, and sets out_file to the filename
 old_count = "int"  # The number of times to cycle old files before deleting
-clean = "bool"  # Add the clean property, used to define if the mounts should be cleaned up after boot
+clean = "bool"  # Add the clean property, used to define if the build directory should be cleaned before building
 shell = "str"  # Set the shell to use for the init process
diff --git a/src/ugrd/base/test.py b/src/ugrd/base/test.py
@@ -55,7 +55,7 @@ def _get_qemu_cmd_args(self, test_image):
         "-cpu": self["test_cpu"],
         "-kernel": self["test_kernel"],
         "-initrd": test_initrd,
-        "-append": self["test_cmdline"],
+        "-append": " ".join(self["test_cmdline"]),
         "-drive": "file=%s,format=raw" % test_rootfs,
     }
 
@@ -86,7 +86,7 @@ def make_test_image(self):
         "validate": False,
         "NO_BASE": True,
         "config": None,
-        "modules": "ugrd.fs.test_image",
+        "modules": ",".join(self["test_modules"]),  # By default is only "ugrd.fs.test_image"
         "out_file": self["test_rootfs_name"],
         "build_dir": self["test_rootfs_build_dir"],
         "custom_parameters": get_copy_config_types(self),
@@ -163,7 +163,10 @@ def test_image(self):
             if self["test_flag"] in line:
                 self.logger.info("Test flag found in output: %s", c_(line, "green"))
                 break
-            elif line.endswith("exitcode=0x00000000"):
+            elif (
+                line.endswith("exitcode=0x00000000")
+                or "---[ end Kernel panic - not syncing: sysrq triggered crash ]---" in line
+            ):
                 failed = True
                 break
             elif "press space" in line.lower():

diff --git a/src/ugrd/base/test.toml b/src/ugrd/base/test.toml
@@ -1,16 +1,16 @@
 test_rootfs_name = 'ugrd-test-rootfs'
 test_rootfs_build_dir = 'initramfs_test_rootfs'
-test_image_size = 16
+test_image_size = 256
 
 test_copy_config = ["_mounts", "mounts", "out_dir", "tmpdir", "clean", "test_image_size", "test_no_rootfs", "test_flag", "cryptsetup"]
 kmod_init = ["ata_piix", "sd_mod"]
 
 test_memory = '256M'
 test_cpu = 'host'
 test_arch = 'x86_64'
-test_timeout = 15
-test_cmdline = 'console=ttyS0,115200 panic=1'
-#qemu_bool_args = ['nographic', 'no-reboot', 'enable-kvm']
+test_timeout = 30
+test_cmdline = ['console=ttyS0,115200', 'panic=0']
+test_modules = [ "ugrd.fs.test_image" ]
 qemu_bool_args = ['nographic', 'enable-kvm' ]
 
 [imports.build_pre]
@@ -24,11 +24,12 @@ test_kernel = "Path"  # Define the kernel to use for the test
 test_memory = "str"  # Define the amount of memory to use for the test image (passed to qemu)
 test_cpu = "str"  # Define the CPU to use for the test image (passed to qemu)
 test_arch = "str"  # Define the qemu arch (added to the qemu-system- command)
-test_cmdline = "str"  # Define the kernel command line for the test image
+test_cmdline = "NoDupFlatList"  # Define the kernel command line for the test image
 test_timeout = "int"  # Define the timeout for the test
 test_image_size = "int"  # Define the size of the test image, in MB
 test_flag = "str"  # Define the success flag for the test
 test_no_rootfs = "bool"  # Toggle to run tests without mounting the root image
 test_rootfs_name = "str"  # Define the name of the rootfs image
 test_rootfs_build_dir = "Path"  # Define the build directory for the rootfs image
+test_modules = "NoDupFlatList" # List of modules to include in test image
 qemu_bool_args = "NoDupFlatList"  # Define the qemu boolean arguments