CRYPTTAB(5)
NAME
crypttab - static information about encrypted filesystems
DESCRIPTION
The file /etc/crypttab contains descriptive information about encrypted
filesystems. crypttab is only read by programs, and not written; it is
the duty of the system administrator to properly create and maintain
this file. Each filesystem is described on a separate line; fields on
each line are separated by tabs or spaces. Lines starting with "#" are
comments, empty lines are ignored. The order of records in crypttab is
important because the init scripts sequentially iterate through
crypttab doing their thing.
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 (which will be automatically mounted as a loop device)
that should hold the encrypted data.
The third field, key file, describes the file to use as a key for
decrypting the data of the source device. 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 precheck,
check, checkargs and tries may be useful.
The fourth field, options, describes the cryptsetup options associated
with the encryption process. At minimum, the field should contain the
string luks or the cipher, hash and size options.
Options are in the format: key=value [,key=value ...]. The supported
options are described below.
Note that all four fields are mandatory and that a missing field will
lead to unspecified behaviour.
OPTIONS
- cipher=<cipher>
- Encryption algorithm. See cryptsetup -c.
- size=<size>
- Encryption key size. See cryptsetup -s.
- hash=<hash>
- Hash algorithm. See cryptsetup -h.
- offset=<offset>
- Start offset. Uses cryptsetup -o.
- skip=<skip>
- Skip sectors at the beginning. Uses cryptsetup -p.
- verify
- Verify password. Uses cryptsetup -y.
- readonly
- The backing device is read-only (eg: a dvd).
- luks
- Use device with luks extensions.
- swap
- Run mkswap on the created device.
- tmp=<tmpfs>
- Run mkfs with filesystem type <tmpfs> on the created device. Default is ext2.
- precheck=<precheck>
- Check the content of the source device by a suitable program; if
the check fails, the device is not created. If a program is
provided as an argument, it is run, giving the source device as
argument. Cryptdisks/cryptroot searches for the given progam in
/lib/cryptsetup/checks/ first, but full path to program is
supported as well. - Prechecks aren't invoked for LUKS devices, as these are checked
with isLUKS anyway. Default for plain dm-crypt devices is set in
/etc/default/cryptdisks, or un_blkid otherwise. Set to /bin/true in order to disable precheck for plain dm-crypt device. - check=<check>
- Check the content of the target device by a suitable program; if
the check fails, the device is removed. If a program is provided as an argument, it is run, giving the decrypted volume (target device) as first argument, and the value of the checkargs option as second argument. Cryptdisks/cryptroot searches for the given program in
/lib/cryptsetup/checks/ first, but full path to program is
supported as well. - Default is set in /etc/default/cryptdisks (blkid).
- checkargs=<arguments>
- Give <arguments> as the second argument to the check script. See
the CHECKSCRIPTS section for more information. - tries=<num>
- The input of the passphrase is tried <num> times in case of
failure. If you want to disable retries, pass "tries=1". Default is 3. For the root device, "tries=0" enables infinitive retries due to a special case in the initramfs scripts. - noearly
The cryptsetup init scripts are invoked twice during the boot
process - once before lvm, evms, raid, etc. are started and once
again after that. Sometimes you need to start your encrypted disks in a special order. With this option the device is ignored during
the first invokation of the cryptsetup init scripts. - noauto
Entirely ignore the device at the boot process. It's still possible to map the device manually using cryptdisks_start. - loud
Be loud. Print warnings if a device does not exist. This option
overwrites the option quiet. - quiet
Be quiet. Don't print warnings if a device does not exist. This
option overwrites the option loud. - keyscript=<path>
The executable at the indicated path is executed with the key file from the third field of the crypttab as its only argument and the
output is used as the key. This also works with encrypted root
filesystems via initramfs if the executable is self-contained (i.e. an executable which does not rely on any external program which is not present in the initramfs environment). - All fields of the appropriate crypttab entry are available to the
keyscript as exported environment variables: - CRYPTTAB_NAME
The target name - CRYPTTAB_SOURCE
The source device - CRYPTTAB_KEY
The key file - CRYPTTAB_OPTIONS
A list of exported crypttab options - CRYPTTAB_OPTION_<option>
The value of the appropriate crypttab option, with value set to 'yes' in case the option is merely a flag.
CHECKSCRIPTS
- blkid
- Checks for any known filesystem. Supports a filesystem type as
argument via <checkargs>: - o no checkargs - succeeds if any valid filesystem is found on the device.
- o "none" - succeeds if no valid filesystem is found on the
device. - o "ext3" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - succeeds if ext3 filesystem is found on the device.
- un_blkid
Checks for no known filesystem. Supports a filesystem type as
argument via <checkargs>: - o no checkargs - succeeds if no valid filesystem is found on the device.
- o "ext3" [or another filesystem type like xfs, swap, crypto_LUKS, ...] - succeeds if no ext3 filesystem is found on the device.
EXAMPLES
# Encrypted swap device
cswap /dev/sda6 /dev/urandom swap
# Encrypted luks disk with interactive password
cdisk0 /dev/hda1 none luks
# Encrypted ext2 disk with interactive password
# - retry 5 times if the check fails
cdisk1 /dev/sda2 none checkargs=ext2,tries=5
# Encrypted disk with interactive password
# - use a nondefault check script
# - no retries
cdisk2 /dev/hdc1 none check=customscript,tries=1
# Encrypted disk with interactive password
# - twofish as the cipher
cdisk3 /dev/sda3 none cipher=twofish
ENVIRONMENT
- CRYPTDISKS_ENABLE
- Set to yes to run cryptdisks initscripts at startup. Set to no to disable cryptdisks initscripts. Default is yes.
- CRYPTDISKS_MOUNT
Specifies the mountpoints that are mounted before cryptdisks is
invoked. Takes mountpoints configured in /etc/fstab as arguments.
Separate mountpoints by space. This is useful for keys on removable devices, such as cdrom, usbstick, flashcard, etc. Default is unset. - CRYPTDISKS_CHECK
Specifies the default checkscript to be run against the target
device, after cryptdisks has been invoked. The target device is
passed as the first and only argument to the checkscript. Takes
effect if the check option is given in crypttab with no value. See documentation for check option above for more information. - CRYPTDISKS_PRECHECK
Specifies the default checkscript to be run against the source
dm-crypt device, before cryptdisks has been invoked. The source
device is given as the first and only argument to the checkscript. Takes effect if the precheck option is given in crypttab with no value. See documentation for precheck option above for more information.
SEE ALSO
cryptsetup(8), /etc/crypttab
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,
Jonas Meurer jonas@freesources.org and David Hrdeman david@hardeman.nu.