cryptsetup

Initialize a LUKS volume with a passphrase (overwrites all data on the partition)

$ cryptsetup luksFormat [/dev/sdXY]

$ cryptsetup open [/dev/sdXY] [mapping_name]

$ cryptsetup status [mapping_name]

$ cryptsetup close [mapping_name]

$ cryptsetup luksChangeKey [/dev/sdXY]

cryptsetup [options] <command> <device> [<args>]

--help, -?
    Display help and exit

--version, -V
    Print version information

--verbose, -v
    Increase verbosity level

--debug
    Enable debug output

--batch-mode, -q
    Suppress interactive prompts

--test-passphrase
    Test passphrase validity without action

--key-file FILE
    Read passphrase from file

--key-file-size N
    Read N bytes from key file

--key-file-offset N
    Seek N bytes in key file

--key-slot, -S N
    Specify LUKS keyslot (0-255)

--tries N
    Maximum passphrase attempts

--cipher SPEC
    Cipher specification (e.g., aes-xts-plain64)

--verify-passphrase
    Verify passphrase by reading data

--master-key-file FILE
    Read master key from file

--allow-discards
    Enable TRIM/discard support

--hash ALG
    Hash algorithm for PBKDF

--iter-time MS
    PBKDF2 iteration time in ms

--pbkdf PBKDF
    PBKDF algorithm (pbkdf2, argon2i, argon2id)

--sector-size N
    Device sector size

--type, -T TYPE
    Mapper type (luks, luks2, plain, veracrypt)

--offset N
    Data offset in sectors

--skip N
    Sectors to skip

--hmac ALG
    HMAC for LUKS2 integrity

--label NAME
    Set LUKS label

--disable-locks
    Disable filesystem lock handling

Cryptsetup is the standard userspace tool for setting up and controlling encrypted block devices on Linux using the kernel's dm-crypt module. It primarily supports the Linux Unified Key Setup (LUKS) format, which provides robust on-disk encryption with features like multiple keyslots, header integrity, and PBKDF2/Argon2 key derivation.

Key uses include formatting devices for encryption (luksFormat), mapping encrypted devices to loopback names for mounting (open or luksOpen), unmapping (close), key management (luksAddKey, luksRemoveKey, luksChangeKey), resizing (resize), status inspection (status, luksDump), and wiping (erase).

It also handles plain dm-crypt mode, VeraCrypt-compatible containers, BitLocker readers, and detached headers. Cryptsetup integrates with systemd, dracut, and initramfs for boot-time unlocking in full-disk encryption setups like those in Ubuntu, Fedora, and Debian. Security emphasizes passphrase strength, header backups (luksHeaderBackup), and anti-forensic stripping. Operations require root and can be scripted with --batch-mode. Always verify setups to avoid data corruption.

Requires root privileges. Mishandling can cause irreversible data loss. Backup LUKS headers with luksHeaderBackup before modifications. Passphrases must be strong; weak ones reduce security. Discards/TRIM may leak data patterns.

luksFormat <dev>: Initialize LUKS.
open|luksOpen <dev> <name>: Map to /dev/mapper/name.
close <name>: Unmap device.
luksAddKey|luksRemoveKey: Manage keyslots.
resize: Resize mapping.
status: Show mapping status.
luksDump: Display header info.

LUKS1: Legacy, PBKDF2 only, 8 keyslots.
LUKS2: Modern, supports Argon2/PBKDF2, unlimited slots, JSON metadata, tokens for FIDO2/PKCS11.

Developed in 2004 by Clemens Fruhwirth as part of LUKS 1.0 specification. Integrated dm-crypt support from early Linux 2.6 kernels. Milan Broz became maintainer in 2011, adding LUKS2 (2015) with Tcrypt/VeraCrypt compatibility, online reencrypt, and Argon2 PBKDF. Now at version 2.7+, essential for distro full-disk encryption.

dmsetup(8), dm-crypt(7), cryptsetup-reencrypt(8), losetup(8), blkid(8)