VPS Import & Export

Three Movement Models

Backup and restore remain separate. Backup is for recoverability; import, export and Fleet-to-Fleet migration are planned movement operations.

Import an External VPS into Fleet

one-click --vps import

What One-Click Does

1. Creates a temporary ocmig_* bootstrap identity and prints one root-run preparation block for the external source.
2. Uses that temporary sudo account to inspect the source before any replacement is built: OS release, architecture, hostname, CPU, RAM, total disk and used disk.
3. Requires a like-for-like supported Linux profile and enough destination storage. The import path currently expects an x86_64 source.
4. Builds the replacement through the normal Fleet --vps create path on the selected hypervisor, using the chosen NAT/public networking and the operator-supplied recovery password.
5. Reads the newly built VM's real oneclick SSH authorization, generates a temporary pull key on that replacement, and maps those credentials onto source oneclick.
6. Verifies replacement-to-source pull access and permanent Fleet-key access, then removes the temporary source bootstrap account before filesystem migration begins.
7. Runs an initial whole-system rsync while the source remains online.
8. Stops detected application/stateful services only for the final synchronization.
9. Stages /etc/passwd, /etc/shadow, /etc/group and /etc/gshadow, performs a final PAM sync, then swaps the account database during cutover and immediately reboots.
10. Waits for the replacement to return over the normal Fleet key after reboot.

What the Destination Keeps

Import is intentionally not a sector-for-sector clone. Infrastructure-specific files on the newly provisioned Fleet VM remain authoritative so the replacement can boot and stay attached to its new environment.

• Boot/kernel and live pseudo-filesystem state
• Destination filesystem mount identity
• Destination network configuration
• Destination SSH daemon configuration and host identity
• Machine identity
• Fleet and virtualisation control state
• Destination WireGuard/Fleet networking identity

The source application data, services, users, groups and oneclick home are otherwise migrated using numeric ownership. There is no UID/GID remapping layer.

Cutover and Split-brain Protection

The first pass is designed to reduce downtime. At final cutover, One-Click stops the detected stateful/application services, performs the final sync, stages the account database, synchronizes PAM, schedules the account-file swap and reboots the destination immediately. It deliberately does not test a fresh SSH login while the destination is in a half-migrated userspace.

If a transfer fails after application services were stopped, the worker attempts to restart them on the source. After a successful transfer, source application services remain stopped until the operator has validated the replacement.

Export a Fleet VPS to an External Replacement

one-click --vps export --name app1

Preparation

Prepare a fresh, like-for-like external Linux VPS and follow the one-time preparation block printed by One-Click. That creates a temporary sudo-capable ocmig_* account only for bootstrapping the external destination.

Transfer

1. The external replacement verifies temporary bootstrap access and ensures rsync is available.
2. The replacement pulls the existing Fleet VPS over SSH as source oneclick.
3. The first whole-system pass runs while the Fleet source remains live.
4. Application/stateful services are stopped for the final synchronization.
5. The source account database is staged and PAM is synchronized.
6. The external destination preserves its own boot, network, SSH and machine identity.
7. The staged source account database is swapped into place and the external replacement reboots immediately.
8. After reboot, One-Click verifies the migrated source oneclick account and then verifies the permanent Fleet controller key.

If the permanent key does not authenticate after export, the temporary export key is retained instead of removing the last known-good access path.

Source Retention

Import does not delete the external source. Export does not delete the original Fleet VPS. The original system is deliberately retained so the operator can validate the migrated machine before decommissioning the old one.

After successful export, the original Fleet VPS's application services remain stopped to avoid two copies of the same stateful workload serving simultaneously. Delete it only through the normal Fleet VPS deletion workflow after validation.

Recovery Paths

Migration State

Each external import/export run keeps machine-readable state below:

/etc/one-click/virtualization/migrations/<migration-id>/state.json

Failed runs retain their state so the operator has an exact record of the selected source, destination and migration phase.