cheatsheet

cryptsetup Command in Linux: LUKS2 Syntax, Options & Examples (Ubuntu)

cryptsetup manages LUKS disk encryption through the kernel dm-crypt device mapper. Use it to format partitions, open and close mapper devices, rotate passphrases, back up headers, and inspect LUKS2 metadata on Ubuntu and most Linux distros.

Published

Updated

Read time 14 min read

Reviewed byDeepak Prasad

cryptsetup Command in Linux: LUKS2 Syntax, Options & Examples (Ubuntu)
About cryptsetup manages LUKS disk encryption through the kernel dm-crypt device mapper. Use it to format partitions, open and close mapper devices, rotate passphrases, back up headers, and inspect LUKS2 metadata on Ubuntu and most Linux distros.
Tested on Ubuntu 26.04 (Resolute Raccoon); cryptsetup 2.8.4; kernel 7.0.0-27-generic
Package cryptsetup (apt/deb) · cryptsetup (dnf/rpm)
Man page cryptsetup(8)
Privilege root / sudo
Distros

Ubuntu, Debian, Fedora, and most Linux distributions ship cryptsetup with LUKS2 support.

Raw dm-crypt without LUKS metadata: dmsetup (lower level; no header or key slots).
Related guide

cryptsetup — quick reference

LUKS format and open/close

Create LUKS2 containers, unlock them as /dev/mapper/name, and tear down mapper devices when you are done.

When to use Command
Format a partition as LUKS2 (destroys existing data) sudo cryptsetup luksFormat --type luks2 /dev/sdc1
Same — skip the uppercase YES confirmation prompt sudo cryptsetup -q luksFormat --type luks2 /dev/sdc1
Pick cipher and key size at format time sudo cryptsetup luksFormat -c aes-xts-plain64 -s 512 /dev/sdc1
Open a LUKS device under a mapper name sudo cryptsetup open /dev/sdc1 secure_data
Open with a key file instead of a typed passphrase sudo cryptsetup open --key-file=/path/to/keyfile /dev/sdc1 secure_data
Check a passphrase without activating the mapper sudo cryptsetup open --test-passphrase /dev/sdc1
Close (remove) an active mapper sudo cryptsetup close secure_data
Test whether a block device has a LUKS header sudo cryptsetup isLuks /dev/sdc1
Print the LUKS UUID sudo cryptsetup luksUUID /dev/sdc1

Key management (luksAddKey, luksRemoveKey, luksChangeKey, luksKillSlot)

Rotate passphrases, add backup keys, and retire compromised key slots on an existing LUKS volume.

When to use Command
Add a new passphrase or key file (prompts for an existing key first) sudo cryptsetup luksAddKey /dev/sdc1
Add a key file into a specific empty slot sudo cryptsetup luksAddKey -S 2 /dev/sdc1 /path/to/new-keyfile
Remove a passphrase or key file from the device sudo cryptsetup luksRemoveKey /dev/sdc1
Change an existing passphrase (old key, then new key) sudo cryptsetup luksChangeKey /dev/sdc1
Wipe one key slot by number (irreversible for that slot) sudo cryptsetup luksKillSlot /dev/sdc1 1
Target a slot when removing a key sudo cryptsetup luksRemoveKey -S 1 /dev/sdc1

Inspection (luksDump, status, benchmark)

Read header metadata, check an open mapper, and measure cipher throughput on the host CPU.

When to use Command
Dump LUKS header, cipher, and key slot details sudo cryptsetup luksDump /dev/sdc1
Dump LUKS2 metadata as JSON sudo cryptsetup luksDump --dump-json-metadata /dev/sdc1
Show cipher, size, and backing device for an open mapper sudo cryptsetup status secure_data
Benchmark a cipher (memory only, no disk I/O) sudo cryptsetup benchmark -c aes-xts-plain64 -s 512
List supported actions and global flags cryptsetup --help
Show installed version cryptsetup --version

