Check a Device for LUKS Before You Touch It

Before you run anything destructive against a device, cryptsetup-isLuks(8) tells you whether it actually holds a LUKS header. You will check a device or file, use the result directly in a shell script, and learn to tell a genuine negative probe apart from a permission or path error.

The examples use cryptsetup 2.7.0, installed here as package version 2:2.7.0-1ubuntu4.2. Allow about ten minutes. You need the cryptsetup-bin package and a device or file you are authorised to inspect. This is a read-only inspection: do not run luksFormat, luksErase or another write operation as part of the check, since those commands can destroy data.

1. Confirm the installed command

Start with ordinary, unprivileged checks. They tell you which executable and package version your shell will use:

$ command -v cryptsetup
/usr/sbin/cryptsetup
$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ dpkg-query -W -f='${Package} ${Version}\n' cryptsetup-bin
cryptsetup-bin 2:2.7.0-1ubuntu4.2

The action is written as cryptsetup isLuks. The manual also names it cryptsetup-isLuks, which is the maintenance command and its manual page. It accepts one device argument after any options.

Checkpoint: if command -v finds nothing, stop and install or repair the package through your normal system administration process. Do not copy a binary from an untrusted source.

2. Probe an ordinary device

Give the command the exact path you intend to use later. This example is deliberately harmless: /dev/null is not a storage volume, and the command only reads enough to reject it.

$ cryptsetup isLuks --verbose /dev/null
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
Command failed with code -4 (wrong device or file specified).
Device /dev/null is not compatible.
$ printf 'exit status: %s\n' "$?"
exit status: 4

On this installed build, a recognised LUKS device produces the success result, while this non-LUKS test produces status 4. Treat the wording and numeric status as implementation details to verify on whatever build you deploy: the portable shell decision is success versus failure, not a guessed error-number table.

--verbose, or -v, adds human-readable feedback. Without it, a failed probe stays quiet, which is usually better for scripts.

3. Use the result in a script

Put the command directly in an if statement. This preserves its exit status and avoids parsing human-readable output:

if cryptsetup isLuks --quiet /dev/mapper/NAME; then
    printf '%s\n' 'LUKS metadata detected'
else
    status=$?
    printf 'Not confirmed as LUKS (status %s)\n' "$status" >&2
fi

Replace /dev/mapper/NAME with a path you have checked. The installed command accepts --quiet as the global batch-mode option -q; it suppresses confirmation questions. This read-only action should never prompt anyway, but keeping output and control flow separate makes the script easier to audit.

Tip: do not write cryptsetup isLuks ...; echo "$?" and then insert another command before reading the status. The special parameter always reports the command immediately before it.

4. Distinguish a negative probe from an access error

A normal non-LUKS result is not the same as "the path could not be opened". Check the path and permissions without changing anything:

$ ls -l /path/to/device
$ test -e /path/to/device && echo 'path exists'
$ test -r /path/to/device && echo 'readable by this user'
$ cryptsetup isLuks --verbose /path/to/device
$ printf 'exit status: %s\n' "$?"

An absent path, an unreadable device, a regular file without a valid header, and a real non-LUKS volume can each need a different response from an operator. The diagnostic text helps while investigating, but do not build a production script that depends on one exact sentence. If access is the issue, use the least privilege needed for that device and review the reason before reaching for sudo: elevation changes who can read storage metadata, it does not make an arbitrary path a LUKS device.

5. Require a particular LUKS version

Use --type when the next operation supports only a particular format. The check then asks for that device type rather than accepting any LUKS version:

$ cryptsetup isLuks --type luks1 /path/to/device
$ printf 'LUKS1 check status: %s\n' "$?"
$ cryptsetup isLuks --type luks2 /path/to/device
$ printf 'LUKS2 check status: %s\n' "$?"

Replace the path and keep the two checks separate. A LUKS2 device should not count as a positive LUKS1 match merely because both are LUKS. Confirm the accepted type names and behaviour in that later command's own manual page.

6. Check a detached LUKS header

Some volumes keep the encrypted payload and the LUKS metadata on different devices. Pass the payload path as the positional argument and the header path with --header:

$ cryptsetup isLuks --header /path/to/detached-header /path/to/encrypted-payload
$ printf 'detached-header check status: %s\n' "$?"

Both paths are placeholders: do not guess them, and do not treat a header backup as a live header without confirming how it was created. The header contains sensitive metadata and can be enough to identify a volume, so protect its permissions and keep private paths out of shared logs.

7. Keep diagnostics safe

Done means