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 <noreply@anthropic.com>
This commit is contained in:
75
README.md
75
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
|
||||
|
||||
Reference in New Issue
Block a user