'\" t
.\"     Title: crypttab
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 2017-05-09
.\"    Manual: cryptsetup manual
.\"    Source: cryptsetup 2:1.7.3-4
.\"  Language: English
.\"
.TH "CRYPTTAB" "5" "2017\-05\-09" "cryptsetup 2:1\&.7\&.3\-4" "cryptsetup manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
crypttab \- static information about encrypted filesystems
.SH "DESCRIPTION"
.sp
The file /etc/crypttab contains descriptive information about encrypted filesystems\&. crypttab is only read by programs (e\&.g\&. \fBcryptdisks_start\fR and \fBcryptdisks_stop\fR), 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 \(lq#\(rq 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\&.
.sp
The first field, \fItarget\fR, 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 \fIsource device\fR will be created at /dev/mapper/target by \fBcryptsetup\fR\&.
.sp
The second field, \fIsource device\fR, describes either the block special device or file that contains the encrypted data\&. Instead of giving the \fIsource device\fR explicitly, the UUID is supported as well, using \fIUUID=<luks_uuid>\fR\&.
.sp
The third field, \fIkey file\fR, describes the file to use as a key for decrypting the data of the \fIsource device\fR\&. Note that the \fIentire\fR key file will be used as the passphrase; the passphrase must \fInot\fR be followed by a newline character\&.
.sp
It can also be a device name (e\&.g\&. /dev/urandom), note however that LUKS requires a persistent key and therefore does \fInot\fR support random data keys\&.
.sp
If the \fIkey file\fR is the string \(lqnone\(rq, a passphrase will be read interactively from the console\&. In this case, the options precheck, check, checkargs and tries may be useful\&.
.sp
The fourth field, \fIoptions\fR, describes the cryptsetup options associated with the encryption process\&. At minimum, the field should contain either the string \fIluks\fR respectively \fItcrypt\fR or the \fIcipher\fR, \fIhash\fR and \fIsize\fR options\&.
.sp
Options are in the format: \fIkey\fR=\fIvalue\fR [,\fIkey\fR=\fIvalue\fR \&...]\&. The supported options are described below\&.
.sp
Note that all four fields are mandatory and that a missing field will lead to unspecified behaviour\&.
.SH "OPTIONS"
.PP
\fIcipher\fR=<cipher>
.RS 4
Encryption algorithm (ignored for LUKS and TCRYPT devices)\&. See
\fBcryptsetup \-c\fR\&.
.RE
.PP
\fIsize\fR=<size>
.RS 4
Encryption key size (ignored for LUKS and TCRYPT devices)\&. See
\fBcryptsetup \-s\fR\&.
.RE
.PP
\fIhash\fR=<hash>
.RS 4
Hash algorithm (ignored for LUKS and TCRYPT devices)\&. See
\fBcryptsetup \-h\fR\&.
.RE
.PP
\fIoffset\fR=<offset>
.RS 4
Start offset (ignored for LUKS and TCRYPT devices)\&. Uses
\fBcryptsetup \-o\fR\&.
.RE
.PP
\fIskip\fR=<skip>
.RS 4
Skip sectors at the beginning (ignored for LUKS and TCRYPT devices)\&. Uses
\fBcryptsetup \-p\fR\&.
.RE
.PP
\fIverify\fR
.RS 4
Verify password\&. Uses
\fBcryptsetup \-y\fR\&.
.RE
.PP
\fIreadonly\fR
.RS 4
The backing device is read\-only (eg: a dvd)\&.
.RE
.PP
\fIdiscard\fR
.RS 4
Allow using of discards (TRIM) requests for device\&.
.sp
\fBWARNING\fR: Assess the specific security risks carefully before enabling this option\&. For example, allowing discards on encrypted devices may lead to the leak of information about the ciphertext device (filesystem type, used space etc\&.) if the discarded blocks can be located easily on the device later\&.
.sp
Kernel version 3\&.1 or more recent is required\&. For older versions is the option ignored\&.
.RE
.PP
\fIluks\fR
.RS 4
Use device with LUKS extensions\&.
.RE
.PP
\fItcrypt\fR
.RS 4
Use device with TCRYPT extensions\&.
.RE
.PP
\fIveracrypt\fR
.RS 4
Use VeraCrypt extension to TCRYPT device\&. Only useful in conjunction with
\fItcrypt\fR
option (ignored for non\-TCRYPT devices)\&.
.RE
.PP
\fIswap\fR
.RS 4
Run
\fBmkswap\fR
on the created device\&.
.RE
.PP
\fItmp\fR=<tmpfs>
.RS 4
Run
\fBmkfs\fR
with filesystem type <tmpfs> on the created device\&. Default is ext4\&.
.RE
.PP
\fIprecheck\fR=<precheck>
.RS 4
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\&.
.sp
Prechecks aren\*(Aqt 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\&.
.RE
.PP
\fIcheck\fR=<check>
.RS 4
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\&.
.sp
Default is set in
/etc/default/cryptdisks
(blkid)\&.
.RE
.PP
\fIcheckargs\fR=<arguments>
.RS 4
Give <arguments> as the second argument to the check script\&. See the CHECKSCRIPTS section for more information\&.
.RE
.PP
\fItries\fR=<num>
.RS 4
The input of the passphrase is tried <num> times in case of failure\&. If you want to disable retries, pass
\(lqtries=1\(rq\&. Default is 3\&. Setting
\(lqtries=0\(rq
will ask for the passphrase until a correct one has been submitted (infinitive retries)\&.
.RE
.PP
\fIinitramfs\fR
.RS 4
The initramfs hook processes the root device, any resume devices and any devices with the
\(lqinitramfs\(rq
option set\&. These devices are processed within the initramfs stage of boot\&. As an example, that allows the use of remote unlocking using dropbear\&.
.RE
.PP
\fInoearly\fR
.RS 4
The cryptsetup init scripts are invoked twice during the boot process \- once before lvm, 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 invocation of the cryptsetup init scripts\&.
.RE
.PP
\fInoauto\fR
.RS 4
Entirely ignore the device at the boot process\&. It\*(Aqs still possible to map the device manually using cryptdisks_start\&.
.RE
.PP
\fIloud\fR
.RS 4
Be loud\&. Print warnings if a device does not exist\&. This option overwrites the option
\fIquiet\fR\&.
.RE
.PP
\fIquiet\fR
.RS 4
Be quiet\&. Don\*(Aqt print warnings if a device does not exist\&. This option overwrites the option
\fIloud\fR\&.
.RE
.PP
\fIkeyscript\fR=<path>
.RS 4
The executable at the indicated path is executed with the
\fIkey file\fR
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)\&.
.sp
LIMITATIONS: All binaries and files on which the keyscript depends must be available at the time of execution\&. Special care needs to be taken for encrypted filesystems like /usr or /var\&. As an example, unlocking encrypted /usr must not depend on binaries from /usr/(s)bin\&.
.sp
WARNING: With systemd as init system, this option might be ignored\&. At the time this is written (December 2016), the systemd cryptsetup helper doesn\*(Aqt support the keyscript option to /etc/crypttab\&. For the time being, the only option to use keyscripts along with systemd is to force processing of the corresponding crypto devices in the initramfs\&. See the \*(Aqinitramfs\*(Aq option for further information\&.
.sp
All fields of the appropriate crypttab entry are available to the keyscript as exported environment variables:
.PP
CRYPTTAB_NAME
.RS 4
The target name
.RE
.PP
CRYPTTAB_SOURCE
.RS 4
The source device
.RE
.PP
CRYPTTAB_KEY
.RS 4
The key file
.RE
.PP
CRYPTTAB_TRIED
.RS 4
Number of previous tries since start of cryptdisks (counts until maximum number of tries is reached)\&.
.RE
.PP
CRYPTTAB_OPTIONS
.RS 4
A list of exported crypttab options
.RE
.PP
CRYPTTAB_OPTION_<option>
.RS 4
The value of the appropriate crypttab option, with value set to \*(Aqyes\*(Aq in case the option is merely a flag\&.
.RE
.sp
.RE
.PP
\fIkeyslot\fR=<slot>
.RS 4
Key slot (ignored for non\-LUKS devices)\&. See
\fBcryptsetup \-S\fR\&.
.RE
.PP
\fIheader\fR=<path>
.RS 4
Detached header file (ignored for plain dm\-crypt devices)\&. See
\fBcryptsetup \-\-header\fR\&.
.RE
.PP
\fItcrypthidden\fR
.RS 4
Use hidden TCRYPT header (ignored for non\-TCRYPT devices)\&.
.RE
.SH "CHECKSCRIPTS"
.PP
\fIblkid\fR
.RS 4
Checks for any known filesystem\&. Supports a filesystem type as argument via <checkargs>:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no checkargs \- succeeds if any valid filesystem is found on the device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"none" \- succeeds if no valid filesystem is found on the device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"ext4" [or another filesystem type like xfs, swap, crypto_LUKS, \&.\&.\&.] \- succeeds if ext4 filesystem is found on the device\&.
.RE
.RE
.PP
\fIun_blkid\fR
.RS 4
Checks for no known filesystem\&. Supports a filesystem type as argument via <checkargs>:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no checkargs \- succeeds if no valid filesystem is found on the device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"ext4" [or another filesystem type like xfs, swap, crypto_LUKS, \&.\&.\&.] \- succeeds if no ext4 filesystem is found on the device\&.
.RE
.RE
.SH "EXAMPLES"
.PP
.if n \{\
.RS 4
.\}
.nf
# Encrypted swap device
cswap /dev/sda6 /dev/urandom cipher=aes\-xts\-plain64,size=256,hash=sha1,swap

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

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

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

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

# Encrypted disk with interactive password
# \- Twofish as the cipher, RIPEMD\-160 as the hash
cdisk3 /dev/sda3 none cipher=twofish,size=256,hash=ripemd160
   
.fi
.if n \{\
.RE
.\}
.sp
.SH "ENVIRONMENT"
.PP
\fICRYPTDISKS_ENABLE\fR
.RS 4
Set to
\fIyes\fR
to run cryptdisks initscripts at startup\&. Set to
\fIno\fR
to disable cryptdisks initscripts\&. Default is
\fIyes\fR\&.
.RE
.PP
\fICRYPTDISKS_MOUNT\fR
.RS 4
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\&.
.RE
.PP
\fICRYPTDISKS_CHECK\fR
.RS 4
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
\fIcheck\fR
option is given in crypttab with no value\&. See documentation for
\fIcheck\fR
option above for more information\&.
.RE
.PP
\fICRYPTDISKS_PRECHECK\fR
.RS 4
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
\fIprecheck\fR
option is given in crypttab with no value\&. See documentation for
\fIprecheck\fR
option above for more information\&.
.RE
.SH "KNOWN UPGRADE ISSUES"
.sp
The upstream defaults for encryption cipher, hash and keysize have changed several times in the past, and they\*(Aqre expected to change again in future, for example if security issues arise\&. On LUKS devices, the used settings are stored in the LUKS header, and thus don\*(Aqt need to be configured in /etc/crypttab\&. For plain dm\-crypt devices, no information about used cipher, hash and keysize are available at all\&. 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\&.
.SH "SEE ALSO"
\fBcryptsetup\fR(8), \fBcryptdisks_start\fR(8), \fBcryptdisks_stop\fR(8)
.SH "AUTHOR"
.sp
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 Härdeman <david@hardeman\&.nu>\&.