From ed12f0454937a42c787dbf48fb141798ddd09f9d Mon Sep 17 00:00:00 2001 From: scott Date: Thu, 5 Mar 2026 11:28:39 -0500 Subject: [PATCH] Update README to reflect CSV import support Document the new --smb-csv / --nfs-csv CLI flags, CSV template files, column reference, and updated project structure. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 59 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8a96cef..d258021 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # 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. +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 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. +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 @@ -22,19 +25,19 @@ TrueMigration reads configuration data out of a TrueNAS debug archive (the `.tgz ### 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. - -```bash -python deploy.py -``` - -or +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. ```bash python -m truenas_migrate ``` -### Command Line Mode +or + +```bash +python deploy.py +``` + +### Command Line Mode — Archive Source ```bash # Inspect the archive before doing anything @@ -61,6 +64,43 @@ python -m truenas_migrate \ --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. + +```bash +# 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**. @@ -78,22 +118,25 @@ 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 | +| 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