man > crypttab(5)

man perldoc info pydoc3 ri search

📝 NAME

crypttab - static information about encrypted filesystems

🚀 Quick Reference

Use Case	Command	Description
Encrypted swap device	cswap /dev/sda6 /dev/urandom plain,cipher=aes-xts-plain64,size=256,hash=sha1,swap	Creates a swap device on top of encrypted dm-crypt using a random key.
LUKS device with interactive password and discard	cdisk0 UUID=123... none luks,discard	Unlocks a LUKS device identified by UUID, prompts for password, enables TRIM.
TrueCrypt device with interactive password	tdisk0 /dev/sr0 none tcrypt,discard	Opens a TrueCrypt device, allows discards.
Plain dm-crypt with check script and retries	cdisk1 /dev/sda2 none plain,…,check,checkargs=ext4,tries=5,discard	Encrypted ext4 device with filesystem verification and 5 retries.
Custom check script, no retries	cdisk2 /dev/sdc1 none plain,…,check=customscript,tries=1,discard	Uses a custom verification script; fails after one try.
Plain dm-crypt with Twofish cipher	cdisk3 /dev/sda3 none plain,cipher=twofish,size=256,hash=ripemd160,discard	Alternative cipher/hash combination for plain dm-crypt.

📖 DESCRIPTION

The file /etc/crypttab contains descriptive information about encrypted devices. crypttab is only read by programs (e.g. cryptdisks_start and cryptdisks_stop), and not written; it is the duty of the system administrator to properly create and maintain this file. crypttab entries are treated sequentially, so their order matters (dependencies need to be listed first).

Each encrypted device is described on a separate line. Fields on each line are separated by tabs or spaces. Lines starting with '#' are comments, and blank lines are ignored. Octal sequences \0num within a field are decoded, which can be used for values containing spaces or special characters. A backslash which doesn't start an octal sequence yields undefined behavior.

The first field, target, describes the mapped device name. It must be a plain filename without any directory components. A mapped device which encrypts/decrypts data to/from the source device will be created at /dev/mapper/target by cryptsetup.

The second field, source device, describes either the block special device or file that contains the encrypted data. Instead of giving the source device explicitly, the UUID (resp. LABEL, PARTUUID and PARTLABEL) is supported as well, using “UUID=<uuid>” (resp. “LABEL=<label>”, “PARTUUID=<partuuid>” and “PARTLABEL=<partlabel>”).

The third field, key file, describes the file to use as a key for decrypting the data of the source device. In case of a keyscript, the value of this field is given as argument to the keyscript. Note that the entire key file will be used as the passphrase; the passphrase must not be followed by a newline character.

It can also be a device name (e.g. /dev/urandom), note however that LUKS requires a persistent key and therefore does not support random data keys.

If the key file is the string none, a passphrase will be read interactively from the console. In this case, the options check, checkargs and tries may be useful.

The fourth field, options, is an optional comma-separated list of options and/or flags describing the device type (luks, tcrypt, bitlk, or plain which is also the default) and cryptsetup options associated with the encryption process. The supported options are described below. For plain dm-crypt devices the cipher, hash and size options are required. Some options can be changed on active mappings using cryptsetup refresh [<options>] <name>. Furthermore some options can be permanently written into metadata of LUKS2 headers using cryptsetup's --persistent flag.

Note that the first three fields are required and that a missing field will lead to unspecified behaviour.

🔄 ON DIFFERENT CRYPTTAB FORMATS

Please note that there are several independent cryptsetup wrappers with their own crypttab format. This manpage covers Debian's implementation for initramfs scripts and SysVinit init scripts. systemd brings its own crypttab implementation. We try to cover the differences between the systemd and our implementation in this manpage, but if in doubt, better check the systemd crypttab(5) manpage, e.g. online at https://www.freedesktop.org/software/systemd/man/crypttab.html.

⚙️ OPTIONS

