From c8cee779b000de8288987becd6957e9ee75e8493 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <philipp.schuster@cyberus-technology.de>
Date: Fri, 13 Mar 2026 23:23:58 +0100
Subject: [PATCH] docs: update live_migration.md

Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
On-behalf-of: SAP philipp.schuster@sap.com
---
 docs/live_migration.md | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/docs/live_migration.md b/docs/live_migration.md
index ac5bf93f7..ac842d317 100644
--- a/docs/live_migration.md
+++ b/docs/live_migration.md
@@ -3,8 +3,9 @@
 This document gives examples of how to use the live migration support
 in Cloud Hypervisor:
 
-1. local migration - migrating a VM from one Cloud Hypervisor instance to another on the same machine;
-1. remote migration - migrating a VM between two machines;
+1. **Local Migration**: Migrating a VM from one Cloud Hypervisor instance to another on the same machine; also called
+  UNIX socket migration.
+1. **Remote Migration** (TCP Migration): migrating a VM between two TCP/IP hosts.
 
 > :warning: These examples place sockets in /tmp. This is done for
 > simplicity and should not be done in production.
@@ -28,7 +29,8 @@ Launch the destination VM from the same directory (on the host machine):
 $ target/release/cloud-hypervisor --api-socket=/tmp/api2
 ```
 
-Get ready for receiving migration for the destination VM (on the host machine):
+Get ready for receiving migration for the destination VM (on the host
+machine):
 
 ```console
 $ target/release/ch-remote --api-socket=/tmp/api2 receive-migration unix:/tmp/sock
@@ -37,14 +39,16 @@ $ target/release/ch-remote --api-socket=/tmp/api2 receive-migration unix:/tmp/so
 Start to send migration for the source VM (on the host machine):
 
 ```console
-$ target/release/ch-remote --api-socket=/tmp/api1 send-migration --local unix:/tmp/sock
+$ target/release/ch-remote --api-socket=/tmp/api1 send-migration destination_url=unix:/tmp/sock,local=true
 ```
 
 When the above commands completed, the source VM should be successfully
 migrated to the destination VM. Now the destination VM is running while
 the source VM is terminated gracefully.
 
-## Remote Migration
+## Remote Migration (TCP Migration)
+
+_Hint: For developing purposes, same-host TCP migrations are also supported._
 
 In this example, we will migrate a VM from one machine (`src`) to
 another (`dst`) across the network. To keep it simple, we will use a
@@ -171,7 +175,13 @@ After a few seconds the VM should be up and you can interact with it.
 Initiate the Migration over TCP:
 
 ```console
-src $ ch-remote --api-socket=/tmp/api send-migration  tcp:{dst}:{port}
+src $ ch-remote --api-socket=/tmp/api send-migration destination_url=tcp:{dst}:{port}
+```
+
+With migration parameters:
+
+```console
+src $ ch-remote --api-socket=/tmp/api send-migration destination_url=tcp:{dst}:{port},downtime_ms=200,timeout_s=3600,timeout_strategy=cancel
 ```
 
 > Replace {dst}:{port} with the actual IP address and port of your destination host.
@@ -180,3 +190,20 @@ After completing the above commands, the source VM will be migrated to
 the destination host and continue running there. The source VM instance
 will terminate normally. All ongoing processes and connections within
 the VM should remain intact after the migration.
+
+#### Migration Parameters
+
+Cloud Hypervisor supports additional parameters to control the
+migration process. Via the API or `ch-remote`, you may specify:
+
+- `downtime_ms <milliseconds>`: \
+  The maximum downtime the migration aims for, in milliseconds.
+  Defaults to `300ms`.
+- `timeout_s <seconds>`: \
+  The timeout for the migration (maximum total duration), in seconds.
+  Defaults to `3600s` (one hour).
+- `timeout_strategy <strategy>` (`[cancel, ignore]`): \
+  The strategy to apply when the migration timeout is reached.
+  Cancel will abort the migration and keep the VM running on the source.
+  Ignore will proceed with the migration regardless of the downtime requirement.
+  Defaults to `cancel`.