# man > cryptsetup(8)

---
type: CommandReference
command: cryptsetup
mode: man
section: 8
source: man-pages
---

## Quick Reference

- `cryptsetup --type luks2 luksFormat /dev/sdX` — Create LUKS2 container on block device
- `cryptsetup luksAddKey --key-slot 5 /dev/sdX` — Add passphrase to key slot 5
- `cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /path/to/backup` — Backup LUKS header
- `cryptsetup open /dev/sdX sdX_crypt` — Open LUKS container and map to /dev/mapper/sdX_crypt
- `cryptsetup erase /dev/sdX` — Erase all key slots (permanently inaccessible without header backup)
- `cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /path/to/backup` — Restore LUKS header from backup
- `cryptsetup open --type plain /dev/sdX e1` — Open plain dm-crypt device
- `cryptsetup close sdX_crypt` — Remove mapping

## Name

cryptsetup — manage plain dm-crypt and LUKS encrypted volumes

## Synopsis

`cryptsetup <options> <action> <action args>`

## Options

### General Options

- `-v, --verbose` — Print more information on command execution
- `--debug` — Run in debug mode with full diagnostic logs
- `--type <device-type>` — Specify device type (plain, luks, luks1, luks2, loopaes, tcrypt, bitlk)
- `-h, --hash <hash-spec>` — Passphrase hash for plain/loopaes open; hash for LUKS key setup
- `-c, --cipher <cipher-spec>` — Cipher specification string (default: aes-xts-plain64 for LUKS)
- `-y, --verify-passphrase` — Ask for passphrase twice (for luksFormat, first open)
- `-d, --key-file <name>` — Read passphrase from file
- `--keyfile-offset <value>` — Skip bytes at key file start
- `-l, --keyfile-size <value>` — Max bytes to read from key file
- `-s, --key-size <bits>` — Key size in bits (multiple of 8)
- `-b, --size <number of 512B sectors>` — Device size in 512-byte sectors (for open/resize)
- `-o, --offset <number of 512B sectors>` — Start offset on backend device (plain/loopaes/LUKS format)
- `-p, --skip <number of 512B sectors>` — IV calculation offset (plain/loopaes)
- `-r, --readonly` — Set up read-only mapping
- `--shared` — Create additional mapping for same ciphertext device (plain only)
- `-q, --batch-mode` — Suppress confirmation questions
- `-t, --timeout <seconds>` — Timeout for passphrase input (0 = forever)
- `-T, --tries <N>` — How many passphrase retries (default 3)
- `--align-payload <sectors>` — Align payload at boundary (deprecated, use --offset)
- `--uuid=<UUID>` — Use specific UUID (for luksFormat or luksUUID)
- `--allow-discards` — Allow discard (TRIM) requests (security risk)
- `--test-passphrase` — Verify passphrase without activating device
- `--header <device or file>` — Use detached LUKS header
- `--header-backup-file <file>` — File for header backup/restore
- `--force-password` — Skip password quality checking
- `--deferred` — Defer device removal (close)
- `--cancel-deferred` — Cancel deferred removal
- `--disable-external-tokens` — Disable external LUKS2 token plugins
- `--disable-locks` — Disable lock protection (LUKS2 only, dangerous)
- `--disable-keyring` — Store volume key directly in dm-crypt (LUKS2)
- `--key-description <text>` — Key description for keyring token
- `--priority <normal|prefer|ignore>` — Set keyslot priority (LUKS2)
- `--token-id <id>` — Specify token to use
- `--token-only` — Fail if token activation fails
- `--token-type <type>` — Restrict tokens to specific type
- `--sector-size <bytes>` — Sector size (512-4096, power of 2; LUKS2/plain)
- `--iv-large-sectors` — Count IV in larger sector size (plain only)
- `--persistent` — Store activation flags persistently in LUKS2 metadata
- `--refresh` — Refresh active device parameters
- `--label <LABEL>` — Set LUKS2 label
- `--subsystem <SUBSYSTEM>` — Set LUKS2 subsystem description
- `--integrity <algorithm>` — Use authenticated disk encryption (LUKS2, experimental)
- `--luks2-metadata-size <size>` — LUKS2 JSON metadata area size (16-4096 kB)
- `--luks2-keyslots-size <size>` — LUKS2 binary keyslot area size (max 128 MB)
- `--keyslot-cipher <cipher-spec>` — Keyslot area cipher (LUKS2)
- `--keyslot-key-size <bits>` — Keyslot area key size (LUKS2)
- `--integrity-no-journal` — Disable data journal for integrity protection
- `--integrity-no-wipe` — Skip wiping integrity tags
- `--unbound` — Create or dump unbound LUKS2 keyslot
- `--tcrypt-hidden` — Use TrueCrypt hidden header
- `--tcrypt-system` — Use TrueCrypt system encryption header
- `--tcrypt-backup` — Use TrueCrypt backup header
- `--disable-veracrypt` — Disable VeraCrypt compatibility
- `--veracrypt-pim <PIM>` — Set VeraCrypt Personal Iteration Multiplier
- `--veracrypt-query-pim` — Prompt for PIM
- `--serialize-memory-hard-pbkdf` — Serialize memory-hard PBKDF unlocking (for parallel activation)
- `--encrypt` — Initialize device encryption (reencrypt)
- `--decrypt` — Initialize device decryption (reencrypt)
- `--init-only` — Initialize reencryption metadata only and exit
- `--resume-only` — Resume existing reencryption operation
- `--resilience <mode>` — Reencryption resilience mode (checksum, journal, none)
- `--resilience-hash <hash>` — Hash for checksum resilience (default sha256)
- `--hotzone-size <size>` — Max reencryption hotzone size
- `--reduce-device-size <size>` — Reduce device size for reencryption (destructive)

