braid

braid is a NixOS CLI tool for managing an encrypted btrfs RAID1 NAS. These docs cover end-user workflows, command reference, design decisions, internals, and development practices.

Common tasks

• First time setup – Getting started
• Add, remove, or replace a disk – add, remove, replace
• USB auto-unlock – Auto-unlock
• Set up disk health alerts – Monitoring and alerts
• Suspend when idle, wake on demand – Power management

Guides

Commands

Commands marked 🧪 are experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Design

Internals

Development

Install NixOS

You can follow NixOS’ own guide here:

• https://nixos.org/manual/nixos/stable/
• https://wiki.nixos.org/wiki/NixOS_Installation_Guide

I’ll document the process and the post-install setup, mostly for my own notes.

Download NixOS image

• Go to https://nixos.org/download/#nix-install-linux
• Scroll down to ISO image section
• Download the Graphical 64-bit Intel/AMD image

This guide uses the graphical installer’s wizard for partitioning, swap, and user creation. The Minimal ISO is out of scope here – if you prefer it, follow NixOS’ install guide instead.

Format USB stick with NixOS image

• Download Etcher
• Plug in USB stick
• Use Etcher to write your downloaded ISO image to your USB stick

Install NixOS on NAS computer

• Plug in USB stick and boot from it
• Choose “Install NixOS (Linux LTS)” – this launches the graphical installer
• Click through the wizard. It handles partitioning, swap, and user creation for you.
• Reboot when done; unplug the USB stick so it doesn’t boot from it again

Post-install

Enable SSH

The graphical installer doesn’t enable SSH by default. Log in physically on the NAS console with your user, then add openssh:

sudo nano /etc/nixos/configuration.nix
# add: services.openssh.enable = true;
sudo nixos-rebuild switch

Find the NAS’s LAN IP and SSH in from your laptop:

# On NAS
ip a            # look for LAN ip address

# On your laptop
ssh [email protected]

# Once logged in on NAS, change your password
passwd

The rest of this guide takes place over SSH from your laptop.

Install vim

We’ll add more packages later. For now I just want vim on the system to make the rest of the setup easier.

sudo nano /etc/nixos/configuration.nix

environment.systemPackages = with pkgs; [ vim ];

sudo nixos-rebuild switch

Make git repo for NixOS config

The beauty of nix is that your OS is configured by git-diffable config files.

Instead of editing /etc/nixos/*.nix files, I like to have a ~/world git repo that tracks the NAS’s nix config and push it to danneu/world.

I’ll name my NAS “nasbox” here.

~/world/
├── flake.nix
└── hosts/
    └── nasbox/                        # NAS (NixOS)
        ├── configuration.nix        # System config (boot, networking, services)
        ├── hardware-configuration.nix
        └── home.nix                 # User config (packages, shell, git, etc.)

Let’s stub out that folder tree:

mkdir -p ~/world/hosts/nasbox

We use home-manager to manage user-level config (packages, git, shell, etc.) separately from the system config. This keeps configuration.nix lean — just boot, networking, and services — while home.nix handles everything specific to your user.

In ~/world/flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    home-manager.url = "github:nix-community/home-manager/release-26.05";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, home-manager, ... }: {
    nixosConfigurations.nasbox = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./hosts/nasbox/configuration.nix
        home-manager.nixosModules.home-manager
        {
          home-manager.useGlobalPkgs = true;
          home-manager.useUserPackages = true;
          home-manager.users.dan = import ./hosts/nasbox/home.nix;
        }
      ];
    };
  };
}

Copy the generated NixOS config into your world repo:

cp /etc/nixos/configuration.nix ~/world/hosts/nasbox/
cp /etc/nixos/hardware-configuration.nix ~/world/hosts/nasbox/

Make sure hosts/nasbox/configuration.nix imports the hardware config with a relative path:

imports = [ ./hardware-configuration.nix ];

Create hosts/nasbox/home.nix for your user-level config:

{ pkgs, ... }:

{
  home.username = "dan";
  home.homeDirectory = "/home/dan";
  home.stateVersion = "26.05";
  programs.home-manager.enable = true;

  home.sessionVariables = {
    EDITOR = "vim";
    VISUAL = "vim";
  };

  programs.git = {
    enable = true;
    userName = "Your Name";
    userEmail = "[email protected]";
    extraConfig = {
      init.defaultBranch = "master";
      pull.rebase = true;
      push.autoSetupRemote = true;
    };
  };

  home.packages = with pkgs; [
    lazygit   # Terminal UI for git
    ripgrep   # Fast recursive grep (rg)
    fd        # Fast find alternative
    jq        # JSON processor
    htop      # Interactive process viewer
  ];
}

Now rebuild from the flake instead of /etc/nixos:

sudo nixos-rebuild switch --flake ~/world#nasbox

From now on, you edit ~/world/ as your normal user and only sudo for the rebuild. System-level config goes in configuration.nix, user-level config goes in home.nix.

Set up git and push to GitHub

Generate an SSH key on the NAS and add it to GitHub so you can push/pull:

ssh-keygen -t ed25519 -C "nasbox"
cat ~/.ssh/id_ed25519.pub

Copy the public key and add it at GitHub > Settings > SSH and GPG keys > New SSH key.

Then init and push:

cd ~/world
git init
git add -A
git commit -m "initial nixos config"
git remote add origin [email protected]:danneu/world.git
git push -u origin master

Set hostname and pin the IP

Edit ~/world/hosts/nasbox/configuration.nix:

networking.hostName = "nasbox";

sudo nixos-rebuild switch --flake ~/world#nasbox

For a stable IP, the simplest approach is a DHCP reservation on your router: look up the NAS’s MAC address (ip link show <iface>) and tell the router to always hand it the same address. The reservation lives on the router, not the host – no nix changes and no nixos-rebuild needed. Bonus: it survives interface renames.

If you’d rather pin it on the host, add to configuration.nix:

networking.interfaces.eno1.ipv4.addresses = [{
  address = "192.168.1.158";
  prefixLength = 24;
}];
networking.defaultGateway = "192.168.1.1";
networking.nameservers = [ "1.1.1.1" "8.8.8.8" ];

Then rebuild:

sudo nixos-rebuild switch --flake ~/world#nasbox

Set up SSH key auth

On your laptop, copy your public key to the NAS:

ssh-copy-id [email protected]

Now you can SSH in without a password. Optionally disable password auth in configuration.nix:

services.openssh = {
  enable = true;
  settings.PasswordAuthentication = false;
};

Set up Claude Code and Codex

numtide/llm-agents.nix is a daily-updated nix flake that packages 40+ AI coding agents, including Claude Code and OpenAI’s Codex CLI. It exposes them via an overlay under pkgs.llm-agents.*.

Add it as a flake input in ~/world/flake.nix and apply its overlay:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    home-manager.url = "github:nix-community/home-manager/release-26.05";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";

    # No `follows = "nixpkgs"` -- llm-agents is built against nixpkgs-unstable.
    llm-agents.url = "github:numtide/llm-agents.nix";
  };

  outputs = { nixpkgs, home-manager, llm-agents, ... }: {
    nixosConfigurations.nasbox = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./hosts/nasbox/configuration.nix
        { nixpkgs.overlays = [ llm-agents.overlays.default ]; }
        home-manager.nixosModules.home-manager
        {
          home-manager.useGlobalPkgs = true;
          home-manager.useUserPackages = true;
          home-manager.users.dan = import ./hosts/nasbox/home.nix;
        }
      ];
    };
  };
}

First, allow unfree packages in hosts/nasbox/configuration.nix:

nixpkgs.config.allowUnfree = true;

Then add both binaries to the existing home.packages list in hosts/nasbox/home.nix:

home.packages = with pkgs; [
  lazygit
  ripgrep
  fd
  jq
  htop
] ++ (with pkgs.llm-agents; [
    claude-code
    codex
  ]);

Rebuild:

sudo nixos-rebuild switch --flake ~/world#nasbox

Now you can run claude and codex from anywhere on the NAS.

Optional: use the numtide binary cache

By default, source-built agents like codex will compile locally on first install. To pull prebuilt binaries instead, add the numtide cache to your system config (in hosts/nasbox/configuration.nix):

nix.settings = {
  extra-substituters = [ "https://cache.numtide.com" ];
  extra-trusted-public-keys = [
    "niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g="
  ];
};

Then rebuild. Subsequent installs will fetch from the cache.

Next steps

At this point you have a working NixOS machine with SSH access, a stable IP, Claude Code + Codex, and a git-tracked config. Next: add braid to your NixOS config.

← braid

Getting started

This guide walks you through first-time braid setup: installing the NixOS module, finding your disks, creating a pool, and unlocking it.

Read this if you have a fresh NixOS machine with empty drives and want to set up an encrypted RAID1 NAS.

What braid manages

braid owns two things:

• LUKS encryption – each drive is individually encrypted with a shared passphrase. Keys are never stored on disk.
• btrfs RAID1 – your encrypted drives form a single filesystem with automatic redundancy and self-healing checksums.

The NixOS module provides the systemd units, mount point, and toolchain. The CLI owns which disks are in the pool – adding or removing a drive is a braid command, not a nixos-rebuild.

Pool membership lives in /var/lib/braid/pool.json. This file is created by braid add and read by braid unlock. It is keyed by each member’s LUKS UUID; the disk name is stored inside each entry for commands and display.

Install the NixOS module

Add braid to your flake inputs and import the module:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    braid.url = "github:danneu/braid?ref=release";
  };

  outputs = { nixpkgs, braid, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        braid.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

?ref=release follows braid’s release channel; nix flake update braid upgrades to the newest release. The snippet also keeps braid on its own pinned nixpkgs (no follows override) on purpose, so braid matches its binary cache (next section).

Minimal configuration:

# configuration.nix
braid = {
  enable = true;
  mountPoint = "/mnt/storage";  # default
};

Only braid.enable = true is required. nixosModules.default defaults braid.package to braid’s pinned braid-cli-unwrapped; mountPoint defaults to /mnt/storage.

Binary cache

braid publishes prebuilt binaries to a public Cachix cache. Add it before rebuilding so the NAS pulls the CLI instead of compiling Rust:

# configuration.nix
nix.settings = {
  extra-substituters = [ "https://braid.cachix.org" ];
  extra-trusted-public-keys = [ "braid.cachix.org-1:I/p7fx1z5n0+O80KzMuT7aXRdkVyHr/buZKaBu7HvJs=" ];
};

This relies on the no-follows input above – the cache only matches braid’s pinned nixpkgs. See NixOS configuration.

Rebuild and switch:

sudo nixos-rebuild switch

Find your disks

Use lsblk to identify the drives you want to add:

lsblk -d -o NAME,SIZE,MODEL,ID-LINK

Example output:

NAME  SIZE MODEL               ID-LINK
sda   12T  TOSHIBA MN07ACA12T  ata-TOSHIBA_MN07ACA12T_XXXX
sdb   12T  TOSHIBA MN07ACA12T  ata-TOSHIBA_MN07ACA12T_YYYY
sdc   12T  TOSHIBA MN07ACA12T  ata-TOSHIBA_MN07ACA12T_ZZZZ
sdd  500G  Samsung SSD 860     ata-Samsung_SSD_860_AAAA      # boot drive -- leave this alone

You need the ID-LINK values. braid always uses /dev/disk/by-id/ paths – never /dev/sdX, which can change between reboots.

Create the pool

Add your drives with braid add. Each drive gets a short name you choose and a by-id path:

sudo braid add \
  toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_XXXX \
  toshiba2=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_YYYY \
  toshiba3=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_ZZZZ

braid will:

1. Ask you to set a LUKS passphrase (used for all drives).
2. Format each drive with LUKS encryption.
3. Create a btrfs RAID1 filesystem across all drives.
4. Mount the pool at /mnt/storage.
5. Write pool membership to /var/lib/braid/pool.json.

All drives join the same btrfs RAID1 filesystem. btrfs RAID1 keeps exactly 2 copies of every block regardless of how many drives you add, so the pool tolerates a single drive failure – a 3-drive pool tolerates the same single failure as a 2-drive pool, with more usable capacity. See Day-to-day usage for what additional drives buy you and how to add them later.

The disk names (toshiba1, toshiba2, etc.) are permanent presentation labels used in all future commands. Pick something short and meaningful. braid uses the LUKS UUID, not the name or LUKS label, as the persistent disk identity.

After braid add completes, the pool is online and mounted. You can start using it immediately:

ls /mnt/storage/
cp photos/* /mnt/storage/photos/

Unlock after reboot

When the NAS reboots, the pool is offline – LUKS drives are closed and nothing is mounted. This is by design: your data stays encrypted until you explicitly unlock it.

SSH into the NAS and unlock:

ssh user@nas
sudo braid unlock

braid prompts for your LUKS passphrase, opens all drives, assembles the btrfs pool, and mounts it.

Check pool health

sudo braid status

This shows:

• Pool state (online/offline)
• Each disk’s health and LUKS status
• Disk allocation and free space
• Scrub status
• Any active alerts

Lock the pool

When you want to take the pool offline (unmount and close LUKS):

sudo braid lock

This is optional – the pool locks automatically on shutdown. Manual locking is useful before maintenance or if you want to ensure the drives are encrypted at rest while the machine stays on.

What’s next

• Day-to-day NAS usage – the reboot/unlock/use cycle, subvolumes, good habits
• Auto-unlock – USB keyfile for unattended reboots
• Monitoring and alerts – get notified when a disk has problems
• Power management – auto-suspend and Wake-on-LAN

Related commands

• add
• unlock
• lock
• status

← braid

Day-to-day NAS usage

This guide covers normal operation: the reboot cycle, checking on your pool, adding disks over time, organizing your data with subvolumes, and good operator habits.

Read this after you have completed Getting started and have a working pool.

The daily cycle

A typical NAS session looks like this:

NAS powers on
  -> boots to login (pool offline, drives encrypted)
  -> SSH in
  -> sudo braid unlock (enter passphrase)
  -> pool online at /mnt/storage
  -> use it (copy files, stream media, backups)
  -> pool locks automatically on shutdown

If you have auto-unlock configured with a USB keyfile, the unlock step happens automatically at boot.

Unlock

ssh user@nas
sudo braid unlock

braid prompts for your LUKS passphrase, opens all drives, and mounts the pool.

Use the pool

The pool is a normal directory at /mnt/storage (or whatever you set braid.mountPoint to). Copy files, create directories, share via Samba/NFS – it works like any other filesystem.

cp ~/photos/* /mnt/storage/photos/
rsync -av ~/documents/ /mnt/storage/documents/

Lock

sudo braid lock

This unmounts the pool and closes all LUKS devices. The pool locks automatically on shutdown, so manual locking is only needed if you want drives encrypted while the machine stays on.

Checking pool health

Run braid status periodically to check on your pool:

sudo braid status

This shows pool state, disk health, allocation, scrub history, and any active alerts. Make a habit of glancing at this after unlocking, especially if the NAS has been running unattended.

For an interactive view:

sudo braid tui

The TUI dashboard shows pool health, disk status, balance progress, and SMART data in a live-updating terminal interface.

Organizing data with subvolumes

btrfs subvolumes are the right way to organize different categories of data on your NAS. Think of them as lightweight partitions within the pool.

Subvolumes vs directories

A plain directory works fine for storing files, but subvolumes give you:

• Independent snapshots – snapshot your documents without snapshotting your movie library.
• Per-subvolume quotas – limit how much space a category can use (optional).
• Selective backup – send/receive individual subvolumes to an external drive.
• No cost upfront – subvolumes are free to create. They share the pool’s space with no pre-allocated size.

There is no downside to creating subvolumes early. If you later decide you do not need snapshots for a category, the subvolume still works exactly like a directory.

Creating subvolumes

Create subvolumes for your major data categories:

sudo btrfs subvolume create /mnt/storage/documents
sudo btrfs subvolume create /mnt/storage/photos
sudo btrfs subvolume create /mnt/storage/movies
sudo btrfs subvolume create /mnt/storage/music
sudo btrfs subvolume create /mnt/storage/backups

Then use them like normal directories:

cp ~/report.pdf /mnt/storage/documents/
rsync -av ~/Photos/ /mnt/storage/photos/

Snapshots

Snapshot a subvolume to create a point-in-time copy:

sudo btrfs subvolume snapshot -r /mnt/storage/documents /mnt/storage/.snapshots/documents-2026-04-09

The -r flag makes it read-only, which is best practice for backup snapshots. Snapshots are nearly instant and use no extra space until the original data changes. Deleting a file from the original subvolume does not reclaim its blocks while any snapshot still references them. To free that space, delete the snapshots holding the data with sudo btrfs subvolume delete /mnt/storage/.snapshots/<name>.

Listing subvolumes

sudo btrfs subvolume list /mnt/storage

To mount a specific subvolume at a custom path, for example for a service or a friendlier path under /home, see Mounting subvolumes.

Adding disks over time

You can add new drives to an existing pool without rebuilding or reformatting:

# Find the new drive
lsblk -d -o NAME,SIZE,MODEL,ID-LINK

# Add it
sudo braid add newdisk=/dev/disk/by-id/ata-NEWDISK_SERIAL

braid formats the new drive with LUKS (using your existing passphrase), adds it to the btrfs pool, and rebalances data across all drives. No nixos-rebuild required.

The balance runs in the foreground – braid add holds the terminal and does not return until it finishes, which can take hours on a large pool. braid shows live balance progress while it runs.

btrfs RAID1 keeps exactly 2 copies of every block no matter how many drives the pool has. A 3rd or 4th drive gives you more usable capacity, but it does not increase fault tolerance – the pool still tolerates a single drive failure, the same as a 2-drive pool. See Decision 001 for the rationale.

Responding to alerts

If the NAS beeps (or sends you an alert via a custom command), something needs attention:

1. SSH in and check status:

   sudo braid status
   

2. The status output shows what triggered the alert: btrfs device errors, a missing disk, or a SMART warning.

3. Investigate and fix the issue (replace a failing disk, check cables, etc.).

4. Once resolved, acknowledge the alert to silence it:

   sudo braid ack
   

See Monitoring and alerts for details on how alerts work.

Good operator habits

• Check braid status after unlocking – a quick glance catches problems early.
• Keep LUKS header backups – braid stores header backups in /var/lib/braid/luks-headers/ after operations that modify LUKS headers. Copy each .luksheader file off the NAS to a separate location, then delete the local file (braid status warns until they are removed). If a drive’s LUKS header is corrupted and you have no off-system backup, the data on that drive is unrecoverable.
• Run braid doctor – periodically check for configuration problems:

  sudo braid doctor
  

• Let scrubs complete – braid runs monthly scrubs by default. Scrubs verify every block’s checksum and repair corruption from redundant copies. braid starts them at low CPU priority (Nice=19) and idle I/O priority (IOSchedulingClass=idle). The CPU priority always applies; the I/O priority is best-effort – how strongly the kernel honors it depends on your block-layer I/O scheduler – so do not treat it as a guarantee that scrubs will never affect interactive workloads. The pool stays online throughout. If scrubs noticeably impact Samba, NFS, or local use on your hardware, retime them with braid.autoScrub.interval (any systemd calendar expression – e.g. "Sun *-*-* 02:00:00") to land in an off-peak window. Do not interrupt a scrub in progress.
• Create subvolumes early – there is no cost to creating them upfront, and you cannot convert a directory to a subvolume later without copying the data.

What’s next

• Auto-unlock – skip the manual passphrase step on boot
• Mounting subvolumes – expose a subvolume at a custom path
• Monitoring and alerts – automatic health checking and notifications
• Power management – suspend when idle, wake on demand

Related commands

• unlock
• lock
• status
• add
• tui
• doctor
• ack

← braid

Auto-unlock

This guide covers setting up unattended unlock with a USB keyfile so the pool comes online automatically at boot.

Read this if you want the NAS to unlock without SSH-ing in to type a passphrase – for example, after a power outage or scheduled reboot.

How it works

By default, braid requires a passphrase to unlock. Auto-unlock adds a binary keyfile stored on a USB drive as a second LUKS unlock method. At boot, braid mounts the USB, reads the keyfile, unlocks all drives, and unmounts the USB.

The passphrase (LUKS slot 0) still works for manual unlock. The keyfile lives in LUKS slot 1.

Boot behavior

With USB key present: NAS boots, braid-auto-unlock.service runs, mounts USB, unlocks pool, unmounts USB. Pool is online by the time you can SSH in.

Without USB key present: The service waits for the USB device (up to timeoutSec, default 5 seconds), then skips gracefully. The pool stays locked. You SSH in and sudo braid unlock with your passphrase as usual.

This means removing the USB key is all it takes to go back to manual unlock.

Step 1: Generate and enroll the keyfile

Plug in a USB drive and find its by-id path:

lsblk -d -o NAME,SIZE,MODEL,ID-LINK

Mount it somewhere temporary:

sudo mount /dev/disk/by-id/usb-SanDisk_Cruzer_XXXX-0:0-part1 /mnt/usb

Generate a random keyfile and enroll it into all pool disks:

sudo braid enroll /mnt/usb --generate

--generate requires /mnt/usb to already be mounted. This creates a 4096-byte random file at /mnt/usb/braid.key and enrolls it into LUKS slot 1 on every disk in the pool. braid asks for your existing passphrase to authorize the enrollment.

Unmount the USB:

sudo umount /mnt/usb

Enroll during braid add

If you are adding a new disk and already have a keyfile on USB, you can enroll in one step:

sudo braid add newdisk=/dev/disk/by-id/ata-NEWDISK_SERIAL --enroll /mnt/usb

The --enroll flag points to the directory containing braid.key. The new disk gets both the passphrase and the keyfile.

Step 2: Enable auto-unlock in NixOS config

Find your USB key’s by-id path (use the raw device, not a partition, if your USB has no partition table):

lsblk -d -o NAME,SIZE,MODEL,ID-LINK

Add to your NixOS configuration:

# configuration.nix
braid = {
  enable = true;

  autoUnlock = {
    enable = true;
    keyDevice = "/dev/disk/by-id/usb-SanDisk_Cruzer_XXXX-0:0-part1";
  };
};

Rebuild:

sudo nixos-rebuild switch

Configuration options

keyDevice must be a /dev/disk/by-id/ path. braid rejects /dev/sdX paths because they can change between reboots.

Degraded mode

By default, auto-unlock refuses to mount if any pool drive is missing. This prevents silent operation with zero redundancy.

If you want the pool to come online even with a missing drive (for example, if a drive has failed and you plan to replace it), set:

autoUnlock.allowDegraded = true;

Redundancy is reduced until the drive is replaced and data rebalances.

Step 3: Test it

Reboot the NAS with the USB key plugged in:

sudo reboot

After boot, SSH in and check:

sudo braid status

The pool should be online. Check the journal to confirm auto-unlock ran:

journalctl -u braid-auto-unlock.service

Then test without the USB key: remove it, reboot, and confirm the pool stays locked until you manually unlock.

Security considerations

The keyfile on the USB drive can unlock your pool without a passphrase. Treat it like a physical key:

• Remove the USB after boot. The auto-unlock service unmounts the USB immediately after reading the keyfile, but physically removing it ensures no one can copy the key from a running system.
• Store the USB securely. If someone has physical access to both the USB key and the NAS drives, they can decrypt your data.
• Keep a backup of the keyfile. If you lose the USB key, you still have your passphrase. But if you want another auto-unlock USB, you need to braid enroll again.

LUKS header backups

After enrolling a keyfile, braid modifies the LUKS header on each drive (adding slot 1). braid stores LUKS header backups in /var/lib/braid/luks-headers/ as a transient byproduct.

Copy each .luksheader file to a separate location (external drive, another machine), then delete the local file. braid status warns until the local copies are removed. If a drive’s LUKS header is corrupted, the off-system backup is the only way to recover access to that drive’s data.

What’s next

• Monitoring and alerts – get notified when a disk has problems
• Power management – auto-suspend and Wake-on-LAN

Related commands

• enroll
• unlock
• add

← braid

Monitoring and alerts

This guide covers how braid monitors disk health and notifies you when something goes wrong.

Read this if you want to understand the alert system, configure notifications, or respond to an alert.

How monitoring works

braid runs a health check every 5 minutes via a systemd timer. The check looks at three things:

1. btrfs device stats – non-zero error counters (read, write, flush, corruption, generation errors) on any drive.
2. Missing devices – a drive that should be in the pool but is not present.
3. SMART alerts – smartd detected a SMART health warning on a drive.

A scrub that discovers unrepairable read, checksum, or generation errors increments the same btrfs device stats, so it follows the same beep and braid status flow as an everyday I/O error.

If any check triggers, braid activates an alert.

What happens on alert

When braid monitor detects an issue (exit code 1), the systemd wrapper starts braid-alert.service, which:

• Beeps the PC speaker (if enabled) until acknowledged. The cadence starts at 5 seconds and backs off exponentially (5s, 10s, 20s, 40s, …) up to once every 15 minutes, so the early beeps are urgent but an ignored alert doesn’t stay obnoxious.
• Runs your custom alert command (if configured).

The beeping is intentionally persistent and annoying – you should not be able to ignore a disk problem on a NAS that holds your data.

Alerts are latched

An alert stays active until you acknowledge it with braid ack, even if the triggering condition goes away. This is by design: “a disk had errors” is worth investigating even if the error count stopped growing.

Configuration

Monitoring is on by default when braid.enable = true. Here is the full set of options:

braid = {
  enable = true;

  monitor = {
    enable = true;        # default: true
    interval = "5min";    # default: "5min" (systemd time span)
    beep = true;          # default: true (PC speaker alert)
    alertCommand = null;  # default: null (optional custom command)
  };
};

Options

Custom alert commands

Set monitor.alertCommand to run a script when an alert fires. This runs in addition to (not instead of) the beep:

braid.monitor.alertCommand = "/home/user/scripts/send-pushover-alert.sh";

The command runs as root. It should be idempotent – it may fire on every monitor cycle while the alert is active.

Disabling the beep

If you do not have a PC speaker or prefer silent alerts:

braid.monitor.beep = false;

You probably want to set a custom alertCommand if you disable the beep, otherwise alerts are silent and only visible in braid status.

SMART integration

braid automatically configures smartd to monitor all drives. When smartd detects a SMART health issue, it writes a flag file that braid’s monitor picks up on the next cycle.

You do not need to configure smartd yourself – braid sets it up with sensible defaults. The NixOS services.smartd options are still available if you need to customize behavior.

Alert workflow

When the NAS beeps (or your alert command fires):

1. SSH in and check status

ssh user@nas
sudo braid status

The output shows a banner when alerts are active and lists the causes:

• BtrfsDeviceErrors – a specific drive has non-zero error counters. Could be a bad cable, a dying drive, or a transient issue.
• MissingDevice – a drive is missing from the pool. Check if a cable came loose or if the drive failed.
• SmartdAlert – SMART reports a health warning. The drive may be failing.

2. Investigate

For device errors, check if they are growing:

# Wait a few minutes and check again
sudo braid status

Steady error counts after a reboot are often transient (power event, cable issue). Growing counts mean the drive is failing.

For a missing device, check physical connections. If the drive is dead, plan a replacement:

sudo braid replace --old deadname --new newname=/dev/disk/by-id/ata-NEW_SERIAL

3. Acknowledge

Once you have investigated and resolved (or accepted) the issue:

sudo braid ack

This silences the beep and resets the alert baseline. New errors after ack will trigger a fresh alert.

Checking monitor status

View the monitor service logs:

journalctl -u braid-monitor.service --since "1 hour ago"

View the alert service:

journalctl -u braid-alert.service

Check if the monitor timer is active:

systemctl status braid-monitor.timer

How the pieces fit together

braid-monitor.timer (every 5 min)
  -> braid-monitor.service
    -> braid monitor (exit 0 = ok/offline/lock-contended, 1 = alert, 2 = setup error)
      -> on exit 1: start braid-alert.service
        -> beep (PC speaker, 5s -> 10s -> ... -> 15min)
        -> alertCommand (if configured)

smartd (always running)
  -> detects SMART issue
  -> writes /var/lib/braid/smartd-alert flag
  -> starts braid-alert.service
  -> next braid monitor cycle picks up the flag

braid ack
  -> clears alert state
  -> braid-alert.service stops (beeping stops)

What’s next

• Power management – auto-suspend and Wake-on-LAN
• Day-to-day NAS usage – good operator habits

Related commands

• monitor
• status
• ack
• doctor

← braid

Power management

This guide covers auto-suspend, Wake-on-LAN (WoL), and troubleshooting the hardware and software chain that makes it all work.

Read this if you want your NAS to sleep when idle and wake on demand.

How auto-suspend works

When enabled, braid uses autosuspend to suspend the entire NAS to RAM when idle. This stops all drives, the CPU, and fans – the machine draws almost no power. Wake it with a Wake-on-LAN magic packet from any device on the network.

Suspend-to-RAM preserves LUKS keys and the mounted btrfs pool in memory. When the NAS wakes, the pool is immediately available – no re-unlock needed.

What counts as activity

The NAS stays awake while any of these are true:

If all checks pass (everything idle) for the configured idle time (default 15 minutes), the NAS suspends.

The WoL check gates braid’s auto-suspend path only. Manual sudo systemctl suspend remains available for maintenance and testing, but it bypasses braid’s pre-suspend WoL check.

Scrub wakeups

The monthly btrfs scrub timer is registered as an autosuspend wakeup source. If the NAS is asleep when a scrub is due, it wakes via RTC alarm, runs the scrub, and suspends again when idle.

Configuration

braid = {
  enable = true;

  autoSuspend = {
    enable = true;
    idleTime = 900;          # seconds before suspend (default: 900 = 15 min)
    wolInterface = "eno1";   # required -- your wired ethernet interface
  };
};

Options

wolInterface is mandatory. Without WoL, a suspended NAS is unreachable until someone presses the power button. Find your interface with:

ip link

Look for your wired ethernet interface (usually eno1, enp1s0, or similar). WiFi interfaces (wl*) are rejected – WoL requires wired ethernet.

Hardware compatibility

Recommended: Intel NICs

Intel ethernet controllers (e.g., X540, I210, I225) have reliable WoL support with the in-kernel ixgbe and igc drivers. These are the lowest-risk choice for a NAS that needs reliable remote wakeup.

Avoid: Aquantia/Marvell AQC107

The AQC107 (atlantic driver) has known WoL reliability issues on Linux. If WoL is important to you, avoid this chipset.

RTL8125 (Realtek 2.5GbE)

The Realtek RTL8125 works for WoL but requires the vendor r8125 driver instead of the in-kernel r8169. See the troubleshooting section below.

WoL troubleshooting

WoL involves a chain from BIOS to NIC driver to PCI bridge. When it does not work, you need to figure out which link in the chain is broken. Work through these steps in order.

1. Check BIOS settings

WoL must be enabled in your BIOS/UEFI. The exact option names vary by vendor, but look for:

• Wake on LAN or Wake on PCI/PCIe – enable this.
• ErP Ready or ErP Lot 6 – disable this. ErP is an EU power-saving regulation that cuts standby power below what the NIC needs to listen for magic packets. If ErP is on, WoL cannot work.
• Deep Sleep – disable if present. Similar to ErP, this cuts power to PCIe slots during standby.

2. Test basic suspend first

Before debugging WoL, verify the NAS can suspend and wake at all:

# Check available sleep states
cat /sys/power/state

You should see mem in the output. Test a manual suspend and wake with the power button:

sudo systemctl suspend

Press the power button to wake. If this does not work, suspend itself is broken (check ACPI settings in BIOS).

Identify spurious wake sources

Sometimes the NAS wakes immediately after suspend. Check what woke it:

# What woke the system last time?
journalctl -b -k | grep -i "wake"

# List ACPI wake sources
cat /proc/acpi/wakeup

The output looks like:

Device  S-state   Status   Sysfs node
XHC0      S3    *enabled   pci:0000:00:14.0
GLAN      S4    *enabled   pci:0000:00:1f.6
...

Disable wake sources one at a time to find the culprit. Use a binary search – disable half, test, narrow down.

To disable a wake source temporarily (resets on reboot):

echo XHC0 | sudo tee /proc/acpi/wakeup

Once you find the problematic device, disable it permanently via a udev rule in your NixOS config:

services.udev.extraRules = ''
  # Disable USB controller wake (XHC0 causes spurious wakeups)
  ACTION=="add", SUBSYSTEM=="pci", ATTR{vendor}=="0x8086", ATTR{device}=="0xa0ed", ATTR{power/wakeup}="disabled"
'';

Find the vendor and device IDs from lspci -nn for the corresponding PCI device.

3. Verify WoL is enabled on the NIC

After rebuild with braid.autoSuspend.wolInterface set, verify with doctor:

sudo braid doctor

Expected row:

[ok]   wake-on-lan     eno1 reports Wake-on: g (magic packet armed)

Wake-on: g means WoL is active (magic packet mode). If doctor reports Wake-on: d (disabled), the NixOS config is not taking effect – check that you rebuilt, that the interface name is correct, and that BIOS/driver WoL settings allow wake.

With autoSuspend enabled, braid also checks this before every automatic suspend. If the NAS is idle but does not sleep, run sudo braid doctor and inspect the wake-on-lan row.

4. Test WoL from another machine

From a different machine on the same network, send a magic packet:

# Install wakeonlan tool (on the sending machine)
# NixOS: nix-shell -p wakeonlan
# macOS: brew install wakeonlan

# Get the NAS MAC address (on the NAS, before suspending)
ip link show eno1
# look for "link/ether xx:xx:xx:xx:xx:xx"

# Suspend the NAS
ssh user@nas sudo systemctl suspend

# Send the magic packet (from the other machine)
wakeonlan xx:xx:xx:xx:xx:xx

If the NAS wakes, WoL is working. If not, continue to the next steps.

5. NIC driver issues

RTL8125 (Realtek 2.5GbE)

The in-kernel r8169 driver handles the RTL8125 but has unreliable WoL. The vendor r8125 driver fixes this.

Add to your NixOS config:

boot.extraModulePackages = with config.boot.kernelPackages; [ r8125 ];
boot.blacklistedKernelModules = [ "r8169" ];

After rebuild, verify the driver:

ethtool -i eno1 | grep driver
# should show: driver: r8125

6. PCI bridge wakeup (PME propagation)

Even with WoL enabled on the NIC, the NIC’s wake signal (PME – Power Management Event) must propagate through the PCI bridge to reach the CPU. Some BIOS implementations do not enable PME on intermediate bridges.

Check if PME is enabled on the bridge:

# Find the NIC's PCI address
lspci | grep -i ethernet
# e.g., 05:00.0 Ethernet controller: Intel ...

# Find its parent bridge
lspci -t
# Look for the tree path to your NIC

# Check PME on the bridge
sudo lspci -vvs 00:1c.0 | grep -i pme
# Look for "PME-Enable+" (good) or "PME-Enable-" (bad)

If PME is disabled on the bridge, enable it with a udev rule:

services.udev.extraRules = ''
  # Enable PME on PCI bridge for NIC WoL
  ACTION=="add", SUBSYSTEM=="pci", ATTR{vendor}=="0x8086", ATTR{device}=="0x7ab8", RUN+="${pkgs.pciutils}/bin/setpci -s %k CAP_PM+04.W=0100:0100"
'';

The setpci command sets the PME_En bit in the PCI PM capability. Replace the vendor/device IDs with those from your bridge:

sudo lspci -nn -s 00:1c.0
# e.g., 00:1c.0 PCI bridge [0604]: Intel Corporation ... [8086:7ab8]

Finding the right bridge

If lspci -t is hard to read, use this to trace the full path from NIC to root:

# Starting from the NIC PCI address (e.g., 05:00.0)
cd /sys/bus/pci/devices/0000:05:00.0
ls -la ..  # parent bridge
# Follow symlinks up until you reach the root bridge

Each bridge in the chain must have PME enabled for WoL to work. In practice, it is usually only one bridge between the NIC and the root that needs fixing.

7. Still not working

If WoL still fails after all the above:

1. Check dmesg on wake – after waking with the power button, look for clues:

   dmesg | grep -i -E "wake|suspend|pme|wol"
   

2. Try a different NIC – if your motherboard has multiple ethernet ports, try WoL on each one. Onboard Intel NICs are most reliable.

3. Test with a minimal NixOS config – remove all non-essential services and test WoL in isolation. If it works minimal but not full, bisect your config.

4. Check the NIC firmware – some NICs need firmware loaded at boot for WoL. Check dmesg | grep firmware for errors.

What’s next

• Monitoring and alerts – disk health alerts
• Day-to-day NAS usage – the reboot/unlock cycle

Related commands

• idle
• status
• lock

← braid

Fan control

This guide covers how to drive chassis fans from HDD temperatures on a NixOS NAS using the braid.fanControl module.

Read this if you want quieter idle and predictable ramp under sustained disk load – BIOS fan curves cannot see HDD temperatures, only CPU and motherboard temperatures.

Why HDD-driven fan control

HDD longevity drops as drives run hotter, so the goal is to keep them under a target temperature – a widely used rule of thumb is ~40 C. The catch is that the BIOS fan curve can’t see drive temperature; it reads only CPU package temp and a motherboard sensor. So no matter how the BIOS ramps the chassis fans, nothing in that loop is actually watching the drives. The BIOS already protects the CPU regardless of its TDP – the drives are the part left unmonitored.

The fix is to move fan control into Linux userspace using drive temps as the signal. The kernel’s drivetemp module exposes each SATA drive’s SMART temperature as a standard hwmon input, and hddfancontrol reads those inputs and drives the chassis fan’s PWM proportionally to the hottest drive.

braid.fanControl wraps hddfancontrol so you only provide two hardware-specific values (the Super I/O platform device name and PWM channel number from pwmconfig) plus two calibration values (pwm.minStart/pwm.maxStop from hddfancontrol pwm-test). The module handles the systemd service, drivetemp loading, SATA hotswap udev rules, and crash recovery.

Scope: braid.fanControl monitors all visible SATA devices, not only braid pool members. Drives generate heat regardless of LUKS state, pool membership, or mount status – binding fan control to pool state would leave warm disks uncooled when the pool is locked or before first unlock. SAS drives are out of scope.

The stack

Setup has two phases: interactive discovery on the running machine (one-time), then committing the result to Nix.

Prerequisites

• BIOS: put chassis fan headers into software/manual control, and match the header mode to the fan type – PWM for 4-pin fans, DC (voltage) for 3-pin fans. Getting this wrong leaves the fan either stuck at a fixed speed or uncontrollable from userspace. If unsure, pwmconfig’s spin-down test (below) will tell you: a fan on the wrong header mode will not ramp down.
• Leave the CPU fan header on BIOS auto. Don’t fight the board’s package thermal logic with userspace – the BIOS is better at protecting the CPU than you are.

Discovery

Discovery is a one-time interactive procedure. Its only output is four values you paste into Nix at the end:

• pwm.platformDevice – platform device name of the Super I/O chip (e.g. f71882fg.656)
• pwm.number – PWM channel number on that chip (e.g. 2 for pwm2)
• pwm.minStart – PWM value needed to start the fan from standstill
• pwm.maxStop – PWM value below which the spinning fan stalls

Install the tooling and load the sensor modules

braid.fanControl loads drivetemp automatically, but the interactive operator tools (sensors, sensors-detect, pwmconfig, hddfancontrol) are only needed on your PATH during discovery. Add them temporarily, plus your board’s Super I/O driver – these can stay in the committed config so future re-runs after drive swaps or chassis changes have the same tools available:

{ pkgs, ... }:
{
  environment.systemPackages = [ pkgs.lm_sensors pkgs.hddfancontrol ];
  boot.kernelModules = [ "coretemp" ];  # drivetemp added by braid.fanControl
}

Rebuild, then confirm you see per-drive temps:

sensors | grep -A1 drivetemp

You should see one drivetemp-scsi-*-0 block per SATA drive, each showing a current temp1 reading. drivetemp must be loaded before you run pwmconfig, or drive temps will not appear as eligible fan inputs.

Find your Super I/O chip

Run sudo sensors-detect and accept the defaults. When it asks whether to write /etc/modules-load.d/lm_sensors.conf, answer no – on NixOS, kernel modules are declared in boot.kernelModules, not in /etc.

At the end sensors-detect prints a summary. For most boards it names a driver (nct6775, it87, …); add that driver to boot.kernelModules alongside coretemp, rebuild, and confirm a new block appears in sensors showing fan RPMs and PWMs.

If the summary says Found unknown chip with ID 0xXXXX, sensors-detect’s chip-ID table has fallen behind the kernel. The kernel driver may already support your chip even though the detect script doesn’t recognize it. Grep the ID in the kernel source to find the driver:

# on github, search drivers/hwmon/*.c in torvalds/linux for the ID
# e.g., 0x1502 turns up in drivers/hwmon/f71882fg.c, so the module is f71882fg

Add the module you found to boot.kernelModules. If modinfo <module> works and sensors still shows no new block after rebuild, move on to the next section.

“Device or resource busy” on module load

If dmesg shows your Super I/O driver correctly identifying the chip but modprobe fails with Device or resource busy, ACPI has reserved the hwmon I/O region. The fix is a kernel parameter:

boot.kernelParams = [ "acpi_enforce_resources=lax" ];

This requires a full reboot – kernel command line changes don’t apply on nixos-rebuild switch alone. After the reboot, sensors should show a block for your Super I/O chip with fan RPMs and PWMs.

Map fans to PWMs with pwmconfig

pwmconfig identifies which PWM controls which fan by briefly stopping each fan in turn. Run it when drives are idle (not mid-scrub or rebuild) – a stalled fan during sustained write load is a bad place to be.

Before starting, record each PWM’s current enable value. pwmconfig flips them to manual (1) to run its spin-down test, and the meaning of other values is driver-specific (e.g. f71882fg uses 0=off / 1=manual / 2=auto; other drivers differ). Restoring the original is safer than hard-coding a mode:

for p in /sys/class/hwmon/*/device/pwm[0-9]_enable; do
  printf '%s = %s\n' "$p" "$(cat "$p")"
done

Save that output somewhere you can read after pwmconfig exits. Then run:

sudo pwmconfig

It walks each PWM, asks whether to switch it to manual (say yes so the spin-down test can run), then stops each fan briefly and asks which fanN_input reading dropped. Answer based on what you observe in the tool’s output.

After identification, it asks which fans to configure. Pick only the chassis fans. Skip the CPU PWM – leave it BIOS-controlled. Also skip any PWM whose fan did not respond (unpopulated header, or fan/header mode mismatch in BIOS).

pwmconfig writes an /etc/fancontrol file at the end. You won’t use that file (braid uses hddfancontrol, not vanilla fancontrol), but the tool’s spin-down output is still how you identify the PWM path and measure stall behavior. Record the PWM sysfs path for the chassis fan – something like /sys/devices/platform/<super-io>/hwmon/hwmonN/device/pwmN.

Translate the PWM path to a platform device

braid.fanControl takes the stable platform device name plus the PWM channel number, and resolves the (unstable) hwmonN segment at service start. Translate the pwmconfig-surfaced sysfs path with:

pwm=/sys/class/hwmon/hwmon4/device/pwm2  # from pwmconfig output
pwm_dir=$(dirname "$pwm")
if [ "$(basename "$pwm_dir")" != device ]; then
  pwm_dir="$pwm_dir/device"
fi
basename "$(readlink -f "$pwm_dir")"
# -> f71882fg.656

The if branch handles both sysfs layouts: hwmon*/device/pwmN (common on f71882fg, nct6775) and hwmon*/pwmN (fallback). Without it, the fallback layout resolves to hwmon4 instead of the platform device.

The PWM number is the numeric suffix on the pwmN filename (2 in the example above).

After pwmconfig exits, restore each skipped PWM to the value you recorded:

echo <original> | sudo tee /sys/class/hwmon/<N>/device/pwmK_enable

Measure minStart and maxStop with hddfancontrol pwm-test

hddfancontrol pwm-test ramps the PWM up and down while measuring fan RPM. It finds:

• pwm.minStart – the PWM at which a stopped fan begins spinning again
• pwm.maxStop – the highest PWM at which a spinning fan stalls

Run it against the chassis PWM path from the previous step:

sudo hddfancontrol pwm-test -p /sys/devices/platform/.../pwmN

It takes a couple of minutes (ramps slowly to avoid bouncing the fan). Record the final minStart and maxStop values it prints.

If the fan has a hardware RPM floor (common on voltage-controlled 3-pin fans, and some boards’ chassis headers even in PWM mode), pwm.maxStop will be 0 and pwm.minStart will be some low value – the fan never actually stops. That’s fine; hddfancontrol still handles the ramp correctly. The --min-fan-speed-prct floor in braid.fanControl prevents the daemon from commanding the fan off in any case.

Committing to Nix

Fan control is a braid sub-feature: it activates only when braid.enable = true (see Getting started). The recipes below show the full braid block; merge the non-braid lines (boot.*, environment.systemPackages) into your existing config.

Minimal recipe

Paste the four discovery values into braid.fanControl:

{ pkgs, ... }:
{
  environment.systemPackages = [ pkgs.lm_sensors ];   # optional: tools for re-running discovery
  boot.kernelModules = [ "coretemp" "nct6775" ];      # your Super I/O driver here
  # boot.kernelParams = [ "acpi_enforce_resources=lax" ];  # only if needed

  braid = {
    enable = true;            # fan control only runs when the braid module is enabled

    fanControl = {
      enable = true;
      pwm = {
        platformDevice = "nct6775.656";
        number = 2;
        minStart = 65;   # from hddfancontrol pwm-test
        maxStop  = 60;   # from hddfancontrol pwm-test
      };
    };
  };
}

The module resolves the PWM sysfs path at service start by globbing /sys/devices/platform/<platformDevice>/hwmon/hwmon*/{device/,}pwm<number>, which handles hwmonN renumbering across reboots. The platform device name (nct6775.656, f71882fg.656, etc.) is stable.

Sane defaults for the rest:

• minTemp = 30 / maxTemp = 40 – fan floors below 30 C, ramps to full at 40 C
• minFanSpeedPercent = 20 – fan never drops below 20% of range (conservative; upstream hddfancontrol default)
• interval = "30s" – 30-second polling interval

Override any of these in the braid.fanControl block if you want a different curve. See NixOS configuration for the full option table.

Tuning the curve

• Ramp starts too soon / fan audibly spools early on idle: raise minTemp (try 32-34).
• Drives climbing past 42-44 C under sustained load: lower maxTemp (try 38) or raise minFanSpeedPercent (try 30).
• Fan noticeably oscillating: raise interval (e.g. "60s"). HDDs heat slowly, so aggressive polling only adds jitter.

Additional sensor modules

For ECC DIMM temp monitoring (visible in sensors; not used by hddfancontrol directly):

boot.kernelModules = [ "coretemp" "nct6775" "jc42" ];

Verification

Watch both the drivetemp input and the PWM/RPM, not RPM alone. CPU heat or ambient temperature can produce a false-positive fan ramp if you’re eyeballing only RPM.

The self-contained recipe for a braid NAS (btrfs is already assumed): run a scrub as the heat source. It reads every extent on every drive, which is representative NAS load and needs no pre-staged payload. The example below uses /mnt/storage as a concrete mount point – substitute your own pool mount:

# pane 1: start the scrub
sudo btrfs scrub start /mnt/storage

# pane 2: watch the thermal signals
watch -n2 sensors

# pane 3: follow the hddfancontrol daemon log
journalctl -u hddfancontrol-braid -f

Expected: drive temps climb 3-8 C over 10+ minutes (HDDs heat slowly), and the PWM tracks in step per your minTemp/maxTemp curve. The daemon log prints temperature readings and speed changes as it polls.

Cancel anytime with:

sudo btrfs scrub cancel /mnt/storage

If drive temps climb but PWM doesn’t move, double-check the resolved PWM file is writable (ls -l /sys/devices/platform/<platformDevice>/hwmon/hwmon*/{device/,}pwm<number>) and that hddfancontrol-braid is running (systemctl status hddfancontrol-braid).

Monitoring commands

Quick reference for monitoring the fan control loop on a running system. These paths assume an f71882fg-family Super I/O; substitute your platform device if different.

# Live chassis fan RPM + drive temps
watch -n2 'cat /sys/devices/platform/f71882fg.656/fan2_input; sensors drivetemp-*'

# Follow daemon log (temp readings, speed changes)
journalctl -u hddfancontrol-braid -f

# Current PWM value (0-255)
cat /sys/devices/platform/f71882fg.656/pwm2

# All fan channels at a glance (RPM, PWM, control mode)
for i in 1 2 3; do echo "fan${i}: $(cat /sys/devices/platform/f71882fg.656/fan${i}_input) RPM, pwm${i}: $(cat /sys/devices/platform/f71882fg.656/pwm${i}), enable: $(cat /sys/devices/platform/f71882fg.656/pwm${i}_enable)"; done

# Service status
systemctl status hddfancontrol-braid

# All hwmon sensors (CPU, board, DIMM, drives)
sensors

# SMART details for a specific drive
sudo smartctl -a /dev/sda

The pwmN_enable values: 0=off, 1=manual (hddfancontrol sets this), 2=BIOS auto. hddfancontrol is configured with --restore-fan-settings, so a clean service stop restores the original enable mode.

TUI fans panel

braid tui’s Data tab gains a Fans row when fan control is enabled. The section title shows daemon: status for hddfancontrol-braid.service; the row shows current PWM/RPM, the Driving column names the hottest drive setting the curve, and the Curve column shows the configured temperature-to-speed range. The panel polls every 5 seconds. Press r to refresh both pool and fan probes immediately.

When braid.fanControl isn’t enough

braid.fanControl drives a single chassis PWM from the hottest SATA drive. That covers the common NAS case. If you need more control – multiple PWMs with different curves, PID-based responsiveness, non-SATA drive temperature sources – the usual escape hatches:

• Configure services.hddfancontrol directly (nixpkgs’s module supports multiple daemons, per-fan config).
• fan2go – Go daemon; supports multiple sensors and PID curves.
• CoolerControl – more featureful, GUI-oriented.

Disable braid.fanControl.enable and bring your own solution. The drivetemp kernel module that braid loads is the only piece you’d need to keep.

Worked example: ASRock Industrial IMB-X1231

A concrete walk-through of the discovery phase on one board, to show what the unknown-chip and ACPI-busy paths look like in practice.

Hardware

• Board: ASRock Industrial IMB-X1231 (mini-ITX, 12th/13th gen Intel)
• CPU: Intel i3-14100T (35W TDP)
• Memory: ECC SODIMM with a jc42-compatible thermal sensor on SMBus
• Chassis fan: single 120mm rear, voltage-controlled (not 4-pin PWM)

sensors-detect reported an unknown chip

Probing for Super-I/O at 0x2e/0x2f
Trying family `VIA/Winbond/Nuvoton/Fintek'...               Yes
Found unknown chip with ID 0x1502
    (logical device 4 has address 0x290, could be sensors)
...
Probing for `National Semiconductor LM78' at 0x290...       Success!
    (confidence 6, driver `lm78')

The lm78 hit is a false positive: it’s a 1995 chip whose ISA probe signature collides with anything living at 0x290. The real chip is whatever has devid 0x1502. Ignore the lm78 recommendation.

Finding the right driver in kernel source

A grep of drivers/hwmon/ in torvalds/linux for 0x1502 pointed at f71882fg.c:

#define SIO_F81866_ID    0x1010
#define SIO_F81966_ID    0x1502
/* ... */
case SIO_F81866_ID:
case SIO_F81966_ID:

So: Fintek F81966, register-compatible with the F81866, driven by the f71882fg module – which has supported this ID since kernel 5.16. lm_sensors 3.6.2’s chip-ID table just hadn’t caught up.

ACPI held the hwmon I/O region

After adding f71882fg to boot.kernelModules and rebuilding, the driver identified the chip in dmesg:

f71882fg: Found f81866a chip at 0x290, revision 48, devid: 1502

But modprobe failed with Device or resource busy. Added boot.kernelParams = [ "acpi_enforce_resources=lax" ], rebooted, and sensors showed the full Super I/O block:

f81866a-isa-0290
  fan1: 1489 RPM       <- rear chassis, voltage-controlled
  fan2: 1573 RPM       <- CPU cooler
  fan3:    0 RPM       <- unpopulated header
  pwm1: 58%  pwm2: 58%  pwm3: 72%
  temp1: 36.0 C  temp2: 20.0 C  temp3: 37.0 C

pwmconfig mapped the fans

The spin-down test confirmed:

• pwm2 -> fan2 (chassis fan; voltage-controlled – RPM floors at ~395 and never fully stops regardless of PWM). Selected for braid.fanControl.
• pwm1 -> fan1 (4-pin PWM CPU fan; stopped cleanly at PWM=60). Skipped – left on BIOS auto.
• pwm3 -> no fan (unpopulated header). Also left on auto.

hddfancontrol pwm-test

sudo hddfancontrol pwm-test -p /sys/devices/platform/f71882fg.656/hwmon/hwmon4/device/pwm2
...
minStart: 65
maxStop:  60

Final Nix config

boot.kernelModules = [ "coretemp" "f71882fg" "jc42" ];
boot.kernelParams  = [ "acpi_enforce_resources=lax" ];

braid = {
  enable = true;

  fanControl = {
    enable = true;
    pwm = {
      platformDevice = "f71882fg.656";
      number = 2;
      minStart = 65;
      maxStop  = 60;
    };
  };
};

End-to-end check

With drive temp at 32 C and the default curve (minTemp=30, maxTemp=40, minFanSpeedPercent=20): expected pwm2 = 20% + (32 - 30) / (40 - 30) * 80% of PWM range above maxStop. Observed pwm2 climbed smoothly with drive temp under a scrub, RPM tracked the pwmconfig correlation table. Control loop arithmetically correct.

What’s next

• Power management – suspend/resume and WoL, which interact with fan control
• Monitoring and alerts – SMART-based alerting complements active cooling

Related

• Arch Wiki: Fan speed control – distro-neutral reference for lm_sensors and fan control
• Kernel drivetemp driver – what the module exposes
• hddfancontrol – upstream project

← braid

UPS

This guide covers enabling UPS (uninterruptible power supply) support on a braid NAS via NUT (Network UPS Tools).

Enabling UPS support (braid.enable = true plus braid.ups.enable = true) turns on three behaviors:

• Orderly poweroff on low battery. When the UPS reports critical, NUT’s upsmon invokes systemctl poweroff. systemd unwinds braid-online.service’s ExecStop, which runs braid lock and cleanly unmounts the pool before the battery exhausts.
• Preflight refusal without verified utility power. braid add / remove / remove-missing / replace check UPS state at startup and refuse to begin a pool mutation unless the UPS reports verified utility power (OL). This narrows the surface that journal recovery needs to cover.
• Live state visibility. braid ups status (and the TUI Data tab) show the parsed upsc output: status flags, battery charge, runtime remaining, load, estimated watts, input voltage, and device info.

Scope

v1 supports a single USB-connected UPS on the NAS, monitored by the NAS itself (single-host standalone). Non-USB drivers work through the escape hatch but are not tested.

Minimal config

# configuration.nix
{
  braid = {
    enable = true;
    ups.enable = true;
  };
}

Defaults: name = "ups", driver = "usbhid-ups", port = "auto". Rebuild and plug the UPS’s USB cable in; NUT’s auto-detect finds the device.

Override the driver or port for non-USB UPSes:

braid = {
  enable = true;

  ups = {
    enable = true;
    name = "myups";
    driver = "apcsmart";
    port = "/dev/ttyS0";
  };
};

Checking status

# Curated human summary
sudo braid ups status

# Machine-readable JSON (stable shape for scripts)
sudo braid ups status --json | jq .

Example human output:

UPS: ups
Status: OL
Battery: 100%
Runtime: 30m 0s
Load: 17% (56 W estimated)
Input: 120.0 V (transfer 88-142 V)
Device: APC Back-UPS ES 550G
Battery manufactured: 2023/04/12
Last test: Done and passed

The watts line is labeled estimated and omitted entirely if the UPS does not report both ups.load and ups.realpower.nominal.

The --json output serializes the full parsed model. Distinct error sentinels are emitted for the common non-OK cases:

TUI UPS panel

braid tui’s Data tab gains a UPS row when UPS support is enabled. Status text is color-coded by severity:

• Green – OL (on utility power).
• Yellow – OB (on battery, not yet critical).
• Red – LB / TESTFAIL / COMMBAD / FSD (critical; shutdown imminent or comms-loss).
• DarkGray – UPS query failed, or no UPS state available yet.

The panel polls on the same 5-second cadence as the TUI fans panel. Press r to refresh both pool and UPS probes immediately.

What happens on low battery

1. upsmon sees ups.status: OB LB, declares the UPS critical.
2. upsmon runs its configured SHUTDOWNCMD. braid overrides the nixpkgs default (shutdown now) with systemctl poweroff.
3. systemd walks its shutdown sequence. braid-online.service stops with ExecStop running braid lock, which unmounts the pool and closes LUKS.
4. The host powers off before the battery exhausts.

Under the default upsmon timings (POLLFREQ = POLLFREQALERT = 5, FINALDELAY = 5) the window between LB detection and poweroff is ~10 seconds, plus however long braid lock takes. The default battery.runtime.low in most UPS drivers is around 120 seconds, which is enough headroom for a single-disk pool’s clean teardown. Larger pools may need a wider battery.runtime.low (set at the NUT level, not through braid).

Mutation refusal when utility power is not verified

With UPS enabled, braid add / remove / remove-missing / replace refuse to start unless upsc returns a non-empty status set that contains OL and no known blocker. The refusal cases are:

• on-battery (OB)
• a critical flag the TUI paints red (LB / TESTFAIL / COMMBAD / FSD)
• OL missing from an otherwise non-blocking status set
• upsc query or invocation failure (stopped daemon, unknown UPS name, or another fatal NUT error – the message includes upsc’s stderr when it exits non-zero)
• an empty or missing ups.status

Known non-critical advisory states such as OL RB, and unknown tokens co-present with OL and no known blocker, still pass: the OL flag is the affirmative utility-power proof, not a guarantee of full battery health. Example refusal:

$ sudo braid add newdisk=/dev/disk/by-id/ata-TOSHIBA_NEW
error: cannot verify UPS is on utility power (UPS reports on-battery)
-- refusing to start add. Check 'braid ups status', restore utility
power, then retry.

Recovery: run braid ups status to confirm, fix the UPS/NUT state, restore utility power, wait for the status to return to a trusted OL, and retry the command.

Two clarifications:

• braid doctor’s ups_daemon: ok means the configured NUT daemon is reachable; it is not a guarantee that mutating-command preflight will pass. The refusal error from add / remove / remove-missing / replace is the primary channel for the exact mutation-readiness blocker.
• The OL gate assumes the configured NUT driver reports OL on utility power as documented by NUT. If a device or driver violates that contract, inspect with braid ups status; the recovery is to fix the NUT driver/config or disable braid.ups until the UPS state can be trusted.

doctor checks

braid doctor adds two UPS-adjacent checks when UPS support is enabled:

• ups daemon – fails if upsc is missing or cannot be spawned, because braid cannot verify the enabled UPS shutdown path. It warns if upsc runs but cannot reach the daemon or exits non-zero. Fix missing upsc by checking the braid wrapper/NUT package path; fix daemon reachability with systemctl status upsd.service.
• braid-online – fails (high severity) if the pool is mounted but braid-online.service is not active. Without that service active, the UPS shutdown path does not unmount the pool, and the safety guarantee silently breaks. Fix by running systemctl start braid-online.service or braid unlock.

Both checks skip when UPS support is disabled, and the braid-online check additionally skips when the pool is not mounted (there is nothing for the UPS shutdown path to unmount).

v1 limitation: no async alert

There is no asynchronous notification when the UPS goes on battery or loses comms in v1. Operators who are not actively watching braid ups status or the TUI will not see those conditions – only the orderly shutdown on LB is automatic.

This is deliberate: integrating UPS events into braid’s shared alert model requires splitting AlertCause by persistence semantics (latched-until-ack for disk errors, active-while-condition-holds for live UPS states) and is out of scope for v1. See decisions/020-ups-integration.md for the open-question status.

If you need asynchronous UPS notifications today, wire NUT’s NOTIFYCMD directly – braid does not touch it.

Related

• ADR: UPS integration – scope, shutdown path, preflight contract.
• upsc man page – the raw command braid parses.
• power.ups NixOS options – the underlying nixpkgs module braid layers opinionated defaults on.

← braid

NixOS configuration

Complete reference for the braid NixOS module options. Read this when setting up braid for the first time or tuning behavior after initial setup.

Minimal config

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    braid.url = "github:danneu/braid?ref=release";
  };

  outputs = { nixpkgs, braid, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        braid.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

?ref=release pins braid to its release channel: a moving branch the release fast-forwards to each tag. nix flake update braid is then the “upgrade to the newest release” button, and flake.lock still pins the exact rev. The snippet deliberately omits braid.inputs.nixpkgs.follows – see Binary cache and Tool overrides for why no-follows is the default.

The braid.url input takes any of:

# flake.nix
braid.url = "github:danneu/braid?ref=release";   # newest release (default)
braid.url = "github:danneu/braid?ref=v0.0.1";    # pin a tag
braid.url = "github:danneu/braid?rev=<commit>";  # pin an exact commit

# configuration.nix
braid = {
  enable = true;
};

nixosModules.default supplies braid.package automatically. Override it only to build the CLI yourself.

Binary cache

braid publishes a prebuilt x86_64-linux CLI to a public Cachix cache on every release. Add it so the NAS pulls the binary instead of recompiling Rust:

# configuration.nix
nix.settings = {
  extra-substituters = [ "https://braid.cachix.org" ];
  extra-trusted-public-keys = [ "braid.cachix.org-1:I/p7fx1z5n0+O80KzMuT7aXRdkVyHr/buZKaBu7HvJs=" ];
};

The cache only hits when braid resolves to the exact store path CI built – that is, with the recommended no-follows setup above. Setting braid.inputs.nixpkgs.follows rebuilds braid against your nixpkgs, producing a different path and a cache miss. See Toolchain pinning and ADR 029.

What you get for free

When braid.enable = true, the module sets up:

• Monthly btrfs scrub – timer + service tied to pool lifecycle. Configurable via braid.autoScrub.
• Resilient boot – a dead drive never blocks boot. LUKS open and btrfs mount are deferred to braid unlock, not wired into boot.initrd.
• Pinned toolchain – btrfs-progs, cryptsetup, util-linux, NUT, smartmontools, and ethtool are pinned to NixOS stable versions. Override with braid.packages.* if needed.
• Shell completions – bash, zsh, and fish completions registered automatically via clap_complete.
• smartd integration – services.smartd enabled by default with a braid-owned alert script. SMART failures trigger the braid alert service.
• Storage group – a storage group is created; mount point is set to root:storage 2770 after unlock. See Sharing and permissions.
• Disk health monitoring – polls btrfs device stats every 5 minutes, audible beep on errors. Configurable via braid.monitor.
• Fan control (opt-in) – drive chassis fans from the hottest SATA drive temp. Handles hddfancontrol, SATA hotswap restart, crash recovery. Configurable via braid.fanControl.

Module options

Core

Tool overrides

Override these only if you need a specific version for compatibility testing. The recommended setup omits braid.inputs.nixpkgs.follows (the Minimal config example above), so nixosModules.default sources these defaults from braid’s own pinned nixpkgs (nixos-26.05) – the same versions the release binary cache is built against, so braid is a cache hit. Adding braid.inputs.nixpkgs.follows = "nixpkgs" is an advanced opt-out: it dedups your closure but rebuilds braid against your nixpkgs (a cache miss) and sources these tools from your nixpkgs instead. If you take it, keep your nixpkgs on the same NixOS stable release braid targets so the parsed tool output stays compatible – see Toolchain pinning.

Auto-scrub

The scrub timer is lifecycle-aware: it starts when the pool comes online and stops when the pool goes offline. Persistent = true ensures a missed scrub runs on next unlock (e.g. the pool was locked over a monthly boundary).

braid’s scrub conflicts with the NixOS built-in services.btrfs.autoScrub. If both are enabled, evaluation fails with a clear error. Disable one or the other.

Monitoring

When beep = true, the module unblacklists the pcspkr kernel module, creates a beep group, and sets up a udev rule for PC speaker access. The beep loops with exponential backoff (5s, 10s, 20s, 40s, …) capped at once every 15 minutes, until acknowledged with braid ack.

alertCommand runs in addition to the beep (not instead of). Use it for push notifications, email, etc.:

braid.monitor.alertCommand = "curl -s -d 'Disk error on NAS' https://ntfy.sh/my-nas-alerts";

See Monitoring and alerts for the full workflow.

Auto-unlock

keyDevice must use a /dev/disk/by-id/ path – /dev/sdX names shift when devices are added or removed.

The auto-unlock service mounts the USB read-only, reads braid.key, unlocks the pool, and unmounts the USB immediately. The keyfile is never left accessible. If the USB is absent at boot, the service exits cleanly without blocking boot.

See Auto-unlock for the enrollment and setup workflow.

Auto-suspend

Requires a wired ethernet interface – WiFi interfaces are rejected at evaluation time (WoL needs ethtool, which does not work for WiFi).

Activity checks that block suspend:

• braid idle – scrub or any btrfs kernel exclusive operation (balance, device add/remove/replace, resize, swap activate)
• Active SSH sessions
• Active local sessions (TTY/X11/Wayland)
• SMB connections (auto-detected if services.samba is enabled)
• NFS connections (auto-detected if services.nfs.server is enabled)

The scrub timer is registered as a wakeup source so the NAS wakes for scheduled scrubs.

See Power management for the full workflow.

Fan control

pwm.platformDevice and pwm.number are found via pwmconfig. pwm.minStart and pwm.maxStop are measured with hddfancontrol pwm-test -p <pwm-path>. All four are hardware-specific.

Monitors all visible SATA devices (not only braid pool members). Requires a board-specific Super I/O driver in boot.kernelModules – see Fan control for the hardware discovery workflow.

UPS

When enabled, NUT triggers an orderly poweroff on low battery (unwinding braid-online.service -> braid lock -> unmount) and pool-mutating commands (add/remove/remove-missing/replace) refuse to start unless the UPS reports verified utility power (OL). Only name is written to /etc/braid/config.json, so braid ups status and the TUI know which UPS to query; driver and port configure the NUT driver only. Non-USB drivers (apcsmart, snmp-ups) are an escape hatch and not first-class.

See UPS for the setup workflow and live status.

Full config example

Every option with its default (or a representative value for required/optional fields):

braid = {
  enable = true;
  # package -- defaults to nixosModules.default's pinned braid-cli-unwrapped;
  # set only to build the CLI yourself.
  mountPoint = "/mnt/storage";   # default
  poolAccessGroup = "storage";   # default; null to disable
  lockSystemdStopDeadlineSecs = 270;  # default; must stay below braid-online TimeoutStopSec

  # Tool version overrides -- the recommended setup omits nixpkgs `follows`, so
  # defaults come from braid's pinned nixos-26.05 (cache hit); `follows` is an
  # opt-out that tracks your nixpkgs but rebuilds braid (cache miss). See "Tool overrides".
  # packages.cryptsetup = pkgs.cryptsetup;
  # packages.btrfsProgs = pkgs.btrfs-progs;
  # packages.utilLinux = pkgs.util-linux;
  # packages.nut = pkgs.nut;
  # packages.smartmontools = pkgs.smartmontools;
  # packages.ethtool = pkgs.ethtool;

  autoScrub = {
    enable = true;       # default
    interval = "monthly"; # default; any systemd calendar expression
  };

  monitor = {
    enable = true;       # default
    interval = "5min";   # default
    beep = true;         # default
    alertCommand = null; # default; e.g. "curl -s -d 'alert' https://ntfy.sh/my-nas"
  };

  autoUnlock = {
    enable = false;  # default
    keyDevice = "/dev/disk/by-id/usb-Kingston_DataTraveler_XXXX-0:0";
    timeoutSec = 5;  # default
    allowDegraded = false; # default
  };

  autoSuspend = {
    enable = false;   # default
    wolInterface = "eno1";
    idleTime = 900;   # default (15 minutes)
  };

  fanControl = {
    enable = false;    # default; opt-in
    pwm = {
      platformDevice = "f71882fg.656";  # from pwmconfig (required)
      number = 2;                        # from pwmconfig (required)
      minStart = 65;     # from hddfancontrol pwm-test (required)
      maxStop = 60;      # from hddfancontrol pwm-test (required)
    };
    minTemp = 30;      # default
    maxTemp = 40;      # default
    minFanSpeedPercent = 20;  # default
    interval = "30s";  # default
  };

  ups = {
    enable = false;        # default; opt-in
    name = "ups";          # default
    driver = "usbhid-ups"; # default
    port = "auto";         # default
  };
};

Related

• Getting started – first-time setup walkthrough
• Auto-unlock – USB keyfile enrollment
• Monitoring and alerts – alert workflow and custom commands
• Power management – auto-suspend and WoL setup
• UPS – NUT-backed orderly poweroff, preflight safety, live status
• Fan control – hardware discovery and fan control setup
• Sharing and permissions – storage group and Samba

← braid

Sharing and permissions

How braid manages mount point permissions and how to share the pool over the network. Read this when setting up file access for multiple users or configuring Samba/NFS.

Mount point permissions

After every mount-producing command (unlock, add, recover), braid sets the mount root to:

root:storage 2770

This means:

• Owner (root): full access
• Group (storage): read, write, execute
• Others: no access
• Setgid bit (2): new files and directories inherit the storage group

Any user in the storage group can read and write files under the mount point. The setgid bit ensures that files created by any group member are owned by the storage group, so all members can manage each other’s files.

Adding users to the storage group

# configuration.nix
users.users.alice = {
  isNormalUser = true;
  extraGroups = [ config.braid.poolAccessGroup ];
};

users.users.bob = {
  isNormalUser = true;
  extraGroups = [ config.braid.poolAccessGroup ];
};

Using config.braid.poolAccessGroup instead of the literal "storage" keeps the reference correct if you customize the group name.

For network-facing services like Jellyfin or Plex that should only read a single subtree, prefer mounting that subvolume separately and using POSIX ACLs over adding the service to the storage group. See Mounting subvolumes for the recipe.

Custom group name

braid.poolAccessGroup = "nas";

The group is created automatically. All behavior (mount permissions, setgid) works the same with any valid Unix group name.

Disabling the storage group

braid.poolAccessGroup = null;

When null, braid does not create a group or set permissions on the mount point after unlock. You manage permissions yourself.

Umask note

The setgid bit on the mount root ensures new files get the correct group. But the creating user’s umask controls the permission bits. The default umask (022) produces files with mode 644 (owner write, group/other read-only).

For collaborative write access where all group members can edit each other’s files, set a more permissive umask for processes that write to the pool:

# In a Samba share definition (see below), force create mode handles this.
# For SSH users, set umask in their shell profile:
programs.bash.interactiveShellInit = ''
  umask 002
'';

With umask 002, new files are 664 (owner and group read-write, other read-only) and new directories are 775.

Samba integration

Samba is not part of the braid module, but it works well with the braid mount point. Here is a declarative NixOS Samba config:

# configuration.nix
services.samba = {
  enable = true;
  openFirewall = true;

  settings = {
    global = {
      workgroup = "WORKGROUP";
      "server string" = "NAS";
      security = "user";
    };

    storage = {
      path = config.braid.mountPoint;
      browseable = "yes";
      "read only" = "no";
      "valid users" = "@${config.braid.poolAccessGroup}";

      # File permissions for Samba-created files
      "create mask" = "0664";
      "force create mode" = "0664";
      "directory mask" = "2775";
      "force directory mode" = "2775";
    };
  };
};

# Set Samba passwords (run once per user):
#   sudo smbpasswd -a alice

Key points:

• valid users = @storage restricts the share to the storage group.
• force create mode and force directory mode ensure group-writable permissions regardless of the client’s umask.
• New files and directories inherit the storage group from the setgid bit braid sets on the mount root – a kernel behavior that does not require inherit permissions. force directory mode = 2775 keeps that setgid bit on Samba-created subdirectories so inheritance carries down the tree.
• Samba users must also be system users in the storage group.

Multiple shares

Create separate shares for different directories under the mount point:

services.samba.settings = {
  photos = {
    path = "${config.braid.mountPoint}/photos";
    browseable = "yes";
    "read only" = "no";
    "valid users" = "@${config.braid.poolAccessGroup}";
    "create mask" = "0664";
    "force create mode" = "0664";
    "directory mask" = "2775";
    "force directory mode" = "2775";
  };

  media = {
    path = "${config.braid.mountPoint}/media";
    browseable = "yes";
    "read only" = "yes";  # read-only share
    "valid users" = "@${config.braid.poolAccessGroup}";
  };
};

Binding shares to the pool lifecycle

By default, samba-smbd.service (the systemd unit NixOS creates from services.samba.enable) keeps running after braid lock. If a client is mid-transfer when you lock, umount blocks until the file handle is released. Wire the share into the pool lifecycle so systemd starts samba-smbd after braid unlock and stops it again before braid lock runs umount:

systemd.services.samba-smbd = {
  # Start smbd when braid marks the pool online after a successful unlock.
  wantedBy = [ "braid-online.service" ];
  # Stop smbd when braid-online stops, before braid lock unmounts the pool.
  bindsTo = [ "braid-online.service" ];
  # Order smbd on the correct side of braid-online start and stop jobs.
  after = [ "braid-online.service" ];
  # Skip boot or direct starts when the braid mount point is not mounted.
  unitConfig.ConditionPathIsMountPoint = config.braid.mountPoint;
};

All four fields are load-bearing and do different jobs:

• wantedBy – samba-smbd starts when braid-online.service starts (i.e. after braid unlock).
• bindsTo – samba-smbd stops if braid-online.service stops or goes inactive (i.e. before braid lock runs umount).
• after – ordering only, ensures samba-smbd is started/stopped on the correct side of braid-online.service.
• ConditionPathIsMountPoint – skips activation when the braid mount point is only an offline directory, so any start the triad did not initiate cannot serve an unmounted pool.

braid lock walks systemctl show -P BoundBy braid-online.service (the reverse of BindsTo=) and stops every consumer this way before unmount, and ConditionPathIsMountPoint keeps them from restarting against an offline pool. This is the same pattern braid’s own scrub timer uses (see modules/braid/storage.nix).

The condition matters even with wantedBy: NixOS also starts Samba at boot through samba.target (which samba-smbd.service is wantedBy), and that boot edge would start smbd before any unlock. ConditionPathIsMountPoint is what stops it from serving the empty, offline mount directory. Only smbd serves files from the pool and can hold it busy during lock, so leave samba.target, nmbd, and winbindd untouched.

NFS

The same approach works for NFS. Export the braid mount point and control access at the network level:

services.nfs.server = {
  enable = true;
  exports = ''
    ${config.braid.mountPoint} 192.168.1.0/24(rw,sync,no_subtree_check,no_root_squash)
  '';
};

Adjust the subnet and options for your network. See exports(5) for the full option reference.

The same wantedBy + bindsTo + after + ConditionPathIsMountPoint pattern on braid-online.service (see “Binding shares to the pool lifecycle” under Samba above) applies to nfs-server.service if you want NFS to stop before braid lock runs umount and start again after braid unlock. As with Samba, the condition gates NixOS’s default nfs-server.service boot-start edge (wantedBy = [ "multi-user.target" ]) against an offline braid mount point.

Auto-suspend integration

If you enable braid.autoSuspend, active SMB and NFS connections automatically block suspend. This is auto-detected from whether services.samba or services.nfs.server is enabled in your NixOS config – no extra configuration needed.

Related

• NixOS configuration – braid.poolAccessGroup option reference
• Getting started – first-time pool setup
• Mounting subvolumes – read-only service access to one subvolume
• Power management – auto-suspend with SMB/NFS awareness

← braid

Mounting subvolumes

Mount a btrfs subvolume at a custom path when a person or service should see one part of the pool as its own filesystem. Common examples are a friendlier path under /home, or a media path like /var/lib/jellyfin/media.

How braid mounts the pool

braid mounts the btrfs top-level subvolume (subvolid=5) at /mnt/storage by default. Treat that as the management mount: it is where you create subvolumes, run btrfs commands, and manage the whole pool. Consumer services do not need access to that mount root.

The subvol= mount idiom

btrfs can mount a subvolume directly with subvol=<path>. The btrfs docs describe the important isolation property this way: “the parent directory is not visible and accessible”, which is “similar to a bind mount”.

For braid, that means a service can see only movies at /var/lib/jellyfin/media without needing permission to traverse /mnt/storage.

Recipe: mount a subvolume at a custom path

Create the subvolume while the pool is unlocked:

sudo btrfs subvolume create /mnt/storage/movies

Find the btrfs filesystem UUID from braid status (look for the FSID: line; the JSON form is braid status --json and the field is fsid):

sudo braid status

Add a native systemd mount unit to your NixOS configuration:

systemd.mounts = [{
  what = "/dev/disk/by-uuid/<btrfs-fs-uuid>";
  where = "/home/dan/my-movies";
  type = "btrfs";
  options = "subvol=movies,ro,noatime";
  wantedBy = [ "braid-online.service" ];
  bindsTo = [ "braid-online.service" ];
  after = [ "braid-online.service" ];
}];

Field notes:

• what points at the btrfs filesystem UUID, not an individual LUKS disk.
• where is the path where the subvolume should appear.
• type = "btrfs" selects the btrfs mount helper.
• options selects the movies subvolume. ro is optional but recommended for read-only consumers.
• wantedBy starts the mount when braid-online.service activates after braid unlock.
• bindsTo is the load-bearing lifecycle edge. It puts the mount unit in BoundBy braid-online.service, which is what braid lock stops before unmounting the pool.
• after orders mount startup after braid-online.service, so the btrfs /dev/disk/by-uuid symlink exists before systemd resolves what.

Rebuild and verify:

sudo nixos-rebuild switch
findmnt /home/dan/my-movies
systemctl show -P BoundBy braid-online.service

The escaped mount unit name, for example home-dan-my\x2dmovies.mount, should appear in BoundBy braid-online.service.

subvol= vs bind mount

Both approaches can expose a subtree at another path. subvol= is the better default for braid because it is conventional btrfs configuration, it mounts the subvolume directly, and it does not require the consumer to traverse /mnt/storage.

Use a bind mount only when the consumer already has permission to traverse the source mount and you need the same mounted data at multiple paths.

Why not fileSystems with x-systemd.requires?

fileSystems is fstab-shaped. systemd’s fstab options can express Requires= and After=, but not an arbitrary BindsTo=braid-online.service edge. Without BindsTo, the mount is not listed in BoundBy braid-online.service, so braid lock will not stop it before unmounting the pool. Use native systemd.mounts for lifecycle-bound subvolume mounts. See ADR 018 for the lifecycle model.

Worked example: read-only access for Jellyfin

Create the media subvolume:

sudo btrfs subvolume create /mnt/storage/movies

Mount it where Jellyfin expects media:

systemd.mounts = [{
  what = "/dev/disk/by-uuid/<btrfs-fs-uuid>";
  where = "/var/lib/jellyfin/media";
  type = "btrfs";
  options = "subvol=movies,ro,noatime";
  wantedBy = [ "braid-online.service" ];
  bindsTo = [ "braid-online.service" ];
  after = [ "braid-online.service" ];
}];

Grant Jellyfin read-only traversal on the subvolume contents:

sudo setfacl -R    -m u:jellyfin:rx /mnt/storage/movies
sudo setfacl -R -d -m u:jellyfin:rx /mnt/storage/movies

Do not add jellyfin to storage. That would grant the daemon read-write access across the whole pool. The ACL above scopes read access to one subvolume, and the subvol= mount means Jellyfin does not need to traverse /mnt/storage itself.

Bind Jellyfin to the mount unit:

services.jellyfin = {
  enable = true;
  openFirewall = true;
};

systemd.services.jellyfin = {
  wantedBy = lib.mkForce [ "var-lib-jellyfin-media.mount" ];
  bindsTo = [ "var-lib-jellyfin-media.mount" ];
  after = [ "var-lib-jellyfin-media.mount" ];
  unitConfig.ConditionPathIsMountPoint = "/var/lib/jellyfin/media";
};

Bind the service to var-lib-jellyfin-media.mount, not directly to braid-online.service. That ensures Jellyfin starts only after its media path is mounted. During braid lock, systemd stops Jellyfin first, then the subvolume mount, then braid unmounts the management mount and closes LUKS.

The full triad pattern is the same lifecycle shape described in Sharing and permissions.

Verify:

sudo -u jellyfin ls /var/lib/jellyfin/media
sudo braid lock
systemctl is-active jellyfin.service
systemctl is-active var-lib-jellyfin-media.mount

Point the Jellyfin web UI at /var/lib/jellyfin/media. After braid lock, both units should be inactive and the LUKS devices should be closed.

Offline mountpoint safety

braid seals the pool mountpoint immutable (chattr +i) while the pool is offline, so a process writing /mnt/storage before the pool mounts fails with EPERM instead of silently landing data on the root filesystem (which the pool would then hide on mount). See ADR 028.

This boot seal covers only the pool mountpoint (/mnt/storage). It has two consequences for subvolume mounts:

• Subvolumes mounted under /mnt/storage are inherently protected by the parent seal – the bare mountpoint is the sealed directory. This is the safe default; prefer it.
• Subvolumes mounted at separate paths (like the /var/lib/jellyfin/media example above) are not auto-sealed. While the pool is offline the systemd.mounts unit is stopped, leaving a bare directory at that path. The unit you wired with bindsTo = braid-online.service does not write while offline, but any other process that writes the path while the pool is offline lands data on root and gets shadowed on the next mount – the same bug the boot seal fixes for /mnt/storage.

To protect a separate-path subvolume mountpoint, seal it manually with the explicit-path form while the pool is offline:

sudo braid seal-mountpoint /var/lib/jellyfin/media

This is the braid-native remedy (the appliance has no chattr on its PATH). It reports a non-zero exit if it could not protect the path, so a failed seal is visible. It is not self-healing – unlike the pool mountpoint, braid does not re-seal these paths on every boot, and braid doctor does not probe them. Re-run it after a reconfiguration that recreates the directory. To clear it later, use braid seal-mountpoint --unseal <path>.

What’s next

• Sharing and permissions
• Day-to-day NAS usage

Related commands

• unlock
• status

← braid

Troubleshooting

Symptom-oriented index for common problems. Find your symptom below and follow the resolution.

Balance fails with “No space left on device”

btrfs balance needs temporary free space to relocate chunks. Braid balances convert both data and metadata profiles, so either side can hit ENOSPC even when there appears to be space available.

Fix: Free up empty data block groups first, then retry the original operation:

sudo btrfs balance start -dusage=0 /mnt/storage

The usage=0 pass relocates only completely empty data block groups, so it does not need temporary work space. Keep recovery balances data-only: metadata block groups are write headroom, and balancing them can hit metadata ENOSPC and force the filesystem read-only.

If the retry still fails, inspect data vs metadata usage:

sudo btrfs filesystem usage /mnt/storage

df’s “Used” and “Available” columns cannot distinguish data, metadata, and snapshot references, while braid status reports the same btrfs-derived capacity. In btrfs filesystem usage, compare the Data and Metadata used/size ratios to see which side is the bottleneck.

If there is enough temporary work space, a non-zero data threshold can reclaim nearly-empty groups, but it moves data:

sudo btrfs balance start -dusage=10 /mnt/storage

Pool won’t mount

Symptom: braid unlock fails because pool.json is missing or corrupted.

Fix: Rebuild UUID-keyed pool.json from disk labels and LUKS UUIDs. How you start depends on the state of pool.json – bare discover previews only when the file is absent; over a corrupt file it refuses and points you to discover --write.

If pool.json is missing – preview, then write:

sudo braid discover
# Shows discovered disks -- verify they look correct
sudo braid discover --write

If pool.json is corrupt or unreadable – skip the preview and rebuild in place (bare discover refuses corrupt state before scanning):

sudo braid discover --write

The corrupt rebuild preserves the original bytes at pool.json.corrupt-<RFC3339-UTC> before overwriting; do not remove it first.

Then unlock normally:

sudo braid unlock

discover scans /dev/disk/by-id/ for LUKS devices with braid-* labels and reconstructs the membership file. See Recovery scenarios for details.

If pool.json is healthy and UUID-keyed, discover --write refuses on purpose. Use braid add / braid remove / braid replace for normal membership changes. If you have deliberately decided to re-discover instead, move the file aside before running discover --write:

sudo mv /var/lib/braid/pool.json /var/lib/braid/pool.json.manual-backup
sudo braid discover --write

Interrupted operation (pending-op.json exists)

Symptom: braid commands fail with an error about a pending operation. This happens when a previous add, remove, remove-missing, or replace was interrupted (power loss, crash, killed process).

Fix: Use braid recover:

sudo braid recover

Recover reads the pending-operation journal, opens LUKS devices and mounts the pool if needed, probes the live btrfs topology, and rebuilds pool.json from actual state. It clears the journal only after the idle/no-paused recovery path succeeds.

Important

If recover refuses owed RAID1 replay because btrfs balance state is paused, running, or unknown, it left pending-op.json in place. Inspect btrfs manually before clearing recovery state.

If devices are missing (drive failure during the interrupted operation):

sudo braid recover --allow-degraded

For scripted/unattended recovery:

echo "my-passphrase" | sudo braid recover --passphrase-stdin

See Recovery scenarios for detailed walkthroughs.

Missing device after drive failure

Symptom: braid status shows a missing device. The pool may be mounted degraded or may fail to mount.

You have two options:

Option A: Replace the disk (rebuilds data onto a new disk)

# Find the old disk name from braid status
sudo braid replace --old toshiba2 \
  --new toshiba4=/dev/disk/by-id/ata-NEW_DRIVE_SERIAL

Replace copies data from surviving redundant copies onto the new disk. This restores full RAID1 redundancy. It takes hours for large disks.

Option B: Forget the missing device (no data rebuild)

# Find the missing device's btrfs devid from braid status
sudo braid remove-missing --missing-id 3

This removes the dead device entry from the btrfs filesystem. No data is rebuilt – you lose the redundant copy that was on the dead drive. The pool continues as a smaller array. Use this when you do not have a replacement disk available.

Auto-unlock fails

Symptom: Pool is not unlocked after reboot despite auto-unlock being configured.

Check the service logs:

journalctl -u braid-auto-unlock.service

Common causes:

• USB device not found: The USB drive was not plugged in or the keyDevice path is wrong. Verify with ls /dev/disk/by-id/ | grep usb.
• Keyfile not found: The USB filesystem does not contain braid.key at the root. The file must be named exactly braid.key.
• Keyfile resolves outside mount: A symlink on the USB points outside /run/braid-key/. The service refuses this for security.
• Timeout too short: The USB device takes longer to enumerate than timeoutSec. Increase it in your NixOS config.
• Missing devices: If a pool disk is dead and allowDegraded = false (the default), auto-unlock exits with code 2. Set braid.autoUnlock.allowDegraded = true to allow degraded mount.

See Auto-unlock for the setup guide.

Beeper won’t stop

Symptom: The PC speaker is beeping (initially every few seconds, then less often) due to a disk health alert.

Fix: Acknowledge the alert:

sudo braid ack

This stops the beep loop and clears the alert state. Then investigate the underlying problem:

sudo braid status
sudo braid doctor

braid commands blocked by “another operation in progress”

Symptom: braid unlock, braid add, or braid recover fails with a message about another braid operation holding the pool lock.

The pool-mutating commands acquire an exclusive lock on /run/braid-pool.lock. If a previous command is still running (or crashed without releasing the lock), new commands fail fast.

Fix: Wait for the running command to finish. If the previous command crashed, the lock file is released automatically (it is a flock on a /run/ file, which is tmpfs and cleared on reboot). If you need to proceed before a reboot:

# Check if any braid process is still running
ps aux | grep braid
# If nothing is running, the lock was released — retry your command

Scrub won’t start

Symptom: systemctl status braid-scrub.timer shows the timer is inactive.

The scrub timer is lifecycle-bound to braid-online.service. It only runs while the pool is unlocked and mounted. If a scrub was cancelled by lock or shutdown, braid resumes the partial scrub the next time the pool comes online.

# Check pool state
sudo braid status
# If pool is offline, unlock it
sudo braid unlock
# Timer should now be active
systemctl status braid-scrub.timer

Scrub reported errors

Symptom: braid status shows Last scrub: <ts> (N errors) or braid monitor raised a btrfs error alert after a scrub.

The scrub error count braid reports is authoritative – braid parses it from btrfs scrub status. Journal lines are diagnostic clues, not a complete per-error ledger: the kernel emits scrub messages through rate-limited helpers, so a busy or bursty scrub can produce fewer journal lines than the count. A non-zero count with sparse or missing journal lines is not a braid bug – it usually means the kernel dropped log entries to stay under its rate limit.

Use the command printed under the scrub status, or run journalctl directly:

sudo journalctl -k --since '<scrub-start-time>' --grep 'BTRFS.*(at logical.*on (dev|mirror)|super block at physical)'

Output comes in two distinct grammars depending on whether the error is in a data/metadata extent or in a superblock copy.

Extent errors (data and metadata). Each affected sector may log a repair-summary line:

• Corrected via RAID1 mirror: fixed up error at logical N on dev /dev/mapper/braid-X physical N (or ... on mirror N when the source mirror has no device). btrfs RAID1 read the healthy mirror and wrote it back over the bad copy. No file path – corrected lines give block coordinates only. A count consisting mostly of fixed up error lines means data integrity was preserved; investigate the disk that produced the bad reads.
• Uncorrectable: unable to fixup (regular) error at logical N on dev X physical N (or ... on mirror N). RAID1 could not recover – the mirror was also bad or no mirror exists. The block is permanently damaged.

An uncorrectable extent error may also log an additional detail line that identifies what was lost. The detail emission is gated by a second rate-limit check, so it is not guaranteed to appear for every uncorrectable error. When present, the shapes are:

• Data extent, path resolved. ... at logical N on dev X, physical N, root N, inode N, offset N, length N, links N (path: subdir/victim.bin). (path: ...) is relative to the affected btrfs subvolume root, not absolute. The kernel builds it from paths_from_inode() (reference/linux/fs/btrfs/scrub.c:457, reference/linux/fs/btrfs/backref.c:2125) and does not know what mount point exposes that subvolume. Prepend the mount point of the affected subvolume (default subvolume at /mnt/storage; named subvolumes wherever you configured them).
• Data extent, path resolution failed. Same shape but ends ... path resolving failed with ret=N instead of (path: ...). Usually means the extent has no remaining inode references (file already deleted) or the inode lives in a snapshot rooted under a different subvolume than the search root.
• Metadata. ... at logical N on dev X, physical N: metadata leaf|node (level N) in tree N. Tree-block corruption – no file path because the bad block lives in a btrfs tree, not in user data. Persistent metadata errors indicate disk failure.

Superblock errors. Logged as standalone messages from scrub_supers, not as repair-summary + detail pairs. The grammar is independent of the extent path:

• super block at physical N devid N has bad csum
• super block at physical N devid N has bad generation N expect N

Damage to one of the device’s superblock copies. Investigate the device (identified by devid), not a file.

For the path-resolution-failed case, you can try inode-resolve as a best-effort:

sudo btrfs inspect-internal inode-resolve <inode> /mnt/storage

This succeeds only if the inode still exists in the subvolume rooted at the supplied path. Deleted files, extents with no remaining references, or files that live in a different subvolume will still produce no result – the kernel logged “path resolving failed” for the same reason.

A non-zero error count after a scrub means at least one block failed its checksum or I/O. With btrfs RAID1, blocks with a healthy mirror are repaired automatically (counted as Corrected – the fixed up lines above); Uncorrectable means both copies were bad and the file (for data) or tree block (for metadata) is now damaged. The journal output is your best diagnostic surface, but treat it as evidence rather than a complete ledger: rely on the scrub count for “how many,” and on the journal for “what kind, and where the kernel could log it.” Restore affected files from backup and run braid ack once you have investigated.

SMB/NFS service inactive after braid lock

Symptom: systemctl status samba-smbd.service (or nfs-server.service) shows inactive (dead) immediately after you ran braid lock.

This is intentional. On NixOS module installs, braid lock stops every service bound to braid-online.service via BindsTo=braid-online.service before it unmounts the pool. The cascade prevents busy-mount unmount failures.

Fix: Run braid unlock. It reactivates braid-online.service after mount, and systemd restarts every consumer that is also WantedBy=braid-online.service.

If the service does not restart on braid unlock, it is wired for the stop side (BindsTo) but not the start side (WantedBy). The recommended setup wires the share into the full pool lifecycle – see Binding shares to the pool lifecycle.

Related

• Recovery scenarios – detailed recovery walkthroughs
• NixOS configuration – module option reference
• Monitoring and alerts – alert system details; see “Scrub reported errors” above for the post-alert investigation steps.

← braid

Recovery scenarios

Detailed walkthroughs for recovering from failures. Read this when braid status or another command tells you something is wrong, or when you are planning for failure ahead of time.

Overview: discover vs recover

braid has two recovery commands that solve different problems:

discover solves metadata loss – the CLI’s record of which disks belong to the pool is gone, but the disks themselves are fine. It reads LUKS labels (braid-<name>) and LUKS UUIDs from /dev/disk/by-id/ devices to reconstruct UUID-keyed membership.

recover solves interrupted operations – an add, remove, remove-missing, or replace was killed mid-flight (power loss, crash, OOM). The pending-operation journal (/var/lib/braid/pending-op.json) records what was in progress. Recover opens the pool, inspects what actually happened on disk, and rebuilds pool.json to match reality.

Lost pool.json

Symptom: braid unlock fails because /var/lib/braid/pool.json does not exist.

Cause: Accidental deletion, filesystem corruption, or migrating to a new NixOS install.

Steps

1. Verify no pending operation exists:

ls /var/lib/braid/pending-op.json
# If this file exists, use `braid recover` instead (see below)

2. Scan for braid disks:

sudo braid discover

Output looks like:

  toshiba1 = /dev/disk/by-id/ata-TOSHIBA_MN08ACA16T_XXXX
  toshiba2 = /dev/disk/by-id/ata-TOSHIBA_MN08ACA16T_YYYY
  toshiba3 = /dev/disk/by-id/ata-TOSHIBA_MN08ACA16T_ZZZZ

3. Verify the output matches your expected pool members. Then write:

sudo braid discover --write

This creates /var/lib/braid/pool.json.

If you can name the expected member count ahead of time, record it from your own records or prior braid status output and pass it as a fail-closed guard:

EXPECTED=3
sudo braid discover --write --expect-count="$EXPECTED"

4. Unlock normally:

sudo braid unlock

Notes

• For a healthy UUID-keyed pool.json, discover --write refuses – use braid add / braid remove / braid replace to mutate membership instead.
• For a corrupt or off-schema existing pool.json, discover --write rebuilds in place; no manual remove step is needed. The original bytes are preserved at pool.json.corrupt-<RFC3339-UTC> adjacent to the new file in case manual forensic recovery is needed (e.g. extracting a devid for a null_underlying member). The snapshot is a hard precondition: if it cannot be written (full disk, read-only state directory), discover --write refuses rather than destroy the corrupt original; free disk space or fix permissions and retry.
• discover --write refuses to run if pending-op.json exists. Use braid recover instead. (Bare discover is read-only and runs regardless.)
• discover only finds LUKS2 devices. LUKS1 devices with braid labels are skipped with a warning.
• The rebuilt pool.json is keyed by LUKS UUID. Disk names are stored in each member value for command input and display.
• When multiple /dev/disk/by-id/ symlinks point to the same device, discover picks the most stable one (wwn > nvme > scsi > ata > usb).

Interrupted add/remove/replace

Symptom: braid commands fail with a message about a pending operation. ls /var/lib/braid/pending-op.json confirms the journal file exists.

Cause: A pool mutation (add, remove, remove-missing, replace) was interrupted before it could complete. The journal records the operation type, the pre-operation membership, and the target membership. Existing-pool add journals also record a phase: PoolMutation for unfinished disk preparation or btrfs membership, and PostAddBalanceRaid1 after membership is committed but balance work remains.

Steps

1. Preview what recover will do:

sudo braid recover --dry-run

This shows the recovery plan without making changes: which LUKS devices will be opened, whether the pool needs mounting, and the final pool.json state.

2. Run recovery:

sudo braid recover

Recover will:

• Open the LUKS devices needed for the journal phase
• Mount the btrfs pool
• Probe the live btrfs topology to determine what actually happened
• For existing-pool add PoolMutation, first open and scan any already-committed journaled add targets that can be reconciled without wiping or adding
• For add PoolMutation, finish only the journaled add targets that are not already live
• For add PostAddBalanceRaid1, skip all disk preparation and btrfs add steps, then run the owed RAID1 balance only when btrfs balance state is idle; preserve pending-op.json when a paused, running, or unknown balance state requires manual inspection
• Rebuild or repair pool.json only when live membership is complete
• Clear pending-op.json only after required membership and balance work is complete

3. Verify:

sudo braid status

Interrupted between returned-disk wipe and add

If an existing braid-labeled disk was being returned to the pool and the add was interrupted after wipefs --types btrfs but before btrfs device add, run:

sudo braid recover

Recover replays the add from the journaled returned-disk target. Do not wipe the disk and retry it as a fresh add; the journal still records the checked LUKS identity and expected pool FSID.

Interrupted fresh-disk add

For an interrupted fresh-disk add, recover replays the format, optional keyfile enrollment, LUKS header backup, mapper open, and btrfs device add from the journaled options when the disk is present.

If the disk is absent or has a different LUKS label than the journal records, recover fails and leaves pending-op.json in place. Reconnect the original disk or replace the target, then rerun sudo braid recover.

Pending-op file corruption

Symptom: braid reports that /var/lib/braid/pending-op.json could not be parsed.

The remediation phrase is:

Remove /var/lib/braid/pending-op.json after manual reconciliation (see docs/internals/luks-unlock.md) and re-run.

It is safe to remove pending-op.json only when one of these is true:

When it is not safe, keep the journal in place and investigate the interrupted operation before editing state.

Out-of-band reformat during recovery

Recover refuses if a target disk’s live LUKS UUID no longer matches the journal. This catches a disk that was reformatted, swapped, or cloned after the original operation started.

Messages to search for:

• add recovery aborted: target ... LUKS UUID mismatch
• recover replace target '...' LUKS UUID mismatch: expected ..., found ...

Do not force the journal forward. Investigate the foreign reformat or swapped disk, restore the intended disk if possible, and rerun recovery.

See also Unlock refused by a foreign or mismatched disk for the same identity check on the braid unlock path.

Never-enriched member with null-underlying mapper

A member can be known to btrfs by devid while its LUKS backing device is gone (cryptsetup status reports device: (null)). If the member was never enriched with a persisted devid, recovery cannot bind that null-underlying mapper back to a UUID-keyed membership entry.

Let braid recover complete when it can preserve the member. The next read-side command observes the live devid and braid remove-missing becomes available again if the device is truly gone.

Duplicate or missing devid in journal snapshot

Recovery may refuse with internal errors equivalent to duplicate journaled devids or no member for a journaled devid. This means the journal snapshot cannot safely resolve a btrfs devid to a UUID-keyed member.

Do not edit pool.json; that resolution did not consult it. Re-run recovery only after manual reconciliation of pending-op.json.

Committed-but-closed add target

If the journaled add target is already a live pool member but its mapper is closed when recover starts, recover opens and scans it during the reconciliation pass. After the live-pool re-probe, the target is included in pool.json and is not re-added.

This can still prompt for the pool passphrase even when the pool is already mounted, because the target mapper may need to be opened before recover can discover that it already committed.

With missing devices

If a drive failed during the interrupted operation:

sudo braid recover --allow-degraded

Without --allow-degraded, recover exits with code 2 when devices are missing. The degraded flag allows mounting with missing devices so recovery can complete. Redundancy is reduced until the missing device is replaced.

Scripted recovery

For unattended recovery (e.g. from a remote script):

echo "my-passphrase" | sudo braid recover --passphrase-stdin

Or with a passphrase file:

sudo braid recover --passphrase-file /path/to/passphrase

Recover for a replace journal when the pool is already mounted

Symptom: sudo braid recover exits with recover refuses to probe an already-mounted pool when the journal records a replace ... and instructs you to run braid lock first.

Cause: The pool was mounted by something other than braid recover itself (typically a manual cryptsetup open + mount after a crash, since braid unlock and braid-auto-unlock.service both refuse to mount when a pending-op journal exists). For a replace journal, the kernel may have resumed an interrupted dev_replace on that mount session, leaving stale in-memory device state that recover cannot distinguish from real topology. The cycle that scrubs this state needs to unmount and remount, which is unsafe on a mount recover does not own.

Steps

sudo braid lock      # works with a journal present -- no pending-op preflight
sudo braid recover   # opens its own mount and runs the relock cycle

braid lock unmounts the pool and closes the LUKS mappers. braid recover then opens a fresh mount session, finishes any in-progress kernel dev_replace, and runs the umount-and-remount cycle that clears stale btrfs_fs_devices – the standard happy path for replace recovery.

Unlock refused by a foreign or mismatched disk

Symptom: braid unlock exits with LUKS UUID mismatch. A disk at a recorded by-id slot reports a LUKS UUID that differs from the one in pool.json; the error names the disk, its by-id path, and the expected vs found UUID.

Cause: The disk was swapped, cloned, or reformatted out of band, so its LUKS identity no longer matches the recorded member. This is a hard refusal during probing, before any mapper opens. --allow-degraded does not bypass it – that flag only covers missing disks, and this disk is present.

If the swap was unintended

Detach the foreign disk and reattach the original. braid unlock then succeeds.

If the swap was intentional

braid replace requires the pool mounted, but the present mismatched disk blocks the mount. Make the slot read as missing first, then replace:

1. Detach the foreign disk so the member reads as absent.
2. Mount the pool degraded:

   sudo braid unlock --allow-degraded
   

3. Replace the now-missing member following Missing disk -> Option A: Replace the disk. braid replace prepares its own --new disk; see braid replace for how it handles a disk that already carries a LUKS header.

See also Out-of-band reformat during recovery for the same identity check on the braid recover path (a different trigger).

Missing disk (drive failure)

Symptom: braid status shows a device as missing. The pool may be mounted degraded or may refuse to mount.

Unlock with a missing disk

If the pool is not mounted:

sudo braid unlock --allow-degraded

This mounts the pool in degraded mode. All data is still accessible (btrfs RAID1 keeps a copy on the surviving disk(s)), but the pool is running with reduced redundancy until you replace the dead drive.

Hot-unplug while pool is mounted

If a drive is physically disconnected while the pool is mounted, its LUKS mapper can remain open with cryptsetup status reporting device: (null). btrfs continues to list the devid but has not yet promoted it to MISSING. braid status reports the devid – it contributes to missing_count and appears in missing_devids – but braid remove-missing --missing-id N and braid replace (with or without --missing-id) refuse the devid because they only act on btrfs-authoritative MISSING entries.

To make progress:

1. Confirm the disk is truly gone (not just a loose cable).
2. Relock and re-unlock the pool degraded so btrfs re-evaluates membership and promotes the devid:

   sudo braid lock
   sudo braid unlock --allow-degraded
   

3. Re-run braid status – the devid should now appear as authoritatively MISSING – then retry braid remove-missing or braid replace.

Option A: Replace the disk

Replaces the dead disk with a new one, rebuilding data from surviving copies:

sudo braid replace --old toshiba2 \
  --new toshiba4=/dev/disk/by-id/ata-NEW_DRIVE_SERIAL

--old identifies the missing member. If you want to cross-check the btrfs devid from braid status, add --missing-id after the required args:

sudo braid replace --old toshiba2 \
  --new toshiba4=/dev/disk/by-id/ata-NEW_DRIVE_SERIAL \
  --missing-id 3

Replace runs btrfs replace start -B under the hood. braid replace is a long-running online operation: the command waits in the foreground and shows progress while the pool remains usable. It can take hours for large drives, so run it from a shell you can leave open (or a tmux/screen session). From another shell, braid status and braid tui can show progress independently.

Option B: Remove the missing device

Forgets the dead device without rebuilding data:

# Find the missing device's btrfs devid from braid status
sudo braid remove-missing --missing-id 3

Use this when you do not have a replacement disk. The pool continues with fewer disks and reduced capacity. Data that was only on the dead drive is lost (but in RAID1, all data has a second copy on another drive).

When this clears the last missing device and 2+ disks remain, remove-missing blocks on a follow-up soft RAID1 balance to restore redundancy on chunks written as single during degraded operation. You will see [wait] pool: restoring RAID1 redundancy... then [ok] pool: RAID1 redundancy restored before the command returns. The wait scales with how much data was written while degraded: an idle pool finishes in seconds, while a pool written to heavily during degraded mode can take longer. A sleep inhibitor is held for the entire operation. See braid remove-missing for the full sequence.

Verify:

sudo braid status

A successful result shows no missing devices and no single profile rows for data or metadata.

Choosing between replace and remove-missing

Degraded mount

A degraded mount means at least one pool disk is missing. The pool is usable but the pool is running with reduced redundancy on the missing device’s share of data.

When degraded mounts happen

• braid unlock --allow-degraded – explicit request
• braid recover --allow-degraded – recovery with missing devices
• braid.autoUnlock.allowDegraded = true – auto-unlock config

Risks

• Reduced redundancy – the pool is short the missing device’s mirror copy of existing data, and on 2-disk pools new writes are allocated as single-profile chunks. A further drive failure could lose data.
• No self-healing – btrfs cannot repair corrupted blocks from a redundant copy if the copy was on the missing device.

Resolution

Replace the missing disk as soon as possible:

sudo braid replace --old <missing-name> \
  --new <new-name>=/dev/disk/by-id/<new-drive>

After replace completes, the pool is fully redundant again.

Recovery decision tree

braid command fails
├── "pending operation" error
│   └── braid recover [--allow-degraded]
├── pool.json missing
│   └── braid discover --write → braid unlock
├── "LUKS UUID mismatch" error
│   └── see "Unlock refused by a foreign or mismatched disk"
├── missing device / won't mount
│   ├── braid unlock --allow-degraded
│   └── then: braid replace or braid remove-missing
└── something else
    └── braid doctor → check troubleshooting guide

State files reference

All state lives under /var/lib/braid/:

Related

• Troubleshooting – symptom-oriented quick fixes
• NixOS configuration – autoUnlock.allowDegraded and other options

← braid

braid add

Add one or more disks to the braid pool. Creates a new pool if none exists, or expands an existing one.

When to use it

• Setting up a new NAS (bootstrap with one or more disks)
• Expanding storage by adding a new drive to an existing pool

Basic example

sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234

Common variations

Bootstrap a new pool with two disks (creates RAID1 immediately):

sudo braid add \
  toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 \
  toshiba2=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_5678

Add a disk to an existing pool:

sudo braid add toshiba3=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_9012

Preview what would happen without making changes:

sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 --dry-run

Skip the confirmation prompt (for scripting):

sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 --yes

Pass passphrase non-interactively:

echo -n 'hunter2' | sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 --passphrase-stdin
sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 --passphrase-file /tmp/pass.txt

Enroll a keyfile for auto-unlock from a mounted USB drive at the same time:

sudo braid add toshiba1=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234 --enroll /mnt/usb

Mount the USB first so the --enroll directory refers to removable media, not persistent host storage.

Important flags

Disk spec format

Each disk is specified as NAME=PATH, where:

• NAME is a short label you choose (e.g. toshiba1)
• PATH is the /dev/disk/by-id/ stable device path

The name is stored in pool.json and used in LUKS mapper names (braid-toshiba1), LUKS labels, and all future commands. The persistent member identity is the LUKS UUID, not the name.

What happens under the hood

1. Probes each disk to determine its state (fresh, braid-labeled, or foreign)

2. Shows a confirmation prompt with the disk’s name and by-id path, plus its model/size/serial (best-effort from the live device via lsblk – omitted if unavailable)

3. For fresh disks: pre-generates a LUKS UUID, LUKS-formats the disk with the pool passphrase and braid-<name> label, enrolls the --enroll keyfile into slot 1 if provided, creates a LUKS header backup, and opens the LUKS mapper

   See Pending LUKS header backups – copy each .luksheader off-system and delete the local copy.

4. If no pool exists: creates a btrfs filesystem (RAID1 if 2+ disks, single if 1 disk; braid explicitly pins the block-group-tree feature bit so that bit is visible and stable across toolchain versions – see ADR-027)

5. If a pool exists: writes a phased UUID-keyed journal, adds the device to the existing btrfs filesystem, records the new membership in pool.json, then advances the journal to the balance phase

6. If the pool now has 2+ disks: balances data to RAID1, then clears the journal – unless the pool has a missing device, in which case the balance is skipped (a [skip] note explains why). Redundancy is restored later by remove-missing or replace, not by the degraded add.

Keyfile enrollment (--enroll DIR): braid enrolls braid.key into LUKS slot 1 on every adopted disk – fresh or returning. On a fresh disk slot 1 is always empty, so the keyfile is always added. On a returning braid disk braid first probes the keyfile: if it already authenticates slot 1 the enrollment is an idempotent skip with no slot change and no new header backup; if slot 1 is empty the keyfile is added. (If slot 1 holds a different, unknown key braid refuses – see Safety checks.) The keyfile is added before the header backup so the backup captures slot 1.

A sleep inhibitor is held during all irreversible operations to prevent the system from suspending mid-operation.

If a btrfs exclusive operation (a running balance, device add/remove/replace, resize, or swap activate) is already in flight on the pool, braid does not fail – its btrfs commands queue behind the in-flight operation (via --enqueue) and the kernel runs them when the pool is free. A paused balance is the exception and is refused (see Safety checks below).

Disk acceptance rules

braid classifies each disk before acting:

• Fresh disk (no LUKS): accepted. LUKS-formatted with the pool passphrase.
• Returning braid disk (braid-labeled LUKS, btrfs FSID matches the pool): accepted as a recovery add. The disk is re-joined to the pool without reformatting. If the old btrfs signature would make btrfs device add refuse the disk, braid first runs the narrow wipe wipefs --all --types btrfs on the verified mapper, then uses btrfs device add -f.
• Non-braid LUKS: refused. braid will not adopt a LUKS device it did not create.
• Braid-labeled, wrong pool: refused. The disk belongs to a different btrfs filesystem.
• Braid-labeled, no btrfs superblock: refused. The disk’s identity is ambiguous (could be partial init, clean eviction, or manual wipe). Wipe the disk and add as fresh.
• Braid-labeled, pool not mounted: refused during bootstrap. Identity cannot be verified without a mounted pool.

Safety checks / refusal cases

• Rejects duplicate disk names in the same command
• Rejects disks that conflict with existing pool membership (same LUKS UUID, same name, or same by-id path)
• Rejects absent disks (not plugged in)
• Verifies the passphrase against an existing pool member before formatting new disks
• Warns if the pool has missing devices but does not refuse: braid add still adds the new disk, but skips the RAID1 convert balance (it surfaces a [skip] note), so the pool stays degraded and redundancy is not restored at add time. To repair, either run braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...> to swap in a new disk for the missing member, or – on a 2-disk degraded pool where remove-missing alone would refuse (it cannot drop RAID1 below two devices) – run braid add then braid remove-missing to drop the dead member and rebalance onto the new disk.
• Warns if existing pool drives have a keyfile but --enroll was not passed
• With --enroll, refuses if an adopted disk’s LUKS slot 1 is occupied by an unknown key the keyfile does not authenticate – remove it first with cryptsetup luksKillSlot, then retry.
• 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 if a btrfs balance is paused on the pool – resume or cancel it first. A paused balance holds the exclusive-operation lock indefinitely, so braid cannot wait it out.
• Refuses when UPS support is enabled and braid ups status cannot verify a trusted OL (utility-power) state.

Interrupted adds

Existing-pool adds recover in two phases:

• PoolMutation: disk preparation and btrfs membership are not fully committed yet. braid recover may finish formatting a fresh target, re-open a verified returned target, run the narrow btrfs-signature wipe for that returned target, and run btrfs device add.
• PostAddBalanceRaid1: membership and pool.json are committed. braid recover will not format, wipe, or add disks in this phase; it only mounts/probes the committed pool, repairs pool.json from the committed live topology if needed, runs the owed RAID1 balance when btrfs balance state is idle, and clears pending-op.json after that succeeds. A paused, running, or unknown balance state fails closed with the journal preserved.

Related commands

• braid status – check pool health and disk info
• braid remove – remove a live disk from the pool
• braid replace – replace a dead or live disk
• braid unlock – open LUKS devices and mount the pool

Related guides

• Getting started – initial setup walkthrough

← braid

braid remove

Remove a live disk from the pool. Data migrates off the disk before it is detached.

When to use it

• Shrinking the pool (retiring a drive you no longer need)
• Removing a drive that is still online and healthy

If the disk is already dead or missing, use braid replace to rebuild data onto a new disk, or braid remove-missing to forget the entry without rebuilding.

Basic example

sudo braid remove toshiba3

Common variations

Preview what would happen:

sudo braid remove toshiba3 --dry-run

Skip the confirmation prompt:

sudo braid remove toshiba3 --yes

Important flags

What happens under the hood

1. Probes the pool to verify the disk is a live member
2. Checks that remaining disks have enough free space to absorb the data being migrated
3. Shows a confirmation prompt with the disk’s name and devid, its model/size/serial (best-effort from the live backing device via lsblk – omitted if unavailable), and the resulting disk count (e.g. Pool: 3 disks -> 2 disks)
4. If removing the second-to-last disk (going from 2 to 1): first balances the pool from RAID1 to single profile, then removes the device
5. Runs btrfs device remove to migrate all data off the disk (this is the long-running step)
6. Closes the LUKS mapper on the removed disk
7. Updates pool.json to remove the member’s UUID entry

A sleep inhibitor is held during data migration and cleanup.

If a btrfs exclusive operation (a running balance, device add/remove/replace, resize, or swap activate) is already in flight on the pool, braid does not fail – its btrfs commands queue behind the in-flight operation (via --enqueue) and the kernel runs them when the pool is free. A paused balance is the exception and is refused (see Safety checks below).

Safety checks / refusal cases

• Refuses if the pool is not mounted
• Refuses if the named disk is not a live member of the pool (suggests braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...> or braid remove-missing if missing devices are detected)
• Refuses to remove the last disk from the pool
• Refuses if there are missing devices in the pool (resolve those first)
• Refuses if remaining disks lack space to absorb the removed disk’s data (ENOSPC pre-flight)
• Warns when removal leaves a single disk (no RAID1 redundancy)
• 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 if a btrfs balance is paused on the pool – resume or cancel it first. A paused balance holds the exclusive-operation lock indefinitely, so braid cannot wait it out.
• Refuses when UPS support is enabled and braid ups status cannot verify a trusted OL (utility-power) state.

Related commands

• braid status – see which disks are in the pool and their devids
• braid remove-missing – forget a dead/missing device entry
• braid replace – replace a disk (live or dead) with a new one
• braid add – add a disk to the pool

← braid

braid remove-missing

Forget a stale missing-device entry from the pool. This does NOT rebuild data – use braid replace for that.

When to use it

• A disk has permanently failed and you want to clean up the pool metadata without replacing it
• You have already recovered your data and just need btrfs to stop reporting the missing device

This is a destructive choice: any data that only existed on the missing disk is lost. If you want to rebuild data onto a new disk, use braid replace instead.

Basic example

Note: braid remove-missing operates only on btrfs-authoritative MISSING devids. A drive that is hot-unplugged while the pool is mounted contributes to missing_count and appears in missing_devids in braid status before btrfs promotes its devid to MISSING; remove-missing refuses the devid with a specific hot-unplug diagnostic until that promotion happens. See Hot-unplug while pool is mounted.

First, find the missing device’s ID:

sudo braid status

Then remove it:

sudo braid remove-missing --missing-id 3

Common variations

Preview what would happen:

sudo braid remove-missing --missing-id 3 --dry-run

Skip the confirmation prompt:

sudo braid remove-missing --missing-id 3 --yes

Important flags

What happens under the hood

1. Probes the pool to verify missing devices exist
2. Validates that the specified devid is actually a missing device (not a live one)
3. Resolves the btrfs devid to the UUID-keyed pool member whose persisted prior devid matches
4. Shows a confirmation prompt with the disk name, devid, and the resulting disk counts (e.g. Pool: 2 present + 1 missing -> 2 disks)
5. Writes a PoolMutation journal and runs btrfs device remove <devid> to clear the missing device entry
6. Updates pool.json to remove the member’s UUID entry, then advances the journal to post-remove-missing maintenance
7. If this was the last missing device and 2+ disks remain: runs a soft RAID1 balance (-dconvert=raid1,soft -mconvert=raid1,soft) to restore redundancy on any single-profile chunks created during degraded operation
8. Clears the journal

A sleep inhibitor is held during the removal and the subsequent soft balance (if triggered).

If a btrfs exclusive operation (a running balance, device add/remove/replace, resize, or swap activate) is already in flight on the pool, braid does not fail – its btrfs commands queue behind the in-flight operation (via --enqueue) and the kernel runs them when the pool is free. A paused balance is the exception and is refused (see Safety checks below).

Safety checks / refusal cases

• Refuses if the pool is not mounted
• Refuses if no missing devices are detected
• Refuses if the specified devid belongs to a live device (use braid remove for that)
• Refuses if the specified devid is not a device in this pool
• Refuses if surviving disks lack space to absorb the missing device’s allocations (ENOSPC pre-flight), or if that pre-flight cannot run (the btrfs device usage probe failed to spawn, returned a nonzero exit, produced unparseable output, did not list the targeted missing devid, or reported an untrusted missing-device allocation shape: the targeted devid is listed more than once, carries an allocation profile braid does not model, or reports no positive Data/Metadata/System RAID1 row), when more than 1 surviving device exists
• Refuses on a 2-disk RAID1 pool with one disk missing – the kernel refuses to drop a RAID1 pool below two devices. Use braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...> to repair the dead disk, or braid add first and then re-run.
• 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 if a btrfs balance is paused on the pool – resume or cancel it first. A paused balance holds the exclusive-operation lock indefinitely, so braid cannot wait it out.
• Refuses when UPS support is enabled and braid ups status cannot verify a trusted OL (utility-power) state.

Related commands

• braid status – find missing device IDs
• braid replace – replace a missing disk with a new one (rebuilds data)
• braid remove – remove a live disk

← braid

braid replace

Replace a disk with a new one using btrfs replace. Works for both live (still-online) and dead/missing disks.

When to use it

• A disk has failed and you need to rebuild data onto a replacement
• Proactively swapping a healthy disk for a larger or newer one

Basic example

The same invocation replaces a disk whether it is still live or already dead/missing. braid resolves --old against pool.json to find the member and detects its state automatically, so there is no mode to choose and --missing-id is never required:

sudo braid replace --old toshiba1 --new toshiba4=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_NEW1

Common variations

Note: braid replace operates only on btrfs-authoritative MISSING devids. A drive that is hot-unplugged while the pool is mounted contributes to missing_count and appears in missing_devids in braid status before btrfs promotes its devid to MISSING; both an explicit --missing-id cross-check and the no-flag auto-resolve path refuse the devid with a specific hot-unplug diagnostic until that promotion happens. See Hot-unplug while pool is mounted.

Optionally assert which missing devid you expect (braid refuses if it disagrees with pool.json):

sudo braid replace \
  --old toshiba1 \
  --new toshiba4=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_NEW1 \
  --missing-id 3

Preview what would happen:

sudo braid replace --old toshiba1 --new toshiba4=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_NEW1 --dry-run

Enroll a keyfile from a mounted USB drive on the new disk:

sudo braid replace \
  --old toshiba1 \
  --new toshiba4=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_NEW1 \
  --enroll /mnt/usb

Mount the USB first so the --enroll directory refers to removable media, not persistent host storage.

Pass passphrase non-interactively:

sudo braid replace --old toshiba1 --new toshiba4=/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_NEW1 --passphrase-file /tmp/pass.txt

Important flags

What happens under the hood

For a fresh replacement disk (no LUKS):

1. Pre-generates the replacement member’s LUKS UUID and LUKS-formats the new disk with the pool passphrase and a braid-<name> label
2. Optionally enrolls a keyfile in slot 1
3. Creates a LUKS header backup
4. Opens the LUKS mapper

Then, for all replacements:

5. Runs btrfs replace start to copy data from the old device (or its mirrors) to the new device
6. Writes committed UUID-keyed membership to pool.json and advances the journal to post-replace maintenance
7. For live replacements: closes the old disk’s LUKS mapper
8. Resizes the new device to use its full capacity (important when the new disk is larger)
9. For missing-disk replacements that clear the last missing device: runs a soft RAID1 balance to restore redundancy on any single-profile chunks
10. Clears the journal

The fresh-disk path always produces a local LUKS header backup in step 3; the existing-LUKS path produces one only when --enroll actually adds slot 1, so an already-enrolled disk is a no-op with no new backup. See Pending LUKS header backups – copy each .luksheader off-system and delete the local copy.

A sleep inhibitor is held throughout the replace to prevent the system from suspending. Suspending mid-replace can corrupt the btrfs topology.

If a btrfs exclusive operation (a running balance, device add/remove/replace, resize, or swap activate) is already in flight on the pool, braid does not fail – its btrfs commands queue behind the in-flight operation (via --enqueue) and the kernel runs them when the pool is free. A paused balance is the exception and is refused (see Safety checks below).

Safety checks / refusal cases

• Refuses if the pool is not mounted
• Refuses if --old and --new are the same disk
• Refuses if the new disk’s LUKS UUID is already in use by the pool (registered membership or live btrfs devices) – detach the conflicting disk before retrying
• Refuses if the new disk is absent (not plugged in)
• Refuses if the new disk’s mapper capacity is smaller than the source disk’s btrfs total_bytes (read via BTRFS_IOC_DEV_INFO, the same value btrfs replace start compares against). For existing LUKS targets, mapper capacity is derived from the LUKS2 segment offset and size (dynamic means raw - offset, fixed means the segment size). For fresh-LUKS targets, braid uses cryptsetup’s default 16 MiB offset; offset-affecting --luks-format-arg flags (--offset/-o, --align-payload, --luks2-metadata-size, --luks2-keyslots-size, --sector-size) are rejected for this reason.
• For live replacements: refuses if the pool has missing devices (resolve those first)
• For missing replacements: refuses if --missing-id points to a live device
• For missing replacements: refuses if --missing-id disagrees with the devid pool.json records for --old (--old already identifies which member to rebuild)
• For missing replacements: refuses if pool.json has no recorded devid for --old – --missing-id cannot substitute, it must match the recorded devid
• Verifies the passphrase against an existing pool member before formatting
• Warns before confirmation and in --dry-run if the live source device has I/O errors (informational, does not block)
• Warns if existing pool drives have a keyfile but --enroll was not passed
• 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 if a btrfs balance is paused on the pool – resume or cancel it first. A paused balance holds the exclusive-operation lock indefinitely, so braid cannot wait it out.
• Refuses when UPS support is enabled and braid ups status cannot verify a trusted OL (utility-power) state.

Related commands

• braid status – find device IDs and see which disks are missing
• braid remove-missing – forget a dead device without replacing it
• braid add – add a new disk (without replacing an existing one)

← 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

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)

Related commands

• braid lock – unmount the pool and close LUKS mappers
• braid status – check pool health after unlocking
• braid replace – repair a missing disk after degraded unlock

← braid

braid lock

Unmount the btrfs pool and close all LUKS mappers.

When to use it

• Before shutting down or rebooting (though systemd handles this automatically)
• When you want to manually take the pool offline
• Before physically removing a disk (after braid remove)

Basic example

sudo braid lock

Common variations

Preview what would happen:

sudo braid lock --dry-run

Important flags

What happens under the hood

1. Checks if the pool is mounted
2. Checks that no btrfs exclusive operation (balance, device remove, etc.) is running. Skipped when the pool is not mounted.
3. Unmounts the btrfs filesystem, retrying up to 3 times if the device is busy (covers the brief race after stopping SMB/NFS consumers, where the kernel has not yet released the last file descriptors)
4. After a successful unmount, runs btrfs device scan --forget for the planned close-set mappers (member-owned plus any orphaned braid-* mappers from a prior crash) that still exist on disk, clearing the kernel’s device registry so stale references do not race with mapper close. Skipped when there is nothing left to forget.
5. Classifies live mappers by LUKS UUID/devid ownership, then closes member-owned observed mapper names, retrying up to 3 times if the device is busy
6. Scans for orphaned braid-* mappers not owned by UUID-keyed membership (e.g. from a prior crash) and closes those too

If the pool is already unmounted and all mappers are already closed, lock reports “pool already locked” and exits cleanly.

On NixOS module installs

When braid is installed via the NixOS module, braid lock also:

• Stops braid-scrub.timer, braid-scrub-resume-trigger.service, and braid-scrub.service before unmount.
• Stops any consumer wired into the pool lifecycle via BindsTo=braid-online.service (lock walks its reverse, BoundBy; e.g. an SMB or NFS unit you set up that way – see Sharing and permissions) before unmount.
• Stops braid-online.service itself after a successful unmount.

braid unlock reverses the third step: it reactivates braid-online.service after mount, which restarts every consumer that is also WantedBy=braid-online.service. A consumer wired with only one of the two half-works – BindsTo stops it before lock, WantedBy restarts it after unlock – so wire both; the sharing guide shows the full setup.

Standalone CLI installs (no NixOS module) skip all three – there is no braid-online.service or scrub unit to stop.

Error handling

• Refuses if another braid operation is in progress (pool lock /run/braid-pool.lock is held) – retry once it finishes.
• If unmount fails after 3 retry attempts (e.g. a process has files open on the mount), lock skips btrfs device scan --forget and still attempts to close the LUKS mappers, reporting the failure
• If a mapper close fails with “device busy” after unmount also failed, the error is downgraded to a warning (the root cause is likely the stuck unmount)
• The hint lsof <mount_point> or fuser -vm <mount_point> is printed when unmount fails, to help identify the blocking process
• If a scanned braid-* mapper’s backing LUKS UUID cannot be verified (for example because its backing device is gone or its LUKS header is unreadable), lock prints a [warn], leaves that mapper open instead of closing it, excludes it from both btrfs device scan --forget and the close step, and still exits cleanly. Re-run braid lock once the mapper’s LUKS UUID is readable. The literal cleanup incomplete summary line appears only under --dry-run; a real run surfaces the per-mapper [warn] and does not print pool already locked. See ADR-024.

Related commands

• braid unlock – open LUKS devices and mount the pool
• braid status – check pool state before locking
• braid idle – check if operations are running before locking

← braid

braid seal-mountpoint

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Set the immutable attribute (chattr +i) on the pool mountpoint while it is unmounted, so a process that writes the path before the pool mounts fails loudly with EPERM instead of silently landing data on the root filesystem (which the pool then hides when it mounts over it).

You rarely run this by hand: the NixOS module runs the bare form automatically from the braid-seal-mountpoint boot/activation unit. The explicit-path forms are maintenance levers. See ADR 028.

When to use it

• Re-seal now after the doctor reports the mountpoint is mutable while offline (instead of waiting for the next boot or nixos-rebuild switch).
• Seal a separate-path subvolume mountpoint the boot seal does not cover (e.g. /var/lib/jellyfin/media – see Mounting subvolumes).
• Clear an orphaned old mountpoint after changing braid.mountPoint.

Basic example

Seal the configured mount point (what the boot unit runs):

sudo braid seal-mountpoint

Common variations

Seal a specific directory (e.g. an offline subvolume mountpoint):

sudo braid seal-mountpoint /var/lib/jellyfin/media

Clear the immutable attribute on a path (e.g. an orphaned old mount point):

sudo braid seal-mountpoint --unseal /mnt/old-storage

Important flags

What happens under the hood

1. Opens the path as a directory (a non-directory is refused).
2. Confirms the path is not currently a mountpoint (via statx’s STATX_ATTR_MOUNT_ROOT, on the same file descriptor, so a racing mount cannot cause it to seal a live filesystem root). A live mountpoint is skipped.
3. Sets (or, with --unseal, clears) FS_IMMUTABLE_FL on the bare directory’s inode. The attribute is persistent – it survives unmount and reboot.

The pool mounts normally over a sealed directory; the mounted filesystem’s own root governs writes.

Exit codes

• Bare form (braid seal-mountpoint) is best-effort and always exits 0 – boot must not fail on it. Problems are logged as warnings to the journal.
• Explicit forms (braid seal-mountpoint <path> / --unseal <path>) report an honest desired-state exit code: exit 0 only if the path actually ends up in the requested state (immutable for seal, mutable for unseal), non-zero otherwise – so a manual seal that silently failed to protect a path is visible.

Error handling

• --unseal refuses the currently configured mount point – it must stay sealed while the pool is offline. Change braid.mountPoint first, then unseal the old path.
• --unseal acquires the pool lock and fails fast if another braid operation is in progress, so it cannot interleave with an unlock that would remount over the path mid-operation.
• A live mountpoint is never touched (the explicit forms report this as a failure).
• If the root filesystem does not support the immutable attribute, the bare form logs one clear warning and protection is unavailable (rare – only non-NAS roots like vfat/9p/nfs).

Related commands

• braid doctor – warns when the offline mountpoint is mutable
• braid lock – take the pool offline (the seal persists across the cycle)
• braid unlock – mount the pool over the sealed directory

← braid

braid idle

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Check if the pool has any active operations. Designed for autosuspend integration.

When to use it

• As an autosuspend check to prevent the system from sleeping during a scrub or any btrfs exclusive operation (balance, device add, device remove, device replace, resize, swap activate)
• In scripts that need to wait for the pool to be idle before proceeding

Basic example

sudo braid idle

Output when the pool is mounted and idle:

idle: pool is idle

Output when the pool is not mounted (still exit 0 – nothing to protect):

idle: pool is offline

Exit codes

The busy reason is printed to stdout:

busy: scrub running (45%)
busy: balance running
busy: balance paused
busy: device add in progress
busy: device remove in progress
busy: device replace in progress
busy: resize in progress
busy: swap activate in progress
busy: unknown (<probe>: <error>)

Only the scrub line carries a percentage. The named btrfs operation states come from scanning /sys/fs/btrfs/*/exclusive_operation, which reports the active operation but not its progress.

busy: unknown (<probe>: <error>) is printed when a probe failed. The probe label is mountinfo for /proc/self/mountinfo, sysfs for /sys/fs/btrfs/*/exclusive_operation, or scrub for btrfs scrub status command/parser failures. The error text preserves the underlying diagnostic.

When the pool is offline (not mounted), exit code is 0 – there is nothing to protect, so suspend is safe.

braid idle must run as root. A non-root invocation exits 1 with error: braid must be run as root on stderr before config loading or any probe runs, with no stdout output. The streams disambiguate this from the documented exits above: exit 0 prints idle: on stdout, busy/probe-failure exit 1 prints busy: on stdout, and config-load exit 2 emits a config-error diagnostic.

Autosuspend integration

braid idle is the activity check behind braid’s auto-suspend. You don’t write this check by hand: set braid.autoSuspend.enable = true and braid’s NixOS module generates the autosuspend services.autosuspend ExternalCommand check (BraidPool) for you. The generated command – bash -c '! timeout -k 2 10 braid idle', with fully qualified /nix/store paths for bash, timeout, and braid – handles the exit-code inversion autosuspend expects and a fail-closed inner timeout. Don’t reproduce it by hand: autosuspend runs the check outside braid’s wrapper, so bare braid/timeout are not on its PATH.

See the power management guide for setup, and ADR 016: Auto-Suspend for the exit-inversion table, the qualified-path requirement, and why timeout must sit inside the !-inverted command.

What happens under the hood

1. Checks if the pool is mounted (via /proc/self/mountinfo)
2. If not mounted: returns idle (exit 0)
3. Reads /sys/fs/btrfs/*/exclusive_operation for any active exclusive operation on any btrfs filesystem: balance, balance paused, device add, device remove, device replace, resize, swap activate
4. If sysfs reports a busy operation or the sysfs probe fails, returns immediately before probing scrub
5. Probes scrub status via btrfs scrub status against the configured pool mount point, only after the sysfs scan is clean (scrub is not in the kernel exclusive-operation set, so sysfs cannot detect it)

When the host has more than one btrfs filesystem (e.g. a btrfs root in addition to the pool), an exclusive op on any of them keeps the system awake while the pool is mounted, and the busy: line above may name an op on the non-pool fs. This is intentionally conservative – see ADR 016: Auto-Suspend. Scrub detection is narrower: braid idle only checks for a scrub on the braid pool itself, so a scrub running on a non-pool btrfs (e.g. the btrfs root) is not detected and does not block suspend.

Related commands

• braid status – detailed pool state including operation progress
• braid lock – take the pool offline

← braid

braid status

Show pool health, per-disk detail, capacity, and operation progress.

When to use it

• After unlocking, to verify everything is healthy
• To check on a running scrub, balance, or replace
• To find device IDs needed by other commands (--missing-id)
• To investigate alerts or degraded state

Basic example

sudo braid status

Common variations

Machine-readable JSON output:

sudo braid status --json

Important flags

Output sections

Pool summary

Pool:     /mnt/storage
Status:   intact
FSID:     <uuid>
Profile:
  Data:      RAID1
  Metadata:  RAID1
  System:    RAID1

Status values:

Profile section:

Profile: summarizes btrfs profiles per block-group type. btrfs profiles are per type, so Data, Metadata, and System can differ; see btrfs balance profiles for the background.

The whole Profile: section is omitted when the pool is not mounted or when btrfs filesystem df failed.

Alert banner

When a health alert is active, a banner appears at the top of the output:

ALERT -- disk health issue detected. Run 'braid ack' to acknowledge and silence.
  - btrfs device errors on toshiba1 (devid 1)
  - SMART health warning

Alert causes include btrfs device errors, missing devices, and SMART health warnings. Alerts are latched – they persist until acknowledged with braid ack, even if the underlying condition resolves.

Allocation table

Shows how data is distributed across block group types:

Allocation:
  Type       Profile  Used        Allocated
  Data       RAID1    1.20 TiB    1.50 TiB
  Metadata   RAID1    512.00 MiB  1.00 GiB
  System     RAID1    64.00 KiB   32.00 MiB

Capacity

Capacity:
  Total:  10.91 TiB (Estimated)
  Used:   1.20 TiB
  Free:   9.50 TiB

For RAID1, the total is estimated as the effective mirrored capacity (not raw disk sum). With mismatched disk sizes, the oversized portion of the largest drive cannot be fully mirrored. The estimate accounts for this.

Total is omitted when the pool is degraded (the estimate would be misleading with missing devices).

Drives (compact listing)

Drives:
  toshiba1     sda  devid=1  present
  toshiba2     sdb  devid=2  present
  toshiba3     -    devid=3  missing

Each row shows the disk name, its short kernel device (e.g. sda), its btrfs devid, and its state. A disk not assembled into the live pool – missing, offline, or LUKS-mismatched – shows - for its device.

The devid column shows devid=N only when the live pool currently counts that device missing: a btrfs-MISSING device, or a hot-unplugged member whose backing device is gone (null-underlying). It falls back to - when no live devid exists – a persisted devid the live pool no longer counts missing, or a member with no recorded devid.

That devid is the input to the braid remove-missing --missing-id and braid replace workflows. As with the JSON missing_devids field, a transient hot-unplug devid shown here is refused by both braid remove-missing and braid replace until btrfs promotes the device to MISSING; see Hot-unplug while pool is mounted.

State values use the same vocabulary as Per-disk detail below, rendered lowercase and hyphenated in this compact list (e.g. missing, offline, luks-uuid-mismatch).

Balance progress

Shown only when a balance is running or paused:

Balance:  running, 3/10 chunks (30% complete)
Balance:  paused, 5/12 chunks (58% complete)

Last scrub result

Last scrub: Mon Jan  1 00:00:00 2024 (no errors)
Last scrub: Mon Jan  1 00:00:00 2024 (3 errors)
Last scrub: Mon Jan  1 00:00:00 2024 cancelled (will resume)
Last scrub: Mon Jan  1 00:00:00 2024 interrupted
Last scrub: never
Last scrub: running (45%)

A nonzero error count replaces (no errors) with (N errors) on a finished scrub, and prefixes the cancelled (will resume) and interrupted lines when a partial scrub recorded errors. When the count is nonzero, braid appends a copyable kernel-journal query for the per-error detail lines:

Last scrub: Mon Jan  1 00:00:00 2024 (3 errors)
  scrub error details:
  sudo journalctl -k --since '2024-01-01 00:00:00' --grep 'BTRFS.*(at logical.*on (dev|mirror)|super block at physical)'

The --since argument is the scrub’s start time. See Scrub reported errors for how to read the journal output – including corrected vs. uncorrectable lines and why the count can exceed the visible journal lines.

Per-disk detail

What each disk shows depends on whether it is a live pool member. A live pool member shows its device path, model, serial, LUKS UUID, btrfs I/O error counters (the btrfs: line), and a SMART verdict (the SMART: line). These last two are different layers: btrfs: is the filesystem’s own I/O accounting, SMART: is the drive’s self-report. Any other disk – missing, offline, UUID mismatch, header-unreadable, or unknown – shows a reduced set: its device path and btrfs: unknown (<reason>) / SMART: unknown (<reason>) lines in place of counters; a UUID-mismatch disk also shows its observed LUKS: UUID so the divergence is visible. Separately, any disk that needs attention – for example a missing disk, or a present member with nonzero error counters – gets an Action: line naming the next command (detailed below).

Disks:

  toshiba1          devid 1   present
    Device:  /dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234
    Model:   TOSHIBA MN07ACA12T
    Serial:  1234ABC
    LUKS:    aaaaaaaa-1111-2222-3333-444444444444
    btrfs:   read 0 / write 0 / flush 0 / corruption 0 / generation 0
    SMART:   ok

  toshiba2          devid 2   present
    Device:  /dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_5678
    Model:   TOSHIBA MN07ACA12T
    Serial:  5678DEF
    LUKS:    bbbbbbbb-1111-2222-3333-444444444444
    btrfs:   read 12 / write 0 / flush 0 / corruption 3 / generation 0
    SMART:   warning (2 reallocated)
    Action:  braid replace --old toshiba2 --new <new-name>=/dev/disk/by-id/<...>

  toshiba3          MISSING
    Device:  /dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_9ABC  (not found)
    btrfs:   unknown (device absent)
    SMART:   unknown (device absent)
    Action:  braid replace --old toshiba3 --new <new-name>=/dev/disk/by-id/<...>

Disk states (compact Drives: list and detail view):

btrfs: line. A live, present pool member shows real btrfs counters (read / write / flush / corruption / generation). Every other disk shows btrfs: unknown (<reason>), where <reason> names why counters are unavailable: device absent, LUKS header unreadable, LUKS UUID mismatch, disk offline -- not in pool, or metadata unavailable. (This line was labeled Errors: before braid reported SMART; it was renamed to btrfs: so it reads as a sibling of the SMART: line, not the only error concept.)

SMART: line. A live, present pool member shows the drive’s SMART verdict: ok, warning, failing, or unknown. When the drive reports an out-of-spec attribute, the verdict carries a parenthetical listing the concern(s) – e.g. warning (2 reallocated) or warning (92 percentage used). The parenthetical follows the evidence, not the verdict word, so a failing drive whose attributes braid reads as non-nominal also lists them (failing (5 reallocated)); a bare failing/ok/unknown has no evidence to show. Every non-present disk shows SMART: unknown (<reason>) with the same reasons as the btrfs: line. The SMART verdict is independent of the btrfs counters: a drive can report clean btrfs I/O while SMART reads warning, and vice versa.

Action: line. When a disk needs attention, braid status appends an Action: line naming the next command, so you do not have to look it up:

Healthy present disks and disks in the OFFLINE or UNKNOWN state get no Action: line. These hints are human-output only; --json consumers derive their own remediation from the status and errors fields (the JSON disks[] element has no action field).

See braid replace to rebuild a missing or failing disk and braid doctor for the guided recovery path.

Advisories

braid status may print one or more warning: lines above the pool summary. Each warning corresponds to an entry in the JSON advisories array.

Foreign filesystem at the mount point. When something other than the braid pool is mounted at the configured mount point (for example, a stale tmpfs or ext4 mount left by another tool), braid status reports Status: not mounted and names the actual filesystem type:

warning: /mnt/storage is mounted but fstype is ext4, not btrfs

Unmount the foreign filesystem before retrying braid unlock – otherwise unlock reports “pool already mounted” because something is in fact mounted at that path.

Pending recovery journal. When /var/lib/braid/pending-op.json exists, an interrupted add / remove / remove-missing / replace is owed. braid status prints the advisory whether or not the pool is mounted:

warning: interrupted operation detected (pending-op.json exists, started 2026-05-20T10:30:00Z) -- run 'braid recover' to reconcile

Run sudo braid recover to reconcile from live pool state; do not remove pending-op.json by hand except under the conditions documented in Pending-op file corruption. If the journal is unreadable, the advisory carries the canonical manual-reconciliation phrase instead – because braid recover cannot load an unparseable journal either:

warning: failed to parse pending-op.json: <detail>. Remove /var/lib/braid/pending-op.json after manual reconciliation (see docs/internals/luks-unlock.md) and re-run.

See Unparseable state-file reconciliation for the safe-to-remove conditions.

Pending LUKS header backups

When a header-mutating operation (braid add, braid replace, braid enroll) writes a local LUKS header backup to /var/lib/braid/luks-headers/<disk>.luksheader, braid status prints a warning until those files are removed:

warning: LUKS header backups exist in /var/lib/braid/luks-headers -- copy offsite and delete local copies

The local copy is a transient byproduct of the header-mutating operation, not the intended backup target. Copy each .luksheader file to an off-system location (USB, another machine, cloud key storage), then remove the local copy to silence the warning.

See LUKS header backup workflow for the full rationale.

ENOSPC risk on RAID1 pool. When an intact mounted pool is one disk-loss away from insufficient RAID1 chunk-pair space, braid status prints:

warning: ENOSPC risk: 1 of 3 devices have less than 1.00 GiB unallocated -- if a disk fails, the pool may be unable to allocate RAID1 chunks to restore redundancy. Add capacity with 'braid add', delete unneeded files or snapshots, or compact data chunks with 'btrfs balance start -dusage=50 <mount>' (data only; do not balance metadata).

For 2-disk pools, the warning fires when either device drops below the threshold because new RAID1 chunks need space on both devices. For 3+ device pools, braid simulates each possible single-disk loss and warns when any survivor set would have too little pairable unallocated space. The per-device threshold is min(1 GiB, 10% of total device bytes), matching btrfs’s effective data chunk size.

See Balance fails with No space left on device for recovery options.

Config-disk probe fault. While building per-disk detail, braid status probes every configured member’s LUKS header and its expected braid-<name> mapper. When that probe fails – a braid-<name> mapper hijacked by a foreign container, a backing-path mismatch, a LUKS1 header, or an unreadable/unspawnable cryptsetup call – the fault is recorded as an advisory naming the affected disk:

warning: disk 'disk2' mapper '/dev/mapper/braid-disk2' is open but not backed by the configured disk. Expected LUKS UUID ..., found ...

Unlike the mutating commands (add, replace, enroll), which fail closed on such a fault, status is the always-available read-only diagnostic: it stays non-fatal (exit 0) and still prints the full pool summary, capacity, and per-disk detail. The fault degrades a single member, not the whole report.

A member already live and healthy in the pool keeps its present row – its identity comes from the LUKS-UUID membership join, which tolerates mapper drift (decision 024) – and the advisory is its only flag. Only an affected member that is not live in the pool additionally gets an unknown disk row, so it is neither silently dropped from the detail section nor mislabeled missing in the compact Drives: list.

JSON output

--json produces a structured report suitable for monitoring tools. Key fields:

• mount_point: the pool’s configured mount path (e.g. /mnt/storage) – the same value shown on the human-readable Pool: line. Always present, in both the mounted and not-mounted envelopes.
• status: "intact", "degraded", or "not_mounted"
• total_devices: total number of devices btrfs reports for the pool, as a number. Present when the pool is mounted; omitted in the not-mounted envelope.
• present_count: number of member devices currently present, equal to total_devices - missing_count, as a number. Present when the pool is mounted; omitted in the not-mounted envelope.
• missing_count: number of member devices counted as missing – the cardinality of the missing_devids array below (btrfs-MISSING devices plus null-underlying mappers whose backing device disappeared); 0 on a healthy pool. Present when the pool is mounted; omitted in the not-mounted envelope.
• fsid: the btrfs filesystem UUID, as a string – the same value shown on the human-readable FSID: line, and distinct from a disk’s luks_uuid. Present when the pool is mounted (a mounted btrfs filesystem always has an FSID); omitted in the not-mounted envelope.
• disks: array of per-disk reports – one element per disk braid knows about: present pool members (matched members and foreign live devices), plus configured disks that are not currently live pool members (reported as missing, offline, unknown, luks-header-unreadable, or luks-uuid-mismatch; see the status values below). The field list below describes a live pool member element (as in the example); diagnostic unpooled elements differ as called out per field and in the note after the example.
  • luks_uuid: the disk’s LUKS UUID – the persistent member identity. For a matched live pool member it equals the pool.json membership key; a foreign live pool device carries an observed UUID that is not in membership (paralleling its mapper-basename name). A luks-uuid-mismatch diagnostic row carries the observed on-disk UUID so the divergence is visible. Other non-live rows (missing, offline, unknown, luks-header-unreadable) report ""; correlate them by name, not luks_uuid.
  • name: operator-facing name (e.g. toshiba1). For a matched present member it is resolved via the UUID-keyed membership join; for a foreign present device it falls back to the mapper basename; for a non-present disk it is the configured name. For display/command selection, not identity.
  • by_id: stable /dev/disk/by-id/... hardware path – a runtime handle, not identity.
  • mapper: device-mapper name – a runtime handle, not identity. For a present pool member it is the observed live mapper; for a matched member that is normally braid-<name> but may have drifted (decision 024 tolerates mapper drift), so do not reconstruct it as braid-${name} or you will miss the drift. For a non-present disk (missing, offline, unknown, luks-header-unreadable, luks-uuid-mismatch) braid does not report an observed mapper, so it emits the expected braid-<name> derived from the configured name, paralleling the configured name and by_id on those rows.
  • underlying: current backing block device (e.g. /dev/sda), or null when the disk is not a live pool member.
  • devid: btrfs device ID as a number (e.g. 1), or null when the disk is not a live pool member.
  • status: one of present, missing, luks-header-unreadable, luks-uuid-mismatch, offline, unknown.
  • btrfs_errors: btrfs I/O error counters (read, write, flush, corruption, generation, all integers) – the filesystem’s I/O accounting. Present when btrfs device stats are available; omitted entirely otherwise – including for present disks when btrfs device stats fails (which also emits a btrfs device stats failed advisory). (This field was named errors before braid reported SMART; it was renamed so it reads as a sibling of smart, not the only error concept.)
  • smart: the drive’s own SMART self-report – a verdict plus supporting evidence, a different layer from btrfs_errors. Present for live pool members; omitted for disks with no backing path to probe. The object always carries health ("ok", "warning", "failing", or "unknown"). When SMART evidence is available it also carries a protocol discriminator ("sata" or "nvme") and the per-protocol counters – for SATA reallocated_sectors, pending_sectors, offline_uncorrectable; for NVMe media_errors, critical_warning, percentage_used, available_spare, available_spare_threshold – plus celsius when the drive reports a current temperature. A drive whose detail log is absent (or whose health is unknown) carries health alone. This field is diagnostic evidence only – it does not feed the alert latch (see the note under alert_causes).

{
  "name": "toshiba1",
  "mapper": "braid-toshiba1",
  "by_id": "/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234",
  "luks_uuid": "aaaaaaaa-1111-2222-3333-444444444444",
  "devid": 1,
  "underlying": "/dev/sda",
  "status": "present",
  "btrfs_errors": { "read": 0, "write": 0, "flush": 0, "corruption": 0, "generation": 0 },
  "smart": { "health": "ok", "protocol": "sata", "reallocated_sectors": 0, "pending_sectors": 0, "offline_uncorrectable": 0, "celsius": 26 }
}

A diagnostic unpooled disk (missing, offline, unknown, or luks-header-unreadable) reports "luks_uuid": "", "devid": null, "underlying": null, and no btrfs_errors or smart key. offline is present but not assembled; the others reach the same blank/null row shape because no live member row is available. Correlate these rows by name.

A config-disk probe fault (see the Advisories section above) on a member that is not live in the pool produces an unknown row of this shape – the advisory carries the cause. A member that is live keeps its present row and is flagged by the advisory alone, so not every probe fault adds an unknown row.

• alert_active: boolean
• alert_causes: array of alert cause objects. Omitted entirely when no alert is active (the key is absent, not []) – check the always-present alert_active boolean first, mirroring how advisories is “omitted when none”. When present, each object is tagged by a type discriminator:
  • { "type": "btrfs_device_errors", "devid": <number> } – btrfs I/O errors on that device.
  • { "type": "missing_device", "devid": <number> } – a device counted as missing.
  • { "type": "smartd_alert" } – a SMART health warning from smartd.
  • { "type": "computation_error", "detail": "<string>" } – braid could not compute alert state; detail explains.

The per-disk smart field does not feed the alert latch. The smartd_alert cause is driven by the smartd daemon’s flag (/var/lib/braid/smartd-alert; see ADR 014 and ADR 030), not by the live per-disk SMART probe status runs. So a report can carry a degraded smart object ("health": "warning") while alert_active is false and no smartd_alert cause is present. This is intentional: the per-disk smart field is diagnostic evidence; smartd remains the alert source.

• advisories: array of human-readable advisory strings (omitted when none). See the Advisories section above for what currently produces them.
• missing_devids: array of every devid counted in missing_count (btrfs-MISSING devices and null-underlying mappers whose backing device has disappeared). For destructive remove-missing / replace --missing-id workflows, see those commands’ notes – a null-underlying devid here will be rejected by those commands until btrfs promotes it to MISSING.
• profile: object with data, metadata, and system arrays, present whenever btrfs reports block-group allocation and omitted when the pool is not mounted or btrfs filesystem df failed. Each array contains raw btrfs profile names such as single, DUP, RAID0, RAID1, RAID1C3, RAID1C4, RAID5, RAID6, RAID10, or an unrecognized name verbatim. Arrays use canonical domain order, not alphabetical order, so mixed data is ["single", "RAID1"], not ["RAID1", "single"]. An empty array means btrfs reported no block groups of that type.
• capacity: total_bytes, used_bytes, free_bytes
• allocation: array of block-group entries, one per allocated type. Each entry has bg_type (e.g. Data, Metadata, System), profile (raw btrfs profile name, same vocabulary as profile above), used_bytes, and allocated_bytes (both integers). Omitted when the pool is not mounted or btrfs filesystem df failed.

3-disk RAID1 profile:

"profile": {
  "data": ["RAID1"],
  "metadata": ["RAID1"],
  "system": ["RAID1"]
}

Single-disk bootstrap profile:

"profile": {
  "data": ["single"],
  "metadata": ["DUP"],
  "system": ["DUP"]
}

Mixed data after interrupted balance:

"profile": {
  "data": ["single", "RAID1"],
  "metadata": ["RAID1"],
  "system": ["RAID1"]
}

The human-facing redundancy annotations from the text output, such as (no redundancy), (same-disk copies; no disk redundancy), and (not fully redundant), do not appear in JSON. The JSON payload carries only the btrfs profile names braid observed; consumers apply their own policy.

• balance: state object (idle, running, paused, unknown)
• last_scrub: state object (never, running, finished, aborted, interrupted, unknown). For finished, aborted, and interrupted, started_at is an offset-free host-local ISO-8601 wall-clock timestamp (YYYY-MM-DDTHH:MM:SS) as reported by btrfs. It records Scrub started, or Scrub resumed after a resumed scrub, and is not directly comparable to UTC fields such as pending-operation started_at values ending in Z. The same three states also carry error_count (integer) – the count btrfs reported, the same number the text output renders as (N errors). The scrub error details: journalctl command from the text output is not part of the JSON (mirroring the profile annotations above); a --json consumer derives its own --since value from started_at.

A complete report for a healthy 3-disk RAID1 pool:

{
  "mount_point": "/mnt/storage",
  "status": "intact",
  "total_devices": 3,
  "present_count": 3,
  "missing_count": 0,
  "profile": {
    "data": ["RAID1"],
    "metadata": ["RAID1"],
    "system": ["RAID1"]
  },
  "fsid": "f5f5f5f5-aaaa-bbbb-cccc-d0d0d0d0d0d0",
  "capacity": {
    "total_bytes": 18000000000000,
    "used_bytes": 6000000000000,
    "free_bytes": 12000000000000
  },
  "last_scrub": {
    "state": "finished",
    "started_at": "2026-05-01T03:00:00",
    "error_count": 0
  },
  "balance": { "state": "idle" },
  "allocation": [
    { "bg_type": "Data", "profile": "RAID1", "used_bytes": 6000000000000, "allocated_bytes": 6500000000000 },
    { "bg_type": "Metadata", "profile": "RAID1", "used_bytes": 8000000000, "allocated_bytes": 9000000000 },
    { "bg_type": "System", "profile": "RAID1", "used_bytes": 65536, "allocated_bytes": 33554432 }
  ],
  "disks": [
    {
      "name": "toshiba1",
      "mapper": "braid-toshiba1",
      "by_id": "/dev/disk/by-id/ata-TOSHIBA_MN07ACA12T_1234",
      "luks_uuid": "aaaaaaaa-1111-2222-3333-444444444444",
      "devid": 1,
      "underlying": "/dev/sda",
      "status": "present",
      "btrfs_errors": { "read": 0, "write": 0, "flush": 0, "corruption": 0, "generation": 0 },
      "smart": { "health": "ok", "protocol": "sata", "reallocated_sectors": 0, "pending_sectors": 0, "offline_uncorrectable": 0, "celsius": 26 }
    }
  ],
  "alert_active": false
}

When the pool is not mounted, every mounted-only field above (total_devices, present_count, missing_count, profile, fsid, capacity, last_scrub, balance, allocation) is omitted, leaving mount_point, status ("not_mounted"), disks ([]), and alert_active. advisories and alert_causes still follow their skip-when-empty rule, so a latched alert or a pending-operation advisory can still appear on an offline pool.

Related commands

• braid unlock – bring the pool online
• braid replace – repair a degraded pool
• braid remove-missing – forget a dead device (operates only on btrfs-authoritative MISSING devids; see that command’s note on transient null-underlying state)
• braid doctor – diagnose pool/disk health and get recovery guidance
• braid idle – machine-friendly idle/busy check for autosuspend

← braid

braid doctor

Runs diagnostic checks on your braid configuration, pool health, RAID profile consistency, LUKS headers, auto-suspend wake path, and alerting hardware. Reports issues and suggests fixes.

When to use it

• After initial setup, to verify everything is wired correctly.
• Periodically, to catch drift (missing disks, mixed RAID profiles, broken alert speaker).
• When something seems wrong and you want a quick health summary.

Basic example

sudo braid doctor

Output:

[ok]   config file     /etc/braid/config.json exists and is valid JSON
[ok]   config schema   required fields present and valid
[ok]   config perms    /etc/braid/config.json permissions ok
[ok]   declared disks  all 3 declared disks present
[ok]   missing devs    no missing devices
[ok]   enospc risk     per-device unallocated space healthy
[ok]   foreign uuids   no foreign LUKS UUIDs in live pool
[ok]   data profiles   data profile: RAID1
[ok]   meta profiles   metadata profile: RAID1
[ok]   system profiles  system profile: RAID1
[ok]   meta pressure   metadata pressure within bounds
[ok]   paused balance  no paused balance
[ok]   smart selftest disk1  passed ~2 days ago
[ok]   smart selftest disk2  passed ~12 days ago
[ok]   smart selftest disk3  passed ~30 days ago
[skip] alert beep      skipped (pass --beep to play the audible alert test beep)
[skip] ups daemon      skipped (braid.ups not enabled)
[skip] braid-online    skipped (braid.ups not enabled)
[skip] wake-on-lan     skipped (braid.autoSuspend not enabled)

The SMART self-test check emits one row per pool drive. If a drive has no recent completed self-test, the row includes a paste-ready smartctl command:

[warn] smart selftest disk2  no completed SMART self-test recorded -- run: smartctl -t short /dev/disk/by-id/...

The hint uses the stable by-id path: braid’s own diagnostic read prefers the member’s live backing device, but a smartctl -t short you run later should use by-id, which survives reboots and controller reordering.

To test the real alert sound:

sudo braid doctor --beep

Machine-readable output

sudo braid doctor --json

Prints a JSON object with status (one of ok, warn, fail, skip) and a checks array. Each check has name, status, and message. Per-drive checks also include subject.

--json mode never plays the alert beep test. The check still appears in the report as skip. --json and --beep conflict; run a separate sudo braid doctor --beep when you want to test the audible alert path.

What it checks

Flags

Exit codes

• 0 – all checks passed (ok/warn/skip)
• 1 – at least one check failed

What happens under the hood

1. Reads and validates /etc/braid/config.json.
2. Loads UUID-keyed pool.json and probes each declared disk via cryptsetup isLuks and cryptsetup luksUUID.
3. If the pool is mounted, queries btrfs filesystem df and btrfs device usage --raw to check RAID profile consistency and metadata allocation headroom, probes for missing devices, reconciles each live pool member’s LUKS UUID against pool.json to flag foreign devices, and runs btrfs balance status to detect paused balances.
4. For each declared disk, runs smartctl --json -A -l selftest <device> – the member’s live backing device when it is assembled into the mounted pool, otherwise its persisted by-id path (including a member that is missing or unassembled on a degraded but mounted pool) – and parses the self-test log to detect active failures and report the age of the most recent passing entry. See ADR-024 for why present members are probed by live path rather than by-id.
5. If the braid monitor NixOS module is configured, reports the alert beep check as skipped by default.
6. With --beep, plays a short test beep through the canonical beep wrapper.
7. If UPS support is enabled, checks upsc and the mounted-pool braid-online.service shutdown hook.
8. If auto-suspend is enabled, runs ethtool <interface> to verify runtime Wake-on-LAN state.
9. Aggregates results and prints a summary.

Related commands

• status – live pool health, disk usage, scrub status
• monitor – automated health check for alerting

← braid

braid monitor

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Checks btrfs device error stats, missing devices, and SMART alerts. Designed to be run automatically by a systemd timer (every 5 minutes by default). Exits with a status code that drives the alert pipeline.

When to use it

You normally don’t run this by hand – the braid-monitor.timer systemd unit runs it automatically. Use it directly when debugging the alert system or testing your monitoring setup.

Basic example

sudo braid monitor

No output on success. Check the exit code:

sudo braid monitor; echo $?

Exit codes

What triggers an alert (exit 1)

• btrfs device errors – any device in the pool has read, write, flush, corruption, or generation errors above the acknowledged baseline, including errors discovered during scrub.
• Missing device – btrfs reports a device as missing or a pool device has a null underlying path.
• SMART alert – smartd has written a SMART alert flag (via the braid smartd notifier).
• Computation error – a probe, parse, btrfs device stats call, mountinfo read, acked-stats baseline load, acked-stats save during self-heal, or alert-latch load/quarantine failed. Monitor fails closed: it latches a ComputationError cause so the beeper fires and braid status shows the detail.

Flags

None. Monitor has no flags – it reads from the braid config and state files.

What happens under the hood

1. Checks if the pool is mounted. If not, exits 0 (nothing to monitor).
2. Runs btrfs device stats on the pool mount point.
3. Loads the acknowledged-stats baseline (acked-stats.json) from a previous braid ack. If the file is unreadable or unparseable, monitor fails closed – it latches a ComputationError rather than firing every acknowledged cause against an empty baseline.
4. Self-heals stale ack state before computing alerts: prunes baseline entries for devices no longer in the pool, and clears the missing-acked flag for any device that was acknowledged missing but is now present again. If the baseline changed, the updated acked-stats.json is written immediately; a write failure (e.g. EROFS, ENOSPC) is itself a fail-closed ComputationError.
5. Computes alert causes against the reconciled baseline: btrfs device errors above the baseline, missing/null-underlying devices, and the smartd alert flag.
6. Merges the causes into the alert latch (alert-latch.json). The latch is sticky: once an alert fires, it stays active until braid ack clears it.

Alert pipeline

braid monitor      --writes--> alert-latch.json --> braid status / braid tui (display)
(timer, every 5m)  --exit 1--> braid-alert.service (beeper + alertCommand)

smartd  --start-->  braid-alert.service (beeper)
        --writes--> smartd-alert --> next braid monitor cycle (latches SmartdAlert)

On exit 1, the braid-monitor.service wrapper starts braid-alert.service (the beeper, plus any alertCommand). After that, two things stay active until you braid ack, each held by a different mechanism:

• The latch and exit 1 – held by monitor. Each cycle it writes the live causes to alert-latch.json, merging them into the existing latch, and re-exits 1 while any cause remains. braid status and the TUI read the same file for display.
• The beep – held by braid-alert.service itself, not the read-back. Once started it stays active on its own (the backoff beep loop when beep is enabled, or a RemainAfterExit oneshot when it’s off), so the wrapper’s per-cycle systemctl start is a no-op and a skipped cycle (offline or lock-contended exit 0) does not silence it. The service never reads alert-latch.json or the smartd-alert flag.

smartd is a second, independent trigger: on a SMART fault it starts braid-alert.service directly and writes the smartd-alert flag, which the next monitor cycle latches as a SmartdAlert cause.

The beep stops only when braid ack clears the latch and runs systemctl stop braid-alert.service.

Related commands

• ack – acknowledge alerts and silence the beeper
• doctor – one-time diagnostic; pass --beep to test the alert beep
• status – shows active alerts in the status output

Related guides

• Monitoring and alerts

← braid

braid ack

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Acknowledges active alerts and silences the PC speaker beeper. When there is an active alert source on a mounted pool, it also sets the current device error counts as the new baseline so the same condition won’t re-trigger.

When to use it

• The beeper is going off and you’ve investigated the cause.
• braid status or braid tui shows active alerts you’ve already addressed.
• After replacing a disk or running a scrub to clear errors.

Basic example

sudo braid ack

Output:

acknowledged 3 alerts

If there’s nothing to acknowledge:

no active alerts

What happens under the hood

1. Reads the alert latch to determine how many alerts are active.
2. If the pool is mounted:
   • If a latch entry exists, the smartd alert flag is present, or the latch is corrupt, snapshots the current btrfs device stats error counters and missing-device state.
   • Writes that snapshot as the new acknowledged baseline (acked-stats.json). Future monitor runs compare against this baseline, so the same error counts won’t trigger again.
   • If none of those alert sources is present, exits 0 with no active alerts and does not query btrfs or rewrite acked-stats.json.
3. Stops braid-alert.service (the beeper), best-effort. This runs first so the stop attempt is reached before any later file-removal I/O error can short-circuit the rest of cleanup.
4. Removes the smartd alert flag (smartd-alert) if present.
5. Removes the alert latch file (alert-latch.json).
6. Removes the corrupt-latch sidecar (alert-latch.json.corrupt) if present.

On a cleanup I/O error, ack preserves retry state so the next braid ack resumes cleanup after the I/O fault is fixed.

When ack reaches cleanup and a later cleanup step fails, it leaves /var/lib/braid/alert-cleanup-pending. braid status surfaces ack cleanup pending -- re-run `braid ack` to resume as an alert cause until cleanup finishes. If that sentinel is the only remaining alert signal, the next braid ack re-enters cleanup directly (no btrfs probe, no baseline rewrite) and prints acknowledged current alerts on success – expected output because only leftover cleanup ran.

If the pool is offline but alerts exist (e.g., a latched smartd alert), ack still clears the latch and flag without snapshotting device stats. Offline means there is no mount at the configured mount point. If that path is occupied by a non-btrfs filesystem, braid ack returns a probe error naming the fstype and preserves alert-latch.json, smartd-alert, and acked-stats.json.

Flags

None.

Safety checks

• If the pool is not mounted and no alerts are latched, ack refuses with “pool is not mounted – nothing to acknowledge”
• If the pool is mounted but healthy with no latch entries, no smartd alert flag, and no corrupt latch, ack is a no-op and does not mutate acked-stats.json
• If the configured mount point is mounted as something other than btrfs, ack refuses with the fstype mismatch and does not clear or rewrite alert state
• If another braid operation holds the pool lock (/run/braid-pool.lock), waits up to 10 seconds for it to finish: proceeds if the lock frees within that window, otherwise exits 1 with the pool-lock retry message.

Related commands

• monitor – the automated check that triggers alerts
• status – view active alerts
• tui – interactive dashboard shows alert state

Related guides

• Monitoring and alerts

← braid

braid enroll

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Enrolls a binary keyfile into LUKS slot 1 on all pool disks. Used to set up USB auto-unlock: plug in a USB drive with the keyfile, and braid unlock --key-file can open the pool without typing a passphrase.

When to use it

• Setting up unattended unlock via USB keyfile.
• After adding a new disk to the pool (enroll the keyfile on it too).

Basic example

Generate a new keyfile on a USB drive and enroll it on all pool disks:

sudo braid enroll /mnt/usb --generate

/mnt/usb must already exist and be mounted. This creates /mnt/usb/braid.key (4096 bytes of random data) and adds it to LUKS slot 1 on every disk in the pool. You’ll be prompted for the pool passphrase.

Common variations

Enroll an existing keyfile (already at /mnt/usb/braid.key):

sudo braid enroll /mnt/usb

Non-interactive (passphrase from stdin):

echo -n 'my-passphrase' | sudo braid enroll /mnt/usb --generate --passphrase-stdin

Passphrase from a file:

sudo braid enroll /mnt/usb --generate --passphrase-file /root/passphrase.txt

Dry run (preview what would happen):

sudo braid enroll /mnt/usb --generate --dry-run

Flags

What happens under the hood

1. Checks for a pending operation journal (refuses if one exists).
2. With --generate: Validates that the target directory exists, is a directory, is already a mount point, and does not already contain braid.key (if a prior --generate run was interrupted, drop --generate and re-run to finish enrolling the existing keyfile; otherwise remove it manually first).
3. Without --generate: Validates that DIR/braid.key already exists and is a regular file.
4. Scans pool membership for present LUKS disks. Absent or non-LUKS disks are skipped with a message. If a present disk’s live LUKS UUID does not match the UUID recorded in pool.json – the disk was swapped, cloned, or reformatted – enrollment aborts before any passphrase prompt or slot change; detach the foreign disk and reattach the original, or run braid replace if the swap was intentional.
5. Verifies the passphrase against every present pool disk before any keyfile probe.
6. Without --generate: Probes the keyfile against each disk. If it authenticates, reports “already enrolled” and skips that disk for the rest of enrollment. A rejected probe means the disk still needs enrollment; any other probe failure (e.g. device busy) aborts immediately rather than treating the disk as un-enrolled.
7. For each disk still needing enrollment, checks LUKS slot 1: proceeds if free; refuses with an error if occupied by an unknown key (you must remove it first with cryptsetup luksKillSlot).
8. With --generate: Only after all preflight checks pass, generates the random keyfile.
9. Enrolls the keyfile into LUKS slot 1 on each disk.
10. Creates a LUKS header backup for each modified disk.

See Pending LUKS header backups – copy each .luksheader off-system and delete the local copy.

Safety checks

• 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 if a present disk’s live LUKS UUID no longer matches its pool.json record – the disk was swapped, cloned, or reformatted; detach the foreign disk and reattach the original, or run braid replace if the swap was intentional. This UUID check is repeated at the mutation boundary, after the passphrase is read and before any keyfile is enrolled, so a disk swapped during the passphrase prompt is still caught before slot 1 is touched.
• With --generate, refuses unless the target directory is already a mount point.
• Passphrase is verified before any mutations.
• Slot 1 conflicts are detected before the keyfile is generated, so you never end up with an orphan keyfile.
• With --generate, refuses if braid.key already exists at the target path; if a prior --generate run was interrupted, drop --generate and re-run to finish enrolling the existing keyfile.
• Without --generate, refuses if the keyfile doesn’t exist.
• Idempotent: if the keyfile is already enrolled on a disk, that disk is skipped.

Related commands

• unlock – use --key-file to unlock with the enrolled keyfile

Related guides

• Auto-unlock

← braid

braid discover

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Scans /dev/disk/by-id/ for LUKS devices with braid-* labels, reads their LUKS UUIDs, and reconstructs UUID-keyed pool membership. This is a repair tool for recovering a lost or corrupt pool.json.

When to use it

• Your pool.json was deleted or corrupted.
• You’re migrating disks to a new machine and need to rebuild pool state.

The normal path for adding disks is braid add. Use discover only when pool.json is missing or corrupt – it refuses to run while a valid pool.json exists. To see the disks already in a healthy pool, use braid status.

Basic example

When pool.json is missing, preview the membership discover would rebuild before saving it (no changes):

sudo braid discover

Output:

  ironwolf = /dev/disk/by-id/ata-ST12000VN0008_XXXXXXXX
  toshiba = /dev/disk/by-id/ata-TOSHIBA_MN08ACA16T_XXXXXXXX
pass --write to save to /var/lib/braid/pool.json

Bare discover prints this preview only when pool.json is absent. Over a valid pool.json it exits with an error – use braid status to view current membership. Over a corrupt pool.json it also refuses, pointing you to discover --write (see Common variations).

The membership rows are written to stdout; the pass --write to save hint, the --write “pool membership written” confirmation, scan warnings, and errors go to stderr. So braid discover > members (or braid discover | grep <disk>) captures only the rows.

Common variations

Write the discovered membership to pool.json:

sudo braid discover --write

If you can name the expected member count ahead of time, pass it as a fail-closed guard against a detached disk or stray braid-labeled disk:

sudo braid discover --write --expect-count 3

Flags

What happens under the hood

1. With --write, refuses if a pending operation journal (pending-op.json) exists. Bare discover is read-only and skips this gate.
2. Refuses over an existing UUID-keyed pool.json (bare and --write). A corrupt or off-schema pool.json is the documented rebuild path: bare discover prints the rebuild remediation, and discover --write writes a forensic pool.json.corrupt-<RFC3339-UTC> snapshot adjacent to the new file, then rebuilds. If the snapshot cannot be written (full disk, read-only state directory), discover --write refuses rather than destroy the corrupt original.
3. Reads all entries in /dev/disk/by-id/ in sorted filename order, skipping partition entries (e.g., ata-TOSHIBA-part1). Sorting up front makes label-collision reporting (step 10) independent of read_dir order.
4. Resolves each by-id symlink to its canonical kernel device. Skips with a cannot canonicalize warning when the symlink is dangling (e.g., udev didn’t clean up after a disk removal).
5. For each entry, runs cryptsetup isLuks to check if it’s a LUKS device.
6. Runs cryptsetup luksDump to read the LUKS label, version, and UUID.
7. Skips LUKS1 devices (braid requires LUKS2).
8. Matches labels of the form braid-<name> and extracts the disk name.
9. Uses the canonical kernel device resolved above to detect multiple /dev/disk/by-id/ symlinks for the same physical disk (i.e. wwn- and ata- aliases), then picks the most stable one (preference order: wwn > nvme > scsi > ata > usb > other, with lexicographic tie-breaking).
10. If two symlinks that share the same braid-<name> label resolve to different kernel devices, refuses the entire scan with an error. Two physically distinct disks share a label – typically after a dd clone or a manual mislabel – and braid cannot safely choose one. Relabel or detach one disk before retrying.
11. If two distinct devices share one LUKS UUID, refuses the entire scan. This usually means a cloned disk is attached.
12. With --write, saves the discovered UUID-keyed membership to pool.json.

Safety checks

• Refuses any operation on an existing UUID-keyed pool.json. Corrupt or off-schema files are allowed for --write rebuild only; the original is copied to pool.json.corrupt-<RFC3339-UTC> before overwrite, and --write refuses if that snapshot cannot be written (full disk, read-only state directory). Run with all intended pool members attached; see docs/internals/luks-unlock.md.
• With --write, refuses if a pending operation journal (pending-op.json) exists – run braid recover to reconcile.
• With --write, refuses if another braid operation is in progress (pool lock /run/braid-pool.lock is held) – retry once it finishes.
• With --expect-count, refuses to write if the discovered member count is not exactly the requested count.
• Without --write, makes no changes at all – read-only scan that takes no pool lock and does not consult the pending-op journal.
• Dangling /dev/disk/by-id/ symlinks are skipped with a warning – a diagnostic operators need when udev leaves a stale alias behind after a disk swap.
• LUKS1 devices are skipped with a warning.
• If no braid-labeled LUKS2 devices are found, discover exits 1 with no braid-labeled LUKS2 devices found -- ... (both bare and --write) – check the intended members are attached, readable, and labeled braid-<name> as LUKS2. An array that is entirely LUKS1, detached, or unreadable lands here, with any present-but-skipped disk warned about above.
• Refuses the scan if two distinct devices share the same braid-<name> LUKS label – relabel or detach one disk before retrying.
• Refuses the scan if two distinct devices share the same LUKS UUID – detach the cloned or unintended disk before retrying.

Related commands

• recover – resume an interrupted operation (has its own membership rebuild from live pool state)
• status – view current pool membership

← braid

braid recover

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Resumes from an interrupted operation (add, remove, replace) by opening LUKS devices, mounting the pool, rebuilding pool.json from live pool state when appropriate, running owed maintenance when the btrfs balance state is idle, and clearing the pending-operation journal only after the safe recovery path completes.

When to use it

• After a crash, power failure, or interrupted braid command.
• When braid status or other commands show “pending operation – run braid recover”.
• Only available when pending-op.json exists.

Basic example

sudo braid recover

You’ll be prompted for the pool passphrase. Output shows the recovery process:

Recovering from interrupted "add" operation (started 2026-03-15T14:30:00Z)...
pool.json written from completed add membership.
pool.json written from committed add membership.
pending-op.json cleared. Recovery complete.

Before the pool.json lines, a real run prints either per-disk LUKS-open and mount rows (if the pool was offline) or a single pool already mounted at ... row (if it was already mounted). On the idle/no-paused owed RAID1 path, after the committed line it prints a RAID1 soft-balance replay row pair before the final pending-op.json cleared line. If the balance check is paused, running, or unknown, recover fails before the replay row and does not clear the journal.

Important

If recover refuses owed RAID1 replay because btrfs balance state is paused, running, or unknown, it left pending-op.json in place. Inspect btrfs manually before clearing recovery state.

Common variations

Non-interactive (passphrase from stdin):

echo -n 'my-passphrase' | sudo braid recover --passphrase-stdin

Passphrase from a file:

sudo braid recover --passphrase-file /root/passphrase.txt

Recover with a missing disk (degraded mode):

sudo braid recover --allow-degraded

Preview what would happen:

sudo braid recover --dry-run

Flags

What happens under the hood

1. Loads pending-op.json (refuses if absent – nothing to recover).

2. Chooses the mount membership from the journal phase. Existing-pool add and remove-missing PoolMutation phases mount from the pre-operation membership. Add, remove-missing, and replace post-maintenance phases mount from the committed target membership. Replace PoolMutation, bootstrap add PoolMutation (the first disk, whose pre-operation membership is empty), and Remove mount from the admission membership (pre-operation snapshot plus target-only members) – for replace this matters because the kernel may still be completing dev_replace.

3. Opens LUKS devices and mounts the pool (or reuses the existing mount if already mounted). Exception: a Replace::PoolMutation journal on an externally-mounted pool is refused (see Safety checks); replace post-maintenance recovery on an already-mounted pool is allowed.

4. For Replace::PoolMutation only, if a kernel-resumed btrfs replace is in progress, waits for it to finish.

5. For Replace::PoolMutation only, if the pool was just mounted by this recover run, performs a full relock-and-remount cycle (umount, btrfs device scan --forget, close LUKS, reopen, remount) to ensure the kernel’s in-memory device topology matches the on-disk state.

6. Probes the live pool to discover actual membership.

7. For interrupted existing-pool add PoolMutation, first runs a non-destructive Add target reconciliation pass: any journaled add target whose underlying disk is physically present and LUKS-openable is opened, scanned, and followed by a live-pool re-probe. Targets that turn out to be live pool members are adopted into the recovered pool.json without wipefs or btrfs device add.

8. For add PoolMutation, replays only journaled targets that are not already live. RecoverableBraidLabeled targets are replayed via wipefs --all --types btrfs plus btrfs device add -f after LUKS UUID and visible-FSID checks. FreshLuks targets that are physically present are replayed from the journaled format options, skipping format if the disk already has the expected LUKS label; if the journal carried enroll_key_file, the keyfile is re-enrolled, then the LUKS header is backed up, the mapper is opened, and btrfs device add runs without -f. FreshLuks targets that are physically absent or carry an unexpected LUKS label make recover fail and leave pending-op.json in place so the disk can be reattached or replaced and recovery rerun.

   See Pending LUKS header backups – copy each .luksheader off-system and delete the local copy.

9. For add PostAddBalanceRaid1, does not format, enroll, back up headers as target prep, wipe, or add disks. It only validates the committed live pool and runs the owed RAID1 balance when btrfs balance state is idle; a paused, running, or unknown balance state fails closed with the journal preserved.

10. For replace and remove-missing PoolMutation, detects whether the primary btrfs membership mutation committed. If it did not commit, recover restores/keeps the pre-operation pool.json, clears the journal, and tells you to rerun the original command. It does not rerun btrfs replace start or btrfs device remove.

11. For replace and remove-missing post-maintenance phases, validates committed live membership, repairs pool.json if needed, and finishes only owed maintenance such as resize or, when btrfs balance state is idle, soft RAID1 balance; it does not rerun the primary btrfs membership mutation. A paused, running, or unknown balance state before owed RAID1 replay fails closed with pending-op.json preserved.

12. Resolves /dev/disk/by-id/ paths from live LUKS UUIDs, using btrfs devid only for missing or null-underlying bindings (not from the journal’s by-id path, which may be stale).

13. Writes or repairs pool.json only after the journal phase allows it and live membership is complete.

14. Clears pending-op.json only after membership is complete and any owed balance work is done.

Safety checks

• Refuses if no pending-op.json exists.
• Refuses if another braid operation is in progress (pool lock /run/braid-pool.lock is held) – retry once it finishes.
• Refuses to adopt live pool members outside the recovery admission membership for the current journal phase (guards against devices added outside braid). Most phases admit the pre-operation snapshot plus target-only members; Replace::PostReplaceMaintenance admits only the committed target membership because btrfs preserves the old device’s devid on the replacement after commit.
• Hard-fails if a live pool device has no /dev/disk/by-id/ symlink (recovery can’t guess a stable identifier).
• Detects interrupted bootstrap add (first disk, no filesystem yet) and gives specific wipe-and-retry instructions instead of a confusing mount error.
• Refuses to overwrite pool.json or clear pending-op.json if the post-mount probe at the configured mount point sees the pool unmounted or with zero btrfs devices. The mount may have been removed externally between recover’s mount step and membership probe; pool.json and pending-op.json are both preserved – investigate the mount, then re-run braid recover.
• For existing-pool add recovery, refuses to clear the journal while any journaled add target is missing from the live pool.
• Returned-disk replay may need a pool passphrase even when the pool is already mounted, because the mapper for the journaled target may still be closed.
• Without --allow-degraded, refuses to mount if devices are missing (exit code 2 for degraded-refused, distinguishing it from other errors).
• Refuses to recover Replace::PoolMutation when the pool is already mounted (admin-mounted, circumventing braid’s pending-op preflight on unlock). The kernel may have resumed an interrupted dev_replace on that mount session, leaving stale in-memory device state that recover cannot scrub without unmounting – which it will not do on a mount it does not own. Remediation: sudo braid lock; sudo braid recover.

Related commands

• status – shows pending operation state and prompts you to recover
• discover – rebuild UUID-keyed pool.json from LUKS labels and UUIDs (when there’s no journal)
• unlock – normal unlock (when no journal exists)

Related guides

• Recovery scenarios

← braid

braid tui

Interactive terminal dashboard showing pool state, disk health, allocation, scrub status, and active alerts.

When to use it

• Quick visual overview of your NAS health.
• Checking disk-level detail (LUKS cipher, SMART health, error counts, transport).
• Monitoring during or after a scrub.

Basic example

sudo braid tui

Demo mode

Try the TUI without a real pool (no config or btrfs required, no root required):

braid tui --demo

Demo mode shows three fake disks with sample data, useful for exploring the interface.

Flags

Keybindings

What it shows

Main view – pool status, mount point, the Profile summary (data <X> | meta <Y> | system <Z>, where each value is the profile name verbatim for a single recognized profile such as RAID1, DUP, or single; partial when that block-group type spans more than one profile; the raw profile name verbatim for an unrecognized profile like RAID5; or unknown only when no block groups of that type were reported), capacity bar, balance state, and active alerts and advisories.

Refreshing – while the pool is mounted, pool, disk, scrub, and alert data refresh automatically about every 10 seconds and immediately when you press r. While the pool is not mounted, that data stays manual-only via r. When enabled, Fans and UPS telemetry also refresh automatically every 5 seconds and immediately on r. The footer’s Reload: r spinner and idle (Xms) duration reflect pool refreshes, including automatic pool refreshes; automatic Fans/UPS polls do not update it. The view redraws periodically while idle so relative ago times stay current.

Disk table – one row per disk: number, name, bus (sata/usb/nvme), SMART health, temperature, btrfs device-error count, and allocated (shown as percent used and allocated/size).

Fans (when fan control is enabled) – Data-tab row with a daemon: header annotation for hddfancontrol-braid.service: active is green, activating and inactive are yellow, failed is red, and unknown is gray. The annotation is not a column; the columns are PWM (raw/255 plus percent), RPM, Driving (the hottest drive and its temperature), and Curve. See the fan control guide.

UPS (when UPS support is enabled) – Data-tab row with the same daemon: header annotation for the NUT daemon. The columns are Status (color-coded flags), Battery, Runtime, and Load. See the UPS guide for Status severity.

Disk detail popup (press Enter on a disk) – disk name, LUKS lock status, cipher, key size, keyslot count, an allocations table (type/profile/size plus unallocated), the btrfs device-error breakdown (read/write/flush/corruption/generation), and a SMART section with the health verdict plus its supporting evidence rows (per-protocol: SATA reallocated/pending/uncorrectable, or NVMe critical-warning/media-errors/available-spare/percentage-used). A row for an out-of-spec attribute is colored red. Temperature is not repeated here – it has its own column in the disk table.

Tabs – three tabs, switched with Tab / Shift-Tab:

• Data (default) – pool allocation breakdown, disk table, capacity bar, plus Fans and UPS rows when enabled.
• Scrub – per-device scrub state, progress, and timing.
• Browse – raw CLI output inspector across five tool families: Btrfs, NUT (UPS), Systemd, SMART (smartctl), and lsblk. Btrfs views include filesystem usage/show/df/commit-stats, device usage/stats, subvolumes with drill-in plus raw full/snapshot/deleted/default views, scrub status/limits, balance status, quota status/qgroups, and inspect-internal chunks. UPS views include status, raw variables, supported instant commands, connected clients, settable variables, and UPS discovery. Systemd views include unit status, show, braid units, failed units, timers, and mounts. SMART views include device scan, health, info, attributes, and self-test/error logs. lsblk views include tree, filesystems, disks, all-columns, and SCSI. NUT > UPSes can help find the correct ups.name before UPS support is enabled.

Related commands

• status – non-interactive pool health output
• ups status – non-interactive UPS state output

← braid

braid ups status

Note

Experimental 🧪

This command is experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.

Query the UPS (NUT) daemon for the currently configured UPS and render a curated human summary or the serialized parsed model as JSON.

Requires UPS support enabled (braid.enable = true and braid.ups.enable = true). With UPS disabled the command prints an enable hint and exits 0 (not an error).

Basic example

sudo braid ups status

Output:

UPS: ups
Status: OL
Battery: 100%
Runtime: 30m 0s
Load: 17% (56 W estimated)
Input: 120.0 V (transfer 88-142 V)
Device: APC Back-UPS ES 550G
Battery manufactured: 2023/04/12
Last test: Done and passed

JSON output

sudo braid ups status --json | jq .

Emits the serialized UpscOutput model. A success body (no top-level error) is trustworthy telemetry: braid faithfully serialized whatever upsc reported. It is not a claim that the UPS is online – on-battery (OB), low-battery (OB LB), and all-unrecognized status sets are all success bodies with no error and no warning.

To judge UPS state, read status_flags: utility power is proven only by the presence of OL with no blocking flag (OB, LB, TESTFAIL, COMMBAD, FSD) – the same affirmative-OL criterion braid’s own mutation preflight uses (see the UPS guide).

Shape:

{
  "status_flags": ["OL"],
  "battery": {
    "charge_pct": 100,
    "runtime_secs": 1800,
    "voltage": "27.0",
    "type": "PbAc",
    "mfr_date": "2023/04/12",
    "runtime_low_secs": 120
  },
  "load_pct": 17,
  "realpower_nominal_watts": 330,
  "input": {
    "voltage": "120.0",
    "transfer_low": "88",
    "transfer_high": "142",
    "sensitivity": "medium"
  },
  "test_result": "Done and passed",
  "device": {
    "model": "Back-UPS ES 550G",
    "mfr": "APC",
    "serial": "3B1234X56789",
    "type": "ups"
  },
  "extra": { "driver.name": "usbhid-ups", "battery.charge.low": "10" }
}

In a success body (the shape above – a reachable UPS, no top-level error), every typed field is always present: a scalar the driver did not report serializes as null rather than being omitted, and the battery, input, and device objects are always present even when all of their fields are null. Test typed fields for a null value, not for a missing key – a has(...) check on any typed key always returns true. status_flags and extra are always present but never null ([] and {} when empty). The only field omitted when absent is the top-level warning (see the table below). Error bodies are the exception – they carry error/detail and none of the typed keys, so a script must confirm there is no top-level error before relying on the rule above.

status_flags lists flags in first-seen ups.status token order (whitespace normalized, duplicate tokens dropped); braid does not sort them, so the order is deterministic for a given UPS state.

extra is a string-keyed map of every upsc line that did not land in a typed field above. Its contents vary with the NUT driver and version (typically driver.* debug keys plus other untyped fields like battery.charge.low or input.voltage.nominal), and values are kept verbatim as strings.

Distinct sentinels cover the common non-OK cases:

If error or warning is present, do not treat the typed body as healthy UPS state. For these cases, --json writes only to stdout – stderr stays silent so the JSON sentinel can be piped into a single sink (jq, tee, CI logs) without a redundant human error line. Other failure modes, such as malformed config, still print a human error to stderr.

The converse does not hold: the absence of error and warning does not by itself mean the UPS is online – inspect status_flags as above. ups_status_empty fires only when ups.status is empty or missing (no flags to read), so it is not a general health signal.

Flags

Related

• UPS guide – shutdown path, preflight refusal, v1 limitations
• tui – the TUI’s Data tab shows the same live UPS state
• doctor – UPS-adjacent configuration checks

Principles

Canonical invariants for braid. Each principle is authoritative — if code or config contradicts a principle, the code is wrong.

1. Resilient by default

Data drives never block boot. The pool is unlocked and mounted by explicit CLI invocations (braid unlock, the braid-auto-unlock.service unit, or braid recover during recovery), not by systemd mount units. No LUKS or btrfs units are generated at build time. Degraded mounts require explicit --allow-degraded — braid refuses to silently run with zero redundancy. Why →

2. CLI-owned membership

Disk membership is runtime state owned by the CLI, stored in /var/lib/braid/pool.json. Adding or removing a drive is braid add name=/dev/disk/by-id/... — no nixos-rebuild required. The NixOS module provides the mount point, services, and toolchain; the CLI owns which disks are in the pool. unlock requires pool.json to exist and be valid — it never creates or repairs it. Recovery is explicit via braid discover --write. Why →

pool.json is a best-effort operational snapshot — it tells braid which drives to attempt unlocking, not what the pool actually looks like. Any state that can be read from live btrfs (devids, device counts, FSID) must come from btrfs, not pool.json. Commands like status must never surface pool.json-sourced devids; for display authority, devids are authoritative only when read from a mounted filesystem via btrfs device usage or equivalent. Persisted DiskMember.devid carries prior-binding authority only: when live btrfs reports a device by devid alone (the null_underlying mapper case and the btrfs missing_devids case), the persisted devid is the authorized fallback binding for re-attaching that live device to its membership entry. This is not a display-side use of pool.json devid; status output continues to draw devids from live btrfs. Why →

3. Safe-by-construction operations

• Each intent command (add, remove, remove-missing, replace) does exactly one thing with risk-appropriate confirmation. replace always uses btrfs replace start — for live disks it replaces in-place, for missing disks it rebuilds from RAID redundancy using the missing device’s devid. remove-missing cleans up a stale missing-device entry; it never rebuilds data onto a new device (that is replace). When clearing the last missing device with ≥2 devices remaining, both remove-missing and replace (missing path) run a follow-up soft balance to restore RAID1 profiles for chunks written during degraded operation.
• Post-commit persist with journal: mutating commands write a pending-operation journal (pending-op.json) with pre/target membership snapshots before the first irreversible disk operation. pool.json is written once the btrfs membership change has committed, so it reflects committed live membership, not necessarily completion of follow-up maintenance such as RAID1 rebalance or resize. Phased journals advance to post-maintenance after the committed pool.json write; those post phases must never rerun the primary btrfs membership mutation. The journal is cleared only after the entire lifecycle succeeds, including required post-mutation maintenance like soft balance. While the journal exists, braid recover replays owed maintenance when btrfs balance state is idle and fails closed with the journal preserved when owed RAID1 replay finds a crash-paused, running, or unknown balance state. If braid crashes or fails mid-operation, the journal triggers recovery mode: membership/mount/key-enrollment commands (add, remove, remove-missing, replace, unlock, enroll, discover --write) hard-fail; read-only diagnostic and cleanup surfaces (status, doctor, lock, bare discover) stay available. braid recover rebuilds membership from the live mounted pool (not LUKS label scanning) and is the only command that clears the journal.
• Environment-side resource acquisition (file locks, sleep inhibitors, dbus/logind handshakes, external service availability) must happen before journal::write_journal. The journal write commits the user to recovery mode on any subsequent failure, so a pure environment failure (logind unreachable, flock contention) must not leave a stranded pending-op.json for what was conceptually a “command never started” failure. The journal write is the line of no return; reorder code so any RAII guards or environment probes that can fail are bound above it. The per-command pre-journal excluded scope (which also covers reversible validation and identity checks) is enumerated in ADR 019.
• Disk names are immutable once recorded in pool membership; name rename/reassignment is rejected by mutating commands and must use explicit replace or remove+add workflows.
• mkfs.btrfs is gated on bootstrap only – bootstrap accepts only disks classified as fresh non-LUKS during add planning, and the LUKS open helpers verify that any pre-existing braid-<name> mapper is backed by the requested by-id disk before pool creation proceeds. mkfs.btrfs is invoked without -f so its own libblkid signature check is the final fail-closed guard.
• An existing LUKS device or pool member is never reformatted — a multi-layer identity check (LUKS label match, LUKS UUID cross-check against pool.json, pool-mounted requirement, btrfs FSID comparison) prevents accidental data loss, with the btrfs superblock guard as defense-in-depth.
• Failed unlock and recovery mount paths close only LUKS mappers braid newly opened during that invocation. They never close pre-existing operator-owned mappers, including mappers that become already open between planning and execution.
• Mounts always include skip_balance — btrfs silently resumes interrupted balances on mount by default, which can re-trigger ENOSPC or surprise the user with heavy I/O. braid manages balance lifecycle explicitly; unlock warns if a paused balance is detected.
• The bare pool mountpoint is sealed immutable (chattr +i) while the pool is offline, so a process writing it before mount fails with EPERM instead of silently landing on the root filesystem and being shadowed when the pool mounts. The seal is always-on (no knob), lives only in the boot/activation unit (braid-seal-mountpoint), and persists across lock/unlock. Why →
• Dry-run previews for migrated mutating commands are rendered from the same typed work plans that execution consumes; Step is output-only. Why ->
• Why →

4. Single passphrase

All drives share one LUKS passphrase. braid unlock and braid add depend on this — one passphrase unlocks all drives. Before any irreversible operation, every reachable existing LUKS device that will remain in or enter post-operation pool membership has its slot 0 verified. Fresh-format disks are excluded because they have no existing slot 0. The live-replace source is excluded when other retained members exist, so a divergent slot 0 on the disk being replaced does not block its own replacement. The same all-relevant-disk rule applies to keyfile credentials used by mount, unlock, and recover. Why →

Binary keyfile support is available via braid enroll (slot 1) and braid.autoUnlock (NixOS module). The passphrase (slot 0) is the default interactive-unlock mechanism; the slot-1 keyfile drives braid.autoUnlock for unattended boots and can also be passed directly to braid unlock --key-file.

5. Stable identifiers

All persistent storage config uses /dev/disk/by-id/ paths. Never /dev/sdX. Mapper names are braid-<disk-name> (e.g., braid-toshiba) — deterministic, human-friendly, debuggable in lsblk, systemd logs, and error messages. LuksUuid is the primary persistent identity for code; the disk name and the LUKS label are presentation; by_id is for hardware addressing. When the live LUKS UUID is unobservable for a device the kernel/btrfs still reports (null_underlying mapper, btrfs missing_devids), btrfs devid is the only authorized live-fallback binding key. No code path may decide membership, target a device, or correlate live pool state by parsing a name out of a mapper path or LUKS label, except in two narrow cases: discover bootstrapping a UUID-keyed membership from cold disks, and returning-disk adoption safety in add (the PresentLuks path may gate adoption on label match, but identity correlation still uses LuksUuid/devid/FSID). Why →

6. btrfs RAID1

Auto-healing checksums, dynamic drive pooling, in-kernel (no out-of-tree modules). 50% space overhead is accepted. btrfs RAID5/6 is not production-ready. Why →

7. Sane defaults

If a knowledgeable admin would always enable it, braid enables it by default. Use lib.mkDefault for simple pass-through defaults on stable NixOS options. Wrap in a braid.* option when the feature is inside braid’s product boundary and benefits from lifecycle control, discoverability, or a unified config surface – even if the mapping is 1:1. Examples: braid.autoScrub (periodic scrub with lifecycle binding to pool online state), poolAccessGroup for mount root access (root:storage 2770). Why ->

8. Test every design decision

NixOS VM tests validate behavior, not just command success. TDD: write failing tests first, confirm they fail for expected reasons, then implement.

9. NixOS-native

Braid only targets NixOS. No portability abstractions, no generic Linux fallbacks. Follow NixOS module conventions — same option types, patterns, and idioms as nixpkgs. When in doubt, nixpkgs is the tiebreaker. Why →

10. Pinned toolchain

Parser-critical tools (btrfs-progs, cryptsetup, util-linux, NUT, smartmontools, ethtool) are pinned to a specific NixOS stable release via the flake input. Wrappers execute with an explicit PATH built from module-controlled packages (braid.packages.*). Parsers assume the output format of the pinned version – upgrading those tools requires updating fixtures and parser tests. These pinned defaults are a compatibility baseline, not a lock; users may override braid.packages.* to pick up newer system versions when needed. Generic helpers (coreutils, systemd) come from the consumer’s package set and are not part of braid’s parser contract, except that Browse parses systemctl list-units --output=json as a tolerant UI-only picker with raw-output fallback. Why ->

11. HDD defaults

Mount options, LUKS flags, and scrub scheduling are chosen for HDD NAS deployments. Why →

12. One pool operation at a time

Rust dispatch acquires /run/braid-pool.lock before loading config, loading pool.json, probing pool state, or prompting for command input. The authoritative command-to-lock-discipline mapping lives in lock_policy in cli/src/main.rs; its wildcard-free exhaustive match makes every Commands variant choose a discipline at compile time.

Lock disciplines are policy categories, not prose-maintained command lists. Interactive mutators acquire non-blocking and fail fast with braid: another braid operation is already in progress so the user can retry once the active operation completes. Short-contention maintenance paths may wait for a bounded timeout, such as the 10-second alert acknowledgement window. Timer-driven monitoring may exit 0 silently on contention because a missed cycle is harmless and exit 1 would falsely start alert notification. Read-only paths and dry-run modes do not acquire the lock; bare discover is read-only, while its write mode participates because the scan -> pool.json write window must be serialized against pool-state mutators. Read-only diagnostics status and doctor never acquire the lock so operators retain a working diagnostic surface during contention; tests/module/pool-lock-readonly-bypass.py pins this invariant.

Mutual exclusion is enforced at the critical section itself, not via systemd unit topology. Under the held lock, unlock re-checks whether the pool is already mounted and exits cleanly if a prior winner mounted it sequentially; other mutators operate on the current locked state rather than stale pre-lock observations.

13. Announce long-running work

Every interactive command emits a [wait] row before any subprocess that can stall the terminal long enough for the user to wonder whether the CLI has hung. The bound categories:

• cryptsetup Argon2 operations (luksFormat, luksOpen, luksAddKey, --test-passphrase);
• cryptsetup close (single attempt or busy-retry loop);
• btrfs balance, replace, and device remove (potentially hours);
• mount and umount (kernel can drain in-flight I/O / replace workers / inhibitors).

A [wait] row is closed by one of:

• the same command’s paired success row ([ok] {same subject}: ...) on the success path,
• a same-subject [fail] row on a known failure path (e.g. lock.rs’s umount failure),
• a same-subject [warn] row on a non-fatal best-effort failure (e.g. mapper_close::close_mapper_best_effort’s LUKS close, or wait_for_kernel_replace_to_finish’s status-poll error — the command continues despite the failure, and the warn row tells the user the wait window is closed without success),
• a same-subject [skip] row on a successful negative or no-op probe (e.g. braid enroll’s pre-mutation keyfile probe finding the keyfile not yet enrolled — the work the wait announced completed, the answer is “no work yet”),
• or the command’s normal error output (MountError / LuksError / PoolError propagation) on uncaught error paths.

A [wait] followed by none of these closers (i.e., success, fail, warn, skip, or non-zero exit) is a documentation bug.

Fast bookkeeping that completes well under a second (mkfs.btrfs on a fresh disk, btrfs device add, btrfs filesystem resize, btrfs device scan, btrfs device scan --forget, cryptsetup luksHeaderBackup, cryptsetup status, blkid, JSON parses, journal writes, pool.json saves, sysfs reads) does not warrant a row.

Rendering uses status_tag::status_line(StatusTag::Wait, ...) against color_enabled_for_stderr() so plain stderr captures contain unwrapped [wait] bytes and TTY output picks up the gray ANSI tag. Why →

Implementation workflow and conventions are in AGENTS.md at the repo root.

Decision: btrfs RAID1

Principle: btrfs RAID1

Context

The NAS needs checksumming (bit rot detection), self-healing (automatic repair from redundant copy), and dynamic drive pooling (add/remove drives without reformatting). The filesystem sits on top of LUKS.

Options considered

ZFS raidz

• Checksumming + self-healing + RAID. Mature and well-tested.
• Rejected: out-of-tree kernel module. Licensing conflict means it can never be mainlined. NixOS supports it but it’s a second-class citizen — kernel updates can break the module, and the build dependency is heavy.

btrfs RAID5/6

• Same benefits as RAID1 with less overhead (parity instead of mirroring).
• Rejected: not production-ready. The write-hole bug has been a known issue for years. Data loss reports exist. The btrfs wiki explicitly warns against it.

SnapRAID + mergerfs

• Parity-based protection with independent drives. ~75% space efficiency with 3+1.
• Rejected: no auto-healing. SnapRAID syncs on a schedule (e.g., nightly). Bit rot between syncs is undetected. No checksumming on read. Drives are independent ext4 — good for recovery but no real-time protection.

btrfs RAID1

• Checksums every block on read, heals from the RAID1 copy automatically. Dynamic pool — btrfs device add/remove at any time with any size drive. In-kernel, first-class NixOS support. Simple stack: LUKS + btrfs.
• Accepted.

Decision

btrfs RAID1. The 50% space overhead is accepted as the cost of real-time auto-healing with a simple, in-kernel stack.

Tradeoffs accepted

• 50% space overhead — 3x 12TB = ~18TB usable. Parity schemes would give ~24TB.
• Fixed 2-way redundancy — btrfs RAID1 keeps exactly 2 copies of every block, regardless of pool size. A 3- or 4-drive pool tolerates one drive failure, the same as a 2-drive pool. Additional drives buy usable capacity, not extra fault tolerance. Higher-redundancy profiles (RAID1C3, RAID1C4) exist in btrfs but are not used by braid — the product’s redundancy story is “tolerate one drive failure.”
• No drive independence — drives are part of a btrfs pool, not individually mountable. Recovery requires a working btrfs toolchain.
• Rebalancing cost — adding or removing a drive triggers a balance operation that can take hours on large pools.
• Incremental growth — start with 1 drive (single profile, no redundancy), add a second to convert to RAID1. This is a feature, not a tradeoff — data is available immediately, protection comes when the second drive arrives.

Replacement strategy

Device replacement always uses btrfs replace start, including when the source device is missing. btrfs replace start <devid> supports replacing by devid when the source is unavailable, rebuilding from RAID1 mirrors. This is preferred over the alternative btrfs device add + btrfs balance + btrfs device remove approach because:

1. No degraded balance: btrfs docs explicitly warn against balancing a degraded filesystem to lower redundancy. btrfs replace avoids this entirely.
2. Devid preservation: the new device inherits the old devid, keeping the pool topology stable.
3. Single operation: one btrfs replace start call vs. three separate commands with partial-failure risk.

braid remove-missing is retained for cleanup only (forgetting stale device entries), not for replacement. When braid blocks a live replacement because the pool has missing devices, the intended next step is repairing the missing device via braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...> (the missing devid auto-resolves from --old), not forgetting it.

See

• cli/src/cmd.rs — base_mount_options() and the btrfs mount invocation
• tests/storage/btrfs-heal.nix — validates auto-healing
• tests/storage/btrfs-grow1.nix, tests/storage/btrfs-shrink.nix — validates dynamic pooling

Superseded by 017-runtime-disk-membership.md.

Decision: Config-First Workflow

Principle: CLI-owned membership (successor)

Context

NixOS is declarative — nixos-rebuild switch should describe the system’s desired state. But cryptsetup luksFormat and btrfs device add are destructive one-shot operations that cannot be made idempotent. Re-running them would destroy data.

Options considered

1. Fully declarative — module handles formatting in an activation script. Simple but catastrophic if re-run.
2. Fully imperative — script manages everything, module reads live state. Works but creates config drift (disk formatted but not in NixOS config; pool unlock breaks).
3. Config-first hybrid — declare disk in NixOS config (source of truth), rebuild (creates LUKS entries that fail gracefully), then run imperative script to format. Script refuses undeclared disks.

Decision

Option 3. The NixOS config is the source of truth. The script is a one-shot executor that reads from it.

Workflow

1. Add disk to braid.disks
2. nixos-rebuild switch — module exports /etc/braid/config.json, creates LUKS entries (which fail gracefully since disk isn’t formatted yet)
3. sudo braid init-disk /dev/disk/by-id/... — reads config, verifies disk is declared, formats LUKS (explicit, one-shot)
4. sudo braid apply — opens LUKS, adds to btrfs pool, balances to RAID1 if applicable
5. Next reboot auto-unlocks

Config export

The module writes /etc/braid/config.json via environment.etc. This is the single Nix→runtime bridge. All CLI tools read it by default. The file is built at nixos-rebuild time and is read-only at runtime.

Config drift prevention

The script refuses to format disks not listed in braid.disks. Error message tells the user exactly what to add and which commands to run. This ensures every formatted disk has a corresponding LUKS entry for pool unlock.

Symmetric guards

Config-first applies to all pool operations, not just add. The guard works in both directions:

• braid init-disk refuses disks not in braid.disks
• braid apply removes disks from pool when they are no longer in braid.disks

Remove workflow: remove disk from braid.disks → nixos-rebuild switch → sudo braid apply. See 007-disk-pool-management.md for full spec.

Constraint

Two-step process (rebuild + run script) instead of a single rebuild. This is the minimum viable approach given that LUKS formatting is destructive.

Revisit trigger

If NixOS ever gets a formatDevice option type that can safely express one-shot destructive operations, this deviation can be revisited.

See

• modules/braid/options.nix — braid.disks option definition
• modules/braid/storage.nix — config export and LUKS entry generation
• cli/src/ — Rust CLI (init-disk, plan, apply, status)
• archive/design-docs/1-nixos-best-practices.md — original best practices analysis (preserved in git history; last present at commit 9df91f9)

Decision: Resilient by Default

Principle: Resilient by default

Context

The OS lives on an internal SSD. Data drives are separate. Nothing about the data drives — bad config, dead drive, unplugged cable — should prevent the system from booting. The data pool is an external resource, like a network mount. The module tries to bring it up, but if it fails, the box is still a working Linux machine you can SSH into and fix.

Options considered

1. Hard dependencies — LUKS required, mount required. Any failure blocks boot. Simple but means a dead drive = unreachable NAS.
2. Degraded toggle — add an option like braid.allowDegraded = true. Default to hard failure, opt in to resilience. Adds complexity and a wrong default.
3. Resilient by default — nofail, wants everywhere. Zero cost when healthy, graceful in every failure case. No toggle. Degraded mounts require explicit opt-in (--allow-degraded or autoUnlock.allowDegraded) to prevent silent zero-redundancy operation.

Decision

Option 3. Resilience is the default, not an option.

Implementation

LUKS unlock is strictly stage-2 — braid-unlock or braid-auto-unlock opens LUKS and mounts the pool. The module does not generate boot.initrd.luks.devices, data-pool fileSystems entries, or LUKS device declarations. The pool is brought online entirely by the CLI at runtime.

Resilience mechanisms:

• No boot-blocking mount units: The module generates no data-pool fileSystems or LUKS entries. The CLI (braid unlock) opens LUKS and mounts btrfs directly with a plain mount call, so nothing referencing data drives can block boot. Mounting outside systemd also sidesteps the SYSTEMD_READY=0 udev quirk (systemd/systemd#36886): a missing btrfs member can mark surviving devices not-ready and stall a systemd-initiated mount — the exact failure resilience-by-default exists to prevent. Related coverage: tests/repro/udev-missing-disk-{io,idle}.py exercise udev events when a member disappears from an already-mounted pool, characterizing disappearance signals rather than the SYSTEMD_READY=0 mount-gating path. (The one build-time fileSystems entry is the optional autoUnlock USB-key mount at /run/braid-key/mnt, marked noauto/nofail so it never blocks boot and references the key device, not the pool.)
• Degraded mount: Requires explicit --allow-degraded (or autoUnlock.allowDegraded for unattended use) — braid refuses to silently mount with zero redundancy.

Three-tier failure model

Identity enforcement

braid unlock uses authoritative pool membership from pool.json and probes only those configured members. --allow-degraded only bypasses degraded-mount refusal; it does not change which disks are considered pool members.

Constraint

This is not configurable. There is no braid.resilient option. Every braid deployment gets resilient boot.

See

• modules/braid/storage.nix — braid-online.service, braid-pool.target
• tests/module/ — module tests validate boot with all drives healthy
• archive/plans/test-boot-degraded.md — original plan and research (preserved in git history; last present at commit 9df91f9)

Decision: Single Passphrase

Principle: Single passphrase

Context

braid unlock and braid add prompt for a passphrase that unlocks all LUKS devices. If each drive had a different passphrase, the user would need to type N passphrases on every unlock. The UX must be: one passphrase, all drives unlock.

Options considered

1. Shared keyfile on boot disk — store a keyfile on the SSD, encrypt the SSD with a passphrase. Unlocking the SSD exposes the keyfile, which unlocks data drives. More complex boot chain, keyfile is at-rest on disk.
2. Same passphrase, no enforcement — tell users to use the same passphrase. They’ll forget or mistype. Boot breaks silently.
3. Same passphrase, enforced at format time — braid add verifies the passphrase matches relevant existing pool members before formatting. Catches mismatches immediately.

Decision

Option 3. Enforcement at format time.

How it works

• First disk: prompt for passphrase twice (confirm match). Standard new-passphrase flow.
• Subsequent disks: prompt once, then verify every reachable existing LUKS device that will remain in or enter post-operation pool membership via cryptsetup luksOpen --test-passphrase. Fresh-format disks are excluded because they have no existing slot 0. The live-replace source is excluded when other retained members exist, so a divergent slot 0 on the disk being replaced does not block its own replacement. If verification fails, refuse to proceed with a clear error.

Finding a verification target

The CLI reads which devices are in the btrfs pool and verifies the supplied passphrase against each relevant underlying LUKS device before opening or mutating disks. The same result-membership rule applies to keyfile credentials used by mount, unlock, and recover: every planned LUKS target is verified before any mapper is opened with that credential.

For add, this widened preflight changes one mixed-failure precedence case. If a non-first pool member has a divergent slot 0 and a closed PresentLuks { mapper_open: false } candidate would later surface a foreign-FSID or no-btrfs identity error during execute Pass 1, the pool-member credential error now wins. The old identity-first ordering in that shape came from the former first-disk-only verify and was not a documented invariant. A divergent slot 0 is a pool-wide integrity issue that affects future operations; surfacing it before the candidate’s one-off selection error is intentional.

Identity errors found during planning are unchanged. The add work-plan builder still validates every PresentLuks candidate’s braid label and classifies already-open candidates before AddPlan::execute runs, before any passphrase read, and before the widened verify.

Scope

This decision governs the shared passphrase: one passphrase, enrolled in LUKS key slot 0 on every pool disk, enforced at format time. Additional unlock mechanisms (USB keyfiles, TPM, etc.) are orthogonal — they use separate LUKS key slots and do not weaken or replace the passphrase requirement.

See

• cli/src/ — passphrase prompt and verification logic in the Rust CLI
• design-docs/1-braid-add-disk.md — original script design (preserved in git history; last present at commit 4112e57)

Decision: Sane Defaults

Context

Braid should protect the user’s data without requiring them to read through NixOS options to find features worth enabling. If a setting is something every NAS should have, braid should turn it on automatically.

The guiding question: would a knowledgeable admin always enable this? If yes, braid enables it by default.

Decision

Braid sets opinionated defaults two ways: lib.mkDefault for simple pass-through defaults on stable NixOS options, and a braid.* wrapper option when the feature is inside braid’s product boundary and benefits from lifecycle control, discoverability, or a unified config surface — even if the mapping is 1:1. The two cases below say which applies.

When to use mkDefault (don’t wrap)

Use lib.mkDefault to set an underlying NixOS option directly when:

• The NixOS option is stable and well-known — wrapping it adds no clarity.
• The meaning doesn’t change if braid’s internals change.
• The mapping is 1:1 and braid doesn’t need lifecycle control.

The user overrides by setting the NixOS option in their own config. mkDefault gives way automatically.

When to wrap in a braid option

Create a braid.* option when:

• One braid option maps to many underlying options — e.g., braid.autoUnlock sets a fileSystems mount entry for the USB key, a braid-auto-unlock.service, systemd.tmpfiles rules, and assertions.
• The underlying tech could change — the abstraction survives an implementation swap.
• The raw option requires braid-specific context — e.g., the pool membership encodes LUKS + mapper naming conventions. Exposing the raw options would require the user to understand braid’s internals.
• The mapping is non-obvious or must stay in sync — e.g., if braid supported multiple pools, scrub fileSystems would need to track all mount points automatically.
• Braid needs lifecycle control — the feature must be tied to the pool’s online state, not the host system’s always-on timers. Example: braid.autoScrub wraps a 1:1 mapping but needs the timer bound to braid-online.service so Persistent=true catches up missed scrubs after unlock.

Defaults applied

Alternatives considered

Wrap scrub in braid.autoScrub

Accepted (reversed). Initially rejected because wrapping a 1:1 mapping seemed like unnecessary indirection. Reversed because braid needs lifecycle control over the scrub timer: the timer must be bound to braid-online.service so it only runs while the pool is online, and Persistent=true can catch up missed scrubs on unlock. The nixpkgs services.btrfs.autoScrub timer fires on calendar boundaries regardless of pool state, causing silent failures when the pool is locked.

Don’t enable scrub by default

Rejected. This is what Synology and Unraid do — scrub is opt-in. Users who don’t know about scrub never enable it. Braid’s philosophy is that data integrity features should be on by default.

Weekly scrub (TrueNAS default)

Rejected. TrueNAS runs ZFS on always-on servers. Braid targets home NAS with spinning disks where weekly scrubs add unnecessary wear and noise. Monthly catches bit rot well before it can compound across a 2-3 drive RAID1.

See

• modules/braid/options.nix — declares the option defaults (braid.autoScrub, braid.poolAccessGroup)
• modules/braid/storage.nix — realizes braid.autoScrub into the scrub lifecycle units (braid-scrub timer/service and braid-scrub-resume-trigger), all bound to braid-online.service
• cli/src/online_state.rs — mark_online() applies the mount-root permissions from braid.poolAccessGroup (root:<group> 2770)
• Resilient by default — related philosophy: protect by default, no toggles

Decision: NixOS-native

Context

Braid is a NixOS module. It only targets NixOS — no portability goal for other distros, container runtimes, or generic Linux. Every design decision can assume the full NixOS ecosystem is available.

Decision

Braid follows NixOS module conventions — same option types, module patterns, and idioms as nixpkgs. When in doubt, nixpkgs is the tiebreaker.

What this means in practice

• Options use standard lib.mkOption types (lib.types.listOf, lib.types.attrsOf, lib.types.submodule, etc.) — not custom validation or string parsing.
• Activation uses systemd units, not custom init scripts or cron jobs.
• Dependencies use systemd ordering (after, wants, requires), not polling or sleep loops.
• Defaults use lib.mkDefault / lib.mkForce priority, not conditional logic.
• Config generation uses NixOS module merge semantics — not imperative file templating.
• No portability shims. Use NixOS mechanisms (boot.initrd.network, environment.etc, systemd.services) directly.

Tiebreaking

When two approaches both work:

1. Check how nixpkgs modules handle the same problem.
2. If no precedent, prefer whichever composes better with the NixOS module system.

Alternatives considered

Support other distros via abstraction layers

Rejected. Braid’s value comes from deep NixOS integration — declarative disk config, reproducible builds, VM-tested infrastructure. The target user already runs NixOS.

Use generic Linux tooling where possible

Rejected. “Generic” means reimplementing what NixOS already provides (shell scripts instead of systemd units, config files instead of NixOS options) — more maintenance, no atomicity or rollback.

See

• Sane defaults — use lib.mkDefault instead of braid-specific wrappers
• Config-first workflow — NixOS rebuild as the entry point

Superseded by 012-intent-cli.md and 017-runtime-disk-membership.md.

Decision: Disk Pool Management

Principle: CLI-owned membership

Context

braid-add-disk exists and is tested. The pool still needs graceful disk removal, status reporting, and a clear replace workflow. All operations must follow the same config-first pattern: edit braid.disks → nixos-rebuild switch → run CLI tool.

Principle: config-first applies symmetrically

Config-first is not just for adding disks. Every pool mutation follows the same workflow:

• Add: declare disk in braid.disks → rebuild → braid-add-disk
• Remove: remove disk from braid.disks → rebuild → braid-remove-disk
• Replace: remove dead disk + add replacement in braid.disks → rebuild → braid-add-disk

Symmetric guards enforce this:

• braid-add-disk refuses disks not in config
• braid-remove-disk refuses disks still in config

braid-remove-disk spec

Three-tier logic

1. Target mapper exists and is open, verified to map to the requested by-id disk → graceful btrfs device remove /dev/mapper/xxx (migrates data off the device)
2. Target is absent/unopenable and pool shows a missing device → btrfs device remove missing
3. Otherwise → fail with clear diagnostic

Graceful remove is preferred when possible. It avoids relying on RAID1 reconstruction and eliminates ambiguity if more than one device is missing.

LUKS cleanup

After btrfs remove, cryptsetup close the mapper. Best-effort:

• Success → print “disk fully released” (safe to physically pull)
• Failure (busy) → print actionable next steps (lsof/fuser + retry), exit non-zero

No passphrase required

Remove does not need a passphrase. The disk is already unlocked or already gone. Root access + config guard + typed confirmation is sufficient.

Confirmation

Normal remove (pool stays RAID1 with 2+ disks):

Type 'remove this disk' to confirm:

Removing would drop below 2 disks (losing redundancy):

WARNING: This leaves 1 disk with no RAID1 redundancy.
A single disk failure will cause data loss.

Type 'remove this disk without redundancy' to confirm:

Warn but allow dropping to 1 disk — consistent with the single-disk start story.

Reboot-in-between safety

If the user reboots between nixos-rebuild switch (which removes the LUKS entry) and running braid-remove-disk, the disk won’t auto-unlock. This is safe: principle #1 (resilient boot) ensures the system boots and is reachable via SSH. The pool requires explicit --allow-degraded (or autoUnlock.allowDegraded) to mount degraded. The CLI handles both paths (tier 1 if disk is still somehow open, tier 2 if it’s absent).

braid-status spec

Default output

Pool health summary: drive count, RAID profile, total/used/free capacity, degraded/missing state, last scrub result. Per-disk detail: model, serial, mapper name, btrfs devid, read/write/corruption error counters, LUKS UUID, present/missing state.

--json

Machine-readable output for monitoring and automation.

Replace workflow

Replace uses braid-add-disk, which already auto-evicts missing devices during rebalance.

Workflow:

1. Remove dead disk from braid.disks, add replacement
2. nixos-rebuild switch
3. sudo braid-add-disk /dev/disk/by-id/<new-disk>

Auto-evict is specifically for missing/dead devices. Planned removal of a healthy disk uses braid-remove-disk.

Future vision

Document only — do not build yet.

Unified CLI: braid plan (dry-run diff of config vs live state), braid apply (execute with checkpoints and resumability), braid status, braid replace-disk <old> <new>.

Phased roadmap:

1. Ship braid-remove-disk and braid-status (solid primitives)
2. Read-only planner (braid plan)
3. Executor with checkpoints (braid apply)
4. First-class braid replace-disk
5. braid-status --json

Nix config remains source of truth throughout. The workflow evolves from edit → rebuild → script to edit → rebuild → plan → apply, but the principle is unchanged.

CLI shape

Separate scripts (braid-add-disk, braid-remove-disk, braid-status) — not a unified CLI yet. The unified braid command is future work that depends on proven primitives.

See

• modules/braid/options.nix — braid.disks option definition
• modules/braid/storage.nix — config export and LUKS entry generation
• docs/design/decisions/002-config-first-workflow.md — original config-first decision

Superseded by 012-intent-cli.md.

Decision: Unified CLI with Plan/Apply

Principle: CLI-owned membership (successor)

Context

Braid had three standalone scripts (braid-add-disk, braid-remove-disk, braid-status). Each handled one operation with its own validation, pool probing, and confirmation flow. The config-first workflow (edit config → rebuild → run script) was sound, but operators had to choose the right script and remember its flags. All three are now replaced by the unified Rust CLI.

A unified braid command with plan (dry-run diff) and apply (execute with checkpoints) replaces the multi-script mental model with one flow: edit config → rebuild → plan → apply.

Options considered

1. Keep separate scripts — add braid-plan as a fourth script. Simple but doesn’t unify the execute path or add checkpoint/resume.
2. Go binary — full rewrite in Go. Better for complex state machines, but high migration risk and slower delivery for equivalent behavior.
3. Bash+jq unified script — single braid dispatcher with subcommands. Reuses existing tested patterns. JSON plan/checkpoint formats work with jq.

Decision

Option 3. Initial implementation was bash+jq. Now replaced by Rust CLI (cli/).

Architecture

Rust CLI (cli/src/) with subcommand dispatcher:

• braid init-disk <by-id> [--force] [--config <path>] — destructive one-shot: LUKS format a declared disk. Requires explicit operator intent. Never called from apply.
• braid plan [--json] [--allow-remove-missing] [--allow-remove-ambiguous] [--config <path>] — read-only diff: desired state (config) vs live state (LUKS/btrfs/mounts). Outputs action list with status (applicable/blocked), warnings, and blocked reasons.
• braid apply [--resume] [--allow-remove-missing] [--allow-remove-ambiguous] [--config <path>] — executes plan with checkpoint persistence. --resume continues from /var/lib/braid/apply-state.json. Never performs luksFormat.
• braid status [--json] [--config <path>] — pool health summary with per-disk detail (replaces braid-status).
• braid doctor [--json] [--config <path>] — run diagnostic checks against config and pool state (config file, schema, permissions, declared disks, data/metadata profile consistency). Reports ok/warn/fail per check.

Packaged via Crane + makeWrapper in flake.nix.

Hard boundary

cryptsetup luksFormat is forbidden in the plan and apply code paths. Only init-disk may invoke luksFormat. See 009-safe-by-construction-reconciliation.md.

Plan status model

Plan JSON includes:

• status: applicable (can be executed) or blocked (requires operator action first)
• blocked_reasons[]: list of reasons the plan cannot proceed (e.g., INIT_REQUIRED, IDENTITY_AMBIGUOUS_ABSENT_DISK)
• warnings[]: non-blocking issues (e.g., DISK_ABSENT_SKIPPED, INIT_REQUIRED, POOL_DEGRADED)
• confirmations[]: actions requiring explicit operator confirmation (e.g., redundancy loss). When multiple confirmations are required, provide all phrases semicolon-separated in BRAID_CONFIRM (e.g., BRAID_CONFIRM='phrase one;phrase two'). Whitespace around semicolons is trimmed.

Plan/apply state machine

1. braid plan produces a JSON plan (action list with types, targets, preconditions)
2. braid apply runs the planner internally, writes checkpoint, executes actions in order
3. Each action updates the checkpoint atomically (write tmp + mv)
4. On success: checkpoint moves to /var/lib/braid/history/<plan_id>.json, active file removed
5. On failure: checkpoint stays for --resume
6. --resume verifies config hash matches before continuing
7. On resume, absent action targets fail with RESUME_TARGET_MISSING (strict in-flight integrity)

Action types

• OPEN_LUKS — open existing LUKS device (non-destructive)
• ADD_DISK_BTRFS_ADD — add mapper to btrfs pool
• BALANCE_TO_RAID1 — convert pool to RAID1 profile
• REMOVE_DISK_GRACEFUL — btrfs device remove (data migrates)
• REMOVE_DISK_MISSING_EXPLICIT — btrfs device remove missing (requires --allow-remove-missing + BRAID_CONFIRM)
• CLOSE_LUKS_MAPPER — cryptsetup close
• VERIFY_POOL_HEALTH — confirm pool state matches expectations
• VERIFY_EXPECTED_DISK_SET — confirm pool members match config

Checkpoint schema

Active: /var/lib/braid/apply-state.json History: /var/lib/braid/history/<plan_id>.json (last 20 retained)

Backward compatibility

braid-add-disk is now an error stub that directs operators to braid init-disk + braid apply. braid-status is deleted (replaced by braid status). braid-remove-disk remains as a standalone legacy script (not yet ported to the Rust CLI).

Constraint

Two commands (plan then apply) instead of one. This is intentional — deterministic dry-run before mutation prevents accidents.

See

• docs/design/decisions/002-config-first-workflow.md — config-first principle this builds on
• docs/design/decisions/009-safe-by-construction-reconciliation.md — destructive boundary principle
• docs/design/decisions/007-disk-pool-management.md — existing pool management spec
• cli/src/ — Rust CLI implementation

Superseded by 012-intent-cli.md.

Decision: Safe-by-Construction Reconciliation

Principle: Safe-by-construction operations

Context

braid apply originally mixed two fundamentally different operation classes:

1. One-time destructive initialization — cryptsetup luksFormat destroys all data on the target device. It is not idempotent. Running it twice destroys a working LUKS volume.
2. Repeatable reconciliation — cryptsetup luksOpen, btrfs device add/remove, balance, verify. These are safe to run repeatedly.

The structural hazard: state ambiguity (temporarily absent disk vs truly new disk) can route execution toward formatting. A disk that was unplugged and replugged could be misidentified as “new” and reformatted, destroying data.

Options considered

1. Registry-based — track disk identity in a persistent registry to distinguish “new” from “returning”. Adds hidden state, drift risk, and recovery complexity.
2. Config flags — add lifecycle state (new/existing/replace) to NixOS config. Violates declarative end-state principle — config becomes imperative.
3. Structural separation — move destructive operations to a separate command that requires explicit operator intent. apply physically cannot format.

Decision

Option 3. Hard boundary between destructive initialization and safe reconciliation.

Architecture

• braid init-disk <by-id> — the only command that may call cryptsetup luksFormat. Requires the disk to be declared in config, not already LUKS-formatted (unless --force), and not in an active pool. Enforces single-passphrase invariant.
• braid plan / braid apply — reconciliation only. Emits OPEN_LUKS (non-destructive open), never luksFormat. Non-LUKS disks produce an INIT_REQUIRED warning telling the operator to run init-disk first.

Hard boundary enforcement

cryptsetup luksFormat is forbidden in the plan/apply code path. This is verified by:

1. Code inspection — no luksFormat call exists in compute_plan(), executor dispatch, or any function reachable from cmd_apply().
2. Test assertion — braid-apply.py includes an explicit test that apply never contains luksFormat.
3. The ADD_DISK_LUKS_FORMAT_OPEN action type has been removed from the planner and executor entirely.

Missing-disk policy

Absent configured disks are skipped with a DISK_ABSENT_SKIPPED warning. The plan remains applicable — other safe operations proceed. This prevents a temporarily disconnected disk from blocking all reconciliation.

Missing pool devices (devices in btrfs but not in config) require explicit operator intent to evict: --allow-remove-missing flag plus BRAID_CONFIRM='remove missing device from pool' environment variable. This prevents accidental eviction of temporarily absent disks.

Device identity is established by LUKS UUID, not by path or mapper name. When a config disk is absent, its UUID is unknowable, creating identity ambiguity for removal decisions. If the planner wants to remove a pool device but cannot verify it doesn’t match an absent config disk, the plan is blocked with IDENTITY_AMBIGUOUS_ABSENT_DISK. The operator can override with --allow-remove-ambiguous plus BRAID_CONFIRM='remove despite ambiguous identity'.

Resume strictness

Fresh apply is tolerant of absent disks (skip + warn). But checkpointed in-flight actions are strict: if a pending action’s target becomes absent during --resume, the apply fails with RESUME_TARGET_MISSING. The checkpoint is preserved for retry after the target is restored.

Constraint

Two commands (init-disk + apply) instead of one. Operators must explicitly initialize each new disk before reconciliation can include it. This is the minimum viable approach given that LUKS formatting is destructive and non-idempotent.

Revisit trigger

If NixOS or LUKS ever provides an idempotent “ensure formatted” primitive that is safe to run on an already-formatted device, the separation can be revisited.

See

• cli/src/ — Rust CLI (init-disk, plan, apply, status)
• 002-config-first-workflow.md — config-first principle
• 008-unified-cli.md — plan/apply architecture and action types

Decision: Toolchain pinning

Context

Braid’s parser-critical runtime tools (btrfs-progs, cryptsetup, util-linux, NUT, smartmontools, ethtool) are parsed by the Rust CLI. Output formats change between tool versions – a flake update to nixpkgs-unstable could silently break parsers. Generic helpers (coreutils, systemd) are used for basic system operations and are outside braid’s parser contract. Browse has one tolerant UI-only systemd exception: it parses systemctl list-units --output=json for a picker and falls back to raw output on parse failure.

Decision

Pin flake.nix to a specific NixOS stable release (nixos-26.05). Pin only parser-critical tools — those whose output braid parses or whose behavior is part of braid’s correctness model. Generic helpers come from the consumer’s system package set.

How it works

• Flake input: nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05" — braid’s own pinned channel, and the source of parser-critical tool packages unless the consumer redirects braid’s nixpkgs input (see the follows note below).
• Module options: braid.packages.* (cryptsetup, btrfsProgs, utilLinux, nut, smartmontools, ethtool) default to braid’s nixpkgs flake input but can be overridden per-system.
• PATH wrapping: The wrapper injects cfg.packages.* into PATH. Generic helpers (coreutils, systemd) are resolved from the consumer’s pkgs, not pinned.
• Two wrapping sites: flake.nix wraps with pkgs.* defaults (for nix run and tests); the module wraps cfg.package with cfg.packages.* (for deployed NixOS systems where package options may be overridden).

Consumer follows decides the actual source

nixosModules.default builds the braid.packages.* defaults with import self.inputs.nixpkgs – braid’s nixpkgs flake input, instantiated cleanly (no consumer overlays). Whether the consumer sets braid.inputs.nixpkgs.follows = "nixpkgs" decides where the pinned tools actually come from.

The recommended default is no follows. With no follows, braid’s nixpkgs input stays on its pinned nixos-26.05, so the pinned tools resolve from braid’s release channel and braid-cli-unwrapped matches the exact binary the release cache publishes – a cache hit instead of a from-source rebuild on the NAS. ADR 029 is the authoritative home for that cache-path-identity rationale; the short version is that follows rebuilds braid against the consumer’s nixpkgs, changing the store path and forcing a recompile.

follows = "nixpkgs" is a valid advanced opt-out (smaller closure via nixpkgs dedup), but it redirects braid’s nixpkgs input to the consumer’s nixpkgs, so the pinned tools then resolve from the consumer’s nixpkgs. The pin therefore guarantees stable parser output only while the consumer’s nixpkgs stays on the same NixOS stable release braid targets (currently nixos-26.05). Within one stable release tool output formats change only for security fixes, so a consumer aligned on braid’s release is safe; a consumer who bumps nixpkgs ahead of braid moves the storage toolchain with it and re-introduces the parser-drift risk this decision otherwise prevents. If you do opt into follows, mitigate by keeping nixpkgs aligned with braid’s release or pinning braid.packages.*.

Operational escape hatch

Parser-critical tools are pinned by default to the flake’s nixpkgs release, but braid.packages.* overrides are intentional – operators may need a newer upstream version for urgent bugfixes or security patches before braid’s next nixpkgs bump. The override takes precedence. Operator-set braid.packages.* overrides sit outside braid’s committed parser contract: the standard fixture-capture and golden-test recipes build fixed flake checks against the flake’s pkgs, so they do not validate an arbitrary override. Treating an override as supported requires a maintainer to reproduce the fixture-refresh workflow under a temporary local input swap (e.g. --override-input nixpkgs on the capture/test commands, or a local flake edit) at the override’s package version, then re-run just test-rust against the resulting fixtures. Operators who skip this step are running unverified parser inputs.

Classification guideline

Pin when: braid parses the tool’s output, or the tool’s behavior is part of braid’s correctness/safety model.

Use system pkgs when: the tool is a generic helper, braid doesn’t parse its output as a correctness contract, and version drift is unlikely to affect correctness. The Browse Systemd picker is a UI-only exception because it parses systemctl list-units --output=json tolerantly and disables drill-in on parse failure.

New runtime dependencies must be classified into one of these two groups when added.

Upgrading tools

A nixpkgs bump can move parser-critical tools to new output formats, so an upgrade must refresh fixtures and re-run every parser-validation lane – not just confirm tool provenance. These steps mirror the canonical sequence in dev/overview.md (“Refresh fixtures and run tests”); keep the two in sync.

1. Bump the nixpkgs input to the next stable release and run nix flake update nixpkgs.
2. Refresh fixtures: just capture-all-fixtures writes golden files under cli/tests/fixtures/nixos-<release>/ (with upsc/ holding the capture-ups-fixtures outputs). just capture-all-fixtures-unstable is the unstable-lane mirror.
3. Run the parser-validation lanes, updating parsers/tests for any output that changed:
   • just test-rust – golden-fixture parser tests.
   • just test-parsers – live-tool parser canary.
   • just test-vm – VM suite. Its tool-versions check verifies provenance: each pinned tool resolves to a /nix/store/ path on the VM’s PATH and its self-reported version matches pkgs.<tool>.version from the same evaluation. Provenance only – tool-versions does not detect that nixpkgs moved a tool to a new version (both sides advance together), so the fixture and parser tests above are the actual drift gate. Run it alone with just test-vm tool-versions for a quick provenance-only check.

NUT specifically: parse_upsc depends on the key: value shape emitted by pkgs.nut’s upsc client (see reference/nut/clients/upsc.c). A nixpkgs bump that touches networkupstools triggers the same fixture-refresh obligation as the other pinned tools – run just capture-ups-fixtures and just test-rust before merging. The braid-status-ups check under just test-parsers is the live-tool mirror of the golden fixtures.

ethtool specifically: wake_on_lan depends on the Supports Wake-on: and Wake-on: lines emitted by pkgs.ethtool. VM virtio NICs do not provide useful Wake-on-LAN state, so there is no live fixture-capture lane; parser coverage is hand-authored in Rust unit tests, and wrapper provenance is covered by the tool-versions and braid-auto-suspend VM tests.

Alternatives considered

BRAID_*_BIN environment variables

Rejected. Adds a second resolution mechanism alongside PATH. Every callsite would need to check the env var, falling back to PATH. More complexity, same result — Nix already controls PATH.

Absolute paths in Rust (no PATH at all)

Rejected. Would require threading Nix store paths into the Rust binary at build time (via build.rs or env vars). Fragile and non-standard — NixOS convention is PATH wrapping via makeWrapper.

Stay on nixpkgs-unstable

Rejected. Unstable channel updates tool versions without notice. A routine nix flake update could change btrfs-progs output format and break parsers silently. Stable releases change only for security fixes.

Pin all runtime tools (blanket pinning)

Previously active, now superseded. Blanket pinning created unnecessary closure duplication for generic helpers (jq, coreutils) that braid does not parse. The braid.packages.coreutils option was also inconsistently wired — storage.nix used pkgs.coreutils directly, bypassing the option. Selective pinning is simpler and honest about what braid actually depends on.

See

• NixOS-native — follow NixOS conventions (PATH wrapping via makeWrapper)
• Release process – cache-path-identity rationale for the no-follows default
• Principle 10 in principles.md

Superseded by 012-intent-cli.md.

Two-Phase Apply (LUKS Pre-Phase)

Context

After a reboot, all LUKS mappers are closed and the btrfs pool is unmounted. The planner runs after probe, which sees no open mappers and no mounted pool. This causes two problems:

1. Misleading plan display: braid plan shows mkfs.btrfs -f -d single -m dup (may run) for disks that are actually returning pool members. The execute-time superblock check prevents data loss, but the plan output is alarming for routine re-mounts.

2. Mount failure after reboot: Per-device btrfs device scan <device> doesn’t reliably assemble multi-device pools. Even after opening all LUKS mappers and scanning each device individually, mount can fail with “missing members” because the kernel’s btrfs subsystem hasn’t been told about all members atomically. btrfs device scan (no arguments) scans all block devices and reliably assembles multi-device pools.

Decision

Move LUKS opening into a pre-phase that runs before plan generation. The sequence changes from:

old:  checkpoint check → probe → plan → checkpoint → execute
new:  checkpoint check → luks_prephase → probe → plan → checkpoint → execute

The luks_prephase function:

1. Opens closed LUKS mappers — iterates config disks, skips absent and already-open, reads passphrase from --passphrase-stdin or TTY lazily (only when the first closed mapper is encountered).
2. Scans all — runs btrfs device scan (no arguments) to register all open btrfs members with the kernel.
3. Mounts pool — if the mount point is not already mounted, finds the first open mapper and attempts mount. Missing-members errors are tolerated (not all disks may be available). Hard errors propagate.

After the pre-phase, probe sees accurate state: all available mappers are open, the pool is mounted (if all members are present) or truly empty (bootstrap). The plan has no OPEN_LUKS actions for available disks, and is_bootstrap is accurate.

Resume with closed LUKS

If braid apply --resume detects closed LUKS mappers (device exists but /dev/mapper/<name> does not), the checkpoint is invalidated and fresh_apply is called instead. This handles the case where a checkpoint was created pre-reboot and the system has since rebooted. The pre-phase in fresh_apply opens LUKS and re-probes, generating a correct plan.

This avoids the complexity of reconciling a stale checkpoint against post-reboot state. The ActionState state machine doesn’t allow Pending → Completed, so marking pre-reboot work as completed would require weakening type safety.

BtrfsDeviceScanAll

A new CmdRequest::BtrfsDeviceScanAll variant runs btrfs device scan with no arguments, scanning all block devices. This replaces per-device scans in the pre-phase and in the execute_btrfs_add bootstrap-with-existing-btrfs path.

Pre-Phase Side-Effect Policy

After the pre-phase, LUKS is open and the pool is mounted even if the planner subsequently returns Blocked. This is a change from the old invariant:

• Old: Blocked = no mutations.
• New: Blocked = no planned mutations, but LUKS/mount happened as a pre-condition for accurate planning.

This is correct operationally — the pool was supposed to be online — but operators should be aware that braid apply with a blocked plan still opens LUKS and mounts the pool. The passphrase is consumed before the plan is generated.

Alternatives Considered

Reconcile stale checkpoint on resume

Walk the old checkpoint, detect which actions completed pre-reboot (by checking mapper/mount state), and mark them completed. Rejected because:

• ActionState::transition_to doesn’t allow Pending → Completed
• Complex reconciliation logic with risk of incorrect state detection
• Simpler to invalidate and re-plan since pre-phase makes re-planning cheap

Keep LUKS opening in the execute phase

Could add btrfs device scan (no args) to the execute phase. Rejected because the planner would still see inaccurate state, generating misleading plans with mkfs.btrfs (may run) for returning pool members.

Dry-run LUKS open (check without opening)

Could probe LUKS UUIDs without opening to give the planner hints. Rejected as more complex than just opening — LUKS needs to be open anyway, so doing it early is simpler.

Active – Supersedes 008-unified-cli.md and 011-two-phase-apply.md.

Intent CLI

Context

Braid’s plan/apply reconciliation engine was over-engineered for NAS drives, which have ~4 events in their lifetime (create pool, add disk, add another, replace a dead one). The generic reconciler created problems:

• Risk flattening: routine reboot and adding a disk produced the same output format (a “plan” with “actions”)
• Combinatorial complexity: --allow-remove-missing, --allow-remove-ambiguous, BRAID_CONFIRM='phrase1;phrase2'
• Ceremony for routine operations: braid apply after every reboot

Decision

Replace plan/apply with five intent commands:

Disk keys

Disk membership is CLI-owned runtime state in /var/lib/braid/pool.json (see 017-runtime-disk-membership.md). pool.json is keyed by LUKS UUID; the disk name is stored as presentation metadata. Disks are added with name=by_id syntax:

braid add toshiba=/dev/disk/by-id/ata-Toshiba_MN07_XXXX \
          ironwolf=/dev/disk/by-id/ata-Ironwolf_ST12_YYYY

Mapper names are braid-<name> (e.g., braid-toshiba) — human-friendly, debuggable in lsblk/systemd logs, deterministic. They are runtime handles, not persistent identity.

Safety model

The old architecture used a structural code boundary — luksFormat was literally unreachable from apply. The new architecture replaces this with:

1. Explicit operator intent: user specifies a disk key and confirms
2. Layered identity check for existing LUKS devices: a. LUKS UUID is the persistent identity. LUKS label braid-<key> is an adoption-safety gate for returning disks; non-braid LUKS is refused outright. b. Pool must be mounted — bootstrap refuses existing LUKS (no pool to verify against). c. Opened mapper’s btrfs FSID must match the current pool — foreign-pool disks are refused. d. Braid-labeled LUKS with no btrfs superblock is refused – this state is ambiguous (clean eviction, partial init, manual wipe, stale data) and cannot be distinguished without tombstones. e. A braid-labeled LUKS disk with a btrfs superblock whose FSID matches the mounted pool may be accepted as a returned-disk add target. The add journal records the LUKS UUID before mutation. If the stale btrfs signature would block btrfs device add, braid runs only wipefs --all --types btrfs on the verified mapper and uses btrfs device add -f. f. Superblock guard is defense-in-depth on the FSID-matching path for existing-LUKS adds. The bootstrap path accepts only disks classified as fresh non-LUKS during add planning, and the LUKS open helpers verify that any pre-existing braid-<key> mapper is backed by the requested by-id disk before pool creation proceeds. mkfs.btrfs itself is invoked without -f, so its own signature check is the final fail-closed guard.
3. Unified confirmation with device context: all mutating commands (add, remove, remove-missing, replace) show a rich device-info block (model, size, serial via lsblk) and confirm with Type 'yes' to continue:. Degraded-path warnings are informational text, not special confirmation phrases. --yes skips the prompt for scripting.
4. Disk name immutability: mutating commands validate names against recorded disk identity and reject name rename/reassignment. Operators must use explicit replace or remove+add workflows instead of renaming.
5. Journal-protected mutations: mutating commands write pending-op.json before the first irreversible step; it is cleared only after the full operation (including follow-up work like soft balance) succeeds. Existing-pool add, replace, and remove-missing journals are phased. Their PoolMutation phases may reconcile whether the primary btrfs membership mutation committed; their post-maintenance phases may only validate committed membership, repair pool.json, and finish owed resize/balance work. On any error exit, the journal persists to enable braid recover.

--dry-run performs side-effect-free, passphrase-free LUKS probes only – LUKS label reads, and the keyfile credential test used by braid enroll (cryptsetup open --test-passphrase --key-file, which evaluates a credential without activating the device). Checks that require a passphrase or an open mapper – e.g. full identity verification (FSID comparison) – are deferred to execution time when the mapper is closed.

The dry-run preview itself stays on stdout. Side-effect-free probes that nevertheless do bound long-running work – specifically the Argon2-bounded --test-passphrase evaluation in braid enroll --dry-run – emit canonical [wait]/[ok]/[skip] status rows to stderr per Principle 13. Announce long-running work. The previous “successful dry-run leaves stderr empty” contract is intentionally relaxed for this case: an Argon2 derivation runs whether or not the user can see it, and silent dry-runs that take seconds-to-minutes look like hangs. The structured preview output is unchanged.

Replace safety constraints

• --old accepts both live (present in pool) and dead/missing disks.
• Both paths use btrfs replace start — the sole replacement primitive. Live disks replace in-place; missing disks are rebuilt from RAID redundancy by devid.
• --missing-id is only valid when --old is dead/missing. Rejected with live --old. Validated against PoolState::missing_devids (live btrfs state via probe::probe_pool).
• The missing devid is auto-resolved from --old’s persisted pool.json devid, cross-checked against PoolState::missing_devids – independent of how many devices are missing. Because --old’s name already identifies the member, no missing-count gate is needed; --missing-id is an optional cross-check (it must equal the persisted devid, else OldDevidMismatch) and is never required.
• Mixed state (live --old + pool has missing devices) is rejected – operator must repair the missing device first with braid replace --old <missing-name> --new <new-name>=/dev/disk/by-id/<...>. braid remove-missing is only for intentional cleanup (forgetting stale entries without rebuilding data).
• No replacement path uses btrfs device add. Missing-path replace may run a post-commit soft RAID1 balance only when it clears the last missing device.

ENOSPC pre-flight check

remove and remove-missing validate that surviving devices have enough unallocated space to absorb the target device’s allocations before invoking btrfs device remove. Without this, btrfs will either ENOSPC instantly or crash the filesystem to read-only mid-relocation (reproduced in tests/repro/).

The >=2-survivor remove path treats relocation-probe uncertainty as warn-and-proceed – a miss falls through to btrfs’s clean instant-ENOSPC – while remove-missing and the 2→1 remove path are fail-closed on any uncertainty, because a miss there can crash the filesystem read-only with pending-op.json already written.