man/common_options.adoc

   1 == OPTIONS
   2
   3 ifdef::ACTION_REENCRYPT[]
   4 *--block-size* _value_ *(LUKS1 only)*::
   5 Use re-encryption block size of _value_ in MiB.
   6 +
   7 Values can be between 1 and 64 MiB.
   8 endif::[]
   9
  10 ifdef::ACTION_REENCRYPT[]
  11 *--use-directio (LUKS1 only)*::
  12 Use direct-io (O_DIRECT) for all read/write data operations related
  13 to block device undergoing reencryption.
  14 +
  15 Useful if direct-io operations perform better than normal buffered
  16 operations (e.g. in virtual environments).
  17 endif::[]
  18
  19 ifdef::ACTION_REENCRYPT[]
  20 *--use-fsync (LUKS1 only)*::
  21 Use fsync call after every written block. This applies for reencryption
  22 log files as well.
  23 endif::[]
  24
  25 ifdef::ACTION_REENCRYPT[]
  26 *--write-log (LUKS1 only)*::
  27 Update log file after every block write. This can slow down reencryption
  28 but will minimize data loss in the case of system crash.
  29 endif::[]
  30
  31 ifdef::ACTION_ISLUKS[]
  32 *--verbose, -v*::
  33 Print more information on command execution.
  34 endif::[]
  35
  36 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSKILLSLOT,ACTION_ISLUKS,ACTION_LUKSDUMP,ACTION_LUKSUUID,ACTION_CONVERT,ACTION_REPAIR,ACTION_REENCRYPT[]
  37 *--type <device-type>*::
  38 ifndef::ACTION_REENCRYPT[]
  39 Specifies required device type, for more info read _BASIC ACTIONS_ section in *cryptsetup*(8).
  40 endif::[]
  41 ifdef::ACTION_REENCRYPT[]
  42 Specifies required (encryption mode) or expected (other modes) LUKS format. Accepts only _luks1_ or _luks2_.
  43 endif::[]
  44 endif::[]
  45
  46 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_TCRYPTDUMP,ACTION_BENCHMARK,ACTION_REENCRYPT[]
  47 *--hash, -h* _<hash-spec>_::
  48 ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[]
  49 Specifies the passphrase hash. Applies to _plain_ and _loopaes_ device types only.
  50 +
  51 For _tcrypt_ device type, it restricts checked PBKDF2 variants when looking for header.
  52 endif::[]
  53 ifdef::ACTION_LUKSFORMAT[]
  54 Specifies the hash used in the LUKS key setup scheme and volume key
  55 digest.
  56 endif::[]
  57 ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[]
  58 The specified hash is used for PBKDF2 and AF splitter.
  59 endif::[]
  60 ifdef::ACTION_REENCRYPT[]
  61 *LUKS1:*
  62 Specifies the hash used in the LUKS1 key setup scheme and volume key digest.
  63 +
  64 *NOTE*: if this parameter is not specified, default hash algorithm is always used
  65 for new LUKS1 device header.
  66 +
  67 *LUKS2:* Ignored unless new keyslot pbkdf algorithm is set to PBKDF2 (see --pbkdf).
  68 endif::[]
  69 +
  70 ifdef::ACTION_LUKSFORMAT[]
  71 The hash algorithm must provide at least 160 bits of output.
  72 Do not use a non-crypto hash like *xxhash* as this breaks security.
  73 Use _cryptsetup --help_ to show the defaults.
  74 endif::[]
  75 endif::[]
  76
  77 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_TCRYPTDUMP,ACTION_BENCHMARK[]
  78 *--cipher, -c* _<cipher-spec>_::
  79 ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[]
  80 Set the cipher specification string for _plain_ device type.
  81 +
  82 For _tcrypt_ device type it restricts checked cipher chains when looking for header.
  83 endif::[]
  84 ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_TCRYPTDUMP[]
  85 Set the cipher specification string.
  86 endif::[]
  87 ifdef::ACTION_REENCRYPT[]
  88 *LUKS2*:
  89 Set the cipher specification string for data segment only.
  90 +
  91 *LUKS1*:
  92 Set the cipher specification string for data segment and keyslots.
  93 +
  94 *NOTE*: In encrypt mode, if cipher specification is omitted the default cipher is applied.
  95 In reencrypt mode, if no new cipher specification is requested, the existing cipher will remain
  96 in use. Unless the existing cipher was "cipher_null". In that case default cipher would
  97 be applied as in encrypt mode.
  98 endif::[]
  99 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 100 +
 101 _cryptsetup --help_ shows the compiled-in defaults.
 102 +
 103 If a hash is part of the cipher specification, then it is used as part
 104 of the IV generation. For example, ESSIV needs a hash function, while
 105 "plain64" does not and hence none is specified.
 106 +
 107 For XTS mode you can optionally set a key size of 512 bits with the -s
 108 option. Key size for XTS mode is twice that for other modes for the same
 109 security level.
 110 endif::[]
 111 endif::[]
 112
 113 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_REPAIR,ACTION_TCRYPTDUMP,ACTION_REENCRYPT[]
 114 *--verify-passphrase, -y*::
 115 When interactively asking for a passphrase, ask for it twice and
 116 complain if both inputs do not match.
 117 ifdef::ACTION_OPEN[]
 118 Advised when creating a _plain_ type mapping for the first time.
 119 endif::[]
 120 Ignored on input from file or stdin.
 121 endif::[]
 122
 123 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[]
 124 *--key-file, -d* _name_::
 125 Read the passphrase from file.
 126 +
 127 If the name given is "-", then the passphrase will be read from stdin.
 128 In this case, reading will not stop at newline characters.
 129 +
 130 ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY[]
 131 The passphrase supplied via --key-file is always the passphrase for existing
 132 keyslot requested by the command.
 133 +
 134 If you want to set a new passphrase via key file, you have to use a
 135 positional argument or parameter --new-keyfile.
 136 +
 137 endif::[]
 138 ifdef::ACTION_OPEN[]
 139 *NOTE:* With _plain_ device type, the passphrase obtained via --key-file option is
 140 passed directly in dm-crypt. Unlike the interactive mode (stdin)
 141 where digest (--hash option) of the passphrase is passed in dm-crypt instead.
 142 +
 143 endif::[]
 144 ifndef::ACTION_REENCRYPT[]
 145 See section _NOTES ON PASSPHRASE PROCESSING_ in *cryptsetup*(8) for more information.
 146 endif::[]
 147 ifdef::ACTION_REENCRYPT[]
 148 *WARNING:* --key-file option can be used only if there is only one active keyslot,
 149 or alternatively, also if --key-slot option is specified (then all other keyslots
 150 will be disabled in new LUKS device).
 151 +
 152 If this option is not used, cryptsetup will ask for all active keyslot
 153 passphrases.
 154 endif::[]
 155 endif::[]
 156
 157 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[]
 158 *--keyfile-offset* _value_::
 159 Skip _value_ bytes at the beginning of the key file.
 160 endif::[]
 161
 162 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_LUKSADDKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_BITLKDUMP[]
 163 *--keyfile-size, -l* _value_::
 164 Read a maximum of _value_ bytes from the key file. The default is to
 165 read the whole file up to the compiled-in maximum that can be queried
 166 with --help. Supplying more data than the compiled-in maximum aborts
 167 the operation.
 168 +
 169 This option is useful to cut trailing newlines, for example. If
 170 --keyfile-offset is also given, the size count starts after the offset.
 171 endif::[]
 172
 173 ifdef::ACTION_LUKSADDKEY[]
 174 *--new-keyfile* _name_::
 175 Read the passphrase for a new keyslot from file.
 176 +
 177 If the name given is "-", then the passphrase will be read from stdin.
 178 In this case, reading will not stop at newline characters.
 179 +
 180 This is alternative method to positional argument when adding new
 181 passphrase via kefile.
 182 endif::[]
 183
 184 ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[]
 185 *--new-keyfile-offset* _value_::
 186 Skip _value_ bytes at the start when adding a new passphrase from key
 187 file.
 188 endif::[]
 189
 190 ifdef::ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY[]
 191 *--new-keyfile-size* _value_::
 192 Read a maximum of _value_ bytes when adding a new passphrase from key
 193 file. The default is to read the whole file up to
 194 the compiled-in maximum length that can be queried with --help.
 195 Supplying more than the compiled in maximum aborts the operation. When
 196 --new-keyfile-offset is also given, reading starts after the offset.
 197 endif::[]
 198
 199 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_BITLKDUMP,ACTION_REENCRYPT[]
 200 *--volume-key-file, --master-key-file (OBSOLETE alias)*::
 201 ifndef::ACTION_REENCRYPT[]
 202 Use a volume key stored in a file.
 203 endif::[]
 204 ifdef::ACTION_FORMAT[]
 205 +
 206 This allows creating a LUKS header with this specific
 207 volume key. If the volume key was taken from an existing LUKS header and
 208 all other parameters are the same, then the new header decrypts the data
 209 encrypted with the header the volume key was taken from. +
 210 endif::[]
 211 ifdef::ACTION_LUKSDUMP,ACTION_BITLKDUMP[]
 212 The volume key is stored in a file instead of being printed out to standard output. +
 213 endif::[]
 214 ifdef::ACTION_LUKSADDKEY[]
 215 This allows adding a new keyslot without having to know passphrase to existing one.
 216 It may be also used when no keyslot is active.
 217 +
 218 endif::[]
 219 ifdef::ACTION_OPEN[]
 220 This allows one to open _luks_ and _bitlk_ device types without giving a passphrase. +
 221 endif::[]
 222 ifdef::ACTION_REENCRYPT[]
 223 Use (set) new volume key stored in a file. +
 224 endif::[]
 225 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_REENCRYPT[]
 226 *WARNING:* If you create your own volume key, you need to make sure to
 227 do it right. Otherwise, you can end up with a low-entropy or otherwise
 228 partially predictable volume key which will compromise security.
 229 endif::[]
 230 endif::[]
 231
 232 ifdef::ACTION_LUKSDUMP[]
 233 *--dump-json-metadata*::
 234 For _luksDump_ (LUKS2 only) this option prints content of LUKS2 header
 235 JSON metadata area.
 236 endif::[]
 237
 238 ifdef::ACTION_LUKSDUMP,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[]
 239 *--dump-volume-key, --dump-master-key (OBSOLETE alias)*::
 240 Print the volume key in the displayed information. Use with care,
 241 as the volume key can be used to bypass
 242 the passphrases, see also option --volume-key-file.
 243 endif::[]
 244
 245 ifdef::ACTION_TOKEN[]
 246 *--json-file*::
 247 Read token JSON from a file or write token to it. --json-file=- reads JSON from
 248 standard input or writes it to standard output respectively.
 249 endif::[]
 250
 251 ifdef::ACTION_TOKEN[]
 252 *--token-replace*::
 253 Replace an existing token when adding or importing a token with the
 254 --token-id option.
 255 endif::[]
 256
 257 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 258 *--use-random*::
 259 *--use-urandom*::
 260 ifdef::ACTION_REENCRYPT[]
 261 Define which kernel random number generator will be used to create the volume key.
 262 endif::[]
 263 ifndef::ACTION_REENCRYPT[]
 264 For _luksFormat_ these options define which kernel random number
 265 generator will be used to create the volume key (which is a long-term
 266 key).
 267 +
 268 See *NOTES ON RANDOM NUMBER GENERATORS* in *cryptsetup*(8) for more
 269 information. Use _cryptsetup --help_ to show the compiled-in default random
 270 number generator.
 271 +
 272 *WARNING:* In a low-entropy situation (e.g. in an embedded system) and older
 273 kernels, both selections are problematic. Using /dev/urandom can lead to weak keys.
 274 Using /dev/random can block a long time, potentially forever, if not
 275 enough entropy can be harvested by the kernel.
 276 endif::[]
 277 endif::[]
 278
 279 ifdef::ACTION_REENCRYPT[]
 280 *--keep-key*::
 281 *LUKS2*:
 282 Do not change effective volume key and change other parameters provided
 283 it is requested.
 284 +
 285 *LUKS1*:
 286 Reencrypt only the LUKS1 header and keyslots. Skips data in-place reencryption.
 287 endif::[]
 288
 289 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSDUMP,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_CONFIG,ACTION_TOKEN,ACTION_REPAIR,ACTION_REENCRYPT[]
 290 *--key-slot, -S <0-N>*::
 291 ifdef::ACTION_LUKSADDKEY[]
 292 When used together with parameter --new-key-slot this option allows you to specify which
 293 key slot is selected for unlocking volume key.
 294 +
 295 *NOTE:* This option is ignored if existing volume key gets unlocked
 296 via LUKS2 token (--token-id, --token-type or --token-only parameters) or
 297 when volume key is provided directly via --volume-key-file parameter.
 298 +
 299 *NOTE:* To maintain backward compatibility, without --new-key-slot parameter,
 300 this option allows you to specify which key slot is selected for the new key.
 301 endif::[]
 302 ifndef::ACTION_OPEN,ACTION_LUKSADDKEY[]
 303 For LUKS operations that add key material, this option allows you to
 304 specify which key slot is selected for the new key.
 305 endif::[]
 306 ifdef::ACTION_OPEN[]
 307 This option selects a specific key-slot to
 308 compare the passphrase against. If the given passphrase would only
 309 match a different key-slot, the operation fails.
 310 endif::[]
 311 +
 312 ifdef::ACTION_REENCRYPT[]
 313 For reencryption mode it selects specific keyslot (and passphrase) that can be used to unlock new volume key.
 314 If used all other keyslots get removed after reencryption operation is finished.
 315 +
 316 endif::[]
 317 The maximum number of key slots depends on the LUKS version. LUKS1 can have up
 318 to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area
 319 size and key size, but a valid key slot ID can always be between 0 and
 320 31 for LUKS2.
 321 endif::[]
 322
 323 ifdef::ACTION_LUKSADDKEY[]
 324 *--new-key-slot <0-N>*::
 325 This option allows you to specify which key slot is selected for
 326 the new key.
 327 +
 328 *NOTE:* When used this option affects --key-slot option.
 329 +
 330 The maximum number of key slots depends on the LUKS version. LUKS1 can have up
 331 to 8 key slots. LUKS2 can have up to 32 key slots based on key slot area
 332 size and key size, but a valid key slot ID can always be between 0 and
 333 31 for LUKS2.
 334 endif::[]
 335
 336 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT,ACTION_BENCHMARK,ACTION_LUKSADDKEY[]
 337 *--key-size, -s* _bits_::
 338 ifndef::ACTION_LUKSADDKEY[]
 339 Sets key size in _bits_. The argument has to be a multiple of 8. The
 340 possible key-sizes are limited by the cipher and mode used.
 341 +
 342 See /proc/crypto for more information. Note that key-size in
 343 /proc/crypto is stated in bytes.
 344 +
 345 endif::[]
 346 ifdef::ACTION_LUKSADDKEY[]
 347 Provide volume key size in _bits_. The argument has to be a multiple of 8.
 348 +
 349 This option is required when parameter --volume-key-file is used to provide
 350 current volume key. Also, it is used when new unbound keyslot is created by
 351 specifying --unbound parameter.
 352 endif::[]
 353 ifdef::ACTION_OPEN[]
 354 This option can be used for _plain_ device type only.
 355 endif::[]
 356 ifndef::ACTION_REENCRYPT,ACTION_OPEN,ACTION_LUKSADDKEY[]
 357 This option can be used for _open --type plain_ or _luksFormat_. All
 358 other LUKS actions will use the key-size specified in the LUKS header.
 359 Use _cryptsetup --help_ to show the compiled-in defaults.
 360 endif::[]
 361 ifdef::ACTION_REENCRYPT[]
 362 *LUKS1*:
 363 If you are increasing key size, there must be enough space in the LUKS header
 364 for enlarged keyslots (data offset must be large enough) or reencryption
 365 cannot be performed.
 366 +
 367 If there is not enough space for keyslots with new key size,
 368 you can destructively shrink device with --reduce-device-size option.
 369 endif::[]
 370 endif::[]
 371
 372 ifdef::ACTION_OPEN,ACTION_RESIZE[]
 373 *--size, -b <number of 512 byte sectors>*::
 374 Set the size of the device in sectors of 512 bytes.
 375 ifdef::ACTION_OPEN[]
 376 Usable only with _plain_ device type.
 377 endif::[]
 378 endif::[]
 379
 380 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 381 *--offset, -o <number of 512 byte sectors>*::
 382 Start offset in the backend device in 512-byte sectors.
 383 ifdef::ACTION_OPEN[]
 384 This option is only relevant with plain or loopaes device types.
 385 endif::[]
 386 ifdef::ACTION_REENCRYPT[]
 387 This option is only relevant for the encrypt mode.
 388 endif::[]
 389 +
 390 ifndef::ACTION_OPEN[]
 391 The --offset option sets the data offset (payload) of data
 392 device and must be aligned to 4096-byte sectors (must be multiple of
 393 8). This option cannot be combined with --align-payload option.
 394 endif::[]
 395 endif::[]
 396
 397 ifdef::ACTION_OPEN[]
 398 *--skip, -p <number of 512 byte sectors>*::
 399 Start offset used in IV calculation in 512-byte sectors (how many
 400 sectors of the encrypted data to skip at the beginning). This option
 401 is only relevant with plain or loopaes device types.
 402 +
 403 Hence, if --offset _n_, and --skip _s_, sector _n_ (the first sector of
 404 the encrypted device) will get a sector number of _s_ for the IV
 405 calculation.
 406 endif::[]
 407
 408 ifdef::ACTION_OPEN,ACTION_REENCRYPT,ACTION_RESIZE[]
 409 *--device-size* _size[units]_::
 410 ifndef::ACTION_RESIZE[]
 411 Instead of real device size, use specified value.
 412 endif::[]
 413 ifdef::ACTION_RESIZE[]
 414 Sets new size of the device. If unset real device size is used.
 415 endif::[]
 416 ifdef::ACTION_OPEN[]
 417 Usable only with _plain_ device type.
 418 endif::[]
 419 ifdef::ACTION_REENCRYPT[]
 420 It means that only specified area (from the start of the device
 421 to the specified size) will be reencrypted.
 422 +
 423 *WARNING:* This is destructive operation. Data beyond --device-size limit may
 424 be lost after operation gets finished.
 425 endif::[]
 426 +
 427 If no unit suffix is specified, the size is in bytes.
 428 +
 429 Unit suffix can be S for 512 byte sectors, K/M/G/T (or KiB,MiB,GiB,TiB)
 430 for units with 1024 base or KB/MB/GB/TB for 1000 base (SI scale).
 431 endif::[]
 432
 433 ifdef::ACTION_OPEN[]
 434 *--readonly, -r*::
 435 set up a read-only mapping.
 436 endif::[]
 437
 438 ifdef::ACTION_OPEN[]
 439 *--shared*::
 440 Creates an additional mapping for one common ciphertext device.
 441 Arbitrary mappings are supported. This option is only relevant for the
 442 _plain_ device type. Use --offset, --size and --skip to specify
 443 the mapped area.
 444 endif::[]
 445
 446 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[]
 447 *--pbkdf <PBKDF spec>*::
 448 Set Password-Based Key Derivation Function (PBKDF) algorithm for LUKS
 449 keyslot. The PBKDF can be: _pbkdf2_ (for PBKDF2 according to RFC2898),
 450 _argon2i_ for Argon2i or _argon2id_ for Argon2id (see
 451 https://www.cryptolux.org/index.php/Argon2[Argon2] for more info).
 452 +
 453 For LUKS1, only PBKDF2 is accepted (no need to use this option). The
 454 default PBKDF for LUKS2 is set during compilation time and is available
 455 in _cryptsetup --help_ output.
 456 +
 457 A PBKDF is used for increasing dictionary and brute-force attack cost
 458 for keyslot passwords. The parameters can be time, memory and parallel
 459 cost.
 460 +
 461 For PBKDF2, only time cost (number of iterations) applies. For
 462 Argon2i/id, there is also memory cost (memory required during the
 463 process of key derivation) and parallel cost (number of threads that run
 464 in parallel during the key derivation.
 465 +
 466 Note that increasing memory cost also increases time, so the final
 467 parameter values are measured by a benchmark. The benchmark tries to
 468 find iteration time (_--iter-time_) with required memory cost
 469 _--pbkdf-memory_. If it is not possible, the memory cost is decreased as
 470 well. The parallel cost _--pbkdf-parallel_ is constant and is checked
 471 against available CPU cores.
 472 +
 473 You can see all PBKDF parameters for particular LUKS2 keyslot with
 474 *cryptsetup-luksDump*(8) command.
 475 +
 476 *NOTE:* If you do not want to use benchmark and want to specify all
 477 parameters directly, use _--pbkdf-force-iterations_ with
 478 _--pbkdf-memory_ and _--pbkdf-parallel_. This will override the values
 479 without benchmarking. Note it can cause extremely long unlocking time.
 480 Use only in specific cases, for example, if you know that the formatted
 481 device will be used on some small embedded system.
 482 +
 483 *MINIMAL AND MAXIMAL PBKDF COSTS:* For *PBKDF2*, the minimum iteration
 484 count is 1000 and maximum is 4294967295 (maximum for 32bit unsigned
 485 integer). Memory and parallel costs are unused for PBKDF2. For *Argon2i*
 486 and *Argon2id*, minimum iteration count (CPU cost) is 4 and maximum is
 487 4294967295 (maximum for 32bit unsigned integer). Minimum memory cost is
 488 32 KiB and maximum is 4 GiB. (Limited by addressable memory on some CPU
 489 platforms.) If the memory cost parameter is benchmarked (not specified
 490 by a parameter) it is always in range from 64 MiB to 1 GiB. The parallel
 491 cost minimum is 1 and maximum 4 (if enough CPUs cores are available,
 492 otherwise it is decreased).
 493 endif::[]
 494
 495 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[]
 496 *--iter-time, -i <number of milliseconds>*::
 497 ifndef::ACTION_REENCRYPT[]
 498 The number of milliseconds to spend with PBKDF passphrase processing.
 499 Specifying 0 as parameter selects the compiled-in default.
 500 endif::[]
 501 ifdef::ACTION_REENCRYPT[]
 502 The number of milliseconds to spend with PBKDF passphrase processing for the
 503 new LUKS header.
 504 endif::[]
 505 endif::[]
 506
 507 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[]
 508 *--pbkdf-memory <number>*::
 509 Set the memory cost for PBKDF (for Argon2i/id the number represents
 510 kilobytes). Note that it is maximal value, PBKDF benchmark or
 511 available physical memory can decrease it. This option is not
 512 available for PBKDF2.
 513 endif::[]
 514
 515 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT,ACTION_BENCHMARK[]
 516 *--pbkdf-parallel <number>*::
 517 Set the parallel cost for PBKDF (number of threads, up to 4). Note
 518 that it is maximal value, it is decreased automatically if CPU online
 519 count is lower. This option is not available for PBKDF2.
 520 endif::[]
 521
 522 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[]
 523 *--pbkdf-force-iterations <num>*::
 524 Avoid PBKDF benchmark and set time cost (iterations) directly. It can
 525 be used for LUKS/LUKS2 device only. See _--pbkdf_ option for more
 526 info.
 527 endif::[]
 528
 529 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 530 *--progress-frequency* _seconds_::
 531 ifndef::ACTION_REENCRYPT[]
 532 Print separate line every _seconds_ with wipe progress.
 533 endif::[]
 534 ifdef::ACTION_REENCRYPT[]
 535 Print separate line every _seconds_ with reencryption progress.
 536 endif::[]
 537 endif::[]
 538
 539 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 540 *--progress-json*::
 541 Prints progress data in JSON format suitable mostly for machine
 542 processing. It prints separate line every half second (or based on
 543 _--progress-frequency_ value). The JSON output looks as follows during
 544 progress (except it's compact single line):
 545 +
 546 ....
 547 {
 548   "device":"/dev/sda"       // backing device or file
 549   "device_bytes":"8192",    // bytes of I/O so far
 550   "device_size":"44040192", // total bytes of I/O to go
 551   "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
 552   "eta_ms":"2520012"        // estimated time to finish an operation in milliseconds
 553   "time_ms":"5561235"       // total time spent in IO operation in milliseconds
 554 }
 555 ....
 556 +
 557 Note on numbers in JSON output: Due to JSON parsers limitations all
 558 numbers are represented in a string format due to need of full 64bit
 559 unsigned integers.
 560 endif::[]
 561
 562 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_LUKSREMOVEKEY,ACTION_LUKSKILLSLOT,ACTION_LUKSDUMP,ACTION_REENCRYPT,ACTION_REPAIR,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TCRYPTDUMP,ACTION_BITLKDUMP[]
 563 *--timeout, -t <number of seconds>*::
 564 The number of seconds to wait before timeout on passphrase input via
 565 terminal. It is relevant every time a passphrase is asked.
 566 It has no effect if used in conjunction with --key-file.
 567 +
 568 This option is useful when the system should not stall if the user
 569 does not input a passphrase, e.g. during boot. The default is a value
 570 of 0 seconds, which means to wait forever.
 571 endif::[]
 572
 573 ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_REENCRYPT[]
 574 *--tries, -T*::
 575 How often the input of the passphrase shall be retried. The default is 3 tries.
 576 endif::[]
 577
 578 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 579 *--align-payload <number of 512 byte sectors>*::
 580 Align payload at a boundary of _value_ 512-byte sectors.
 581 +
 582 If not specified, cryptsetup tries to use the topology info provided by
 583 the kernel for the underlying device to get the optimal alignment. If
 584 not available (or the calculated value is a multiple of the default)
 585 data is by default aligned to a 1MiB boundary (i.e. 2048 512-byte
 586 sectors).
 587 +
 588 For a detached LUKS header, this option specifies the offset on the data
 589 device. See also the --header option.
 590 +
 591 *WARNING:* This option is DEPRECATED and has often unexpected impact to
 592 the data offset and keyslot area size (for LUKS2) due to the complex
 593 rounding. For fixed data device offset use _--offset_ option instead.
 594 endif::[]
 595
 596 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSUUID,ACTION_REENCRYPT[]
 597 *--uuid <UUID>*::
 598 ifndef::ACTION_REENCRYPT[]
 599 Use the provided _UUID_ for the _luksFormat_ command instead of
 600 generating a new one. Changes the existing _UUID_ when used with the
 601 _luksUUID_ command.
 602 +
 603 endif::[]
 604 ifdef::ACTION_REENCRYPT[]
 605 When used in encryption mode use the provided _UUID_ for the new LUKS header
 606 instead of generating a new one.
 607 +
 608 *LUKS1 (only in decryption mode)*:
 609 To find out what _UUID_ to pass look for temporary files LUKS-_UUID_.[|log|org|new]
 610 of the interrupted decryption process.
 611 +
 612 endif::[]
 613 The _UUID_ must be provided in the standard UUID format, e.g.
 614 12345678-1234-1234-1234-123456789abc.
 615 endif::[]
 616
 617 ifdef::ACTION_OPEN,ACTION_REFRESH[]
 618 *--allow-discards*::
 619 Allow the use of discard (TRIM) requests for the device. This is also not
 620 supported for LUKS2 devices with data integrity protection.
 621 +
 622 *WARNING:* This command can have a negative security impact because it
 623 can make filesystem-level operations visible on the physical device. For
 624 example, information leaking filesystem type, used space, etc. may be
 625 extractable from the physical device if the discarded blocks can be
 626 located later. If in doubt, do not use it.
 627 +
 628 A kernel version of 3.1 or later is needed. For earlier kernels, this
 629 option is ignored.
 630 endif::[]
 631
 632 ifdef::ACTION_REFRESH,ACTION_OPEN[]
 633 *--perf-same_cpu_crypt*::
 634 Perform encryption using the same cpu that IO was submitted on. The
 635 default is to use an unbound workqueue so that encryption work is
 636 automatically balanced between available CPUs.
 637 +
 638 *NOTE:* This option is available only for low-level dm-crypt performance
 639 tuning, use only if you need a change to default dm-crypt behaviour.
 640 Needs kernel 4.0 or later.
 641 endif::[]
 642
 643 ifdef::ACTION_REFRESH,ACTION_OPEN[]
 644 *--perf-submit_from_crypt_cpus*::
 645 Disable offloading writes to a separate thread after encryption. There
 646 are some situations where offloading write bios from the encryption
 647 threads to a single thread degrades performance significantly. The
 648 default is to offload write bios to the same thread.
 649 +
 650 *NOTE:* This option is available only for low-level dm-crypt performance
 651 tuning, use only if you need a change to default dm-crypt behaviour.
 652 Needs kernel 4.0 or later.
 653 endif::[]
 654
 655 ifdef::ACTION_REFRESH,ACTION_OPEN[]
 656 *--perf-no_read_workqueue, --perf-no_write_workqueue*::
 657 Bypass dm-crypt internal workqueue and process read or write requests
 658 synchronously.
 659 +
 660 *NOTE:* These options are available only for low-level dm-crypt
 661 performance tuning, use only if you need a change to default dm-crypt
 662 behaviour. Needs kernel 5.9 or later.
 663 endif::[]
 664
 665 ifdef::ACTION_OPEN[]
 666 *--test-passphrase*::
 667 Do not activate the device, just verify passphrase. The device mapping name is
 668 not mandatory if this option is used.
 669 endif::[]
 670
 671 ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP[]
 672 *--header <device or file storing the LUKS header>*::
 673 ifndef::ACTION_OPEN[]
 674 Use a detached (separated) metadata device or file where the LUKS
 675 header is stored. This option allows one to store ciphertext and LUKS
 676 header on different devices.
 677 +
 678 endif::[]
 679 ifdef::ACTION_OPEN[]
 680 Specify detached (separated) metadata device or file where the header is stored.
 681 +
 682 *WARNING:* There is no check whether the ciphertext device specified
 683 actually belongs to the header given. In fact, you can specify an
 684 arbitrary device as the ciphertext device with the --header option.
 685 Use with care.
 686 endif::[]
 687 ifndef::ACTION_REENCRYPT[]
 688 ifdef::ACTION_LUKSFORMAT[]
 689 With a file name as the argument to --header, the file
 690 will be automatically created if it does not exist. See the cryptsetup
 691 FAQ for header size calculation.
 692 +
 693 The --align-payload option is taken as absolute sector alignment on ciphertext
 694 device and can be zero.
 695 endif::[]
 696 ifndef::ACTION_LUKSFORMAT,ACTION_OPEN[]
 697 For commands that change the LUKS header (e.g. _luksAddKey_),
 698 specify the device or file with the LUKS header directly as the LUKS
 699 device.
 700 endif::[]
 701 endif::[]
 702 ifdef::ACTION_REENCRYPT[]
 703 If used with --encrypt/--new option, the header file will be created (or overwritten).
 704 Use with care.
 705 +
 706 *LUKS2*:
 707 For decryption mode the option may be used to export original LUKS2 header
 708 to a detached file. The passed future file must not exist at the time
 709 of initializing the decryption operation. This frees space in head of data
 710 device so that data can be moved at original LUKS2 header location. Later on
 711 decryption operation continues as if the ordinary detached header was passed.
 712 +
 713 *WARNING:* Never put exported header file in a filesystem on top of device
 714 you are about to decrypt! It would cause a deadlock.
 715 endif::[]
 716 endif::[]
 717
 718 ifdef::ACTION_LUKSHEADERBACKUP,ACTION_LUKSHEADERRESTORE[]
 719 *--header-backup-file <file>*::
 720 Specify file with header backup file.
 721 endif::[]
 722
 723 ifdef::ACTION_REENCRYPT[]
 724 *--force-offline-reencrypt (LUKS2 only)*::
 725 Bypass active device auto-detection and enforce offline reencryption.
 726 +
 727 This option is useful especially for reencryption of LUKS2 images put in
 728 files (auto-detection is not reliable in this scenario).
 729 +
 730 It may also help in case active device auto-detection on particular
 731 data device does not work or report errors.
 732 +
 733 *WARNING:* Use with extreme caution! This may destroy data if the device
 734 is activated and/or actively used.
 735 endif::[]
 736
 737 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[]
 738 *--force-password*::
 739 Do not use password quality checking for new LUKS passwords.
 740 +
 741 This option is ignored if cryptsetup is built without password
 742 quality checking support.
 743 +
 744 For more info about password quality check, see the manual page for
 745 *pwquality.conf(5)* and *passwdqc.conf(5)*.
 746 endif::[]
 747
 748 ifdef::ACTION_CLOSE[]
 749 *--deferred*::
 750 Defers device removal in _close_ command until the last user closes
 751 it.
 752 endif::[]
 753
 754 ifdef::ACTION_CLOSE[]
 755 *--cancel-deferred*::
 756 Removes a previously configured deferred device removal in _close_
 757 command.
 758 endif::[]
 759
 760 ifdef::ACTION_OPEN,ACTION_LUKSRESUME,ACTION_RESIZE,ACTION_TOKEN[]
 761 *--disable-external-tokens*::
 762 Disable loading of plugins for external LUKS2 tokens.
 763 endif::[]
 764
 765 ifndef::ACTION_BENCHMARK,ACTION_BITLKDUMP,ACTION_TCRYPTDUMP[]
 766 *--disable-locks*::
 767 Disable lock protection for metadata on disk. This option is valid
 768 only for LUKS2 and ignored for other formats.
 769 +
 770 ifdef::ACTION_REENCRYPT[]
 771 *NOTE:* With locking disabled LUKS2 images in files can be fully (re)encrypted
 772 offline without need for super user privileges provided used block ciphers are
 773 available in crypto backend.
 774 +
 775 endif::[]
 776 *WARNING:* Do not use this option unless you run cryptsetup in a
 777 restricted environment where locking is impossible to perform (where
 778 /run directory cannot be used).
 779 endif::[]
 780
 781 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_REFRESH,ACTION_LUKSFORMAT,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_REENCRYPT[]
 782 *--disable-keyring*::
 783 Do not load volume key in kernel keyring and store it directly in the
 784 dm-crypt target instead. This option is supported only for the LUKS2 type.
 785 endif::[]
 786
 787 ifdef::ACTION_TOKEN[]
 788 *--key-description <text>*::
 789 Set key description in keyring for use with _token_ command.
 790 endif::[]
 791
 792 ifdef::ACTION_CONFIG[]
 793 *--priority <normal|prefer|ignore>*::
 794 Set a priority for LUKS2 keyslot. The _prefer_ priority marked slots
 795 are tried before _normal_ priority. The _ignored_ priority means, that
 796 slot is never used, if not explicitly requested by _--key-slot_
 797 option.
 798 endif::[]
 799
 800 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_TOKEN,ACTION_LUKSADDKEY[]
 801 *--token-id*::
 802 ifndef::ACTION_TOKEN,ACTION_LUKSADDKEY[]
 803 Specify what token to use and allow token PIN prompt to take precedence over interative
 804 keyslot passphrase prompt. If omitted, all available tokens (not protected by PIN)
 805 will be checked before proceeding further with passphrase prompt.
 806 endif::[]
 807 ifdef::ACTION_LUKSADDKEY[]
 808 Specify what token to use when unlocking existing keyslot to get volume key.
 809 endif::[]
 810 ifdef::ACTION_TOKEN[]
 811 Specify token number. If omitted, first unused token id is used when adding or importing
 812 new token.
 813 endif::[]
 814 endif::[]
 815
 816 ifdef::ACTION_LUKSADDKEY[]
 817 *--new-token-id*::
 818 Specify what token to use to get the passphrase for a new keyslot.
 819 endif::[]
 820
 821 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[]
 822 *--token-only*::
 823 ifndef::ACTION_LUKSADDKEY[]
 824 Do not proceed further with action if token based keyslot unlock failed. Without the
 825 option, action asks for passphrase to proceed further.
 826 +
 827 It allows LUKS2 tokens protected by PIN to take precedence over interactive keyslot
 828 passphrase prompt.
 829 endif::[]
 830 ifdef::ACTION_LUKSADDKEY[]
 831 Use only LUKS2 tokens to unlock existing volume key.
 832 +
 833 *NOTE*: To create a new keyslot using passphrase provided by a token use --new-token-id parameter.
 834 endif::[]
 835 endif::[]
 836
 837 ifdef::ACTION_OPEN,ACTION_RESIZE,ACTION_LUKSRESUME,ACTION_LUKSADDKEY[]
 838 *--token-type* _type_::
 839 ifndef::ACTION_LUKSADDKEY[]
 840 Restrict tokens eligible for operation to specific token _type_.
 841 Mostly useful when no --token-id is specified.
 842 +
 843 It allows LUKS2 _type_ tokens protected by PIN to take precedence over interactive keyslot
 844 passphrase prompt.
 845 endif::[]
 846 ifdef::ACTION_LUKSADDKEY[]
 847 Specify what token type (all _type_ tokens) to use when unlocking existing keyslot to get volume key.
 848 endif::[]
 849 endif::[]
 850
 851 ifdef::ACTION_OPEN,ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 852 ifndef::ACTION_REENCRYPT[]
 853 *--sector-size* _bytes_::
 854 endif::[]
 855 ifndef::ACTION_REENCRYPT[]
 856 ifdef::ACTION_OPEN[]
 857 Set encryption sector size for use with _plain_ device type. It must be power of two
 858 and in range 512 - 4096 bytes. The default mode is 512 bytes.
 859 +
 860 Note that if sector size is higher than underlying device hardware
 861 sector, using this option can increase risk on incomplete sector writes during a
 862 power fail.
 863 endif::[]
 864 ifdef::ACTION_LUKSFORMAT[]
 865 Set sector size for use with disk encryption. It must be power of two
 866 and in range 512 - 4096 bytes. This option is available only with LUKS2
 867 format.
 868 +
 869 For LUKS2 devices it's established based on parameters provided by
 870 underlying data device. For native 4K block devices it's 4096 bytes.
 871 For 4K/512e (4K physical sector size with 512 bytes emulation) it's
 872 4096 bytes. For drives reporting only 512 bytes block size it remains
 873 512 bytes. If data device is regular file put in filesystem it's 4096
 874 bytes.
 875 +
 876 Note that if sector size is higher than underlying device hardware
 877 sector and there is not integrity protection that uses data journal,
 878 using this option can increase risk on incomplete sector writes during a
 879 power fail.
 880 +
 881 If used together with _--integrity_ option and dm-integrity journal, the
 882 atomicity of writes is guaranteed in all cases (but it cost write
 883 performance - data has to be written twice).
 884 endif::[]
 885 +
 886 Increasing sector size from 512 bytes to 4096 bytes can provide better
 887 performance on most of the modern storage devices and also with some hw
 888 encryption accelerators.
 889 endif::[]
 890 ifdef::ACTION_REENCRYPT[]
 891 *--sector-size* _bytes_ *(LUKS2 only)*::
 892 Reencrypt device with new encryption sector size enforced.
 893 +
 894 *WARNING:* Increasing encryption sector size may break hosted filesystem. Do not
 895 run reencryption with --force-offline-reencrypt if unsure what block size
 896 was filesystem formatted with.
 897 endif::[]
 898 endif::[]
 899
 900 ifdef::ACTION_OPEN[]
 901 *--iv-large-sectors*::
 902 Count Initialization Vector (IV) in larger sector size (if set)
 903 instead of 512 bytes sectors. This option can be used only with _plain_
 904 device type.
 905 +
 906 *NOTE:* This option does not have any performance or security impact,
 907 use it only for accessing incompatible existing disk images from other
 908 systems that require this option.
 909 endif::[]
 910
 911 ifdef::ACTION_OPEN,ACTION_REFRESH[]
 912 *--persistent*::
 913 If used with LUKS2 devices and activation commands like _open_ or
 914 _refresh_, the specified activation flags are persistently written
 915 into metadata and used next time automatically even for normal
 916 activation. (No need to use cryptab or other system configuration
 917 files.)
 918 +
 919 If you need to remove a persistent flag, use _--persistent_ without the
 920 flag you want to remove (e.g. to disable persistently stored discard
 921 flag, use _--persistent_ without _--allow-discards_).
 922 +
 923 Only _--allow-discards_, _--perf-same_cpu_crypt_,
 924 _--perf-submit_from_crypt_cpus_, _--perf-no_read_workqueue_,
 925 _--perf-no_write_workqueue_ and _--integrity-no-journal_ can be stored
 926 persistently.
 927 endif::[]
 928
 929 ifdef::ACTION_OPEN[]
 930 *--refresh*::
 931 Refreshes an active device with new set of parameters. See
 932 *cryptsetup-refresh*(8) for more details.
 933 endif::[]
 934
 935 ifdef::ACTION_LUKSFORMAT,ACTION_CONFIG,ACTION_REENCRYPT[]
 936 *--label <LABEL> --subsystem <SUBSYSTEM>*::
 937 Set label and subsystem description for LUKS2 device.
 938 The label and subsystem are optional fields and can be later used
 939 in udev scripts for triggering user actions once the device marked
 940 by these labels is detected.
 941 endif::[]
 942
 943 ifdef::ACTION_LUKSFORMAT[]
 944 *--integrity <integrity algorithm>*::
 945 Specify integrity algorithm to be used for authenticated disk
 946 encryption in LUKS2.
 947 +
 948 *WARNING: This extension is EXPERIMENTAL* and requires dm-integrity
 949 kernel target (available since kernel version 4.12). For native AEAD
 950 modes, also enable "User-space interface for AEAD cipher algorithms" in
 951 "Cryptographic API" section (CONFIG_CRYPTO_USER_API_AEAD .config
 952 option).
 953 +
 954 For more info, see _AUTHENTICATED DISK ENCRYPTION_ section in *cryptsetup*(8).
 955 endif::[]
 956
 957 ifdef::ACTION_LUKSFORMAT[]
 958 *--integrity-legacy-padding*::
 959 Use inefficient legacy padding.
 960 +
 961 *WARNING*: Do not use this option until you need compatibility with specific
 962 old kernel.
 963 endif::[]
 964
 965 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 966 *--luks2-metadata-size <size>*::
 967 This option can be used to enlarge the LUKS2 metadata (JSON) area. The
 968 size includes 4096 bytes for binary metadata (usable JSON area is
 969 smaller of the binary area). According to LUKS2 specification, only
 970 these values are valid: 16, 32, 64, 128, 256, 512, 1024, 2048 and 4096
 971 kB The <size> can be specified with unit suffix (for example 128k).
 972 endif::[]
 973
 974 ifdef::ACTION_LUKSFORMAT,ACTION_REENCRYPT[]
 975 *--luks2-keyslots-size <size>*::
 976 This option can be used to set specific size of the LUKS2 binary
 977 keyslot area (key material is encrypted there). The value must be
 978 aligned to multiple of 4096 bytes with maximum size 128MB. The <size>
 979 can be specified with unit suffix (for example 128k).
 980 endif::[]
 981
 982 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[]
 983 *--keyslot-cipher <cipher-spec>*::
 984 This option can be used to set specific cipher encryption for the
 985 LUKS2 keyslot area.
 986 endif::[]
 987
 988 ifdef::ACTION_LUKSFORMAT,ACTION_LUKSADDKEY,ACTION_LUKSCHANGEKEY,ACTION_LUKSCONVERTKEY,ACTION_REENCRYPT[]
 989 *--keyslot-key-size <bits>*::
 990 This option can be used to set specific key size for the LUKS2 keyslot
 991 area.
 992 endif::[]
 993
 994 ifdef::ACTION_REFRESH[]
 995 *--integrity-no-journal*::
 996 Activate device with integrity protection without using data journal
 997 (direct write of data and integrity tags). Note that without journal
 998 power fail can cause non-atomic write and data corruption. Use only if
 999 journalling is performed on a different storage layer.
1000 endif::[]
1001
1002 ifdef::ACTION_LUKSFORMAT[]
1003 *--integrity-no-wipe*::
1004 Skip wiping of device authentication (integrity) tags. If you skip
1005 this step, sectors will report invalid integrity tag until an
1006 application write to the sector.
1007 +
1008 *NOTE:* Even some writes to the device can fail if the write is not
1009 aligned to page size and page-cache initiates read of a sector with
1010 invalid integrity tag.
1011 endif::[]
1012
1013 ifdef::ACTION_OPEN,ACTION_LUKSADDKEY,ACTION_LUKSDUMP,ACTION_TOKEN[]
1014 *--unbound*::
1015 ifdef::ACTION_LUKSADDKEY[]
1016 Creates new LUKS2 unbound keyslot.
1017 endif::[]
1018 ifdef::ACTION_LUKSDUMP[]
1019 Dumps existing LUKS2 unbound keyslot.
1020 endif::[]
1021 ifdef::ACTION_OPEN[]
1022 Allowed only together with --test-passphrase parameter, it allows one to test
1023 passphrase for unbound LUKS2 keyslot. Otherwise, unbound keyslot passphrase
1024 can be tested only when specific keyslot is selected via --key-slot parameter.
1025 endif::[]
1026 ifdef::ACTION_TOKEN[]
1027 Creates new LUKS2 keyring token assigned to no keyslot. Usable only with _add_ action.
1028 endif::[]
1029 endif::[]
1030
1031 ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[]
1032 *--tcrypt-hidden*::
1033 *--tcrypt-system*::
1034 *--tcrypt-backup*::
1035 Specify which TrueCrypt on-disk
1036 header will be used to open the device. See _TCRYPT_ section in
1037 *cryptsetup*(8) for more info.
1038 endif::[]
1039
1040 ifdef::ACTION_TCRYPTDUMP,ACTION_OPEN[]
1041 *--veracrypt*::
1042 This option is ignored as VeraCrypt compatible mode is supported by
1043 default.
1044 endif::[]
1045
1046 ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[]
1047 *--disable-veracrypt*::
1048 This option can be used to disable VeraCrypt compatible mode (only
1049 TrueCrypt devices are recognized). Only for TCRYPT extension. See
1050 _TCRYPT_ section in *cryptsetup*(8) for more info.
1051 endif::[]
1052
1053 ifdef::ACTION_OPEN,ACTION_TCRYPTDUMP[]
1054 *--veracrypt-pim*::
1055 *--veracrypt-query-pim*::
1056 Use a custom Personal Iteration Multiplier (PIM) for
1057 VeraCrypt device. See _TCRYPT_ section in *cryptsetup*(8) for more info.
1058 endif::[]
1059
1060 ifdef::ACTION_OPEN[]
1061 *--serialize-memory-hard-pbkdf*::
1062 Use a global lock to serialize unlocking of keyslots using memory-hard
1063 PBKDF.
1064 +
1065 *NOTE:* This is (ugly) workaround for a specific situation when multiple
1066 devices are activated in parallel and system instead of reporting out of
1067 memory starts unconditionally stop processes using out-of-memory killer.
1068 +
1069 *DO NOT USE* this switch until you are implementing boot environment
1070 with parallel devices activation!
1071 endif::[]
1072
1073 ifdef::ACTION_REENCRYPT[]
1074 *--encrypt, --new, -N*::
1075 Initialize (and run) device in-place encryption mode.
1076 endif::[]
1077
1078 ifdef::ACTION_REENCRYPT[]
1079 *--decrypt*::
1080 Initialize (and run) device decryption mode.
1081 endif::[]
1082
1083 ifdef::ACTION_REENCRYPT[]
1084 *--init-only (LUKS2 only)*::
1085 Initialize reencryption (any mode) operation in LUKS2 metadata only
1086 and exit. If any reencrypt operation is already initialized in
1087 metadata, the command with --init-only parameter fails.
1088 endif::[]
1089
1090 ifdef::ACTION_REENCRYPT[]
1091 *--resume-only (LUKS2 only)*::
1092 Resume reencryption (any mode) operation already described in LUKS2
1093 metadata. If no reencrypt operation is initialized, the command with
1094 --resume-only parameter fails. Useful for resuming reencrypt operation
1095 without accidentally triggering new reencryption operation.
1096 endif::[]
1097
1098 ifdef::ACTION_REENCRYPT[]
1099 *--resilience* _mode_ *(LUKS2 only)*::
1100 Reencryption resilience _mode_ can be one of _checksum_, _journal_ or
1101 _none_.
1102 +
1103 _checksum_: default mode, where individual checksums of ciphertext
1104 hotzone sectors are stored, so the recovery process can detect which
1105 sectors were already reencrypted. It requires that the device sector
1106 write is atomic.
1107 +
1108 _journal_: the hotzone is journaled in the binary area (so the data are
1109 written twice).
1110 +
1111 _none_: performance mode. There is no protection and the only way it's
1112 safe to interrupt the reencryption is similar to old offline
1113 reencryption utility.
1114 +
1115 Resilience modes can be changed unless _datashift_ mode is used for
1116 operation initialization (encryption with --reduce-device-size option)
1117 endif::[]
1118
1119 ifdef::ACTION_REENCRYPT[]
1120 *--resilience-hash* _hash_ *(LUKS2 only)*::
1121 The _hash_ algorithm used with "--resilience checksum" only. The default
1122 hash is sha256. With other resilience modes, the hash parameter is
1123 ignored.
1124 endif::[]
1125
1126 ifdef::ACTION_REENCRYPT[]
1127 *--hotzone-size* _size_ *(LUKS2 only)*::
1128 This option can be used to set an upper limit on the size of
1129 reencryption area (hotzone). The _size_ can be specified with unit
1130 suffix (for example 50M). Note that actual hotzone size may be less
1131 than specified <size> due to other limitations (free space in keyslots
1132 area or available memory).
1133 +
1134 With decryption mode for devices with LUKS2 header placed in head of data
1135 device, the option specifies how large is the first data segment moved
1136 from original data offset pointer.
1137 endif::[]
1138
1139 ifdef::ACTION_REENCRYPT[]
1140 *--reduce-device-size* _size_::
1141 This means that last _size_ sectors on the original device will be lost,
1142 data will be effectively shifted by specified number of sectors.
1143 +
1144 It could be useful if you added some space to underlying partition or
1145 logical volume (so last _size_ sectors contains no data).
1146 +
1147 For units suffix see --device-size parameter description.
1148 +
1149 *WARNING:* This is a destructive operation and cannot be reverted. Use
1150 with extreme care - accidentally overwritten filesystems are usually
1151 unrecoverable.
1152 +
1153 *LUKS2*:
1154 Initialize LUKS2 reencryption with data device size reduction
1155 (currently only encryption mode is supported).
1156 +
1157 Recommended minimal size is twice the default LUKS2 header size
1158 (--reduce-device-size 32M) for encryption mode.
1159 +
1160 *LUKS1*:
1161 Enlarge data offset to specified value by shrinking device size.
1162 +
1163 You cannot shrink device more than by 64 MiB (131072 sectors).
1164 endif::[]
1165
1166 ifdef::COMMON_OPTIONS[]
1167 *--batch-mode, -q*::
1168 Suppresses all confirmation questions. Use with care!
1169 +
1170 If the --verify-passphrase option is not specified, this option also
1171 switches off the passphrase verification.
1172 endif::[]
1173
1174 ifdef::COMMON_OPTIONS[]
1175 *--debug or --debug-json*::
1176 Run in debug mode with full diagnostic logs. Debug output lines are
1177 always prefixed by *#*.
1178 +
1179 If --debug-json is used, additional LUKS2 JSON data structures are printed.
1180 endif::[]
1181
1182 ifdef::COMMON_OPTIONS[]
1183 *--version, -V*::
1184 Show the program version.
1185 endif::[]
1186
1187 ifdef::COMMON_OPTIONS[]
1188 *--usage*::
1189 Show short option help.
1190 endif::[]
1191
1192 ifdef::COMMON_OPTIONS[]
1193 *--help, -?*::
1194 Show help text and default parameters.
1195 endif::[]