Configure a LUKS Volume Safely with crypttab

You will add a Debian-style /etc/crypttab entry for an existing LUKS volume, check the source UUID, and test the resulting mapping without guessing at device names. Allow about 15 minutes for a known volume, plus a maintenance window if the mapping is needed during boot.

This guide uses the installed Debian crypttab format from cryptsetup 2.7.0, packaged here as 2:2.7.0-1ubuntu4.2. It is written for a volume that has already been created and contains data. It does not create, format or erase a disk.

Checkpoint: identify the volume first

Do this as your normal user. Replace the example device with the partition you intend to unlock. The 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 to use in the second field. Do not copy a UUID from a different partition. If luksUUID reports that the device is not a LUKS volume, stop and check the source rather than adding a plain dm-crypt entry.

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

1. Back up the current configuration

Editing /etc/crypttab requires 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, 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. Fields are separated by spaces or tabs. The first three fields are required by this Debian manpage.

vault UUID=REPLACE_WITH_LUKS_UUID none luks,tries=3

For this line, the decrypted mapping will appear as /dev/mapper/vault. The target is a plain name, not a path. none asks for a passphrase at the console. luks selects LUKS handling, whose cipher, hash and key size come from the LUKS header rather than from this file. tries=3 is explicit: the installed format defaults to three attempts, while tries=1 disables retries and tries=0 means unlimited retries.

Use an editor with root privileges, for example:

$ sudoedit /etc/crypttab

Keep the line order in mind. Entries are processed sequentially, so a mapping needed by another entry 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 at the time the mapping is activated. The complete file contents are used as the passphrase; 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 in a separately protected location. A key file that is missing at early boot can make a volume appear broken even when the LUKS header is healthy.

Do not use /dev/urandom for a persistent LUKS volume. The local manpage describes it for transient encrypted swap, and explicitly says that LUKS requires a persistent key.

Checkpoint: inspect before activating

Read the edited line back and confirm that 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

Compare the UUIDs yourself. This is a useful pause point: a typo in the target or UUID can cause a boot-time prompt for a volume that does not exist, while a wrong key path can expose the same symptom.

4. Test the mapping with a maintenance window

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

$ sudo cryptdisks_start vault

A successful start should create /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 contains a filesystem, mount it only at the correct, empty mountpoint and follow your normal backup and unmount procedure.

5. Undo a failed test

Closing a mapping is service-disrupting if anything is using it. 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 prevents 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 using your documented recovery method, and disable only the faulty line by adding # at its start.

Common traps

• Do not assume every crypttab has the same extensions. 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 add cipher=, hash= or size= to a normal LUKS entry just to make it look complete. LUKS stores those settings in its header. They matter for plain dm-crypt, where the manpage recommends recording them explicitly because the mapping has no header containing them.
• Consider discard a security decision, not a harmless performance switch. It can reveal information about filesystem type or used space through discard patterns.
• Remember that a valid syntax check is not proof that the key works. The meaningful test is a successful activation followed by cryptsetup status, with the original data left untouched.