Backup e ripristino (nextxch Protect): esportazione probatoria, configurazione, dati, ripristino e cambio di provider

# 1. Admin > Backup & Recovery > Configuration: set up the backup key
#    (passphrase of 12+ characters or recovery key, keep it safe outside the server)
# 2. Schedules & targets: add a target (directory, SMB share \\nas\backup\nextxch or S3) and "Test"
# 3. Back up the configuration (every tier) and take it along as a file:
nextxch-cli config backup --label "before migration" -o nextxch-config.zip

# 4. Data backup (Business): full first, then incremental by schedule
nextxch-cli backup run --target nas --full
nextxch-cli backup list --target nas

# 5. Verify, with the passphrase including decryption of the sample
export NEXTXCH_BACKUP_PASSPHRASE='...'
nextxch-cli backup verify --target nas --passphrase-env NEXTXCH_BACKUP_PASSPHRASE --limit 200

nextxch-evidence-20261111-0930-1a2b3c4d.zip
  messages/000001-<archiveId>.eml     original message, byte for byte
  messages/000002-<archiveId>.eml
  SHA256SUMS.txt                      verifiable with sha256sum -c
  manifest.json                       format nextxch-evidence-export/1, scope (incl. caseReference), items[]
  manifest.json.sig                   Ed25519: algorithm, keyId, publicKey, signedSha256, signature
  README.txt

# Start an export (202, status under GET /api/compliance/exports/{id}):
curl -X POST https://mail.company.com/api/compliance/exports -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"mailbox","account":"anna@company.com","sinceUtc":"2026-01-01T00:00:00Z","caseReference":"Case 2026-0815"}'

# Verify offline, without access to the server (exit code 0 valid, 1 invalid/tampered, 2 usage error):
curl -s https://mail.company.com/api/compliance/exports/public-key > nextxch-evidence-key.json
nextxch-cli export verify nextxch-evidence-20261111-0930-1a2b3c4d.zip --public-key <publicKey from the file>
unzip -d export nextxch-evidence-20261111-0930-1a2b3c4d.zip && cd export && sha256sum -c SHA256SUMS.txt

nextxch-cli config list                                   # versions (reason: manual, pre-update, after-change, pre-restore, import)
nextxch-cli config diff 20261101T020000Z-a1b2c3 current             # difference between two versions or to the current state
nextxch-cli config backup --label "before update" --passphrase-env BACKUP_PW -o nextxch-config.zip
nextxch-cli config import -f nextxch-config.zip           # take over a package of another server

# Partial restore: preview first, then apply
nextxch-cli config restore 20261101T020000Z-a1b2c3 --sections dkim,config:domains --domain company.com --dry-run
nextxch-cli config restore 20261101T020000Z-a1b2c3 --sections dkim,config:domains --domain company.com --yes

# REST: POST /api/v1/config/backups/{id}/restore
# {"sections":["dkim","config:domains"],"domain":"company.com","prune":false,"dryRun":true}

<target>/                                 directory, SMB share or s3://bucket/nextxch-backup/
  nextxch-backup.json                       target marker
  keys/backup-key-<keyId>.json              public key + sealed private key
  keys/dk-<dataKeyId>.json                  data key of one run (ECDH wrapped)
  blobs/ab/cd/<sha256>.nxb                  one mail or file content, immutable
  versions/20261111T023000Z-a1b2c3/
    catalog.json  catalog.json.sig          catalog (written last = version complete) + signature
    blobs.ndjson.gz                         blob index of the version
    db/<table>.ndjson.gz.nxb                database snapshot, one file per table
    files/<path>.nxb                        state files of the data directory
    archive-manifest.json.gz.nxb            retention, legal hold, integrity chain

# Settings via REST (PUT /api/admin/protect/backups/settings):
{"verifyEveryHours":24,"verifySampleSize":50,"alertOnFailure":true,"uploadParallelism":4}

# Back up a domain or single mailboxes:
nextxch-cli backup run --target s3-fsn1 --scope domains:company.com,company.at
nextxch-cli backup run --target s3-fsn1 --scope mailboxes:anna@company.com --no-wait

nextxch-cli restore points  --account anna@company.com --source backup
nextxch-cli restore browse  --account anna@company.com --source backup --point latest --folder INBOX --filter "invoice"
nextxch-cli restore preview --account anna@company.com --source archive --as-of 2026-10-31T23:59:59Z --folder "Projects/Plant"
nextxch-cli restore start   --account anna@company.com --source archive --as-of 2026-10-31T23:59:59Z \
  --folder "Projects/Plant" --target restored --label "Plant (restored)"

# Whole mailbox into a successor mailbox:
nextxch-cli restore start --account ben@company.com --source backup --point day:2026-11-01 \
  --target account --target-account successor@company.com --passphrase-env NEXTXCH_BACKUP_PASSPHRASE
