info > CRYPTTAB

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	Plain dm-crypt swap with random key
🔑 LUKS device with interactive password	cdisk0 UUID=12345678-9abc-def012345-6789abcdef01 none luks,discard	LUKS by UUID, prompt for passphrase, allow TRIM
💿 TCRYPT device	tdisk0 /dev/sr0 none tcrypt,discard	TrueCrypt-compatible mode with discard
✅ Plain dm-crypt with filesystem check	cdisk1 /dev/sda2 none plain,cipher=aes-xts-plain64,size=256,hash=sha1,check,checkargs=ext4,tries=5,discard	Plain encryption, verify ext4 filesystem, retry 5 times
📜 Using keyscript	csec /dev/sdb1 myscript keyscript=/lib/cryptsetup/scripts/myscript	Key provided by external script

📖 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 value of this option.
• 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> — 📄 Specifies the number of bytes to skip at the start of the key file.
• keyfile-size=<keyfile-size> — 📄 Specifies the maximum number of bytes to read from the key file. The default is to read the whole file up to the compiled-in maximum, that can be queried with cryptsetup --help. This option is ignored for plain dm-crypt devices, as the key file size is then given by the encryption key size (option size).
• keyslot=<slot>, key-slot=<slot> — 🔑 Key slot (ignored for non-LUKS devices). See cryptsetup -S.
• header=<path> — 📂 Detached header file (ignored for plain dm-crypt devices). See cryptsetup --header.
• verify — ✅ Verify password. Uses cryptsetup -y.
• readonly, read-only — 🔒 Set up a read-only mapping.
• tries=<num> — 🔄 Try to unlock the device <num> before failing. It's particularly useful when using a passphrase or a keyscript that asks for interactive input. If you want to disable retries, pass tries=1. Default is 3. Setting tries=0 means infinitive retries.
• discard — 🗑️ Allow using of discards (TRIM) requests for device. WARNING: Assess the specific security risks carefully before enabling this option.
• luks — 🔑 Force LUKS mode. Ignores cipher=, hash=, size=.
• plain — 📄 Force plain encryption mode.
• bitlk — 🪟 Force BITLK (Windows BitLocker-compatible) mode. WARNING: crypttab support is currently experimental.
• tcrypt — 🔐 Use TrueCrypt encryption mode. Ignores cipher=, hash=, keyfile-offset=, keyfile-size=, size=.
• veracrypt, tcrypt-veracrypt — 🔐 Use VeraCrypt extension. Only useful with tcrypt.
• tcrypthidden, tcrypt-hidden — 🙈 Use hidden TCRYPT header.
• same-cpu-crypt — 💻 Perform encryption using the same CPU that IO was submitted on.
• submit-from-crypt-cpus — 📤 Disable offloading writes to a separate thread after encryption.
• no-read-workqueue, no-write-workqueue — ⏩ Bypass dm-crypt internal workqueue and process read or write requests synchronously.
• swap — 🔄 Run mkswap on the created device. Ignored for initramfs devices.
• tmp[=<tmpfs>] — 📁 Run mkfs with filesystem type <tmpfs> (or ext4 if omitted) on the created device. Ignored for initramfs devices.
• check[=<check>] — ✅ Check the content of the target device by a suitable program; if the check fails, the device is closed immediately. See CHECKSCRIPTS section. (Debian-specific, not supported by systemd)
• checkargs=<arguments> — 📝 Give <arguments> as the second argument to the check script. (Debian-specific)
• initramfs — 🧪 Process device within initramfs stage of boot. (Debian-specific)
• noearly — ⏰ Ignore device during first invocation of cryptsetup init scripts. (Debian-specific)
• noauto — 🚫 Ignore device at boot; still manually mappable via cryptdisks_start. (Debian-specific)
• loud — 🔊 Print warnings if device does not exist. (Debian-specific)
• quiet — 🤫 Don't print warnings if device does not exist. (Debian-specific)
• keyscript=<path> — 📜 Execute the indicated path to obtain decryption key. The keyscript's stdout is passed to cryptsetup. Environment variables available: CRYPTTAB_NAME, CRYPTTAB_SOURCE, CRYPTTAB_KEY, CRYPTTAB_OPTIONS, CRYPTTAB_OPTION_<option>, CRYPTTAB_TRIED. (Debian-specific, not supported by systemd; must use initramfs with systemd)

✅ CHECKSCRIPTS

• blkid — Checks for any known filesystem.
  • No checkargs: succeeds if any valid filesystem is found.
  • none: succeeds if no valid filesystem is found.
  • ext4 (or other type): succeeds if that specific filesystem is found.
• un_blkid — Checks for no known filesystem.
  • No checkargs: succeeds if no valid filesystem is found.
  • ext4 (or other type): succeeds if that specific filesystem 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 — Specifies mountpoints that are mounted before cryptdisks is invoked. Useful for keys on removable devices.
• CRYPTDISKS_CHECK — Specifies the default checkscript to be run against the target device after cryptdisks has been invoked.

⚠️ KNOWN UPGRADE ISSUES

The upstream defaults for encryption cipher, hash and keysize have changed several times in the past, and they're expected to change again in future. For LUKS devices, the used settings are stored in the LUKS header, so they don't need to be configured in /etc/crypttab. For plain dm-crypt devices, no information about used cipher, hash and keysize are available. Therefore we strongly suggest to configure the cipher, hash and keysize in /etc/crypttab for plain dm-crypt devices, even if they match the current default.

📚 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 Hardeman <david@hardeman.nu> and Jonas Meurer <jonas@freesources.org>.

📝 NAME 🚀 Quick Reference 📖 DESCRIPTION 🔗 ON DIFFERENT CRYPTTAB FORMATS ⚙️ OPTIONS ✅ CHECKSCRIPTS 📝 EXAMPLES 🌐 ENVIRONMENT ⚠️ KNOWN UPGRADE ISSUES 📚 SEE ALSO 👤 AUTHOR