Set LUKS2 Labels and Keyslot Policy with cryptsetup config

You will change persistent metadata in a LUKS2 header: a human-readable label, a subsystem name, or the priority of a keyslot. The encrypted payload and the passphrase material stay unchanged. Allow about 15 minutes for a real device, including a header backup and verification. You need the cryptsetup-bin package, a LUKS2 device or detached header, and elevated privileges if your account cannot read and write the target.

1. Check the installed command and format

cryptsetup-config(8) documents the config action as part of the cryptsetup command. It is not a separate executable. The local package used for these examples is cryptsetup-bin 2:2.7.0-1ubuntu4.2, providing cryptsetup 2.7.0.

$ command -v cryptsetup
/usr/sbin/cryptsetup
$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ cryptsetup config --help | sed -n '1,8p'
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
Usage: cryptsetup [OPTION...] <action> <action-specific>

The config action is supported only for LUKS2. Check the target before making a change:

$ sudo cryptsetup luksDump /dev/mapper/REPLACE_WITH_DEVICE
LUKS header information
Version:        2
...

Replace the example path with the underlying LUKS device, not the mounted filesystem or an already-created device-mapper path. If the header says Version: 1, stop: this action is not for that format.

2. Back up the header before editing it

Use luksHeaderBackup and write the backup to a protected location with enough free space. This is an elevated command because the source header is normally restricted:

$ sudo cryptsetup luksHeaderBackup /dev/REPLACE_WITH_LUKS_DEVICE \
    --header-backup-file /secure/backup/REPLACE_WITH_NAME.luks2-header
$ sudo ls -l /secure/backup/REPLACE_WITH_NAME.luks2-header

Keep the backup with the same care as the encrypted data. It contains the metadata and keyslot material needed to recover access, so do not upload it to an untrusted location or leave it readable by ordinary users. The backup is only useful if you can later identify the matching device and restore it deliberately.

3. Inspect the current label, subsystem and keyslots

Record the current state before changing it. The output includes the LUKS version, label, subsystem and each keyslot's priority:

$ sudo cryptsetup luksDump /dev/REPLACE_WITH_LUKS_DEVICE
LUKS header information
Version:        2
Label:          (no label)
Subsystem:      (no subsystem)
...
Keyslots:
  0: luks2
    Priority:   normal

Slot numbers are zero-based. Do not assume slot 0 is the slot you use: inspect the complete output and choose an existing slot deliberately. A keyslot priority affects the order in which cryptsetup tries slots. It does not change the passphrase, key material or encrypted data.

4. Set a label and subsystem name

Labels are useful for identification. A subsystem description can be consumed by udev rules or other host tooling. Set either field or both with one command:

$ sudo cryptsetup config \
    --label 'archive-2026' \
    --subsystem 'archive-vault' \
    /dev/REPLACE_WITH_LUKS_DEVICE

A successful run normally produces no output and returns status 0. Verify the new values in the header:

$ sudo cryptsetup luksDump /dev/REPLACE_WITH_LUKS_DEVICE | sed -n '1,12p'
LUKS header information
Version:        2
...
Label:          archive-2026
Subsystem:      archive-vault

These fields are stored in the header, so the change remains after reboot. They are metadata, not access controls. Anyone who can read the header can usually see them.

5. Change a keyslot priority carefully

The accepted priority values are prefer, normal and ignore. Select the slot explicitly with --key-slot:

$ sudo cryptsetup config \
    --key-slot 2 \
    --priority prefer \
    /dev/REPLACE_WITH_LUKS_DEVICE
$ sudo cryptsetup luksDump /dev/REPLACE_WITH_LUKS_DEVICE | sed -n '/Keyslots:/,$p'
Keyslots:
  2: luks2
    Priority:   prefer

prefer slots are tried before normal slots. An ignore slot is not used unless you explicitly request it with --key-slot. That can look like a failed passphrase after a reboot even though the keyslot is intact. Use ignore only when you have another working recovery route and have recorded the slot number.

The command does not add or remove a keyslot. If the requested slot does not exist, cryptsetup reports an error; do not work around that by guessing another number. Re-run luksDump and review the header backup.

6. Handle detached headers and locking warnings

If the LUKS header is stored separately from the data device, pass the header device or file with --header, and use the data device as the final argument only when your layout requires it. For a header-only configuration, the detached header path is the object being edited:

$ sudo cryptsetup config \
    --header /secure/headers/REPLACE_WITH_HEADER_FILE \
    --label 'archive-2026' \
    /dev/REPLACE_WITH_DATA_DEVICE

Confirm the exact arrangement from the command that created the volume before using this form. A wrong header path can fail safely, but it can also make you inspect or edit a different LUKS2 header than intended.

Do not add --disable-locks as a generic fix. The manual restricts it to environments where metadata locking is impossible because the runtime cannot use /run. Disabling locks while another process can touch the header creates a corruption risk. Stop competing storage jobs instead, or use the option only in the restricted environment it is meant for.

7. Recover or undo a mistaken change

For a typo in a label or subsystem, run cryptsetup config again with the intended value and verify with luksDump. For a mistaken priority, set the affected slot back to normal or to the priority you recorded:

$ sudo cryptsetup config \
    --key-slot 2 --priority normal \
    /dev/REPLACE_WITH_LUKS_DEVICE
$ sudo cryptsetup luksDump /dev/REPLACE_WITH_LUKS_DEVICE | grep -A2 '^  2:'

If the header is corrupted or the wrong metadata was edited, stop using the volume and restore the matching backup with the documented luksHeaderRestore workflow. Do not restore a backup over a live device or a header from a different volume. A restore is a destructive replacement of current metadata and can discard later keyslot changes.