From b9163bf4317cca827c17584080aac35ba0438ca1 Mon Sep 17 00:00:00 2001
From: Jinrong Liang <cloudliang@tencent.com>
Date: Mon, 2 Dec 2024 19:45:48 +0800
Subject: [PATCH] docs: Add documentation for cross-host TCP live migration

Updated the live migration documentation to include instructions for
performing cross-host live migrations over TCP connections.

Signed-off-by: Jinrong Liang <cloudliang@tencent.com>
---
 docs/live_migration.md | 75 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 11 deletions(-)

diff --git a/docs/live_migration.md b/docs/live_migration.md
index 7a4bee439..94c9afc23 100644
--- a/docs/live_migration.md
+++ b/docs/live_migration.md
@@ -1,7 +1,7 @@
 # Live Migration
 
-This document gives two examples of how to use the live migration
-support in Cloud Hypervisor:
+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;
@@ -50,14 +50,11 @@ 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
 minimal VM setup without storage.
 
-Because Cloud Hypervisor does not natively support migrating via TCP
-connections, we will tunnel traffic through `socat`.
-
 ### Preparation
 
 Make sure that `src` and `dst` can reach each other via the
 network. You should be able to ping each machine. Also each machine
-should have an open TCP port. For this example we assume port 6000.
+should have an open TCP port.
 
 You will need a kernel and initramfs for a minimal Linux system. For
 this example, we will use the Debian netboot image.
@@ -75,7 +72,11 @@ src $ curl $DEBIAN/initrd.gz > /var/images/initrd
 
 Repeat the above steps on the destination host.
 
-### Starting the Receiver VM
+### Unix Socket Migration
+
+If Unix socket is selected for migration, we can tunnel traffic through "socat".
+
+#### Starting the Receiver VM
 
 On the receiver side, we prepare an empty VM:
 
@@ -92,10 +93,10 @@ dst $ ch-remote --api-socket=/tmp/api receive-migration unix:/tmp/sock
 In yet another terminal, forward TCP connections to the Unix domain socket:
 
 ```console
-dst $ socat TCP-LISTEN:6000,reuseaddr UNIX-CLIENT:/tmp/sock
+dst $ socat TCP-LISTEN:{port},reuseaddr UNIX-CLIENT:/tmp/sock
 ```
 
-### Starting the Sender VM
+#### Starting the Sender VM
 
 Let's start the VM on the source machine:
 
@@ -111,14 +112,16 @@ src $ cloud-hypervisor \
 
 After a few seconds the VM should be up and you can interact with it.
 
-### Performing the Migration
+#### Performing the Migration
 
 First, we start `socat`:
 
 ```console
-src $ socat UNIX-LISTEN:/tmp/sock,reuseaddr TCP:dst:6000
+src $ socat UNIX-LISTEN:/tmp/sock,reuseaddr TCP:{dst}:{port}
 ```
 
+> Replace {dst}:{port} with the actual IP address and port of your destination host.
+
 Then we kick-off the migration itself:
 
 ```console
@@ -127,3 +130,53 @@ src $ ch-remote --api-socket=/tmp/api send-migration unix:/tmp/sock
 
 When the above commands completed, the VM should be successfully
 migrated to the destination machine without interrupting the workload.
+
+### TCP Socket Migration
+
+If TCP socket is selected for migration, we need to consider migrating
+in a trusted network.
+
+#### Starting the Receiver VM
+
+On the receiver side, we prepare an empty VM:
+
+```console
+dst $ cloud-hypervisor --api-socket /tmp/api
+```
+
+In a different terminal, prepare to receive the migration:
+
+```console
+dst $ ch-remote --api-socket=/tmp/api receive-migration tcp:0.0.0.0:{port}
+```
+
+#### Starting the Sender VM
+
+Let's start the VM on the source machine:
+
+```console
+src $ cloud-hypervisor \
+        --serial tty --console off \
+        --cpus boot=2 --memory size=4G \
+        --kernel /var/images/linux \
+        --initramfs /var/images/initrd \
+        --cmdline "console=ttyS0" \
+        --api-socket /tmp/api
+```
+
+After a few seconds the VM should be up and you can interact with it.
+
+#### Performing the Migration
+
+Initiate the Migration over TCP:
+
+```console
+src $ ch-remote --api-socket=/tmp/api send-migration  tcp:{dst}:{port}
+```
+
+> Replace {dst}:{port} with the actual IP address and port of your destination host.
+
+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.