Add a LUKS Volume to /etc/crypttab

/etc/crypttab is what turns a LUKS volume from a passphrase typed by hand at every boot into something that just activates. This guide covers the installed Debian crypttab format from cryptsetup 2.7.0, packaged here as 2:2.7.0-1ubuntu4.2. Allow about 15 minutes for a known volume, plus a maintenance window if the mapping is needed during boot.

It is written for a volume that already exists and holds data. It does not create, format or erase a disk.

Before you start

Do this as your normal user first. Replace the example device with the partition you intend to activate; these commands only inspect devices:

$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ lsblk -f /dev/sdX2
$ sudo cryptsetup luksUUID /dev/sdX2

The value from luksUUID is the stable identifier for the second field. Do not copy a UUID from a different partition. If luksUUID reports the device is not a LUKS volume, stop and check the source rather than adding a plain dm-crypt entry.

A UUID avoids tying the configuration to a kernel device name such as /dev/sda2, which can change when disks or boot order change. It belongs after UUID=, with no surrounding quotes.

1. Back up the current configuration

Editing /etc/crypttab needs elevated privileges and changes how encrypted devices may be activated at boot. Before editing, make a dated copy in root's configuration directory:

$ sudo cp --preserve=all /etc/crypttab /etc/crypttab.before-example

If the file does not exist yet, create it later with the same ownership and permissions normally used for system configuration. Do not publish a copy containing key paths or other sensitive local details.

2. Add the four fields

Each active line has a mapped name, source device, key field and optional comma-separated options, separated by spaces or tabs. This Debian manpage requires the first three:

vault UUID=REPLACE_WITH_LUKS_UUID none luks,tries=3

• vault is the mapped name; the decrypted mapping appears as /dev/mapper/vault, a plain name, not a path.
• none asks for a passphrase at the console.
• luks selects LUKS handling, so cipher, hash and key size come from the LUKS header, not this file.
• tries=3 is explicit here, though it is also the installed format's default. tries=1 disables retries; tries=0 means unlimited retries.

Use an editor with root privileges:

$ sudoedit /etc/crypttab

Keep line order in mind: entries are processed sequentially, so a mapping another entry needs must come first. Comments begin with # and blank lines are ignored.

3. Choose a key deliberately

For a human-entered passphrase, keep none. For a key file, put its path in the third field and make sure the file is available when the mapping activates. The complete file contents are used as the passphrase, so an accidental trailing newline changes the key:

vault UUID=REPLACE_WITH_LUKS_UUID /etc/cryptsetup-keys.d/vault.key luks,tries=1

Treat that path as sensitive configuration. Restrict the key file to the intended owner and keep a recovery copy somewhere separately protected. A key file missing at early boot can make a volume look broken even when the LUKS header is fine.

4. Inspect before activating

Read the edited line back and confirm the UUID, target name and key choice are the ones you intended:

$ sudo sed -n '/^[[:space:]]*[^#[:space:]]/p' /etc/crypttab
$ sudo cryptsetup luksUUID /dev/sdX2

5. Test the mapping with a maintenance window

Activation changes system state and may prompt for the passphrase. Make sure the target mapping is not already active and anything mounted from it is unmounted first. Then, as root, start only the named entry:

$ sudo cryptdisks_start vault

A successful start creates /dev/mapper/vault. Verify the mapping without writing to it:

$ ls -l /dev/mapper/vault
$ sudo cryptsetup status vault

Do not run filesystem repair, formatting or mount commands as a substitute for this check. If the volume holds a filesystem, mount it only at the correct, empty mountpoint and follow your normal backup and unmount procedure.

6. Undo a failed test

Closing a mapping disrupts anything using it, so check consumers first. After unmounting the filesystem cleanly, close the mapping:

$ findmnt /dev/mapper/vault
$ sudo cryptdisks_stop vault
$ test ! -e /dev/mapper/vault && echo "mapping closed"

If the entry blocks a planned boot, restore the backup made earlier, then inspect it before the next restart:

$ sudo cp --preserve=all /etc/crypttab.before-example /etc/crypttab

Do not remove the backup until the replacement has been tested and the volume is recoverable. If a boot prompt is unexpected, record the exact target name and error, boot with your documented recovery method, and disable only the faulty line by adding # at its start.

Common traps

• Not every crypttab is the same: this article's check, checkargs, keyscript, initramfs and noauto options are Debian-specific in the installed manpage and are not supported by systemd's implementation.
• Do not pad a LUKS entry with cipher settings: adding cipher=, hash= or size= to a normal LUKS entry does not make it more complete. LUKS stores those settings in its header. They matter for plain dm-crypt, where the manpage recommends recording them explicitly because that mapping has no header to hold them.
• Discard is a security decision, not a free performance switch: it can reveal filesystem type or used-space information through discard patterns.
• A clean syntax check is not proof the key works: the meaningful test is a successful activation followed by cryptsetup status, with the original data left untouched.

Done means

• Version and UUID checked: the installed cryptsetup version and actual LUKS UUID were confirmed.
• Entry reviewed: /etc/crypttab contains one reviewed entry with the correct target, UUID and key choice.
• Activation tested: the mapping was activated and inspected during a controlled test.
• Rollback ready: the mapping can be closed cleanly, and the pre-edit configuration is still available.
• Format boundaries understood: you know which options belong to Debian's format and which behaviour comes from a different implementation such as systemd.