TrueMigration

A Python CLI tool for migrating TrueNAS configuration from a debug archive to a live destination system. Designed for systems integration teams working in pre-production deployment environments.

What It Does

TrueMigration reads configuration data out of a TrueNAS debug archive (the .tgz produced by System → Save Debug in the TrueNAS UI) and re-creates that configuration on a destination TrueNAS system via its WebSocket API.

Currently supported:

• SMB shares
• NFS exports

Planned:

• iSCSI (targets, extents, portals, initiator groups)

Requirements

• Python 3.9+
• No external packages — stdlib only

Usage

Interactive Mode (recommended)

Drop a TrueNAS debug archive in the current directory and run with no arguments. The wizard will guide you through archive selection, destination configuration, per-share selection, a dry run preview, and final confirmation before making any changes.

python deploy.py

or

python -m truenas_migrate

Command Line Mode

# Inspect the archive before doing anything
python -m truenas_migrate --debug-tar debug.tgz --list-archive

# Dry run — connects to destination but makes no changes
python -m truenas_migrate \
    --debug-tar  debug.tgz \
    --dest       192.168.1.50 \
    --api-key    "1-xxxxxxxxxxxx" \
    --dry-run

# Live migration
python -m truenas_migrate \
    --debug-tar  debug.tgz \
    --dest       192.168.1.50 \
    --api-key    "1-xxxxxxxxxxxx"

# Migrate only SMB shares
python -m truenas_migrate \
    --debug-tar  debug.tgz \
    --dest       192.168.1.50 \
    --api-key    "1-xxxxxxxxxxxx" \
    --migrate smb

Generating an API Key

In the TrueNAS UI: top-right account menu → API Keys → Add.

Conflict Policy

TrueMigration never overwrites or deletes existing configuration on the destination. Conflicts are silently skipped:

Type	Conflict detected by
SMB share	Share name (case-insensitive)
NFS export	Export path (exact match)

Always run with --dry-run first to preview what will and won't be created.

Archive Compatibility

Source version	Archive format	Notes
SCALE 24.04+	ixdiagnose (lowercase)	Combined JSON plugin files
SCALE (older)	ixdiagnose (uppercase)	Per-query JSON files
CORE	freenas-debug/fndebug	Plain-text dumps with embedded JSON blocks
HA bundles	Outer .tgz + inner .txz	Active node archive selected automatically

Project Structure

deploy.py                    # Entry point shim
truenas_migrate/
    __main__.py              # python -m truenas_migrate
    colors.py                # ANSI color helpers and shared logger
    summary.py               # Migration summary and report
    archive.py               # Debug archive parser
    client.py                # TrueNAS WebSocket API client
    migrate.py               # SMB and NFS migration routines
    cli.py                   # Interactive wizard and argument parser

Safety Notes

• SSL certificate verification is disabled by default, as TrueNAS systems commonly use self-signed certificates. Use --verify-ssl to enable it.
• The tool targets the TrueNAS 25.04+ WebSocket API endpoint (wss://<host>/api/current).
• Exit code 2 is returned if any errors occurred during migration.