Header backup/restore (luksHeaderBackup, luksHeaderRestore)

Copy the LUKS header and key slots to a file so you can recover from header corruption — not a substitute for full-disk backup.

When to use Command
Back up header and key slots to a file sudo cryptsetup luksHeaderBackup --header-backup-file /root/sdc1-luks-header.bin /dev/sdc1
Restore header from backup (dangerous if the wrong file) sudo cryptsetup luksHeaderRestore --header-backup-file /root/sdc1-luks-header.bin /dev/sdc1
Restore without interactive confirmation sudo cryptsetup -q luksHeaderRestore --header-backup-file /root/sdc1-luks-header.bin /dev/sdc1

See LUKS header backup and restore for a full walkthrough.

Resize and reencrypt mention

Grow or shrink the encrypted payload after partition changes, or reencrypt a LUKS2 volume in place (cryptsetup 2.x).

When to use Command
Resize an open mapper after the partition grew sudo cryptsetup resize secure_data
Resize to an explicit sector count sudo cryptsetup resize --size 1048576 secure_data
Shrink encrypted payload before shrinking the partition (LUKS2) sudo cryptsetup --reduce-device-size 32M resize secure_data
Start LUKS2 online reencryption (encrypt, reencrypt, or decrypt) sudo cryptsetup reencrypt /dev/sdc1
Initialize reencryption metadata only (no data movement yet) sudo cryptsetup reencrypt --init-only /dev/sdc1
Resume an interrupted LUKS2 reencryption sudo cryptsetup reencrypt --resume-only /dev/sdc1

Partition-level resize workflows live in resize a LUKS partition.

Tokens (LUKS2)

