Initialise a LUKS2 Device with cryptsetup luksFormat

Setting up encryption on a new disk before any real data lands on it? cryptsetup luksFormat initialises the LUKS container, sets its first passphrase, and gives you a header you can verify before trusting it with anything important.

Allow 10 to 20 minutes for a prepared device, plus longer if the device is slow or the format includes an integrity wipe. This guide uses the locally installed cryptsetup 2.7.0 from the cryptsetup-bin package.

1. Check the command and identify the target

You need cryptsetup, a target device or deliberately chosen image file, and a passphrase you can store safely. Formatting normally needs elevated privileges because a real block device is protected by the operating system. Do not use a mounted filesystem, an active LVM physical volume or an active RAID member as the target: it must be unmounted and unused.

$ command -v cryptsetup
/usr/sbin/cryptsetup
$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,MOUNTPOINTS
$ findmnt --source /dev/EXAMPLE_DEVICE

Replace /dev/EXAMPLE_DEVICE only after lsblk and findmnt show it is the intended, unmounted device. A blank findmnt result is useful, but it does not prove the device is disposable: check its contents and ownership separately.

2. Choose the on-disk format

With cryptsetup 2.7.0, the normal choice is LUKS2: it supports the current metadata layout and PBKDF choices. Use LUKS1 only when a known older boot environment or other compatibility requirement needs it. Make the choice explicit in a script so a future reader can see the format that was intended.

# New deployment, normally LUKS2
$ sudo cryptsetup --type luks2 luksFormat /dev/EXAMPLE_DEVICE

# Compatibility case only
$ sudo cryptsetup --type luks1 luksFormat /dev/EXAMPLE_DEVICE

Do not run either command on a real target yet if you have not completed the checks in the next steps. Both are destructive examples, not harmless probes.

3. Use an interactive passphrase for the first format

For an interactive format, let cryptsetup prompt on the terminal and use --verify-passphrase so a typing error is caught immediately. Enter the passphrase at the prompt; do not place it in the shell command, command history or a process list.

$ sudo cryptsetup --type luks2 --verify-passphrase luksFormat /dev/EXAMPLE_DEVICE
WARNING!
========
This will overwrite data on /dev/EXAMPLE_DEVICE irrevocably.
Are you sure? (Type 'yes' in capital letters): YES
Enter passphrase for /dev/EXAMPLE_DEVICE:
Verify passphrase:

The exact warning and progress output varies with the device and build. A successful run returns to the shell without an error. The verification option is ignored when the passphrase comes from a file or standard input, so it gives no second check in those modes.

4. Use a key file only when its handling is designed

A key file can contain binary data and is read as the passphrase. The optional second argument is a key file, and --key-file is the explicit alternative. The local manual says --key-file - reads from standard input without stopping at newline characters, which makes automation possible but also makes accidental exposure easier.

$ sudo cryptsetup --type luks2 --key-file /secure/path/volume.key luksFormat /dev/EXAMPLE_DEVICE

# Read a bounded key file, excluding a trailing newline if required
$ sudo cryptsetup --type luks2 --key-file /secure/path/volume.key \
    --keyfile-size 32 luksFormat /dev/EXAMPLE_DEVICE

Protect the key file with filesystem permissions and your secret-storage process. Do not use echo 'passphrase' | sudo cryptsetup ...: it can leak through shell history, logs or process supervision. If a script must read standard input, test the complete secret-delivery path before using it on a real device.

5. Verify the new header

After formatting, inspect the metadata without opening the volume. These checks are ordinary read operations, although reading the target may still need sudo on your system.

$ sudo cryptsetup isLuks /dev/EXAMPLE_DEVICE
$ sudo cryptsetup luksDump /dev/EXAMPLE_DEVICE | sed -n '1,45p'
LUKS header information
Version:        2
Epoch:          ...
Metadata area:  ...
Keyslots:
  0: luks2

isLuks succeeds when the target has a recognised LUKS header. In luksDump, check the reported version and that keyslot 0 exists. The epoch, offsets and PBKDF details are device-specific, so do not compare them to a fabricated fixed output.

6. Back up the header before adding data

A header backup is part of the recovery plan, not a substitute for the passphrase. Store it separately from the encrypted device and protect it like sensitive material: someone with the header and the passphrase may be able to access the data, while losing or damaging the only header can make the data unavailable.

$ sudo cryptsetup luksHeaderBackup /dev/EXAMPLE_DEVICE \
    --header-backup-file /secure/backup/EXAMPLE_DEVICE.luks-header
$ sudo cryptsetup luksDump /secure/backup/EXAMPLE_DEVICE.luks-header | sed -n '1,12p'

Confirm the backup file exists, has the expected owner and permissions, and is included in your backup process. Do not restore it merely to test it on the live device: a restore replaces header and keyslot metadata and can make newer changes disappear.

Common traps

• Device busy? Stop rather than adding forceful options. Find mounts with findmnt, then inspect LVM, RAID and device-mapper users. Unmount or deactivate the dependent service only when you understand the impact.
• Formatted the wrong disposable image? Remove that image through your normal storage procedure.
• Formatted the wrong real device? Stop writing to it and use the latest verified header backup with cryptsetup luksHeaderRestore, only after checking the device and backup pair. Recovery of overwritten data is not guaranteed.
• Leave --batch-mode out of first-time commands. It suppresses confirmation questions and also disables passphrase verification unless --verify-passphrase is supplied.
• Leave PBKDF tuning at the compiled defaults unless you have measured the target hardware and know the opening-speed constraints. Forced memory or iteration values can make opening unusably slow or exhaust memory.