Agent Server Migration

Agent Server Migration moves already-enrolled agents from one Athena server to another — for example when you stand up a replacement server, rename a server's URL, or split a fleet across a second server. You pick the agents, give the new server's URL, and the server sends each connected agent a migration instruction over the connection it already holds. There are two modes: Mint replaces an agent's home server in place, and Paste adds a second server alongside the first. Every migration is Admin-only and written to the audit log.

The two modes#

Every migration request carries a mode that decides where the destination token comes from and what the agent does with its on-disk server list:

Paste is the default, because migrating to a different server is the more common operational case; Mint serves the narrower same-server URL-change scenario. In Mint mode the server generates the token itself through the normal registration-token machinery, with a MaxUsages large enough for the batch and the TTL you choose. In Paste mode you first create a registration token on the destination server, then hand it to the migration on the source server.

The migration request#

A migration is started with POST api/agent-migration/start (Admin-only). The body names the target agents and the new URL, plus mode-specific fields:

# Paste mode: move two agents to a second server using a token minted there
POST api/agent-migration/start
{
  "agentIds": ["a1…", "b2…"],
  "newUrl": "https://athena-b:8444",
  "mode": 0,
  "token": "<token-minted-on-athena-b>",
  "newServerName": "secondary",
  "timeoutSeconds": 60
}

Validation rules#

The server enforces a set of cross-field rules before dispatching anything; a request that breaks any of them is rejected with 400 and an explanatory message, and no agent is contacted:

• agentIds must contain at least one agent, and newUrl must be present.
• Mint mode: token must be empty; validityHours is required and must be 1, 2, or 4; newServerName must be empty (Mint replaces in place).
• Paste mode: token is required and must be at least 16 characters; validityHours must be empty; newServerName is required, at most 50 characters, and must not contain path-invalid characters.

Starting a migration in the UI#

In the web console, agent migration lives under Settings → Agent → Migration. There you choose Mint or Paste, enter the new server URL, fill in the mode-specific fields (validity hours for Mint; the pasted token and new server name for Paste), set the timeout, and select the agents to migrate. After you start, the same panel shows the dispatch result and recent migration history, updating in real time as each agent reports progress.

What happens after dispatch#

The server processes the batch and then tracks each agent independently:

1. It validates the request, clamps the timeout to 10–300 seconds, and resolves the token — minting one in Mint mode, or using the token you pasted in Paste mode.
2. For each agent it writes a migration-history record (status Pending) and sends the agent a migration message — the migration ID, source server name, new URL, token, timeout, mode, and (for Paste) the new server name — over the agent's existing connection.
3. The agent attempts to connect and register at the new URL. In Mint mode it replaces its source server entry; in Paste mode it adds a new one. It reports progress back, which advances the history record's status.
4. Each dispatch is written to the audit log, whether it succeeded or failed.

The response summarises the batch: successCount, failedCount, a per-agent results map, and a migrationIds map linking each agent to its history record. An agent that is not currently connected cannot be reached, so its history row is marked Failed with "Agent not connected" and it is counted as a failure — reconnect the agent (or wait for it) and start the migration again.

Migration status & history#

Every migration creates a history record you can review per agent or fleet-wide. Each record tracks the agent and hostname, the source server name, the fromUrl → toUrl, who initiated it, timestamps, an error message on failure, and a status:

Read history with GET api/agent-migration/history, optionally filtered by agentId, with a limit (default 50). History reads are available to Operator or Admin; only the terminal statuses (Promoted, Failed) stamp a completion time.

Roles#

Callers without the required role receive 403; unauthenticated callers receive 401. See Roles & Permissions.

Auditing#

Migrating an agent's home server is treated as a high-risk action — it points the agent at a new control endpoint — so every dispatch is audited, successful or not. Each audit event records the agent and hostname, the source server name, the source and new URLs, who initiated it, and a token-source descriptor that lets a SIEM tell the two modes apart (minted server-side (TTL Nh) for Mint, or an operator-provided token … adds new ServerEntry '…' descriptor for Paste). See Audit & SIEM.

REST API#

PowerShell#

The Athena module wraps both endpoints:

# Mint mode: replace the URL for one agent in place, minting a 1-hour token
Start-AthenaAgentMigration -Mint -AgentId $agentId -NewUrl "https://athena-2:8444" -ValidityHours 1

# Paste mode: add a second server to every online agent using a token minted there
Get-AthenaAgent -Online | Start-AthenaAgentMigration -Paste -NewUrl "https://athena-b:8444" -Token $tokenFromB -NewServerName "secondary"

# Review what happened
Get-AthenaAgentMigrationHistory -Limit 20

See the PowerShell Module reference for full cmdlet details.