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

INFO | Intializing class: InitramfsGenerator
INFO | Intializing class: InitramfsConfigDict
INFO | Module version: 2.0.3
INFO | Processing module: ugrd.base.base
INFO | Processing module: ugrd.base.core
INFO | Adding library path: /lib
INFO | Adding library path: /usr/lib
INFO | Processing module: ugrd.fs.mounts
INFO | Processing module: ugrd.base.cmdline
INFO | Processing module: ugrd.kmod.kmod
INFO | Processing module: ugrd.fs.cpio
INFO | Processing module: ugrd.base.checks
INFO | Loading config file: /etc/ugrd/config.toml
INFO | Processing module: ugrd.kmod.standard_mask
INFO | Processing module: ugrd.kmod.nosound
INFO | Processing module: ugrd.kmod.novideo
INFO | Processing module: ugrd.kmod.nonetwork
INFO | Building initramfs
INFO | Detected init at: /usr/bin/init
WARNING | Cleaning build directory: /tmp/initramfs_build
INFO | [find_libgcc] Skipping libgcc_s dependency resolution
INFO | Found device mapper devices: dm-0
INFO | Autodetected root type: btrfs
INFO | Autodetected root source: uuid=3be017a2-7afa-49a4-b0dc-c773f03a7028
INFO | [mounts] Updating mount: root
INFO | Auto-enabling module: btrfs
INFO | Processing module: ugrd.fs.btrfs
INFO | Detected a device mapper mount: /dev/mapper/root
INFO | Autodetected LUKS mount, enabling the cryptsetup module: root
INFO | Processing module: ugrd.crypto.cryptsetup
INFO | [root] LUKS volume uuid: a06a894f-67a4-4b9f-8ce0-199ba0641e47
INFO | [ugrd.crypto.cryptsetup:root] No retries specified, using default: 5
INFO | [root] Configuring cryptsetup for LUKS mount (root) on: dm-0
root:
  uuid: a06a894f-67a4-4b9f-8ce0-199ba0641e47
  retries: 5

INFO | Using detected kernel version: 6.6.30-gentoo-dist
INFO | Autodetected kernel modules: snd_hda_codec_generic, qxl, irqbypass, dm_multipath, crct10dif_pclmul, polyval_clmulni, polyval_generic, sha512_ssse3, sha256_ssse3, i2c_smbus, sha1_ssse3, lpc_ich, virtio_console, virtio_net, virtio_balloon, virtio_blk, crc32c_intel, qemu_fw_cfg, serio_raw, ghash_clmulni_intel, crc32_pclmul, ccp, vfat, fat, dm_crypt, pcieport, ahci, i801_smbus, virtio_pci, xhci_hcd
INFO | Not adding built-in module to dependencies: btrfs
INFO | Not adding built-in module to dependencies: dm_mod
WARNING | [snd_hda_codec_generic] Failed to process autodetected kernel module dependencies: [snd_timer] Kernel module dependency is in ignore list: snd
WARNING | [qxl] Failed to process autodetected kernel module dependencies: [drm_ttm_helper] Kernel module dependency is in ignore list: ttm
ERROR | [ccp] Firmware file does not exist: /lib/firmware/amd/amd_sev_fam19h_model1xh.sbin
ERROR | [ccp] Firmware file does not exist: /lib/firmware/amd/amd_sev_fam19h_model0xh.sbin
ERROR | [ccp] Firmware file does not exist: /lib/firmware/amd/amd_sev_fam17h_model3xh.sbin
ERROR | [ccp] Firmware file does not exist: /lib/firmware/amd/amd_sev_fam17h_model0xh.sbin
WARNING | [pcieport] Failed to process autodetected kernel module dependencies: [pcieport] Modinfo returned no output.
WARNING | [i801_smbus] Failed to process autodetected kernel module dependencies: [i801_smbus] Modinfo returned no output.
INFO | [deploy_nodes] Skipping real device node creation with mknod, as mknod_cpio is not specified.
INFO | Regenerating kernel module metadata files.
INFO | Running init generator functions
INFO | Init kernel modules: dm_crypt, irqbypass, dm_multipath, crct10dif_pclmul, polyval_clmulni, sha512_ssse3, sha256_ssse3, i2c_smbus, sha1_ssse3, lpc_ich, virtio_console, virtio_net, virtio_balloon, virtio_blk, crc32c_intel, qemu_fw_cfg, serio_raw, ghash_clmulni_intel, crc32_pclmul, ccp, vfat
INFO | Included kernel modules: fat, crc32c, polyval_generic
WARNING | Ignored kernel modules: cfg80211, rfkill, 8021q, garp, mrp, stp, llc, binfmt_misc, intel_rapl_msr, intel_rapl_common, ledtrig_audio, snd_hda_intel, snd_intel_dspcfg, snd_intel_sdw_acpi, snd_hda_codec, snd_hda_core, kvm_amd, snd_hwdep, snd_pcm, snd_timer, iTCO_wdt, kvm, snd, intel_pmc_bxt, joydev, drm_ttm_helper, i2c_i801, iTCO_vendor_support, ttm, soundcore, pcspkr, net_failover, failover, btrfs, dm_mod, snd_hda_codec_generic, qxl, pcieport, ahci, i801_smbus, virtio_pci, xhci_hcd
WARNING | 'cryptsetup_prompt' is disabled, if the 'quiet' kernel parameter is not set, the prompt may be hidden under log messages at runtime.
INFO | Wrote file: /tmp/initramfs_build/etc/profile
INFO | Included functions: check_var, setvar, readvar, prompt_user, retry, 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, load_modules, mount_fstab, crypt_init, mount_cmdline_root, do_switch_root
INFO | Wrote file: /tmp/initramfs_build/init
INFO | [0] Cycling file: /tmp/initramfs_out/ugrd-6.6.30-gentoo-dist.cpio.xz -> /tmp/initramfs_out/ugrd-6.6.30-gentoo-dist.cpio.old
INFO | XZ compressing the CPIO data, original size: 15.50 MiB
INFO | Wrote 4.95 MiB to: /tmp/initramfs_out/ugrd-6.6.30-gentoo-dist.cpio.xz
INFO | Completed 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.