ugRD

µgRD (Microgram Ramdisk) is a framework used to generate ramdisks using TOML definitions and Python functions.

µgRD was originally designed to create a very minimal initramfs for LUKS decryption. It started as a simple script to do dependency resolution for binaries pulled into the system, to avoid having to compile tools statically. Currently, it supports multiple encryption methods, such as YubiKey/GPG, and automatic configuration and validation for basic LUKS based rootfs encryption.

Unlike many other frameworks, µgRD aims to do nothing more than mount the rootfs, so booting can continue. It does not include udev, and requires no configuration for most systems. By default µgRD configures the initramfs image specifically to boot the system which built it. This enables it to run various checks to validate the image will actually function before the user reboots.

µgRD is written using only a few thousand lines of Python, the majority of which are for logging, validation, or contain embedded shell code. The init file generated by µgRD will generally be fewer than 10 lines of POSIX shell, with most lines being references to functions placed in the generated /etc/profile.

Note
µgRD is pronounced like yogurt.

Installation

Emerge

root #emerge --ask sys-kernel/ugrd

Installkernel

To install the ugrd hook for sys-kernel/installkernel, enable the ugrd USE flag for installkernel in /etc/portage/package.use.

FILE /etc/portage/package.use/installkernel

sys-kernel/installkernel ugrd

Usage

Installkernel (dist-kernel) integration

If the ugrd USE flag is enabled on sys-kernel/installkernel, ugrd will automatically run on each kernel install.

Successful builds will automatically be installed to /boot or /efi.

Building an initramfs manually

Microgram Ramdisk supports extensive customization, but is designed to configure for the system it was built on by default. All options can be configured in the config file /etc/ugrd/config.toml but some options such as validation, autodetection, and path to a custom config file can be specified as arguments.

These options and full syntax can be viewed with:

root # ugrd -h

To build an initramfs with ugrd, run ugrd:

root #ugrd

INFO     | Processing module: ugrd.base.base
INFO     | Processing module: ugrd.base.core
INFO     | Processing module: ugrd.fs.mounts
INFO     | Adding library path: /usr/lib64
INFO     | Processing module: ugrd.base.cmdline
INFO     | Processing module: ugrd.base.banner
INFO     | Processing module: ugrd.kmod.kmod
INFO     | Processing module: ugrd.kmod.standard_mask
INFO     | Processing module: ugrd.kmod.platform
INFO     | Processing module: ugrd.kmod.input
INFO     | Processing module: ugrd.fs.cpio
INFO     | Processing module: ugrd.base.checks
INFO     | Loading config file: /etc/ugrd/config.toml
INFO     | Processing module: ugrd.crypto.smartcard
INFO     | Processing module: ugrd.crypto.gpg
INFO     | Processing module: ugrd.base.console
INFO     | Registered custom init function: custom_init
INFO     | Processing module: ugrd.crypto.cryptsetup
INFO     | Adding library path: /usr/lib/gcc/x86_64-pc-linux-gnu/15
INFO     | Using smartcard public key file: /etc/ugrd/pubkey.gpg
INFO     | -- | Running ugrd v2.1.0
INFO     | -- | Running build tasks
INFO     | Detected init at: /usr/sbin/init
INFO     | Source path for libgcc_s: /usr/lib/gcc/x86_64-pc-linux-gnu/15/libgcc_s.so.1
INFO     | Using default shell: /bin/sh
INFO     | Found virtual block devices: dm-1, dm-0
INFO     | [/dev/mapper/root] Auto-enabling kernel modules for device: dm_mod
INFO     | [/dev/mapper/root] Autodetected mount type from device: btrfs
INFO     | [root] Autodetected mount source: uuid=e661c915-4b14-48ed-8e08-7c4b4aeefd16
INFO     | [/] Detected virtual block device: /dev/mapper/root
INFO     | [/dev/nvme0n1p1] Auto-enabling kernel modules for device: nvme
INFO     | [root] LUKS volume uuid: fd8499aa-94ac-478c-9a62-0bb41f44bb4c
INFO     | [root] Configuring cryptsetup for LUKS mount (root) on: dm-0
root:
  key_type: gpg
  key_file: /boot/luks.gpg
  try_nokey: True
  key_command: gpg --decrypt /boot/luks.gpg
  plymouth_key_command: gpg --batch --pinentry-mode loopback --passphrase-fd 0 --decrypt /boot/luks.gpg
  reset_command: { gpgconf --reload && einfo "$(gpg --card-status)"; }
  uuid: fd8499aa-94ac-478c-9a62-0bb41f44bb4c

