cryptsetup-suspend - automatically suspend LUKS devices on system suspend

This manual page was written by Jonas Meurer <jonas@freesources.org> in December 2019. cryptsetup 2:2.8.0-1ubunt 2025-07-25 CRYPTSETUP-SUSPEND(7)

cryptsetup-suspend brings support to automatically suspend LUKS devices before entering system suspend mode. Devices will be unlocked at system resume time, asking for passwords if required. The feature is enabled automatically by installing the cryptsetup-suspend package. No further configuration is required. cryptsetup-suspend supports all setups of LUKS devices that are supported by the cryptsetup packages. To do so, it depends on scripts from the Debian package cryptsetup-initramfs. See the INTERNALS section about details on how it works.

cryptsetup-suspend consists of three parts: cryptsetup-suspend: A c program that takes a list of LUKS devices as arguments, suspends them via luksSuspend and suspends the system afterwards. , cryptsetup-suspend-wrapper: A shell wrapper script which works the following way: 1. Disable swap and extract the initramfs into a tmpfs (the chroot), 2. Run (systemd) pre-suspend scripts, stop udev, freeze cgroups, 3. run cryptsetup-suspend in chroot, 4. resume initramfs devices inside chroot after resume, 5. resume non-initramfs devices outside chroot, 6. thaw groups, start udev, run (systemd) post-suspend scripts, 7. Unmount the tmpfs and re-enable swap , A systemd unit drop-in file that overrides the Exec property of systemd-suspend.service so that it invokes the script cryptsetup-suspend-wrapper.

The cryptsetup-suspend feature is limited to LUKS devices and doesn't work with plaindm-crypt or tcrypt devices.

cryptsetup-suspend - automatically suspend LUKS devices on system suspend

Suspending LUKS devices basically means to remove the corresponding encryption keys from system memory. This protects against all sort of attacks that try to read out the memory from a suspended system, like for example cold-boot attacks. cryptsetup-suspend protects only the encryption keys of your LUKS devices against being read from the memory. Most likely there's more sensitive data in system memory, be it other kinds of private keys (e.g. OpenPGP, OpenSSH) or any kind of documents with sensitive content. The initramfs image is extracted in memory and left unencrypted (see the INTERNALS section) so all key material it might include, for instance key files copied using the hooks' KEYFILE_PATTERN= option, will remain unprotected.

cryptsetup(8), crypttab(5)