scott
1f527476e6
- Add truenas_migrate/csv_source.py: parses SMB and NFS share definitions from customer-supplied CSV files; returns same dict shape as parse_archive() so migrate.py is untouched - Add smb_shares_template.csv and nfs_shares_template.csv with annotated headers and example rows (# comment rows are skipped by the parser) - Update cli.py: interactive wizard gains a source-type step (archive vs CSV); run() resolves CSV source via --smb-csv / --nfs-csv args; --debug-tar is now optional; argparse validates mutual exclusion of archive and CSV flags Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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-sslto enable it. - The tool targets the TrueNAS 25.04+ WebSocket API endpoint (
wss://<host>/api/current). - Exit code
2is returned if any errors occurred during migration.