arca

A CLI tool for mounting and unmounting LUKS-encrypted volumes. Latin for "strongbox."

arca talks to udisks2 over D-Bus for passphrase/keyfile unlock (no root needed) and falls back to cryptsetup for FIDO2/TPM2 token-based unlock (requires doas/sudo). It handles the unlock-then-mount and unmount-then-lock sequences as single commands.

Usage

arca mount backup              # unlock + mount by config alias
arca mount /dev/sda1           # unlock + mount by device path
arca mount backup -m /mnt/usb  # mount at a specific mountpoint
arca unmount backup            # unmount + lock
arca status                    # show all LUKS volumes and their state
arca init                      # generate config from detected devices
arca --version                 # print version

Mount and unmount are idempotent: mounting an already-mounted device prints the existing mount point; unmounting an already-locked device is a no-op.

Configuration

Optional. Without a config file, arca works with device paths directly using passphrase unlock.

Run arca init to auto-generate a config from detected LUKS devices (excludes the root filesystem). Edit the generated file to set aliases, methods, and mount points.

~/.config/arca/config.yaml (respects $XDG_CONFIG_HOME):

devices:
  backup:
    uuid: "b8b2f8e3-4cde-4aca-a96e-df9274019f9f"
    mountpoint: "/mnt/backup"  # optional — udisks2 picks if omitted
    methods:                   # optional — default: [passphrase]
      - fido2
      - passphrase
  media:
    uuid: "a1b2c3d4-5678-9abc-def0-1234567890ab"
    methods:
      - keyfile
      - passphrase
    keyfile: "/path/to/media.key"

Config fields

Field	Required	Description
uuid	yes	LUKS partition UUID (stable across device path changes)
mountpoint	no	Where to mount; udisks2 picks if omitted
methods	no	Ordered unlock strategies; default: [passphrase]
keyfile	no	Path to keyfile (required if keyfile is in methods)

Unlock methods

Method	Backend	Root required	Notes
passphrase	udisks2	no	Prompts on terminal
keyfile	udisks2	no	Reads file from keyfile config field
fido2	cryptsetup	yes (doas)	Requires enrolled FIDO2 token
tpm2	cryptsetup	yes (doas)	Requires enrolled TPM2 key

Methods are tried in order. If the first fails (e.g., FIDO2 key not plugged in), arca tries the next.

Installation

Nix flake

# flake.nix
inputs.arca.url = "git+https://git.wntrmute.dev/kyle/arca";

# in your NixOS config
environment.systemPackages = [ inputs.arca.packages.${system}.default ];

From source

go install git.wntrmute.dev/kyle/arca@latest

Requirements

• Linux with udisks2 running (standard on most desktop distributions)
• D-Bus system bus access
• For FIDO2/TPM2: cryptsetup, doas or sudo
• For FIDO2/TPM2: token must be enrolled via systemd-cryptenroll

NixOS Notes

cryptsetup loads token handler plugins (FIDO2, TPM2) via dlopen, but NixOS's glibc only searches the binary's baked-in RUNPATH, which doesn't include systemd's plugin directory. arca works around this by setting LD_LIBRARY_PATH to the systemd cryptsetup plugin directory when invoking cryptsetup.

The plugin directory is discovered automatically from /run/current-system/sw/lib/cryptsetup or by resolving the systemd-cryptenroll binary path.

Note: cryptsetup's --external-tokens-path flag does not work on NixOS due to the same RUNPATH limitation — the flag is accepted but the dlopen call still uses the default search path.

Enrolling a FIDO2 key

doas systemd-cryptenroll --fido2-device=auto /dev/sda1

This prompts for the existing passphrase, then enrolls the FIDO2 key. Verify with:

doas cryptsetup luksDump /dev/sda1 | grep -A3 Token

Troubleshooting

"cannot connect to udisks2": The udisks2 service isn't running. Check systemctl status udisks2.

"device not found": The device path or alias doesn't match anything udisks2 knows about. Run arca status to list detected devices, or arca init to regenerate the config.

"No usable token is available": The FIDO2/TPM2 token isn't enrolled on this LUKS device. Enroll with systemd-cryptenroll. Also check that the token plugin is discoverable (see NixOS Notes above).

"Not authorized to perform operation": udisks2 polkit authorization failed. This happens when mounting a device unlocked via cryptsetup (root-owned mapping). Use --mountpoint or set mountpoint in config to use privileged mount instead.

FIDO2 key not detected: Ensure the key is plugged in and /dev/hidraw* devices are accessible. Check doas systemd-cryptenroll --fido2-device=list.