### PBKDF Options

- `--pbkdf <PBKDF spec>` — PBKDF algorithm (pbkdf2, argon2i, argon2id)
- `-i, --iter-time <ms>` — Time to spend in PBKDF (for LUKS add/format)
- `--pbkdf-memory <number>` — Memory cost for Argon2 (kilobytes)
- `--pbkdf-parallel <number>` — Parallel threads for Argon2 (1-4)
- `--pbkdf-force-iterations <num>` — Set iterations directly (skip benchmark)

### Performance Options

- `--perf-same_cpu_crypt` — Encrypt on same CPU as IO submission
- `--perf-submit_from_crypt_cpus` — Disable offloading write bios
- `--perf-no_read_workqueue` — Synchronous reads
- `--perf-no_write_workqueue` — Synchronous writes

## Examples

shell
# 1. Create LUKS2 container
sudo cryptsetup --type luks2 luksFormat /dev/sdX

# 2. Add passphrase to key slot 5
sudo cryptsetup luksAddKey --key-slot 5 /dev/sdX

# 3. Backup LUKS header
sudo cryptsetup luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/backup

# 4. Open LUKS container
sudo cryptsetup open /dev/sdX sdX_crypt

# 5. Erase all key slots (destructive)
sudo cryptsetup erase /dev/sdX

# 6. Restore LUKS header from backup
sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/backup
## See Also

- [losetup(8)](https://www.chedong.com/phpMan.php/man/losetup/8/markdown) — Set up loop devices
- [dmsetup(8)](https://www.chedong.com/phpMan.php/man/dmsetup/8/markdown) — Low-level device-mapper management
- [urandom(4)](https://www.chedong.com/phpMan.php/man/urandom/4/markdown) — Kernel random number sources
- [pwquality.conf(5)](https://www.chedong.com/phpMan.php/man/pwquality.conf/5/markdown) — Password quality configuration
- [passwdqc.conf(5)](https://www.chedong.com/phpMan.php/man/passwdqc.conf/5/markdown) — Password quality control
- LUKS website: <https://gitlab.com/cryptsetup/cryptsetup/>
- LUKS FAQ: <https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions>
- LUKS1 specification: <https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification>
- LUKS2 specification: <https://gitlab.com/cryptsetup/LUKS2-docs>
- loop-AES: <http://loop-aes.sourceforge.net>
- TrueCrypt: <https://en.wikipedia.org/wiki/TrueCrypt>
- VeraCrypt PIM: <https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html>

## Exit Codes

| Code | Meaning                    |
|------|----------------------------|
| 0    | Success                    |
| 1    | Wrong parameters           |
| 2    | No permission (bad passphrase) |
| 3    | Out of memory              |
| 4    | Wrong device specified     |
| 5    | Device already exists or busy |