TrueMigration/README.md

# 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.

```bash
python -m truenas_migrate
```

or

```bash
python deploy.py
```

### Command Line Mode — Archive Source

```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
```

### 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:** `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.