Start a crypttab Mapping Safely with cryptdisks_start

cryptdisks_start starts a dm-crypt mapping already defined in crypttab, but the wrong name opens the wrong device. This walks through starting the mapping named in /etc/crypttab and confirming the expected device appears under /dev/mapper. Allow about ten minutes for a known-good entry and its passphrase.

This guide uses the Ubuntu package cryptsetup 2:2.7.0-1ubuntu4.2; the installed wrapper is from the 2.7.0 manual set.

Warning: Unlocking a mapping can make a filesystem available to other processes, and a bad crypttab entry can prompt for the wrong secret or target the wrong block device. Check the source device and mapping name before using an elevated command, and never test against a device you cannot identify.

1. Check the wrapper and its prerequisites

cryptdisks_start is a root-only wrapper around cryptsetup. It reads /etc/crypttab, finds the entry whose first field matches the name you supply, and asks cryptsetup to create that mapping. It does not take a device path directly:

$ command -v cryptdisks_start
/usr/sbin/cryptdisks_start
$ dpkg-query -W -f='${Package} ${Version}\n' cryptsetup
cryptsetup 2:2.7.0-1ubuntu4.2
$ cryptdisks_start --help
Usage: /usr/sbin/cryptdisks_start [-r|--readonly] <name> [.. <name>]

The installed wrapper also accepts --readonly, requesting a read-only mapping. The manual page's short synopsis shows only the required name, so treat this option as behaviour verified on the installed 2.7.0 package rather than a portability promise for every release.

Checkpoint: If command -v finds nothing, stop here. Installing or repairing the package is a separate system-administration task.

2. Inspect the matching crypttab entry

Read the file before starting anything:

• Field one is the target name.
• Field two identifies the encrypted source.
• Field three is a key file or the special value none.
• Field four holds optional settings.

The resulting device is /dev/mapper/<target>. Entries are processed in order, so any dependency needs to appear first:

$ sudo awk '$1 == "vault" { print NR ":" $0 }' /etc/crypttab
12:vault UUID=REPLACE-WITH-ACTUAL-UUID none luks

Replace vault with the exact target you intend to start. The UUID above is deliberately a placeholder: copy the real value from your host, not from this example. A line using none reads the passphrase interactively. If field three names a key file, this wrapper passes --key-file=- to cryptsetup, so the complete key-file content must not end with a newline.

Warning: Never paste a secret into a shell command or put a real key into a guide, ticket or shell history. Check an existing key file's permissions and ownership separately, and keep its contents out of diagnostic output.

3. Start one mapping

Starting a mapping changes kernel device state and may make encrypted data available. Use the exact target from field one, and keep the terminal available for an interactive passphrase prompt:

$ sudo cryptdisks_start vault
 * Starting crypto disk ...

Output formatting can vary with the init-script helper; a successful return status matters more than the decorative progress text. If the entry uses none, enter the passphrase when prompted, and do not answer repeated prompts blindly: three failed attempts is the usual crypttab default, but a given entry may set a different tries value.

For a mapping that must not accept writes, use the wrapper's read-only option:

$ sudo cryptdisks_start --readonly vault

Read-only mapping does not make an untrusted filesystem safe to mount. Filesystem drivers, mount options and the application accessing the device still matter.

4. Verify the mapping without mounting it

Confirm both the command status and the mapping name. None of this mounts a filesystem:

$ printf 'start status: %s\n' "$?"
start status: 0
$ ls -l /dev/mapper/vault
lrwxrwxrwx 1 root root ... /dev/mapper/vault -> ../dm-2
$ sudo cryptsetup status vault
/dev/mapper/vault is active and is in use.

The device number and exact status wording vary. A zero exit status plus an active mapping is the useful result; it is not proof the filesystem is healthy, that the source UUID was the one you expected, or that it is safe to mount. If you need that assurance, verify the source device and filesystem in a separate, read-only workflow.

5. Diagnose the common failures

• Name not found in crypttab? Compare the spelling and inspect field one again. The command never infers a target from a source device path.
• Refused because you are not root? Rerun the same command through sudo. Changing the name will not fix a privilege error.
• Unlocking fails? Check the source identifier, encryption type and key selection in /etc/crypttab. A wrong passphrase is different from a missing device. Do not remove or recreate a mapping to make an error disappear, and never run formatting commands as a test; preserve the original entry while investigating.
• Key file suspiciously refused? A key file created with a text editor often has a trailing newline, which matters here because the wrapper supplies it as standard input to cryptsetup. Fix it only through your normal secret-management procedure; do not print it to prove that it changed.

6. Stop the mapping when finished

Stopping the mapping removes the active device but does not erase the encrypted data. First unmount any filesystem that uses it, stop applications using it, and check for open users. Then run the matching wrapper:

$ sudo cryptdisks_stop vault
 * Stopping crypto disk ...

Verify it is no longer active:

$ sudo cryptsetup status vault
Device vault is not active.

The exact message varies by version. If stopping fails because the mapping is busy, do not force removal while it is mounted: find and close the remaining users, unmount cleanly, and retry.

Done means

• Version and target confirmed. You checked the installed cryptsetup version and the exact target name.
• Entry inspected. You looked at the matching /etc/crypttab entry and identified its source device.
• Mapping started safely. You used elevated privileges and kept passphrases out of shell history.
• Mapping verified. cryptsetup status and /dev/mapper/<target> confirm the expected active mapping.
• Shutdown order understood. You know to unmount users before running cryptdisks_stop.