Read or Change a LUKS UUID Safely with cryptsetup

cryptsetup luksUUID prints the UUID stored in a LUKS header, and can change it deliberately for a duplicate or a migration. The read-only check takes a few seconds. A UUID change takes a few minutes if you first make and verify a header backup.

Before you start

You need the cryptsetup-bin package and the path to the encrypted device, such as /dev/nvme0n1p3. Replace every example device with the exact block device you have identified. A wrong path can inspect or overwrite a different LUKS header.

Reading metadata may require root access, depending on the device permissions and how the storage is exposed. The commands below use sudo for predictable access. Run them from an account that is allowed to administer the machine, and keep the device mounted or active only when your normal maintenance procedure permits metadata inspection.

This guide describes cryptsetup 2.7.0, installed here from cryptsetup-bin. Check your own version before comparing output with another host:

cryptsetup --version

On this machine, that prints a line beginning with cryptsetup 2.7.0. Option names and the basic action are the same in the local cryptsetup-luksUUID(8) manual.

1. Identify the device

Do not start with a guessed partition number. Use the host's inventory tools, then compare the result with your storage record, mount point or provider console. For example:

lsblk -o NAME,PATH,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINTS

For a LUKS device, the UUID displayed by filesystem or udev tools can describe a layer above the LUKS header. The command in the next step reads the LUKS UUID itself. That is the value that matters to cryptsetup and to tools locating the encrypted container.

Checkpoint: Write down the full device path you intend to inspect. If the device is a removable disk, check its size and serial information as well, because names such as /dev/sdb can change after a reboot.

2. Print the current LUKS UUID

Run the action with the device as its final argument:

sudo cryptsetup luksUUID /dev/EXAMPLE_LUKS_DEVICE

A successful run prints one UUID and nothing else, for example:

12345678-1234-1234-1234-123456789abc

The value uses the standard UUID form. Save it before making any change. A second read is a simple way to catch a pasted path that was not the one you meant:

sudo cryptsetup luksUUID /dev/EXAMPLE_LUKS_DEVICE | tee /tmp/luks-uuid-before.txt

The temporary file contains metadata, not a passphrase, but treat it as operational information and remove it when you no longer need it. If cryptsetup reports that the device does not exist, access is denied, or it is not a LUKS device, stop and correct the path or permissions. Do not add --type merely to silence an error: that option tells cryptsetup which device type is required and does not turn an ordinary block device into LUKS.

3. Back up the header before changing anything

Changing a UUID edits the LUKS metadata. It does not re-encrypt the data, but a mistake in the target or a later metadata failure can prevent activation. Make a binary header and keyslot backup first:

sudo cryptsetup luksHeaderBackup /dev/EXAMPLE_LUKS_DEVICE \
  --header-backup-file /var/tmp/EXAMPLE_LUKS_DEVICE.header.backup

Protect that backup like the encrypted device. It contains the header and keyslot area, so copying it to an unprotected shared location weakens your recovery boundary. Check that the file exists and has a plausible non-zero size, then copy it to your normal protected backup store before proceeding.

Warning: Do not overwrite an old backup casually. Give each backup a device, date and purpose in its filename, and ensure you can identify which physical or virtual device it belongs to.

4. Change the UUID deliberately

Choose a new UUID in the standard format, then run the write operation during a maintenance window:

sudo cryptsetup luksUUID \
  --uuid 12345678-1234-1234-1234-123456789abc \
  /dev/EXAMPLE_LUKS_DEVICE

There is normally no success message. The command's exit status is the useful signal. Check it immediately, then read the header again:

sudo cryptsetup luksUUID /dev/EXAMPLE_LUKS_DEVICE
printf 'exit status: %s\n' "$?"

Expect the new UUID followed by exit status: 0. If the command fails, do not assume the UUID changed. Read it again and keep the original backup until the device is confirmed healthy.

Changing a UUID can affect boot entries, /etc/crypttab, monitoring rules, inventory records and scripts that refer to the old value. Search and update those references as part of the same change. A running mapping may continue to use its existing name, but that does not make stale boot configuration correct on the next activation.

5. Use a detached LUKS header when required

If the LUKS header is stored in a separate device or file, pass it with --header and still provide the associated data device. Do not replace the data device with the header path:

sudo cryptsetup luksUUID \
  --header /path/to/EXAMPLE_LUKS_HEADER.img \
  /dev/EXAMPLE_DATA_DEVICE

For a detached header, back up the header file or device using the same care as an on-device header. Confirm the mapping between the data device and header from your deployment record before changing the UUID. A detached header in the wrong place can make a valid data device appear unreadable.

6. Recover if the metadata change was wrong

Recovery restores the complete saved header and keyslot area. It is not an undo button for a backup made after the mistake, so stop using the affected backup until you have selected the correct pre-change copy. The restore operation is destructive to the current header:

sudo cryptsetup luksHeaderRestore /dev/EXAMPLE_LUKS_DEVICE \
  --header-backup-file /var/tmp/EXAMPLE_LUKS_DEVICE.header.backup

Use the matching detached-header form when the header is separate. Make sure the target is unmounted and inactive according to your normal storage procedure, and verify the device path twice before pressing Enter. After restoration, print the UUID and test the ordinary activation path. If the backup does not match the device, do not improvise with another header; stop and recover from the storage system's documented backup.

Done means