Files

scott 40daf20809 Redesign CSV templates with human-readable column headers

- Replace API field names (guestok, abe, ro, maproot_user, etc.) with
  plain-English headers (Guest Access, Access-Based Enumeration, Read Only,
  Map Root User, etc.) for customer clarity
- Drop comment rows that rendered poorly in spreadsheet apps
- Use two realistic example rows instead to teach by example
- Update csv_source.py to map friendly header names to API field names
  before validation and coercion (raw API names still accepted)
- Update README column reference to match new header names

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-05 11:32:25 -05:00

5.5 KiB

Raw Blame History

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

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: Share Name (required), Path (required), Description, Purpose, Read Only, Browsable, Guest Access, Access-Based Enumeration, Hosts Allow, Hosts Deny, Time Machine, Enabled

NFS columns: Path (required), Description, Read Only, Map Root User, Map Root Group, Map All User, Map All Group, Security, Allowed Hosts, Allowed Networks, Enabled

Boolean columns (Read Only, Browsable, etc.) accept true or false. List columns (Hosts Allow, Hosts Deny, Security, Allowed Hosts, Allowed Networks) accept space-separated values.

Valid Purpose values: NO_PRESET, DEFAULT_SHARE, ENHANCED_TIMEMACHINE, MULTI_PROTOCOL_NFS, PRIVATE_DATASETS, WORM_DROPBOX

Valid Security values: SYS, KRB5, KRB5I, KRB5P

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.

5.5 KiB Raw Blame History