TrueNAS Unlocker

A Python service to automatically unlock encrypted TrueNAS SCALE datasets upon system boot or restart.

The script monitors one or more TrueNAS instances and, if it finds a locked dataset specified in the configuration, it uses the provided passphrase to unlock it. The mechanism relies on a fixed IP or hostname for the TrueNAS instance, ensuring that the unlock process will not function if the server is moved to a different network.

Project Structure

.
├── app/
│   └── truenas-unlocker.py
├── systemd/
│   └── truenas-unlocker.service
├── config.yaml
├── Justfile
├── requirements.txt
└── README.md

Prerequisites

• A Linux system with systemd.
• Python 3.10+
• git command-line tool.
• just command runner.

Configuration

1. config.yaml

This file defines the TrueNAS instances and datasets to monitor.

• check_interval_seconds: The interval in seconds between each check.
• truenas_instances: A list of TrueNAS servers.
  • host: The static IP address or hostname of the TrueNAS server.
  • api_key_file: The absolute path to a file containing the TrueNAS API key.
  • datasets: A list of datasets to monitor on this instance.
    • name: The full ZFS name of the dataset (e.g., pool/dataset).
    • passphrase_file: The absolute path to a file containing the dataset's passphrase.

Example config.yaml:

check_interval_seconds: 300
truenas_instances:
  - host: "192.168.1.100"
    api_key_file: "/opt/truenas-unlocker/secrets/truenas.key"
    datasets:
      - name: "tank/media"
        passphrase_file: "/opt/truenas-unlocker/secrets/media.pass"
      - name: "tank/documents"
        passphrase_file: "/opt/truenas-unlocker/secrets/documents.pass"

2. Secret Files

All secrets (API keys and passphrases) must be stored in separate text files. Each file should contain only the secret string and nothing else. Ensure these files have restrictive permissions (chmod 600).

Installation and Management

A Justfile is provided to automate all common tasks.

Installation

The install command will:

1. Create a dedicated system user (unlocker-user).
2. Copy all necessary project files to /opt/truenas-unlocker.
3. Install the required Python dependencies system-wide.
4. Set secure ownership and permissions on the installation directory.
5. Copy the systemd service file to /etc/systemd/system/.
6. Enable the service to start on boot.

To install the service, run:

just install

Note: After installation, you must manually copy your secret files (API keys, passphrases) into the /opt/truenas-unlocker/ directory and ensure the paths in config.yaml are correct.

Usage

All commands are run via just.

Command	Description
just install	Installs the systemd service and all required files.
just uninstall	Stops and removes the service, user, and all related files.
just start-service	Starts the systemd service.
just stop-service	Stops the systemd service.
just restart-service	Restarts the systemd service (useful after changing config.yaml).
just status	Shows the current status and recent logs of the service.
just logs	Follows the service logs in real-time.
just run	Runs the script manually in the foreground for testing.
just setup	(For development) Creates a local Python virtual environment.
just run-venv	(For development) Runs the script using the local virtual environment.