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