nextxch-cli restore jobs --account ben@company.com

# REST: /api/compliance/restore (sources, points, browse, preview, jobs, policy)
# Webmail: GET /api/mail/self-restore, POST /api/mail/self-restore {"ids":[...]}

# Headless via CLI (same API /api/setup):
export NEXTXCH_SETUP_TOKEN="$(cat /var/lib/nextxch/first-run/setup-token.txt)"
export NEXTXCH_BACKUP_PASSPHRASE='...'
nextxch-cli setup restore --config nextxch-config.zip --data s3://dr-bucket/nextxch/ --prune --dry-run
nextxch-cli setup restore --config nextxch-config.zip --data s3://dr-bucket/nextxch/ --prune --yes

# Unattended on first start (Docker Compose, Kubernetes, MSI):
environment:
  NEXTXCH_RESTORE_FROM: s3://dr-bucket/nextxch/          # .zip, directory, s3://, https:// or config-backup:<id>
  NEXTXCH_RESTORE_PASSPHRASE: ${BACKUP_PASSPHRASE}       # without: configuration without secrets
  NEXTXCH_RESTORE_DATA_FROM: s3://dr-bucket/nextxch/     # optional, location of the data backup
  NEXTXCH_RESTORE_PRUNE: "true"                          # remove bootstrap objects
  NEXTXCH_RESTORE_WITH_CREDENTIALS: "true"               # passwords, API keys, licence (default true)
  NEXTXCH_RESTORE_S3_ENDPOINT: https://fsn1.your-objectstorage.com
  NEXTXCH_RESTORE_S3_ACCESS_KEY: ${S3_KEY}
  NEXTXCH_RESTORE_S3_SECRET_KEY: ${S3_SECRET}
# Result: {DataDirectory}/pipeline-restore/first-start.json ("ok": true = variable is ignored afterwards)
# Helm: restore.from, restore.scope, restore.mapping, restore.passphrase, restore.s3.* (replicaCount: 1)

# mapping.yaml
apiVersion: nextxch/v1
kind: RestoreMapping
hostnames:
  mail.old-provider.example: mail.company.com
ips:
  203.0.113.10: 198.51.100.20
paths:
  "C:\\Data\\NextxchData": /var/lib/nextxch
certificates:
  mode: acme                      # backup | acme | files
  acme: {contactEmail: hostmaster@company.com}
database:
  provider: Postgres              # must match the new host (Storage__Provider)
  connectionStringEnv: NEXTXCH_PG_CONNECTION
storage:
  blobBackend: S3
  s3: {endpoint: https://fsn1.your-objectstorage.com, bucket: nextxch-mail}

# Plan (dry run, shows every replacement), then restore with checks:
nextxch-cli deploy --restore ./nextxch-config.zip --scope config --map mapping.yaml --dry-run
nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --map mapping.yaml --test-mail mailpit --dns-instructions --yes

# REST: POST /api/v1/deploy/restore (dryRun defaults to true)
# {"source":"s3://dr-bucket/nextxch/","scope":"all","mapping":"...","dryRun":false,"testMail":"mailpit","hashSample":20}
# Local package: POST /api/v1/deploy/restore/upload (application/zip) -> source "upload:<sha256>"
# Runs: GET /api/v1/deploy/restore/runs

deploy/ci/github-actions/nextxch-restore.yml        plan on a throwaway instance, container with restore on first start, checks, DNS step
deploy/ci/github-actions/nextxch-dr-probe.yml       nightly DR probe with RTO/RPO report
deploy/ci/gitlab/.gitlab-ci.yml                     restore (RESTORE_SOURCE, RESTORE_SCOPE, PLAN_ONLY ...) + DR probe (NEXTXCH_PIPELINE=dr-probe)
deploy/ci/azure-devops/azure-pipelines.yml          restore with parameters, deployment job on environment production
deploy/ci/azure-devops/azure-pipelines-dr-probe.yml nightly DR probe, report in the run summary
deploy/ci/ansible/playbook-restore.yml              role nextxch_restore: container (Linux) or MSI (Windows)
deploy/ci/mapping.example.yaml, mapping.schema.json example and JSON Schema of the mapping file

nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --scope all --yes                          # 1. full restore (baseline)
nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --live-sync --dry-run                      # remaining delta, changes nothing
nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --live-sync --interval 5m --until-cutover  # 2. follow the old server
nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --cutover                                  # 3. instructions for the freeze
# old server: block ports, then  nextxch-cli backup run --full
nextxch-cli deploy --restore s3://dr-bucket/nextxch/ --cutover --source-frozen                  # 4. last backup, last run