INFO     | [mounts] Updating mount: root
INFO     | Auto-enabling module: btrfs
INFO     | Processing module: ugrd.fs.btrfs
INFO     | Auto-enabling ugrd.kmod.usb for USB device: /dev/sda1
INFO     | Processing module: ugrd.kmod.usb
INFO     | [/dev/sda1] Auto-enabling kernel modules for device: sd_mod
INFO     | [/dev/sda1] Autodetected mount type from device: vfat
INFO     | [boot] Autodetected mount source: uuid=4182-B466
INFO     | Detected kernel version: 6.12.58-custom
INFO     | Detected regulator drivers: reg-dummy
INFO     | [Keychron Keychron Q65 Consumer Control] Detected driver: hid-generic
INFO     | [Keychron Keychron Q65 Keyboard] Detected driver: hid-generic
INFO     | [Logitech G502 HERO Gaming Mouse Keyboard] Detected driver: hid-generic
INFO     | [Keychron Keychron Q65] Detected driver: hid-generic
INFO     | [Yubico YubiKey OTP+FIDO+CCID] Detected driver: hid-generic
WARNING  | Cleaning build directory: /tmp/initramfs_build
INFO     | Processing module: ugrd.kmod.novideo
INFO     | Processing module: ugrd.kmod.nosound
INFO     | Processing module: ugrd.kmod.nonetwork
INFO     | Detected cryptsetup backend: openssl
INFO     | Setting shebang to: #!/bin/sh -l
INFO     | [deploy_nodes] Skipping real device node creation with mknod, as make_nodes is not specified.
INFO     | Regenerating ld.so.cache
INFO     | Wrote file: /tmp/initramfs_build/etc/ld.so.conf
INFO     | Wrote file: /tmp/initramfs_build/etc/fstab
INFO     | Regenerating kernel module metadata files.
INFO     | -- | Generating init functions
INFO     | Init kernel modules: dm_crypt, uhid, crc32c, uas, vfat, nvme
INFO     | Included kernel modules: usb_storage, nvme_core, nvme_auth, fat
WARNING  | Ignored kernel modules: reg_dummy
INFO     | Wrote file: /tmp/initramfs_build/etc/profile
INFO     | Included functions: check_var, setvar, readvar, wait_for_space, prompt_user, retry, klog, edebug, einfo, ewarn, eerror, rd_fail, rd_restart, _find_init, mount_default_root, parse_cmdline_bool, parse_cmdline_str, get_crypt_dev, open_crypt_dev, mount_base, export_exports, parse_cmdline, print_banner, check_kver, load_modules, mount_fstab, crypt_init, mount_root, umount_fstab, do_switch_root
INFO     | Wrote file: /tmp/initramfs_build/init_main.sh
INFO     | Wrote file: /tmp/initramfs_build/init
INFO     | -- | Packing build
WARNING  | Deleting old file: /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.old.1
INFO     | [1] Cycling file: /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.old -> /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.old.1
INFO     | [0] Cycling file: /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.xz -> /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.old
INFO     | [XZ] Compressing the CPIO data, original size: 69.57 MiB
INFO     | Wrote 20.17 MiB to: /tmp/initramfs_out/ugrd-6.12.58-custom.cpio.xz
INFO     | -- | Running checks

Tip
By default, ugrd will output images to the path defined by out_dir, which is /tmp/initramfs_out

Note
The new image will be named ugrd-<kver>.cpio.xz where <kver> refers to the current kernel version string.

Installing the Ramdisk to an alternate location

By default, when invoked directly (not by installkernel), the output image is created at /tmp/initramfs_out/ugrd-<kver>

The output path can be specified at build time by specifying a directory or file path as an arg:

root # ugrd /boot/test.img

Tip
This path may be permanently changed by altering the out_dir variable in the configuration file /etc/ugrd/config.toml

Note
If a directory is specified as an arg, an image named ugrd-<kver> will be created under that directory.

Configuration

For most basic setups, ugrd should work without any additional config.

If keyfiles are used, or more specific configuration is required, /etc/ugrd/config.toml can be modified.

See also

More detailed configuration usage is described in the project documentation.
Additional bootloader examples are also shown on the project Github page.
In order to enable resume from the hibernated state located in the swap file on the encrypted root partition see Github Issue 345

Tip
Example configurations are located at examples.

Warning
In most cases, ugrd does not require additional configuration. It's important to realize that autodetection will generally not run if a parameter already has a value.

systemd

When ugrd is used to boot a systemd system, and mounts based on LUKS/LVM volumes are required during the boot process, systemd will stall without the fakeudev module.

This module can be enabled by adding ugrd.fs.fakeudev to the modules list in /etc/ugrd.config.toml.

In the event of boot issues cause by this problem, mount -a can be used to mount filesystems so systemd can continue.

Tip
This module is automatically enabled on systemd systems in version 2+

Important
fakeudev issues is open for discussion about this udev issue.

Kernel log level

By default, ugrd sets the kernel log level to 5. This can be adjusted by setting loglevel in ugrd's config, or by passing the loglevel as a command line arg to the kernel.

Tip
While both methods act similarly, setting the value in ugrd will set it shortly after init, while setting it in the kernel command line sets it immediately.