LUKS

LUKS is the standard for Linux disk encryption. This cheatsheet covers cryptsetup commands for creating, managing, and accessing encrypted volumes.

Installation

Linux/Ubuntu

# Debian/Ubuntu
sudo apt-get install cryptsetup

# RHEL/CentOS
sudo dnf install cryptsetup

# Arch
sudo pacman -S cryptsetup

# Fedora
sudo dnf install cryptsetup-libs

Basic Commands

Command	Description
cryptsetup --version	Show cryptsetup version
cryptsetup benchmark	Test encryption/decryption speed
cryptsetup help	Display help information
cryptsetup luksFormat <device>	Create LUKS volume
cryptsetup luksOpen <device> <name>	Unlock and mount encrypted device
cryptsetup luksClose <name>	Lock encrypted device
cryptsetup luksDump <device>	Display LUKS header information
cryptsetup status <name>	Check device status

Volume Creation

Create New LUKS Volume

# Interactive prompt for password
sudo cryptsetup luksFormat /dev/sdXn

# Specify cipher and key size
sudo cryptsetup luksFormat --cipher aes-xts-plain64 \
  --key-size 512 \
  --hash sha256 \
  /dev/sdXn

# Without interactive prompt (with key file)
sudo cryptsetup luksFormat --key-file keyfile.key /dev/sdXn

Open/Mount LUKS Volume

# Standard unlock
sudo cryptsetup luksOpen /dev/sdXn encrypted_name

# Mount encrypted volume
sudo mkdir -p /mnt/encrypted
sudo mount /dev/mapper/encrypted_name /mnt/encrypted

# One-command mount with auto-open
sudo mount -t ext4 /dev/mapper/encrypted_name /mnt/encrypted

Close/Unmount Volume

# Unmount filesystem
sudo umount /mnt/encrypted

# Close LUKS device
sudo cryptsetup luksClose encrypted_name

# Close all LUKS devices
sudo cryptsetup luksClose --all

Key Management

Add New Passphrase

# Add additional key slot
sudo cryptsetup luksAddKey /dev/sdXn

# Add key with specific slot
sudo cryptsetup luksAddKey --key-slot 1 /dev/sdXn

# Add key from file
sudo cryptsetup luksAddKey /dev/sdXn --key-file existing.key

Remove Passphrase

# Remove passphrase from slot
sudo cryptsetup luksRemoveKey /dev/sdXn

# Remove specific key slot
sudo cryptsetup luksKillSlot /dev/sdXn 1

Change Passphrase

# Change existing passphrase
sudo cryptsetup luksChangeKey /dev/sdXn

# Change specific key slot
sudo cryptsetup luksChangeKey --key-slot 0 /dev/sdXn

Key Slot Management

# Show key slots
sudo cryptsetup luksDump /dev/sdXn

# Backup header (before key changes)
sudo cryptsetup luksHeaderBackup /dev/sdXn --header-backup-file backup.img

# Restore header
sudo cryptsetup luksHeaderRestore /dev/sdXn --header-backup-file backup.img

# Erase header
sudo cryptsetup erase /dev/sdXn

Advanced Operations

Encryption Options

# AES-XTS with 512-bit key (recommended)
sudo cryptsetup luksFormat --cipher aes-xts-plain64 \
  --key-size 512 \
  /dev/sdXn

# Argon2i key derivation (slow, secure)
sudo cryptsetup luksFormat --pbkdf argon2i \
  --pbkdf-force-iterations 4 \
  /dev/sdXn

# Custom iteration count (higher = slower, more secure)
sudo cryptsetup luksFormat --iter-time 2000 /dev/sdXn

Resize Encrypted Volume

# Resize physical partition first
sudo parted /dev/sdX resize N START END

# Grow cryptsetup mapping
sudo cryptsetup resize encrypted_name

# Grow filesystem
sudo resize2fs /dev/mapper/encrypted_name

Open with Key File

# Generate random key file
sudo dd if=/dev/urandom of=keyfile.key bs=1024 count=4
sudo chmod 600 keyfile.key

# Use key file to open
sudo cryptsetup luksOpen --key-file keyfile.key /dev/sdXn encrypted_name

# Add key file as additional unlock method
sudo cryptsetup luksAddKey /dev/sdXn keyfile.key

Backup and Recovery

Backup LUKS Header

# Backup header
sudo cryptsetup luksHeaderBackup /dev/sdXn \
  --header-backup-file luks-header.backup

# List backup contents
sudo cryptsetup luksDump luks-header.backup

# Restore from backup
sudo cryptsetup luksHeaderRestore /dev/sdXn \
  --header-backup-file luks-header.backup

Device Information

Display Encryption Details

# Full LUKS header information
sudo cryptsetup luksDump /dev/sdXn

# Concise status
sudo cryptsetup status /dev/mapper/encrypted_name

# Table mapping
sudo dmsetup table /dev/mapper/encrypted_name

# Device info
sudo cryptsetup info /dev/sdXn

Performance Tuning

Benchmark Ciphers

# Test all available ciphers
sudo cryptsetup benchmark

# Test specific cipher
sudo cryptsetup benchmark --cipher aes-xts-plain64

# Test with different key sizes
sudo cryptsetup benchmark --cipher aes-xts --key-size 256

Optimize Performance

# Use faster cipher for less security-critical data
sudo cryptsetup luksFormat --cipher aes-cbc-plain64 \
  --key-size 256 \
  /dev/sdXn

