Safely stop an encrypted mapping with cryptdisks_stop

You will close a named device-mapper encryption mapping using the name from /etc/crypttab, then check that the mapping is gone without disturbing the backing device or the crypttab entry. Allow about ten minutes for a known mapping, plus time to confirm that no process is still using its mounted filesystem.

This guide describes the installed cryptsetup package, version 2:2.7.0-1ubuntu4.2, and its cryptdisks_stop(8) wrapper. The command needs root privileges. Stopping a live mapping can make an application lose access to data, so identify the target carefully and arrange a maintenance window where necessary.

1. Check the command and your privileges

First confirm which program will run and check its version. These are ordinary read-only commands:

$ command -v cryptdisks_stop
/usr/sbin/cryptdisks_stop
$ dpkg-query -W -f='${Package} ${Version}\n' cryptsetup
cryptsetup 2:2.7.0-1ubuntu4.2

The wrapper's documented syntax is cryptdisks_stop <name>. It reads /etc/crypttab and stops the device-mapper mapping corresponding to that name. It does not take a source device path, a mount point or a LUKS UUID as its argument.

Check the current identity before using sudo:

$ id -u
1000
$ sudo -v
$ sudo id -u
0

If id -u already prints 0, run the later commands without sudo. If the wrapper is run without root, the installed command exits with status 1 and prints that it needs root privileges. Root access is a requirement, not an option that selects a different mode.

2. Find the exact crypttab name

Read the relevant entry before stopping anything:

$ sudo awk '$1 == "CRYPTTAB_NAME" { print }' /etc/crypttab

Replace CRYPTTAB_NAME with the first field of the entry you want to inspect. For example, if the entry begins with vault UUID=..., the mapping name is vault and the device-mapper path is normally /dev/mapper/vault. The first field is a plain target name, not a path.

Do not use a broad command such as cat /etc/crypttab in a pasted support transcript if the file contains key-file paths or other sensitive deployment details. Show only the line you need, and treat the file as configuration data rather than as a shell script. The wrapper reads it; it does not write it.

Checkpoint: confirm both the name and the active mapping:

$ sudo cryptsetup status vault
/dev/mapper/vault is active.
  type:    LUKS2
  cipher:  ...
$ sudo ls -l /dev/mapper/vault

The status details vary with the device and installed cryptsetup build. If cryptsetup status says that the mapping is inactive, stop here: there is nothing for cryptdisks_stop to close under that name. If the name is wrong, correct the name rather than trying several guesses.

3. Check for users before the disruptive action

Stopping the mapping is service-disrupting. If it contains a mounted filesystem, unmount that filesystem first using the normal procedure for its service. Find mounts associated with the mapping without changing state:

$ findmnt --source /dev/mapper/vault

No output means findmnt did not find that source mounted. Output identifies a mount point that must be dealt with before the mapping can be closed. Also check for open files when the mapping is not mounted or when an unmount reports that it is busy:

$ sudo fuser -vm /dev/mapper/vault

Stop the owning service through its normal service manager, then repeat the checks. Do not kill an unknown process merely to make the stop command succeed. If the encrypted volume contains swap, a database, a virtual machine disk or another managed resource, use that resource's shutdown procedure first.

4. Stop one mapping

$ sudo cryptdisks_stop vault
 * Stopping crypto disk ...done.

The exact progress punctuation depends on the init-style logging functions on the host. The wrapper reads /etc/crypttab, finds the entry for vault, and asks cryptsetup to remove the corresponding mapping. It does not delete the crypttab line and it does not erase the encrypted data on the backing device.

Capture the exit status immediately if you are scripting or recording the operation:

$ status=$?
$ printf 'cryptdisks_stop exit status: %s\n' "$status"
cryptdisks_stop exit status: 0

Status 0 means the wrapper completed successfully. A non-zero status means the stop operation needs investigation; it is not permission to assume that the mapping is gone.

5. Verify that the mapping is inactive

Check both the cryptsetup view and the device node:

$ sudo cryptsetup status vault
Device vault is not active.
$ test ! -e /dev/mapper/vault && echo 'mapping is absent'
mapping is absent

The wording of the inactive message can differ between builds. The useful result is that cryptsetup status no longer reports an active mapping and the expected mapper node is absent. If the node remains, do not edit /etc/crypttab as a first response. Inspect the command's error, the service using the device and the system journal:

$ sudo journalctl -b --no-pager -n 80 | grep -iE 'crypt|dm-|vault'

Use the actual target name in place of vault. If you stopped the wrong mapping, there is no undo operation that restores its running state automatically. Follow the normal start procedure for your host, commonly cryptdisks_start vault, after confirming that no dependent service will be surprised by the remount or unlock.

6. Stop several named mappings deliberately

The installed wrapper accepts more than one name, and processes each supplied name. Use this only when you have checked every mapping and its dependency order:

$ sudo cryptdisks_stop cache vault
 * Stopping crypto disk ...done.

Do not pass every name from /etc/crypttab as a shortcut. Dependent filesystems and services may need an ordered shutdown, and a failed name can produce a non-zero overall result even if an earlier mapping was stopped. Verify each expected mapper node afterwards:

$ for name in cache vault; do
>     if sudo cryptsetup status "$name" 2>/dev/null | grep -q active; then
>         printf '%s is still active\n' "$name"
>     else
>         printf '%s is inactive\n' "$name"
>     fi
> done
cache is inactive
vault is inactive