Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

← braid

braid unlock

Open LUKS devices and mount the btrfs pool.

When to use it

  • After a boot, to unlock and mount the pool

Unless you’ve configured braid to automatically unlock on boot (braid.autoUnlock), you must use braid unlock to mount and access the pool.

Basic example

sudo braid unlock

You will be prompted for the pool passphrase.

Common variations

Pass passphrase non-interactively (useful for scripts or remote unlock):

echo -n 'hunter2' | sudo braid unlock --passphrase-stdin
sudo braid unlock --passphrase-file /tmp/pass.txt

Unlock with a binary keyfile from a mounted USB drive (e.g. for auto-unlock via systemd):

sudo braid unlock --key-file /mnt/usb/braid.key

Mount the USB first so the keyfile path refers to removable media, not persistent host storage.

Mount in degraded mode when a disk is missing:

sudo braid unlock --allow-degraded

Preview what would happen:

sudo braid unlock --dry-run

Important flags

FlagPurpose
--passphrase-stdinRead passphrase from stdin instead of TTY prompt
--passphrase-file <path>Read passphrase from a file (conflicts with --passphrase-stdin)
--key-file <path>Unlock with a binary keyfile instead of passphrase (conflicts with passphrase flags)
--allow-degradedAllow mounting with missing devices (degraded mode)
--dry-runShow what would happen without executing

What happens under the hood

  1. Checks that no other braid operation is pending
  2. Probes each UUID-keyed member in pool.json: checks whether the by-id device is present, whether its LUKS UUID matches, and whether its LUKS mapper is already open
  3. Verifies the selected credential against every disk it will unlock before opening any mapper
  4. Opens LUKS mappers for all locked disks using the verified credential
  5. Runs btrfs device scan to let the kernel discover all pool members
  6. Mounts the btrfs filesystem with noatime, skip_balance, and subvolid=5
  7. If any disks are unavailable and --allow-degraded is set: mounts with the degraded option
  8. After mount: enriches pool.json with live btrfs device IDs and related metadata – best-effort
  9. Checks for a paused balance and prints a warning if one is found

If all mappers are already open and the pool is already mounted, unlock is a no-op.

On NixOS module installs

After a successful mount, braid unlock activates braid-online.service. Any unit you have wired into the pool lifecycle with WantedBy=braid-online.service (e.g. an SMB or NFS unit – see Sharing and permissions) starts as part of that activation. braid lock stops them again on the way down via the matching BindsTo=braid-online.service.

Standalone CLI installs (no NixOS module) skip this – there is no braid-online.service to activate.

Degraded mode

When a disk is missing (physically absent or with an unreadable LUKS header), unlock refuses to mount by default. The error message names the affected disk and tells you to pass --allow-degraded.

In degraded mode, the pool mounts with reduced redundancy. New writes are NOT mirrored to the missing disk. You should repair the pool as soon as possible with braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...>.

The exit code is 2 when a degraded mount is refused (vs. 1 for other errors), so scripts can distinguish the two cases.

Safety checks / refusal cases

  • Refuses if a pending operation journal (pending-op.json) exists – run braid recover to reconcile.
  • Refuses if another braid operation is in progress (pool lock /run/braid-pool.lock is held) – retry once it finishes.
  • Refuses to mount degraded without explicit --allow-degraded
  • Refuses if a present disk’s LUKS UUID does not match the UUID recorded in pool.json – the disk was swapped, cloned, or reformatted out of band. The error names the disk, its by-id path, and the expected vs found UUID. This is a hard error caught during the initial probe, before any mapper opens; --allow-degraded does not bypass it (that flag only covers missing disks). If unintended, detach the foreign disk and reattach the original; if the swap was intentional, see Unlock refused by a foreign or mismatched disk.
  • If any disk rejects the selected credential during verification, unlock fails before opening any mapper and names the failing disk. If another disk already accepted the same credential, that points to disk-specific credential drift outside braid.
  • Does not prompt for a passphrase if all mappers are already open (idempotent re-run)