Merge devel: add README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-04 22:18:11 -05:00
parent 3f98fa4843 880fa42f5b
commit 93b6cd136c
1 changed files with 106 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,106 @@
+# 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.
+
+```bash
+python deploy.py
+```
+
+or
+
+```bash
+python -m truenas_migrate
+```
+
+### Command Line Mode
+
+```bash
+# 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-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.