TrueMigration

A Python CLI tool for migrating SMB and NFS share configuration to a live TrueNAS destination system. Designed for systems integration teams working in pre-production deployment environments.

What It Does

TrueMigration reads share configuration from a source and re-creates it on a destination TrueNAS system via its WebSocket API. Two source types are supported:

• TrueNAS debug archive — the .tgz produced by System → Save Debug in the TrueNAS UI
• CSV files — customer-supplied spreadsheets for migrating from non-TrueNAS sources

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)

Run with no arguments. The wizard will guide you through source selection, destination configuration, per-share filtering, a dry run preview, and final confirmation before making any changes.

python -m truenas_migrate

or

python deploy.py

Command Line Mode — Archive Source

# 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

Command Line Mode — CSV Source

Fill in the provided template files and pass them on the command line. You can supply one or both.

# Dry run from CSV files
python -m truenas_migrate \
    --smb-csv    smb_shares.csv \
    --nfs-csv    nfs_shares.csv \
    --dest       192.168.1.50 \
    --api-key    "1-xxxxxxxxxxxx" \
    --dry-run

# Live migration — SMB only
python -m truenas_migrate \
    --smb-csv    smb_shares.csv \
    --dest       192.168.1.50 \
    --api-key    "1-xxxxxxxxxxxx"

CSV Templates

Copy and fill in the templates included in this repository:

File	Purpose
smb_shares_template.csv	One row per SMB share
nfs_shares_template.csv	One row per NFS export

Each template includes a header row, annotated comment rows explaining valid values for each column, and one example data row to replace. Lines beginning with # are ignored by the parser.

SMB columns: name (required), path (required), comment, purpose, ro, browsable, guestok, abe, hostsallow, hostsdeny, timemachine, enabled

NFS columns: path (required), comment, ro, maproot_user, maproot_group, mapall_user, mapall_group, security, hosts, networks, enabled

Boolean columns accept true / false. List columns (hostsallow, hostsdeny, security, hosts, networks) accept space-separated values.

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
smb_shares_template.csv      # SMB CSV template for customers
nfs_shares_template.csv      # NFS CSV template for customers
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
    csv_source.py            # CSV parser for non-TrueNAS sources
    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.