diff options
Diffstat (limited to 'upstream/debian-bookworm/man5/crypttab.5')
| -rw-r--r-- | upstream/debian-bookworm/man5/crypttab.5 | 499 |
1 files changed, 499 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man5/crypttab.5 b/upstream/debian-bookworm/man5/crypttab.5 new file mode 100644 index 00000000..78036c0c --- /dev/null +++ b/upstream/debian-bookworm/man5/crypttab.5 @@ -0,0 +1,499 @@ +'\" t +.\" Title: crypttab +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023-12-18 +.\" Manual: cryptsetup manual +.\" Source: cryptsetup 2:2.6.1-4~deb12u2 +.\" Language: English +.\" +.TH "CRYPTTAB" "5" "2023\-12\-18" "cryptsetup 2:2\&.6\&.1\-4~deb1" "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 devices\&. 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\&. crypttab entries are treated sequentially, so their order matters (dependencies need to listed first)\&. +.sp +Each encrypted device is described on a separate line\&. Fields on each line are separated by tabs or spaces\&. Lines starting with \*(Aq#\*(Aq are comments, and blank lines are ignored\&. Octal sequences \e0\fInum\fR within a field are decoded, which can be used for values containing spaces or special characters\&. A backslash which doesn\*(Aqt start an octal sequence yields undefined behavior\&. +.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 (resp\&. LABEL, PARTUUID and PARTLABEL) is supported as well, using \(lqUUID=<uuid>\(rq (resp\&. \(lqLABEL=<label>\(rq, \(lqPARTUUID=<partuuid>\(rq and \(lqPARTLABEL=<partlabel>\(rq)\&. +.sp +The third field, \fIkey file\fR, describes the file to use as a key for decrypting the data of the \fIsource device\fR\&. In case of a \fIkeyscript\fR, the value of this field is given as argument to the keyscript\&. 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 \fInone\fR, a passphrase will be read interactively from the console\&. In this case, the options check, checkargs and tries may be useful\&. +.sp +The fourth field, \fIoptions\fR, is an optional comma\-separated list of options and/or flags describing the device type (\fIluks\fR, \fItcrypt\fR, \fIbitlk\fR, \fIfvault2\fR, or \fIplain\fR 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 \fIcipher\fR, \fIhash\fR and \fIsize\fR options are required\&. Some options can be changed on active mappings using \fBcryptsetup refresh [<options>] <name>\fR\&. Furthermore some options can be permanently written into metadata of LUKS2 headers using cryptsetup\*(Aqs \fI\-\-persistent\fR flag\&. +.sp +Note that the first three fields are required and that a missing field will lead to unspecified behaviour\&. +.SH "ON DIFFERENT CRYPTTAB FORMATS" +.sp +Please note that there are several independent cryptsetup wrappers with their own \fIcrypttab\fR format\&. This manpage covers Debian\*(Aqs implementation for \fIinitramfs\fR scripts and \fISysVinit\fR init scripts\&. \fIsystemd\fR brings its own \fIcrypttab\fR implementation\&. We try to cover the differences between the \fIsystemd\fR and our implementation in this manpage, but if in doubt, better check the \fIsystemd\fR \fBcrypttab\fR(5) manpage, e\&.g\&. online at \m[blue]\fB\%https://www.freedesktop.org/software/systemd/man/crypttab.html\fR\m[]\&. +.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 +\fIsector\-size\fR=<bytes> +.RS 4 +Sector size\&. See +\fBcryptsetup\fR(8) +for possible values and the default value of this option\&. +.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 +\fIkeyfile\-offset\fR=<keyfile\-offset> +.RS 4 +Specifies the number of bytes to skip at the start of the key file\&. +.RE +.PP +\fIkeyfile\-size\fR=<keyfile\-size> +.RS 4 +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 +\fBcryptsetup \-\-help\fR\&. This option is ignored for plain dm\-crypt devices, as the key file size is then given by the encryption key size (option +\fIsize\fR)\&. +.RE +.PP +\fIkeyslot\fR=<slot>, \fIkey\-slot\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 +\fIverify\fR +.RS 4 +Verify password\&. Uses +\fBcryptsetup \-y\fR\&. +.RE +.PP +\fIreadonly\fR, \fIread\-only\fR +.RS 4 +Set up a read\-only mapping\&. +.RE +.PP +\fItries\fR=<num> +.RS 4 +Try to unlock the device <num> before failing\&. It\*(Aqs particularly useful when using a passphrase or a +\fIkeyscript\fR +that asks for interactive input\&. If you want to disable retries, pass +\(lqtries=1\(rq\&. Default is +\(lq3\(rq\&. Setting +\(lqtries=0\(rq +means infinitive retries\&. +.RE +.PP +\fIdiscard\fR +.RS 4 +Allow using of discards (TRIM) requests for device\&. +.sp +Starting with Debian 10 (Buster), this option is added per default to new dm\-crypt devices by the Debian Installer\&. If you don\*(Aqt care about leaking access patterns (filesystem type, used space) and don\*(Aqt have hidden truecrypt volumes inside this volume, then it should be safe to enable this option\&. See the following warning for further information\&. +.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\&. +.RE +.PP +\fIluks\fR +.RS 4 +Force LUKS mode\&. When this mode is used, the following options are ignored since they are provided by the LUKS header on the device: +\fIcipher=\fR, +\fIhash=\fR, +\fIsize=\fR +.RE +.PP +\fIplain\fR +.RS 4 +Force plain encryption mode\&. +.RE +.PP +\fIbitlk\fR +.RS 4 +Force BITLK (Windows BitLocker\-compatible) mode\&. WARNING: +\fIcrypttab\fR +support is currently experimental\&. +.RE +.PP +\fIfvault2\fR +.RS 4 +Force Apple\*(Aqs FileVault2 mode\&. Only the (legacy) FileVault2 format based on Core Storage and HFS+ filesystem (introduced in MacOS X 10\&.7 Lion) is currently supported; the new version of FileVault based on the APFS filesystem used in recent macOS versions is not supported\&. +.RE +.PP +\fItcrypt\fR +.RS 4 +Use TrueCrypt encryption mode\&. When this mode is used, the following options are ignored since they are provided by the TrueCrypt header on the device or do not apply: +\fIcipher=\fR, +\fIhash=\fR, +\fIkeyfile\-offset=\fR, +\fIkeyfile\-size=\fR, +\fIsize=\fR +.RE +.PP +\fIveracrypt\fR, \fItcrypt\-veracrypt\fR +.RS 4 +Use VeraCrypt extension to TrueCrypt device\&. Only useful in conjunction with +\fItcrypt\fR +option (ignored for non\-TrueCrypt devices)\&. +.RE +.PP +\fItcrypthidden\fR, \fItcrypt\-hidden\fR +.RS 4 +Use hidden TCRYPT header (ignored for non\-TCRYPT devices)\&. +.RE +.PP +\fIsame\-cpu\-crypt\fR +.RS 4 +Perform encryption using the same cpu that IO was submitted on\&. +.RE +.PP +\fIsubmit\-from\-crypt\-cpus\fR +.RS 4 +Disable offloading writes to a separate thread after encryption\&. +.RE +.PP +\fIno\-read\-workqueue\fR, \fIno\-write\-workqueue\fR +.RS 4 +Bypass dm\-crypt internal workqueue and process read or write requests synchronously\&. +.RE +.PP +\fIswap\fR +.RS 4 +Run +\fBmkswap\fR +on the created device\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices\&. +.RE +.PP +\fItmp\fR[=<tmpfs>] +.RS 4 +Run +\fBmkfs\fR +with filesystem type <tmpfs> (or ext4 if omitted) on the created device\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices\&. +.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 closed immediately\&. The program is being run with decrypted volume (target device) as first positional argument and, if the +\fIcheckargs\fR +option is used, its value as second argument\&. See the CHECKSCRIPTS section for more information\&. +.sp +The program is either specified by full path or relative to +/lib/cryptsetup/checks/\&. If omitted, then the value of $CRYPTDISKS_CHECK set in +/etc/default/cryptdisks +is used (blkid +by default)\&. +.sp +This option is specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.RE +.PP +\fIcheckargs\fR=<arguments> +.RS 4 +Give <arguments> as the second argument to the check script\&. See the CHECKSCRIPTS section for more information\&. +.sp +This option is specific to the Debian \fIcrypttab\fR format\&. It\*(Aqs not supported by \fIsystemd\fR\&. +.RE +.PP +\fIinitramfs\fR +.RS 4 +The initramfs hook processes the root device, any resume devices and any devices with the +\fIinitramfs\fR +option set\&. These devices are processed within the initramfs stage of boot\&. As an example, that allows the use of remote unlocking using dropbear\&. +.sp +This option is specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.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\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices and specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.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\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices and specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.RE +.PP +\fIloud\fR +.RS 4 +Be loud\&. Print warnings if a device does not exist\&. This option overrides the option +\fIquiet\fR\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices and specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.RE +.PP +\fIquiet\fR +.RS 4 +Be quiet\&. Don\*(Aqt print warnings if a device does not exist\&. This option overrides the option +\fIloud\fR\&. +.sp +This option is ignored for +\fIinitramfs\fR +devices and specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.RE +.PP +\fIkeyscript\fR=<path> +.RS 4 +The executable at the indicated path is executed with the value of the +\fIthird field\fR +as only argument\&. The keyscript\*(Aqs standard output is passed to cryptsetup as decyption key\&. Its exit status is currently ignored, but no assumption should be made in that regard\&. When used in initramfs, the executable either needs to be self\-contained (i\&.e\&. doesn\*(Aqt rely on any external program which is not present in the initramfs environment) or the dependencies have to added to the initramfs image by other means\&. The program is either specified by full path or relative to +/lib/cryptsetup/scripts/\&. +.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 +This option is specific to the Debian +\fIcrypttab\fR +format\&. It\*(Aqs not supported by +\fIsystemd\fR\&. +.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, _CRYPTTAB_NAME +.RS 4 +The target name (after resp\&. before octal sequence decoding)\&. +.RE +.PP +CRYPTTAB_SOURCE, _CRYPTTAB_SOURCE +.RS 4 +The source device (after resp\&. before octal sequence decoding and device resolution)\&. +.RE +.PP +CRYPTTAB_KEY, _CRYPTTAB_KEY +.RS 4 +The value of the third field (after resp\&. before octal sequence decoding)\&. +.RE +.PP +CRYPTTAB_OPTIONS, _CRYPTTAB_OPTIONS +.RS 4 +A list of exported crypttab options (after resp\&. before octal sequence decoding)\&. +.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\&. For option aliases, such as \*(Aqreadonly\*(Aq and \*(Aqread\-only\*(Aq, the variable name refers to the first alternative listed (thus \*(AqCRYPTTAB_OPTION_readonly\*(Aq in that case)\&. If the crypttab option name contains \*(Aq\-\*(Aq characters, then they are replaced with \*(Aq_\*(Aq in the exported variable name\&. For instance, the value of the \*(AqCRYPTTAB_OPTION_keyfile_offset\*(Aq environment variable is set to the value of the \*(Aqkeyfile\-offset\*(Aq crypttab option\&. +.RE +.PP +CRYPTTAB_TRIED +.RS 4 +Number of previous tries since start of cryptdisks (counts until maximum number of tries is reached)\&. +.RE +.sp +.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 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 + +.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 +.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), /usr/share/doc/cryptsetup\-initramfs/README\&.initramfs\&.gz +.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>, David Härdeman <david@hardeman\&.nu> and Jonas Meurer <jonas@freesources\&.org>\&. |