# Disable integrity checking (faster, less secure)
sudo cryptsetup luksFormat --integrity none \
  /dev/sdXn

# Adjust iteration parameters for speed
sudo cryptsetup luksFormat --iter-time 1000 /dev/sdXn

Scripting and Automation

Automated Mount Script

#!/bin/bash
# Auto-mount encrypted volume

DEVICE="/dev/sdXn"
MAPPER_NAME="encrypted"
MOUNT_POINT="/mnt/encrypted"
KEYFILE="/root/keyfile.key"

# Open encrypted device
sudo cryptsetup luksOpen --key-file "$KEYFILE" "$DEVICE" "$MAPPER_NAME"

# Create mount point
sudo mkdir -p "$MOUNT_POINT"

# Mount filesystem
sudo mount /dev/mapper/"$MAPPER_NAME" "$MOUNT_POINT"

echo "Device mounted at $MOUNT_POINT"

Batch Encrypt Partitions

#!/bin/bash
# Encrypt multiple partitions

PARTITIONS=("/dev/sdb1" "/dev/sdc1")
PASSWORD="your-secure-password"

for PARTITION in "${PARTITIONS[@]}"; do
    echo "Encrypting $PARTITION..."

    echo -n "$PASSWORD" | \
    sudo cryptsetup luksFormat --type luks2 \
        --cipher aes-xts-plain64 \
        --key-size 512 \
        "$PARTITION" -

    echo "Successfully encrypted $PARTITION"
done

Troubleshooting

Common Issues

Issue: Device already in use

# Check what's using the device
sudo lsof /dev/mapper/encrypted_name
sudo fuser -m /mnt/encrypted

# Force unmount
sudo umount -l /mnt/encrypted
sudo cryptsetup luksClose --deferred encrypted_name

Issue: Wrong passphrase

# Verify passphrase works
echo "your_password" | \
sudo cryptsetup luksOpen --key-file - /dev/sdXn test_name

# If successful, close and try normal opening
sudo cryptsetup luksClose test_name
sudo cryptsetup luksOpen /dev/sdXn encrypted_name

Issue: Corrupted header

# Check header integrity
sudo cryptsetup luksDump /dev/sdXn

# Restore from backup if available
sudo cryptsetup luksHeaderRestore /dev/sdXn \
  --header-backup-file luks-header.backup

Issue: Permission denied

# Run cryptsetup with sudo
sudo cryptsetup luksOpen /dev/sdXn encrypted_name

# Add user to disk group (persistent)
sudo usermod -a -G disk $USER

# Log out and back in

Debug Commands

# Verbose output
sudo cryptsetup -v luksFormat /dev/sdXn

# Debug information
sudo cryptsetup -vvv luksOpen /dev/sdXn encrypted_name

# Dry-run (don't modify)
sudo cryptsetup --test-passphrase luksOpen /dev/sdXn

Security Best Practices

Key Management

• Generate passphrases with at least 15 random characters
• Store key files with 600 permissions (chmod 600)
• Back up LUKS headers before key changes
• Use separate key slots for different access methods
• Regularly rotate passphrases on sensitive volumes
• Never store key files on the encrypted volume

Cipher Selection

• Use AES-XTS with 512-bit keys for standard security
• Use Argon2i key derivation for increased security
• Adjust iteration count based on security/performance needs
• Benchmark ciphers for your hardware before deployment

Volume Management

• Always backup critical data before encryption
• Test recovery procedures before deploying
• Monitor disk space on encrypted volumes
• Keep cryptsetup updated
• Document encryption parameters and key slots

Full Workflow Example

#!/bin/bash
# Complete LUKS encryption workflow

set -e

DEVICE="/dev/sdXn"
MAPPER_NAME="secure_data"
MOUNT_POINT="/mnt/secure"

echo "=== LUKS Encryption Setup ==="

# 1. Format device with LUKS
echo "Formatting $DEVICE..."
sudo cryptsetup luksFormat --cipher aes-xts-plain64 \
    --key-size 512 \
    --hash sha256 \
    "$DEVICE"

# 2. Open encrypted device
echo "Opening encrypted device..."
sudo cryptsetup luksOpen "$DEVICE" "$MAPPER_NAME"

# 3. Create filesystem
echo "Creating filesystem..."
sudo mkfs.ext4 /dev/mapper/"$MAPPER_NAME"

# 4. Mount filesystem
echo "Mounting filesystem..."
sudo mkdir -p "$MOUNT_POINT"
sudo mount /dev/mapper/"$MAPPER_NAME" "$MOUNT_POINT"
sudo chown $USER:$USER "$MOUNT_POINT"

# 5. Verify setup
echo "Verifying setup..."
sudo cryptsetup luksDump "$DEVICE"
mount | grep "$MAPPER_NAME"

echo "=== Setup Complete ==="

Environment Information

Variable	Description
CRYPTSETUP_TIMEOUT	Timeout for interactive password entry
CRYPTSETUP_HASH	Default hash algorithm (default: sha256)
CRYPTSETUP_CIPHER	Default cipher (default: aes-xts-plain64)

Related Tools

• dm-crypt - LUKS encryption layer
• ecryptfs - File-level encryption
• VeraCrypt - Cross-platform disk encryption
• TrueCrypt - Legacy encryption (predecessor to VeraCrypt)

---

Last updated: 2026-03-30