Unified Security Stack Migration Tool — User Guide

Follow this guide to migrate a Unified Security Stack V1.7.21 installation to V1.7.22.

Before you start

You need:

• A working Unified Security Stack V1.7.21 installation

• A Linux server (Ubuntu, Debian, or similar)

• sudo** / root access** on that server

• Internet access (the tool downloads the migration agent from Google Cloud Storage)

You should also know:

• Whether you are upgrading on the same server (in-place) or moving to a new server (two servers)

• The IP and SSH credentials of your V1.7.21 server (only required if you run the tool from a separate workstation)

Installation

1. Download and make it executable:

sudo curl -L -o synoti_migration_tool
https://synoti.com/downloads/synoti_migration_tool

sudo chmod +x synoti_migration_tool

./synoti_migration_tool --help

A list of commands should appear. If it does, the binary is operational.

Recommended workflow

Most users only need two commands, in this exact order:

# Step 1: Stage the migration agent on every Unified Security Stack agent.
sudo ./synoti_migration_tool prepare-agents

# Step 2: Upgrade the backend itself.
sudo ./synoti_migration_tool upgrade

Run prepare-agents** first**, then upgrade. The upgrade command checks that
prepare-agents already executed and otherwise refuses to launch. This is by design:
it keeps agents from being orphaned in V1.7.21 once the backend moves to V1.7.22.

Commands

prepare-agents — Stage the migration agent

Before upgrading the backend, every Unified Security Stack agent must receive the
migrate_agent binary. This command handles that and retains its
progress, so you may halt it (Ctrl+C) and pick up later without losing work.

How to run it

On the V1.7.21 server itself (no config file needed):

sudo ./synoti_migration_tool prepare-agents

From a separate workstation, with a config file:

sudo ./synoti_migration_tool prepare-agents --config config.yaml

Flags

What you will see

The command opens a loop that:

• Polls the AgentManager every 60 seconds

• Detects new agents that came online and deploys to them

• Retries failed agents with a backoff (30 s, 1 m, 2 m, 4 m, 8 m, then capped)

• Marks agents as gone if they disappear from the AgentManager for several cycles

• Outputs one progress line for each cycle, for example.

  Progress: 47 deployed | 3 pending | 2 offline | 0 failed | 0 skipped | 0 gone | total 52

The loop ends in one of three ways:

1. Every agent reaches a terminal state (deployed, skipped, or gone).

2. You press Ctrl+C and accept marking the remaining agents as skipped.

3. The AgentManager stays unreachable for too long (the command stops with a clear error).

Interrupting the loop

If you do not want to wait for offline agents to come back online, press
Ctrl+C. The tool will:

• Stop the loop

• Show how many agents are still pending / offline / failed

• Ask whether to mark them all as skipped

If you accept, those agents are recorded as skipped. Skipped agents will
need the migration agent to be installed by hand after the upgrade. If you say no,
state is preserved and you can run prepare-agents again later to continue.

Resuming

Execute that command again from the same directory. The SQLite state file
(agents-migration.db) keeps track of which agents are already done — they
will not be redeployed.

Important: Run the command from the same directory every time, so it
finds the same agents-migration.db.

upgrade — In-place V1.7.21 → V1.7.22 upgrade

This command performs an upgrade of the backend on the same server. It is destructive:
V1.7.21 is taken out and V1.7.22 is put in its place. Automatic rollback is not available.

How to run it

On the V1.7.21 server itself (recommended, no config file needed):

sudo ./synoti_migration_tool upgrade

From a separate workstation:

sudo ./synoti_migration_tool upgrade --config config.yaml

Flags

What it does

1. Confirms the destructive operation with you (you must type yes)

2. Checks that agents-migration.db exists (proof that prepare-agents ran)

3. Opens the database port

4. Exports all V1.7.21 configuration data to a backup file

5. Removes the V1.7.21 installation

6. Downloads and installs Unified Security Stack V1.7.22

7. Imports the data back into V1.7.22

8. Closes the database port

About --skip-agent-check

upgrade refuses to run if it can't find agents-migration.db in the current
directory. This safeguard keeps you from forgetting to prepare your agents.

If you have a legitimate reason to skip it (test environment, no agents, agents
deployed by other means), pass --skip-agent-check. Any agent that did not
get the migration agent will stay on V1.7.21 and lose connection after the upgrade.

migrate — Move V1.7.21 to a new V1.7.22 server

Use this when you want to move from one server to a different one (for example,
new hardware). The source V1.7.21 stays as is until the migration completes successfully.

How to run it

sudo ./synoti_migration_tool migrate --config config.yaml

Flags

The config file must define both source (V1.7.21) and destination (V1.7.22). See
Configuration file below.

What it does

1. Connects to the source V1.7.21 server over SSH

2. Exports all V1.7.21 data into a YAML file

3. Connects to the destination V1.7.22 server over SSH

4. Imports the data into V1.7.22

5. Synchronizes the security key between both servers

6. Asks whether to delete the temporary data file

export — Save V1.7.21 data to a file

Writes V1.7.21 data to a YAML file you can retain for later. Goes with import.

sudo ./synoti_migration_tool export --config config.yaml
sudo ./synoti_migration_tool export --config config.yaml --output my-backup.yml

import — Load a saved file into V1.7.22

Reads a YAML file produced by export and saves its content to a V1.7.22 server.