• cipher=<cipher> — Encryption algorithm (ignored for LUKS and TCRYPT devices). See cryptsetup -c.
• size=<size> — Encryption key size (ignored for LUKS and TCRYPT devices). See cryptsetup -s.
• sector-size=<bytes> — Sector size. See cryptsetup(8) for possible values and the default.
• hash=<hash> — Hash algorithm (ignored for LUKS and TCRYPT devices). See cryptsetup -h.
• offset=<offset> — Start offset (ignored for LUKS and TCRYPT devices). Uses cryptsetup -o.
• skip=<skip> — Skip sectors at the beginning (ignored for LUKS and TCRYPT devices). Uses cryptsetup -p.
• keyfile-offset=<keyfile-offset> — Number of bytes to skip at the start of the key file.
• keyfile-size=<keyfile-size> — Maximum number of bytes to read from the key file. Default is whole file up to compiled-in maximum. Ignored for plain dm-crypt (key size from size option).
• keyslot=<slot> / key-slot=<slot> — Key slot (ignored for non-LUKS). See cryptsetup -S.
• header=<path> — Detached header file (ignored for plain dm-crypt). See cryptsetup --header.
• verify — Verify password. Uses cryptsetup -y.
• readonly / read-only — Set up a read-only mapping.
• tries=<num> — Number of unlock attempts before failing. Default 3; “tries=0” means infinite. Useful with passphrase or keyscript.
• discard — Allow discards (TRIM) requests. ⚠️ Security: may leak filesystem type and used space. Added by default in Debian 10+ for new dm-crypt devices.
• luks — Force LUKS mode. Ignores cipher=, hash=, size= (provided by header).
• plain — Force plain encryption mode (default).
• bitlk — Force BITLK (Windows BitLocker) mode. ⚠️ Experimental.
• tcrypt — TrueCrypt mode. Ignores cipher=, hash=, keyfile-offset=, keyfile-size=, size=.
• veracrypt / tcrypt-veracrypt — VeraCrypt extension to TrueCrypt. Use with tcrypt.
• tcrypthidden / tcrypt-hidden — Use hidden TCRYPT header (ignored for non-TCRYPT).
• same-cpu-crypt — Perform encryption on same CPU that submitted IO.
• submit-from-crypt-cpus — Disable offloading writes to separate thread.
• no-read-workqueue / no-write-workqueue — Bypass dm-crypt workqueue; process synchronously.
• swap — Run mkswap on the created device. Ignored for initramfs devices.
• tmp[=<tmpfs>] — Run mkfs with filesystem type (default ext4) on the device. Ignored for initramfs.
• check[=<check>] — Run a check program on the target device; close on failure. Program path or relative to /lib/cryptsetup/checks/. Default from CRYPTDISKS_CHECK (blkid). Debian-specific, not supported by systemd.
• checkargs=<arguments> — Pass arguments to the check script. Debian-specific.
• initramfs — Process device in initramfs (root, resume, or marked). Allows remote unlocking. Debian-specific.
• noearly — Ignore device during first invocation of cryptsetup init scripts (before lvm, raid). Ignored for initramfs. Debian-specific.
• noauto — Ignore device at boot; can still be mapped manually via cryptdisks_start. Ignored for initramfs. Debian-specific.
• loud — Print warnings if device does not exist. Overrides quiet. Ignored for initramfs. Debian-specific.
• quiet — Do not print warnings if device does not exist. Overrides loud. Ignored for initramfs. Debian-specific.
• keyscript=<path> — Execute the given path with the third field as argument; output used as key. Environment variables: CRYPTTAB_NAME, CRYPTTAB_SOURCE, CRYPTTAB_KEY, CRYPTTAB_OPTIONS, CRYPTTAB_OPTION_<option>, CRYPTTAB_TRIED. ⚠️ With systemd as init, this option may be ignored (use initramfs). Debian-specific.

🔍 CHECKSCRIPTS

• blkid — Checks for known filesystem. Accepts argument via checkargs:
  • No argument: succeeds if any valid filesystem.
  • "none": succeeds if no valid filesystem.
  • "ext4" (or other type): succeeds if that filesystem type is found.
• un_blkid — Checks for no known filesystem. Accepts argument:
  • No argument: succeeds if no valid filesystem.
  • "ext4" (etc.): succeeds if that filesystem type is NOT found.

📝 EXAMPLES

# Encrypted swap device
cswap /dev/sda6 /dev/urandom plain,cipher=aes-xts-plain64,size=256,hash=sha1,swap

# Encrypted LUKS disk with interactive password, identified by its UUID, discard enabled
cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks,discard

# Encrypted TCRYPT disk with interactive password, discard enabled
tdisk0 /dev/sr0 none tcrypt,discard

# Encrypted ext4 disk with interactive password, discard enabled
# - retry 5 times if the check fails
cdisk1 /dev/sda2 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check,checkargs=ext4,tries=5,discard

# Encrypted disk with interactive password, discard enabled
# - use a nondefault check script
# - no retries
cdisk2 /dev/sdc1 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check=customscript,tries=1,discard

# Encrypted disk with interactive password, discard enabled
# - Twofish as the cipher, RIPEMD-160 as the hash
cdisk3 /dev/sda3 none plain,cipher=twofish,size=256,hash=ripemd160,discard

🌍 ENVIRONMENT

• CRYPTDISKS_ENABLE — Set to yes (default) to run cryptdisks initscripts at startup; no to disable.
• CRYPTDISKS_MOUNT — Mountpoints (from /etc/fstab) to mount before cryptdisks is invoked. Useful for keys on removable media. Default unset.
• CRYPTDISKS_CHECK — Default checkscript to run against target device. Used when check option is given without value. Default is blkid.

🔄 KNOWN UPGRADE ISSUES

Upstream defaults for encryption cipher, hash and keysize have changed several times and may change again. For LUKS devices, settings are stored in the header and don't need configuration. For plain dm-crypt devices, no such information is stored; therefore we strongly suggest to configure cipher, hash and keysize in /etc/crypttab for plain devices, even if they match current defaults.

📚 SEE ALSO

• cryptsetup(8)
• cryptdisks_start(8)
• cryptdisks_stop(8)
• /usr/share/doc/cryptsetup-initramfs/README.initramfs.gz

👤 AUTHOR

This manual page was originally written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of cryptsetup. It has been further improved by Michael Gebetsroither <michael.geb@gmx.at>, David Härdeman <david@hardeman.nu> and Jonas Meurer <jonas@freesources.org>.

---

cryptsetup 2:2.4.3-1ubunt 2024-11-14 CRYPTTAB(5)

📝 NAME 🚀 Quick Reference 📖 DESCRIPTION 🔄 ON DIFFERENT CRYPTTAB FORMATS ⚙️ OPTIONS 🔍 CHECKSCRIPTS 📝 EXAMPLES 🌍 ENVIRONMENT 🔄 KNOWN UPGRADE ISSUES 📚 SEE ALSO 👤 AUTHOR