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 support 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 bash. The init file generated by µgRD will generally be fewer than 10 lines of bash, with most lines being references to functions placed in the generated /etc/profile.

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/ugrd

sys-kernel/installkernel ugrd

Usage

Installkernel integration

If the ugrd USE flag is enabled on sys-kernel/installkernel, ugrd will automatically run on each kernel install. If ugrd is unable to make a working image, it will fail, and a new image will not be installed to /boot or /efi.

Building an initramfs manually

To build an initramfs with ugrd, run ugrd:

root #ugrd

Expand

INFO     | Processing module: ugrd.base.base
INFO     | Processing module: ugrd.base.core
INFO     | Adding library path: /usr/lib64
INFO     | Processing module: ugrd.fs.mounts
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.fs.cpio
INFO     | Processing module: ugrd.base.checks
INFO     | Loading config file: /etc/ugrd/config.toml
INFO     | Processing module: ugrd.base.console
INFO     | Registered custom init function: custom_init
INFO     | -- | Running ugrd v1.30.1
INFO     | -- | Running build tasks
INFO     | Detected init at: /usr/bin/init
INFO     | Source path for libgcc_s: /usr/lib/gcc/x86_64-pc-linux-gnu/14/libgcc_s.so.1
INFO     | Found virtual block devices: dm-1, dm-0
INFO     | Auto-enabling kernel modules for device: dm_mod
INFO     | Autodetected mount type: btrfs
INFO     | [root] Autodetected mount source: uuid=9f6a673d-1630-46ec-a148-05ca86e51e38
INFO     | [mounts] Updating mount: root
INFO     | Auto-enabling module: btrfs
INFO     | Processing module: ugrd.fs.btrfs
INFO     | [/] Detected virtual block device: /dev/mapper/vg0-root
INFO     | Autodetected LVM mount, enabling the lvm module.
INFO     | Processing module: ugrd.fs.lvm
INFO     | [vg0-root] LVM volume contianer uuid: 0tMcF4-JUAf-CrJP-8vaD-BOZ9-VJ8C-1GPPm7
INFO     | Auto-enabling kernel modules for device: dm_mod
INFO     | [/] Detected virtual block device: /dev/mapper/root
INFO     | Autodetected LUKS mount, enabling the cryptsetup module: root
INFO     | Processing module: ugrd.crypto.cryptsetup
INFO     | [root] LUKS volume uuid: f13931bf-6887-4f72-a519-2698a7d1b192
INFO     | [ugrd.crypto.cryptsetup:root] No retries specified, using default: 5
INFO     | [root] Configuring cryptsetup for LUKS mount (root) on: dm-0
root:
  uuid: f13931bf-6887-4f72-a519-2698a7d1b192
  retries: 5

INFO     | Auto-enabling kernel modules for device: virtio_blk
INFO     | [root] Autodetected device mapper container: vda2
INFO     | [vg0-root] Autodetected device mapper container: dm-0
INFO     | Detected kernel version: 6.6.67-gentoo-dist
INFO     | Build directory does not exist, skipping cleaning: /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     | [deploy_nodes] Skipping real device node creation with mknod, as make_nodes is not specified.
INFO     | Regenerating kernel module metadata files.
INFO     | -- | Generating init functions
INFO     | Init kernel modules: crc32c, dm_crypt, virtio_blk
INFO     | Wrote file: /tmp/initramfs_build/etc/profile
INFO     | Included functions: check_var, setvar, readvar, prompt_user, retry, klog, edebug, einfo, ewarn, eerror, rd_fail, rd_restart, _find_init, mount_root, parse_cmdline_bool, parse_cmdline_str, get_crypt_dev, mount_base, export_exports, parse_cmdline, print_banner, load_modules, mount_fstab, crypt_init, init_lvm, mount_cmdline_root, do_switch_root
INFO     | Wrote file: /tmp/initramfs_build/init_main.sh
INFO     | Wrote file: /tmp/initramfs_build/init
INFO     | -- | Packing build
INFO     | XZ compressing the CPIO data, original size: 20.15 MiB
INFO     | Wrote 6.52 MiB to: /tmp/initramfs_out/ugrd-6.6.67-gentoo-dist.cpio.xz
INFO     | -- | Running checks

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

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.

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 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.

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.