sudo ./synoti_migration_tool import --config config.yaml --input my-backup.yml

Configuration file

The configuration file uses YAML. Its structure varies by command:

• For upgrade when run locally on the V1.7.21 server: no file is required.

• For upgrade / prepare-agents / export running remotely: only source is required.

• For migrate / import: destination is required (and source for migrate).

Minimal example for remote operations

source:
  host: "192.168.1.100"          # V1.7.21 server IP or hostname
  ssh_user: "synoti"           # SSH username
  ssh_password: "your-ssh-pass"  # SSH password
  # ssh_private_key: "/home/me/.ssh/id_rsa"   # Alternative to ssh_password

Minimal example for migrate

source:
  host: "192.168.1.100"
  ssh_user: "synoti"
  ssh_password: "ssh-pass-source"

destination:
  host: "192.168.1.200"
  ssh_user: "synoti"
  ssh_password: "ssh-pass-destination"

All available fields

source:
  host: "192.168.1.100"      # Required for remote operations
  port: 5432                 # PostgreSQL port (default 5432)
  user: "postgres"           # PostgreSQL user (default postgres)
  password: ""               # Auto-detected from compose.yml if empty
  sslmode: "disable"         # PostgreSQL SSL mode (default disable)
  ssh_user: "synoti"       # SSH user (required for remote)
  ssh_password: ""           # SSH password
  ssh_private_key: ""        # Path to a private key file (alternative to ssh_password)
  ssh_port: 22               # SSH port (default 22)

destination:
  # Same fields as source. Used by migrate and import.

Tip: You usually only need host, ssh_user, and either ssh_password or
ssh_private_key. Everything else is detected automatically.

Common workflows

Workflow 1 — Local in-place upgrade (simplest)

You are working on the V1.7.21 server and want to perform an in-place upgrade to V1.7.22.

ssh [email protected]
sudo ./synoti_migration_tool prepare-agents
# wait until all agents are deployed (or Ctrl+C and accept skip)
sudo ./synoti_migration_tool upgrade

Workflow 2 — Remote in-place upgrade

You administer your V1.7.21 server from a separate machine.

cat > config.yaml <<EOF
source:
  host: "192.168.1.100"
  ssh_user: "synoti"
  ssh_password: "your-ssh-pass"
EOF

sudo ./synoti_migration_tool prepare-agents --config config.yaml
sudo ./synoti_migration_tool upgrade --config config.yaml

Workflow 3 — Move to a new server

You have a new V1.7.22 server and want to move V1.7.21 data over while leaving V1.7.21 untouched.

cat > config.yaml <<EOF
source:
  host: "192.168.1.100"
  ssh_user: "synoti"
  ssh_password: "v1.7.21-ssh-pass"

destination:
  host: "192.168.1.200"
  ssh_user: "synoti"
  ssh_password: "v1.7.22-ssh-pass"
EOF

sudo ./synoti_migration_tool prepare-agents --config config.yaml
sudo ./synoti_migration_tool migrate --config config.yaml

Workflow 4 — Export now, import later

When you want to back up V1.7.21 and import the data afterward (or to several V1.7.22 servers).

# Export
sudo ./synoti_migration_tool export --config config.yaml --output backup.yml

# (Move backup.yml wherever you need it, review it, etc.)

# Import on the V1.7.22 side
sudo ./synoti_migration_tool import --config config.yaml --input backup.yml

Troubleshooting

"permission denied" reading /root/synoti.yml or /root/compose.yml

You must run the tool with sudo. The configuration files reside under /root/
on Unified Security Stack V1.7.21, and only root has read access to them.

sudo ./synoti_migration_tool prepare-agents

"State database 'agents-migration.db' not found" on upgrade

You forgot to run prepare-agents before upgrade, or you are running
upgrade from another directory.

Either:

• Run prepare-agents first from the same directory, or

• Pass --skip-agent-check if you are confident in what you are doing.

"AgentManager unreachable after 5 consecutive failures"

The tool is unable to reach the AgentManager service on the V1.7.21 server. Verify that:

• The V1.7.21 server is up and docker service ls shows synoti_agentmanager running

• Port 9000 is reachable from where you are running the tool

• The internal key in /root/synoti.yml has not been modified by hand

"compose.yml not found"

The tool looks for compose.yml in these locations, in order:

• ~/compose.yml (the home directory of the user running the tool)

• /root/compose.yml

• /home/synoti/compose.yml

If your compose.yml lives elsewhere, copy or symlink it into one of those
paths, or start the tool from a directory where it is present.

"failed to connect via SSH"

Check that:

• The SSH credentials in config.yaml are correct

• SSH (port 22 by default) is reachable from your machine

• You can connect manually: ssh synoti@<host>

• If you use ssh_private_key, the file path is correct and the key is unencrypted

Loop ran for hours but several agents stay offline

That is expected if those agents are physically off, on a laptop that's closed,
or located behind a network that cannot be reached. Two options are available to you:

• Keep prepare-agents running and wait for them to come back

• Press Ctrl+C, accept marking them as skipped, run upgrade, and install
  the migration agent on those machines manually later

The import step fails on a specific table

The tool uses ON CONFLICT DO UPDATE, so re-running the import is safe — it
will not duplicate data. Resolve the root issue (for instance, a constraint in
V1.7.22) and run import again.

Files the tool creates

Getting help

• Run any command with --help to see all its options.

• Contact support if you hit a real bug.