How to Configure Swap Resumption in Ubuntu Using systemd-hibernate-resume-generator

In modern Linux workstation and server environments, hibernation (suspend-to-disk or ACPI state S4) provides an essential capability: saving the entire volatile RAM memory contents to swap storage and powering down the machine completely. When the system powers back on, the early-boot sequence must detect the hibernation signature in swap, locate the exact memory snapshot, and restore memory pages into the physical RAM controller before initializing standard system services or mounting filesystems.

In Ubuntu and systemd-based distributions, this early-boot handover is managed dynamically by systemd-hibernate-resume-generator. Executing during initramfs initialization, this generator evaluates kernel command line options (such as resume= and resume_offset=), dynamically synthesizing a native [email protected] unit that instructs the kernel to restore memory state. When hibernation fails to restore—forcing a clean reboot that wipes open work—understanding how the resume generator operates and how to calculate swap file offsets is critical. This guide covers how the resume generator operates, how to calculate swap offsets, how to configure bootloader parameters, and how to troubleshoot failed resumption cycles.

Understanding the systemd-hibernate-resume-generator Architecture

The systemd-hibernate-resume-generator is a specialized binary executed by systemd inside the early user space (initramfs) before any root filesystems are mounted in read-write mode:

• Kernel Parameter Evaluation: The generator scans /proc/cmdline for two primary flags:
  • resume=<device>: Identifies the swap partition or filesystem containing the hibernation image (e.g., resume=UUID=1234-5678 or resume=/dev/nvme0n1p3).
  • resume_offset=<offset>: Required when hibernating to a swap file (rather than a raw partition). Specifies the physical starting block offset on the underlying filesystem where the swap file begins.
• Transient Unit Synthesis: When valid resume parameters are detected, the generator synthesizes a runtime unit file named systemd-hibernate-resume@<device>.service inside /run/systemd/generator/.
• Dependency Ordering: The synthesized unit declares strict ordering:
  • Before=local-fs-pre.target and Before=sysinit.target.
  • After=systemd-udev-settle.service to ensure block device nodes are fully populated before the resume signature is queried.
• Kernel Resume Trigger: The service executes /lib/systemd/systemd-hibernate-resume, which writes the major and minor device numbers (and offset) into /sys/power/resume, prompting the kernel to read back the memory image.

Configuring Swap Partitions for Hibernation Resumption

If your Ubuntu system uses a dedicated swap partition, configuring hibernation resumption requires identifying the partition’s persistent filesystem UUID.

First, identify the swap partition UUID using blkid:

# Query UUID of the swap partition
sudo blkid -t TYPE=swap -s UUID -o value

Add the resume= parameter to your persistent GRUB configuration in /etc/default/grub:

# Edit GRUB configuration to include swap resume UUID
sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="/GRUB_CMDLINE_LINUX_DEFAULT="resume=UUID=12345678-abcd-ef01-2345-6789abcdef01 /' /etc/default/grub

# Update GRUB bootloader configuration
sudo update-grub

Calculating Swap File Offsets with filefrag

In modern Ubuntu installations, swap files (such as /swap.img) are commonly used instead of dedicated partitions. When hibernating to a swap file, the kernel requires both the partition UUID and the exact physical sector offset where the file begins.

First, retrieve the UUID of the partition hosting the swap file:

# Query partition UUID containing the swap file
findmnt -no UUID -T /swap.img

Next, calculate the physical block offset using filefrag:

# Calculate the starting extent block offset of the swap file
sudo filefrag -v /swap.img | awk '{if($1=="0:"){print substr($4, 1, length($4)-2)}}'

The command returns a numerical integer offset (e.g., 34816). Configure both parameters in /etc/default/grub:

# Configure GRUB with partition UUID and resume offset
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash resume=UUID=87654321-fedc-ba98-7654-3210fedcba98 resume_offset=34816"

Save the file and regenerate the bootloader files:

# Update GRUB and update initramfs archive
sudo update-grub
sudo update-initramfs -u -k all

Testing the Generator Manually in User Space

You can test whether systemd-hibernate-resume-generator correctly parses kernel command line parameters without rebooting by simulating execution in a temporary directory:

# Create temporary directory for generator simulation
mkdir -p /tmp/resume-generator-test

# Run the generator in simulation mode
sudo /lib/systemd/system-generators/systemd-hibernate-resume-generator /tmp/resume-generator-test /tmp/resume-generator-test /tmp/resume-generator-test

Inspect the output directory to verify that the unit was created:

# List generated resume units and dependency links
ls -la /tmp/resume-generator-test/

Examine the generated unit file to review the startup arguments:

# View generated resume service unit
cat /tmp/resume-generator-test/systemd-hibernate-resume@*.service

Auditing Kernel Hibernation Capabilities and States

Before testing hibernation, verify that the Linux kernel supports software suspension and that power states are accessible:

# Check supported ACPI power states
cat /sys/power/state

The output must include disk (e.g., freeze mem disk). Next, inspect the current resume target registered with the kernel:

# Inspect currently registered resume device major:minor number
cat /sys/power/resume

If this file reads 0:0 on a running system after boot, no resume partition was registered during startup.

Troubleshooting Common Hibernation Resumption Failures

When Ubuntu fails to resume from hibernation, keep these key diagnostic pointers in mind:

• Kernel Lockdown with Secure Boot Enabled: If UEFI Secure Boot is active and kernel lockdown is set to [integrity] or [confidentiality], the kernel blocks software hibernation by default because an unauthenticated swap image could be used to tamper with kernel memory. You must either sign swap images or adjust Secure Boot policies. Check lockdown status via cat /sys/kernel/security/lockdown.
• Btrfs and ZFS Swap File Restrictions: Hibernation to swap files on copy-on-write (CoW) filesystems like Btrfs or ZFS requires strict configuration. On Btrfs, the swap file must reside in a dedicated subvolume with CoW disabled (chattr +C), and offset calculations require btrfs inspect-internal map-swapfile instead of filefrag.
• Swap Space Smaller Than Active RAM: If the active memory footprint exceeds the available swap capacity at the moment of hibernation, the kernel aborts the snapshot with an “out of memory” error. Ensure your swap partition or file is at least 1.5 times the size of physical RAM.
• Initramfs Missing Resume Tools: If GRUB passes the parameters but resumption still does not occur, ensure initramfs-tools includes the resume script by checking /etc/initramfs-tools/conf.d/resume and rebuilding the image with sudo update-initramfs -u.

Configuring systemd-hibernate-resume-generator ensures that swap memory snapshots are reliably recognized and restored during early boot, providing seamless power management across Ubuntu workstations and servers.