Linux Hibernation and Resume: Image Storage, Initramfs, and Recovery

Linux hibernation, also called suspend-to-disk, saves a system image to persistent storage and then powers down or enters a platform-specific state. Resume has to find that image early enough in boot, recognize it, and restore the saved kernel state before normal filesystems are remounted. A machine that boots normally after hibernation may have silently discarded the image and performed a cold boot. Reliable diagnosis must distinguish image creation, storage, boot-time discovery, hardware restoration, and userspace continuation.

Hibernation support depends on kernel configuration, architecture, storage drivers, firmware, and device behavior. This guide covers software suspend (swsusp) and common Linux resume configuration. Distribution tools may generate configuration differently; use the distribution’s supported tooling and the kernel documentation for the target release. Commands that initiate hibernation can suspend or power off the system. Do not run them remotely without a tested recovery path.

Hibernation is not suspend-to-RAM

Suspend-to-RAM keeps state in memory while the machine uses a low-power state. Hibernation writes a memory image to persistent storage so the machine can shut down or enter a deeper platform state. The paths have different hardware requirements and recovery modes. A successful sleep/resume cycle does not prove that hibernation image writing or early resume works.

The image needs enough swap capacity according to the configured kernel image-size policy and the workload’s memory state. The image is typically compressed, but its size depends on actual memory contents and kernel behavior. Do not size swap from installed RAM using a universal ratio. Validate peak image requirements on the target workload and preserve enough free swap for ordinary system operation if the same area serves both roles.

The kernel exposes hibernation interfaces under /sys/power on systems with support. Availability of a sysfs file is not proof that platform firmware can complete the transition. Confirm the suspend mode and available states on the target, then run controlled repeated tests under a local console.

Resume device and swap file offset

For a swap partition, early resume needs the partition or device that contains the hibernation image. The kernel can receive it through the resume= command-line parameter or the documented /sys/power/resume interface. For a swap file, the file is not necessarily contiguous and its swap header is not necessarily at the start of the containing partition. The resume path therefore also needs the correct offset, commonly provided as resume_offset= or through the corresponding sysfs interface.

Do not copy a swap-file offset from a guide for another filesystem, kernel, or boot setup. The distribution’s tooling may calculate and maintain the correct value. Recreate or relocate the swap file can change the offset and invalidate the initramfs configuration. After changing the swap location, regenerate the relevant boot artifacts using the supported toolchain and confirm that the resulting kernel command line or initramfs configuration refers to the correct device and offset.

cat /proc/cmdline
swapon --show --output=NAME,TYPE,SIZE,USED,PRIO

These commands only inspect current boot parameters and swap configuration. A production runbook should record the exact swap device, backing filesystem, whether it is a partition or file, and the method used to calculate the resume offset. If a distribution encrypts swap or uses layered storage, follow its documented resume setup rather than deriving a physical device manually.

Resume must happen before filesystem mounts

The resume image restores a prior kernel and userspace state. If normal filesystems are mounted and modified before the hibernation image is checked, the restored memory state can disagree with on-disk data. For this reason, when resume is initiated from an initramfs, it must occur before filesystems are remounted, even read-only according to the kernel documentation. Verify initramfs hook ordering and required storage drivers.

The resume device must be discoverable at the time the initramfs attempts to read it. If the storage driver is only available as a module loaded later, the early resume attempt can fail and boot proceeds normally. Review initramfs contents, crypt or volume activation order where applicable, kernel logs, and distribution-generated resume configuration. A resume= parameter that names a valid device is not enough if the device is not ready yet.

Resume configuration can drift after storage maintenance. Recreating a swap file, changing an LVM layout, migrating a root filesystem, or renumbering devices can leave an old resume target in the boot entry. Compare the configured value with the active swap reported by the running system and with the initramfs that actually booted, not only with a source configuration file. If multiple boot entries exist, confirm the expected parameters are present in the entry selected by firmware or the boot manager.

Some resume failures look like ordinary boot because the kernel continues after failing to find the image. Compare boot ID and restored process state with the pre-hibernation session, check early-boot logs, and observe whether the swap image signature is found. Make sure the initramfs does not clear or recreate the swap area before resume detection.

Hibernation mode and device callbacks

The system can support different hibernation modes, such as a platform-assisted path or a shutdown/reboot-style path. Available modes and behavior are hardware-specific. A test using a reboot mode may help isolate image creation and resume but can skip some platform callbacks needed in normal operation. The kernel debugging documentation recommends repeating tests and trying the appropriate platform mode when behavior differs.

Devices must suspend and resume in a safe order. Drivers can fail to quiesce, firmware may not restore device state, and storage needed for the image can become unavailable. Test with USB, external displays, docking stations, network interfaces, storage controllers, and workloads that use accelerators. Remove optional devices one at a time to isolate a failing callback; do not conclude that the hibernation core is defective based on a single peripheral failure.

Diagnose creation versus restoration

Separate four milestones: the kernel accepted the request; the memory image was created; the image was written to the configured swap target; and the next boot found and restored it. Capture kernel logs and system journal around each stage. Verify free swap and image-size settings before testing, then inspect early boot messages and the post-resume state.

If hibernation fails during image creation, investigate memory availability, device suspend callbacks, and kernel logs. If image storage fails, validate swap activation, capacity, and device I/O. If the next boot cold-starts, focus on resume parameters and initramfs ordering. If state restores but devices misbehave, focus on the platform and driver resume callbacks.

Use the kernel’s pm_test facilities for controlled suspend/hibernation debugging where supported. These tests can help isolate device, platform, processor, and core transitions, but they are diagnostic modes and should not be mistaken for a successful real power transition. Follow the kernel documentation and distribution instructions; restore the normal test mode before production use.

Repeated attempts matter because a storage race, a device that fails only after a second cycle, or a stale swap image can make one success misleading. After each test, record whether the same processes and unsaved in-memory state were restored. Check the boot identifier and the expected continuity marker rather than judging by a familiar desktop appearing. Test cold boot separately so a working normal boot is not confused with restored state.

Operational recovery and test plan

Before a change, ensure a known-good boot entry, local access, and a backup of irreplaceable work. Test a full hibernate/resume cycle multiple times, including after a kernel update, initramfs rebuild, swap-file recreation, or firmware update. Repeat from idle and a representative working set. Confirm that a deliberate cold boot remains available if the stored image is stale or unsupported.

Record the kernel and initramfs versions, command line, swap configuration, resume offset method, firmware version, and devices attached. If a failed hibernation leaves a stale image, follow the distribution’s documented recovery procedure rather than clearing swap blindly. Never interrupt image writing or resume with a forced power cut unless data recovery is understood.

A working Linux hibernation path depends on a valid image area, accurate resume identification, early restoration before filesystem activity, and compatible platform/device callbacks. Validate each stage independently, run repeated end-to-end tests, and keep a safe cold-boot recovery path for image or firmware failures.

Related:

Sources: