truenas-unlock 1.3.0

Unlock encrypted ZFS datasets on TrueNAS via the API

TrueNAS Unlock

Unlock encrypted ZFS datasets on TrueNAS via the API.

https://github.com/user-attachments/assets/172c8fd7-5b66-4c5b-bae0-32e378e9305a

• Install
• Setup
• Usage
• CLI
• Running as a Service
• Development
• Credits
• License

Install

# With uv (recommended)
uv tool install truenas-unlock

# With pip
pip install truenas-unlock

Setup

Create ~/.config/truenas-unlock/config.yaml:

host: 192.168.1.214:443
api_key: ~/.secrets/truenas-api-key  # file path or literal
skip_cert_verify: true

# secrets: auto  # auto (default) | files | inline

datasets:
  tank/syncthing: ~/.secrets/syncthing-key  # reads from file
  tank/photos: my-literal-passphrase        # used as-is (no such file)

The secrets mode controls how values are interpreted:

• auto (default): if file exists, read from it; otherwise use as literal
• files: always treat values as file paths
• inline: always treat values as literal secrets

Usage

# Run once
truenas-unlock

# Run as daemon (every 10 seconds)
truenas-unlock --daemon

# Custom interval
truenas-unlock --daemon --interval 30

# Dry run
truenas-unlock --dry-run

CLI

truenas-unlock --help

 Usage: truenas-unlock [OPTIONS] COMMAND [ARGS]...

 Unlock TrueNAS ZFS datasets

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config    -c      PATH     Config file path                                │
│ --dry-run   -n               Show what would be done                         │
│ --daemon    -d               Run continuously                                │
│ --interval  -i      INTEGER  Seconds between runs [default: 10]              │
│ --dataset   -D      TEXT     Filter by dataset path                          │
│ --help      -h               Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ lock      Lock configured datasets.                                          │
│ status    Show lock status of configured datasets.                           │
│ service   Manage system service                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Running as a Service

Requires uv to be installed. Auto-detects Linux (systemd) or macOS (launchd):

# Install and start
truenas-unlock service install

# Check status
truenas-unlock service status

# View logs (follows by default)
truenas-unlock service logs

# Uninstall
truenas-unlock service uninstall

Development

# Clone and install
git clone https://github.com/basnijholt/truenas-unlock
cd truenas-unlock
uv sync --dev

# Run tests
uv run pytest

# Run lints
uv run ruff check .
uv run mypy truenas_unlock.py

Credits

Inspired by ThorpeJosh/truenas-zfs-unlock.

License

MIT