Skip to content

LUKS disk encryption — full-disk and detached header layouts

Encrypting a Linux disk with LUKS2, choosing between full-disk and detached-header layouts, and unlocking remotely without typing a passphrase at boot.

LUKS is the de facto disk encryption format on Linux. The cryptsetup tool turns a block device into an encrypted volume that you unlock with a passphrase or a key file, then mount as if it were plain. This article covers a LUKS2 install on a data disk, the detached-header pattern for hardened deployments, and remote unlock so a rebooted server does not sit at a passphrase prompt waiting for someone to walk into the data centre.

How to verify

Inspect what is encrypted on a host and how:

sudo lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT,TYPE
sudo cryptsetup status <name>      # e.g. data_crypt
sudo cryptsetup luksDump /dev/<device>
sudo cat /etc/crypttab
sudo dmsetup table <name> | head

luksDump prints the header: which cipher, KDF, key slots in use, and (for LUKS2) any tokens. The crypttab line is the boot-time wiring — without it, the volume stays locked across reboots.

What’s happening

LUKS sits between the block device and the filesystem. Open a LUKS volume with cryptsetup luksOpen and the kernel creates a /dev/mapper/<name> device that decrypts on read and encrypts on write. The encryption key (the master key) is generated once at format time and stored encrypted in the LUKS header — one of up to eight passphrases or key files unwraps it. Changing a passphrase only re-encrypts the master key in one slot; it does not re-encrypt the data.

LUKS2 is the current format. It supports per-slot key derivation function (argon2id by default), tokens that point at external unlock paths (TPM2, smartcard), and a JSON header that is easier to debug than the binary LUKS1 layout. New deployments should always use LUKS2 unless an old kernel forces LUKS1.

The detached-header pattern stores the LUKS header on a separate device — a USB key, a network share, or a second disk. The encrypted data on the main disk looks like random noise without the header. This defends against a “disk lost in transit” scenario: an adversary with the disk and no header has nothing.

Remote unlock for boot uses one of three patterns: a key file fetched from a secrets manager, the dracut-network-based “dropbear in initramfs” approach (you SSH in and type the passphrase), or Clevis with a Tang server (the host fetches a Shamir-sharded key from a network service it can only reach inside the network — geo-fenced unlock).

The procedure

  1. Format a new data disk. sudo cryptsetup luksFormat --type luks2 --cipher aes-xts-plain64 --key-size 512 --hash sha256 --pbkdf argon2id /dev/sdb. Type YES at the prompt and a strong passphrase. The key size is 512 because XTS-AES uses two 256-bit keys.
  2. Open the volume. sudo cryptsetup luksOpen /dev/sdb data_crypt. A /dev/mapper/data_crypt device appears, the same size as the underlying disk minus the header.
  3. Make a filesystem on the mapper device. sudo mkfs.ext4 -L data /dev/mapper/data_crypt && sudo mkdir -p /srv/data && sudo mount /dev/mapper/data_crypt /srv/data.
  4. Add a key file for unattended unlock. sudo dd if=/dev/urandom of=/etc/luks-keys/data.key bs=4096 count=1 && sudo chmod 0400 /etc/luks-keys/data.key && sudo cryptsetup luksAddKey /dev/sdb /etc/luks-keys/data.key. Now /etc/luks-keys/data.key is one of up to 8 things that can unlock the volume.
  5. Wire crypttab and fstab. /etc/crypttab gets data_crypt UUID=$(sudo blkid -s UUID -o value /dev/sdb) /etc/luks-keys/data.key luks,discard. /etc/fstab gets /dev/mapper/data_crypt /srv/data ext4 defaults,nofail 0 2. On boot, systemd-cryptsetup processes the crypttab line and the mount follows.
  6. (Detached header variant) Format with --header /mnt/usb/luks-header.img. The data device contains only ciphertext; the header file is the unlock token. Mount the USB before boot; without it, the system cannot unlock the disk.
  7. (Remote unlock variant) Install dropbear and the initramfs network module. sudo apt install dropbear-initramfs. Add your unlock SSH key to /etc/dropbear/initramfs/authorized_keys. Set IP=dhcp in /etc/initramfs-tools/initramfs.conf. Regenerate the initramfs (sudo update-initramfs -u). On reboot, SSH to the box on the boot port, type the passphrase, then the system resumes booting.
  8. Back up the LUKS header. sudo cryptsetup luksHeaderBackup /dev/sdb --header-backup-file /mnt/secure/sdb-header.bin. Without this, a corrupted header (a misaligned partition tool edit) means the data is gone. Treat the header backup like the master key — restricted, offline, with a documented recovery procedure.

Common pitfalls

  • TRIM on an encrypted SSD reveals which sectors are unused, leaking some metadata. The discard option in crypttab enables TRIM passthrough — accept the leak (mild) for the lifetime gains (significant) on consumer SSDs, refuse it on hosts where the metadata matters.
  • cryptsetup luksRemoveKey requires a passphrase that is still valid; you cannot remove a slot by referencing it by number. Add a new slot first, verify, then remove the old one.
  • The kernel cipher modules (aes-xts, dm-crypt) must be available in the initramfs for boot-mount volumes. Custom kernels often miss them — verify with lsinitramfs /boot/initrd.img-$(uname -r) | grep -E 'crypt|aes'.
  • A passphrase change with cryptsetup luksChangeKey re-encrypts the master key in one slot only. The plaintext data is the same. To re-key the data itself, cryptsetup-reencrypt (slow, offline).
  • Tang-based unlock (Clevis) is convenient but creates a hidden dependency: the Tang server must be reachable at boot. A Tang outage during a reboot leaves the host hung. Run Tang in a small HA cluster on the same network.

In the engagements we run, full-disk encryption is the default for any host with data at rest the customer cares about. Key escrow, header backups, and remote unlock are part of Managed Operations — the disk being encrypted is necessary but not sufficient.