LUKS2 tokens automate unlock with external handlers (TPM, PKCS#11, FIDO2, and plugins). Requires LUKS2 and token support in your cryptsetup build.

When to use Command
Export one token definition as JSON sudo cryptsetup token export --token-id 0 /dev/sdc1
Import a token JSON file into the header sudo cryptsetup token import --json-file token.json /dev/sdc1
Add a token from JSON on stdin sudo cryptsetup token import --token-id 0 /dev/sdc1
Remove a token by ID sudo cryptsetup token remove --token-id 0 /dev/sdc1
Open using tokens only (no direct passphrase prompt) sudo cryptsetup open --token-id 0 /dev/sdc1 secure_data

cryptsetup — command syntax

Synopsis from cryptsetup --help on Ubuntu 26.04 (cryptsetup 2.8.4):

text 
cryptsetup <action> <action-specific>

Common LUKS actions:
  luksFormat <device> [<key file>]     format device as LUKS
  open <device> [<name>]               open LUKS device as mapper <name>
  close <name>                         remove mapper device
  luksDump <device>                    dump LUKS header information
  luksAddKey <device> [<new key file>] add key to LUKS device
  luksRemoveKey <device> [<key file>]  remove key from LUKS device
  luksChangeKey <device> [<key file>]  change existing key
  luksKillSlot <device> <key slot>     wipe key slot
  luksHeaderBackup <device>            backup header and keyslots
  luksHeaderRestore <device>           restore header and keyslots
  status <name>                        show active mapper status
  benchmark [--cipher <cipher>]        benchmark cipher
  reencrypt <device>                   reencrypt LUKS2 device
  token <import|export|remove> <device>  manage LUKS2 tokens
  isLuks <device>                      test for LUKS header
  luksUUID <device>                    print LUKS UUID

cryptsetup writes LUKS metadata on the block device (or a detached header file with --header) and creates /dev/mapper/ nodes through device-mapper. Most actions need sudo. After open, create filesystems on /dev/mapper/name, not on the raw LUKS partition — see encrypt a partition with LUKS2.

cryptsetup — command examples

Essential Inspect a LUKS2 header with luksDump

Run luksDump when you need the LUKS version, UUID, cipher, and which key slots are in use — before adding keys or after luksFormat.

On the lab volume /dev/sdc1 (LUKS2 UUID 5f452b2f-3b11-4494-890b-d6c3e509c0ef):

bash 
sudo cryptsetup luksDump /dev/sdc1

Sample output (trimmed):

text 
LUKS header information
Version:       	2
UUID:          	5f452b2f-3b11-4494-890b-d6c3e509c0ef
Label:         	(no label)

Data segments:
  0: crypt
	offset: 16777216 [bytes]
	length: (whole device)
	cipher: aes-xts-plain64
	sector: 512 [bytes]

Keyslots:
  0: luks2
	Key:        512 bits
	PBKDF:      argon2id
  1: luks2
	Key:        512 bits
	PBKDF:      argon2id
Tokens:
Digests:
  0: pbkdf2

Confirm the partition type with blkid:

bash 
sudo blkid /dev/sdc1

Sample output:

text 
/dev/sdc1: UUID="5f452b2f-3b11-4494-890b-d6c3e509c0ef" TYPE="crypto_LUKS" PARTLABEL="primary" PARTUUID="b2ec5a76-8585-4e6b-9926-3ca5094fcea1"

Two active luks2 key slots means a backup passphrase is already configured. An empty Tokens: section is normal until you add LUKS2 token handlers.

Essential Check an open LUKS mapper with status

After cryptsetup open, the cleartext block device lives at /dev/mapper/name. Use status to see cipher, size, and the backing LUKS partition.

bash 
sudo cryptsetup status secure_data

Sample output:

text 
/dev/mapper/secure_data is active.
  type:    LUKS2
  cipher:  aes-xts-plain64
  keysize: 512 [bits]
  key location: keyring
  device:  /dev/sdc1
  sector size:  512 [bytes]
  offset:  32768 [512-byte units] (16777216 [bytes])
  size:    10448896 [512-byte units] (5349834752 [bytes])
  mode:    read/write

Pair with lsblk to see the mapper and filesystem stack:

bash 
lsblk -f /dev/sdc1

Sample output:

text 
NAME          FSTYPE      FSVER LABEL       UUID                                 FSAVAIL FSUSE% MOUNTPOINTS
sdc1          crypto_LUKS 2                 5f452b2f-3b11-4494-890b-d6c3e509c0ef
└─secure_data ext4        1.0   secure-data 9fe05bbb-e530-48ed-a8f7-461febc7329f

Mount workflows are covered in mount a LUKS encrypted partition.

Essential Validate a passphrase without opening the device

Use --test-passphrase when you want to confirm a password before reboot or before scripting open, without creating a mapper device.

Wrong passphrase (safe to run on a live volume):

bash 
sudo cryptsetup open --test-passphrase /dev/sdc1 <<< 'wrong-passphrase-test'

Sample output:

text 
No key available with this passphrase.

When the passphrase matches a key slot, cryptsetup exits 0 and prints nothing. That silent success is the signal you want before updating crypttab or rebooting.

Common Benchmark cipher speed before luksFormat

benchmark measures CPU encryption throughput in memory — useful when choosing between aes-xts-plain64 and other ciphers supported by /proc/crypto.

bash 
sudo cryptsetup benchmark -c aes-xts-plain64 -s 512

Sample output:

text 
# Tests are approximate using memory only (no storage IO).
# Algorithm |       Key |      Encryption |      Decryption
    aes-xts        512b      2569.4 MiB/s      2524.7 MiB/s

Numbers vary by CPU and kernel crypto API. Disk I/O during real LUKS use is usually lower than these peaks.

Common Back up the LUKS header and key slots

Header backup protects against metadata corruption. It does not copy encrypted file data — pair this with a full backup strategy.

bash 
sudo cryptsetup luksHeaderBackup \
  --header-backup-file /root/sdc1-luks-header.bin \
  /dev/sdc1
ls -lh /root/sdc1-luks-header.bin
file /root/sdc1-luks-header.bin

Sample output:

text 
-r-------- 1 root root 16M Jul  4 21:06 /root/sdc1-luks-header.bin
/root/sdc1-luks-header.bin: LUKS encrypted file, ver 2, header size 16384, ID 4, algo sha256, ... UUID: 5f452b2f-3b11-4494-890b-d6c3e509c0ef, ...

Store the file offline with restrictive permissions (600 or tighter). Restore only onto the matching device — see LUKS header backup and restore.

Common luksAddKey fails when the existing key is wrong

Adding a backup passphrase requires proof of an existing key first. This shows the error you get when the current passphrase does not match any slot.

bash 
printf 'wrong-pass\nwrong-pass\n' | sudo cryptsetup luksAddKey /dev/sdc1

Sample output:

text 
No key available with this passphrase.

When the first passphrase is valid, cryptsetup prompts for the new key (twice if typed interactively) and allocates the next free slot. Verify with sudo cryptsetup luksDump /dev/sdc1 — a third luks2 line under Keyslots: confirms success.

Common luksKillSlot on an empty slot

luksKillSlot wipes one key slot. Trying to kill a slot that was never used returns a clear error instead of changing the header.

bash 
sudo cryptsetup luksKillSlot /dev/sdc1 7

Sample output:

text 
Keyslot 7 is not active.

To retire an active backup slot, pick the slot number from luksDump (for example slot 1) and run sudo cryptsetup luksKillSlot /dev/sdc1 1 after confirming you still have another working key.

Advanced Export LUKS2 metadata as JSON

LUKS2 stores structured metadata. --dump-json-metadata prints it for auditing, automation, or comparing headers across hosts.

bash 
sudo cryptsetup luksDump --dump-json-metadata /dev/sdc1 | head -20

Sample output:

text 
{
  "keyslots":{
    "0":{
      "type":"luks2",
      "key_size":64,
      "af":{
        "type":"luks1",
        "stripes":4000,
        "hash":"sha256"
      },
      "area":{
        "type":"raw",
        "offset":"32768",
        "size":"258048",
        "encryption":"aes-xts-plain64",
        "key_size":64
      },
      "kdf":{
        "type":"argon2id",
        "time":4,

Pipe the full JSON to a file for diffing. This read-only dump never exposes passphrases or volume keys.

Advanced isLuks probe and token export without tokens

Scripts often gate on isLuks before calling luksDump. Token export fails cleanly when no LUKS2 tokens are configured.

Test for a LUKS header:

bash 
sudo cryptsetup isLuks /dev/sdc1
echo "luks exit: $?"
sudo cryptsetup isLuks /dev/sda1 2>/dev/null
echo "non-luks exit: $?"

Sample output:

text 
luks exit: 0
non-luks exit: 1

Try exporting a token when the header has none:

bash 
sudo cryptsetup token export /dev/sdc1 2>&1 | tail -1

Sample output:

text 
cryptsetup: Action requires specific token. Use --token-id parameter.

After you token import a handler (TPM2, FIDO2, etc.), pass --token-id N to export or use open --token-id N for automated unlock.

cryptsetup — when to use / when not

Use cryptsetup when Use something else when
  • You are creating or opening a LUKS1/LUKS2 encrypted partition or disk
  • You need to add, remove, or rotate LUKS passphrases and key files
  • You want to back up or restore a LUKS header after corruption scares
  • You are resizing the encrypted payload or running LUKS2 online reencryption
  • You need a supported, distro-packaged tool for dm-crypt volumes on Linux
  • The volume is already open and you only need to mount ext4/XFS → mount LUKS encrypted partition
  • You want encryption without a LUKS header (ephemeral keys, scripts) → plain `dmsetup` / cryptsetup plainOpen
  • You are managing LVM on top of encryption → lvcreate after the mapper is open
  • You need VeraCrypt/BitLocker containers → cryptsetup tcryptOpen / bitlkOpen (separate workflows)
  • You forgot every passphrase and have no header backup → offline recovery tools; cryptsetup cannot brute-force keys

cryptsetup vs dmsetup

cryptsetup dmsetup
Role High-level LUKS and dm-crypt helper Low-level device-mapper table manager
Metadata LUKS header with key slots on disk None unless you manage keys yourself
Typical admin luksFormat, open, luksDump, key rotation create, remove, suspend, manual tables
Best for Standard disk encryption on Linux Custom maps, debugging, non-LUKS setups

Day-to-day LUKS work stays in cryptsetup; reach for dmsetup when you already have a mapped table and need low-level control.

Block devices, filesystems, and storage layout around LUKS workflows.

Command One line
lsblk Tree view of disks, LUKS containers, and mapper children
parted Create or resize GPT/MBR partitions before luksFormat
losetup Attach loop devices when testing image files
cryptsetup LUKS format, open, key management (this page)

Browse the full index in our Linux commands reference.

cryptsetup — interview corner

Practice these before exams or storage standups. Each card explains the idea in plain language, then ends with a short answer you can say aloud.

What does cryptsetup do in Linux?

cryptsetup is the user-space tool for LUKS disk encryption on Linux. It formats block devices with a LUKS header, derives keys from passphrases or key files, and asks the kernel dm-crypt layer to expose a /dev/mapper/ device you can partition, format, and mount.

Typical flow:

  1. luksFormat writes LUKS2 metadata on /dev/sdXN
  2. open unlocks the volume as /dev/mapper/name
  3. mkfs and mount run on the mapper — not on the raw LUKS partition
  4. close removes the mapper when unmounted

It ships on Ubuntu, Debian, and Fedora as the cryptsetup package.

A strong answer is:

"cryptsetup manages LUKS encryption through dm-crypt — format with luksFormat, unlock with open to /dev/mapper, manage keys in the header, and close when done. Filesystems always sit on the mapper device."

What is the difference between LUKS1 and LUKS2?

Both store encrypted volume keys in on-disk key slots, but LUKS2 is the modern default (cryptsetup 2.x on current distros).

LUKS1 LUKS2
Metadata Fixed legacy layout JSON-based, extensible
Key derivation PBKDF2 common Argon2id default on Ubuntu 26.04
Extra features Limited Tokens, online reencryption, detached headers
Format flag --type luks1 --type luks2 (default)

luksDump reports Version: 2 for LUKS2 volumes. New installs should use LUKS2 unless something legacy requires LUKS1.

A strong answer is:

"LUKS2 is the current default — flexible JSON metadata, stronger KDF defaults, tokens, and online reencrypt. LUKS1 is legacy; I only pick it when an old system cannot read LUKS2."

Should you mkfs on /dev/sdc1 or /dev/mapper/name after LUKS?

Always /dev/mapper/name after cryptsetup open.

/dev/sdc1 holds the LUKS container (header + encrypted payload). Formatting it directly destroys the header or writes an unencrypted filesystem beside LUKS metadata.

Correct sequence:

bash 
sudo cryptsetup open /dev/sdc1 secure_data
sudo mkfs.ext4 /dev/mapper/secure_data
sudo mount /dev/mapper/secure_data /mnt/secure-data

A strong answer is:

"After open, mkfs and mount go on /dev/mapper/name — the cleartext device. The raw partition is only for luksFormat and cryptsetup key operations."

How do LUKS key slots work?

LUKS stores up to several key slots in the header. Each slot holds key material wrapped by a passphrase or key file. Any active slot that unlocks grants access to the same volume key.

Common operations:

Task Command
Inspect slots sudo cryptsetup luksDump /dev/sdc1
Add backup passphrase sudo cryptsetup luksAddKey /dev/sdc1
Change a passphrase sudo cryptsetup luksChangeKey /dev/sdc1
Remove one key sudo cryptsetup luksRemoveKey /dev/sdc1
Wipe a slot by number sudo cryptsetup luksKillSlot /dev/sdc1 1

Keep at least one working slot before luksKillSlot. Header backup covers metadata loss, not forgotten passphrases with no remaining slots.

A strong answer is:

"LUKS key slots are independent wrappers around the same volume key — luksAddKey adds backup passphrases, luksChangeKey rotates one, luksKillSlot wipes a slot. I always confirm another slot still works before killing one."

Why back up the LUKS header?

The LUKS header stores key slots and encryption parameters. If that metadata is corrupted — bad sectors, mistaken dd, partial clone — the encrypted payload may be intact but unreadable without the header.

luksHeaderBackup copies header + key slot blobs to a file. luksHeaderRestore writes them back to the same physical device UUID.

Important limits:

  • Header backup does not replace full-disk backup of ciphertext
  • Restore must target the matching device and backup file
  • Passphrases still required after restore — backup is not a master key

A strong answer is:

"I luksHeaderBackup after luksFormat and whenever I change keys — it protects metadata corruption. It is not a data backup, and restore only works with the correct header file on the same volume."

What is cryptsetup reencrypt for LUKS2?

cryptsetup reencrypt performs online LUKS2 reencryption — change cipher, encrypt an unencrypted region, or decrypt in place — while the volume can stay mapped (with restrictions documented in the man page).

Typical flags:

Flag Purpose
--encrypt Add encryption to an existing LUKS2 payload
--decrypt Remove encryption (destructive planning required)
--init-only Stage metadata without moving data yet
--resume-only Continue after interruption

Always read the man page and have backups before starting. Partition shrink/grow coordination is in resize a LUKS partition.

A strong answer is:

"reencrypt is LUKS2 online reencryption — rotate ciphers or encrypt/decrypt in place with init and resume steps. I treat it as a planned maintenance window with full backups, not a casual flag."

Troubleshooting

Common cryptsetup failures on Ubuntu — symptom, likely cause, and the fix to try first.

Symptom Likely cause Fix
No key available with this passphrase Wrong password or key file; slot disabled Retry with --test-passphrase; check luksDump for active slots
Device secure_data already exists Mapper name in use sudo cryptsetup close secure_data or pick another name
Device is still active on close Mount or swap still open umount / swapoff the mapper, then close
Not a valid LUKS device / isLuks exit 1 No LUKS header on partition Confirm device with lsblk -f; rerun luksFormat only if data loss is acceptable
Keyslot N is not active Empty slot in luksKillSlot Pick an active slot from luksDump
Option --header-backup-file is required Old positional backup syntax Use luksHeaderBackup --header-backup-file FILE DEVICE
Command not found: cryptsetup Package missing sudo apt install cryptsetup
Filesystem missing after reboot Mapper not opened at boot Add an /etc/crypttab entry; see mount LUKS encrypted partition

References

Deepak Prasad

R&D Engineer

Founder of GoLinuxCloud with more than 15 years of expertise in Linux, Python, Go, Laravel, DevOps, Kubernetes, Git, Shell scripting, OpenShift, AWS, Networking, and Security. With extensive …

Related Articles

storage

How to Back Up and Restore a LUKS Header in Linux

Back up and restore a LUKS2 header with cryptsetup luksHeaderBackup and luksHeaderRestore, use a detached …

10 min readstorage

Change LUKS Passphrase, Volume Key, and Cipher on Linux

Rotate LUKS passphrases and key slots, change cipher or volume key with cryptsetup reencrypt on LUKS2, and …

12 min readstorage

How to Encrypt a Disk Partition with LUKS in Linux

Encrypt a new Linux disk partition with LUKS2 using cryptsetup: partition the disk, run luksFormat, open the …

10 min read