[PATCH] doc: Add mock of migration source and target

[Stefano Brivio <sbrivio@redhat.com>]

These test programs show the migration of a TCP connection using the
passt-repair helper.

Signed-off-by: Stefano Brivio <sbrivio@redhat.com>
---
Note: I'm merging this right now, but posting anyway to ease review.

 doc/migration/.gitignore |   2 +
 doc/migration/Makefile   |  20 ++++++++
 doc/migration/README     |  51 ++++++++++++++++++++
 doc/migration/source.c   |  92 +++++++++++++++++++++++++++++++++++
 doc/migration/target.c   | 102 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 267 insertions(+)
 create mode 100644 doc/migration/.gitignore
 create mode 100644 doc/migration/Makefile
 create mode 100644 doc/migration/README
 create mode 100644 doc/migration/source.c
 create mode 100644 doc/migration/target.c

diff --git a/doc/migration/.gitignore b/doc/migration/.gitignore
new file mode 100644
index 0000000..59cb765
--- /dev/null
+++ b/doc/migration/.gitignore
@@ -0,0 +1,2 @@
+/source
+/target
diff --git a/doc/migration/Makefile b/doc/migration/Makefile
new file mode 100644
index 0000000..04f6891
--- /dev/null
+++ b/doc/migration/Makefile
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# PASST - Plug A Simple Socket Transport
+#  for qemu/UNIX domain socket mode
+#
+# PASTA - Pack A Subtle Tap Abstraction
+#  for network namespace/tap device mode
+#
+# Copyright (c) 2025 Red Hat GmbH
+# Author: Stefano Brivio <sbrivio@redhat.com>
+
+TARGETS = source target
+CFLAGS = -Wall -Wextra -pedantic
+
+all: $(TARGETS)
+
+$(TARGETS): %: %.c
+
+clean:
+	rm -f $(TARGETS)
diff --git a/doc/migration/README b/doc/migration/README
new file mode 100644
index 0000000..375603b
--- /dev/null
+++ b/doc/migration/README
@@ -0,0 +1,51 @@
+<!---
+SPDX-License-Identifier: GPL-2.0-or-later
+Copyright (c) 2025 Red Hat GmbH
+Author: Stefano Brivio <sbrivio@redhat.com>
+-->
+
+Migration
+=========
+
+These test programs show a migration of a TCP connection from one process to
+another using the TCP_REPAIR socket option.
+
+The two processes are a mock of the matching implementation in passt(1), and run
+unprivileged, so they rely on the passt-repair helper to connect to them and set
+or clear TCP_REPAIR on the connection socket, transferred to the helper using
+SCM_RIGHTS.
+
+The passt-repair helper needs to have the CAP_NET_ADMIN capability, or run as
+root.
+
+Example of usage
+----------------
+
+* Start the test server
+
+        $ nc -l 9999
+
+* Start the source side of the TCP client (mock of the source instance of passt)
+
+        $ ./source 127.0.0.1 9999 9998 /tmp/repair.sock
+
+* The client sends a test string, and waits for a connection from passt-repair
+
+        # passt-repair /tmp/repair.sock
+
+* The socket is now in repair mode, and `source` dumps sequences, then exits
+
+        sending sequence: 3244673313
+        receiving sequence: 2250449386
+
+* Continue the connection on the target side, restarting from those sequences
+
+        $ ./target 127.0.0.1 9999 9998 /tmp/repair.sock 3244673313 2250449386
+
+* The target side now waits for a connection from passt-repair
+
+        # passt-repair /tmp/repair.sock
+
+* The target side asks passt-repair to switch the socket to repair mode, sets up
+  the TCP sequences, then asks passt-repair to clear repair mode, and sends a
+  test string to the server
diff --git a/doc/migration/source.c b/doc/migration/source.c
new file mode 100644
index 0000000..d44ebf1
--- /dev/null
+++ b/doc/migration/source.c
@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/* PASST - Plug A Simple Socket Transport
+ *  for qemu/UNIX domain socket mode
+ *
+ * PASTA - Pack A Subtle Tap Abstraction
+ *  for network namespace/tap device mode
+ *
+ * doc/migration/source.c - Mock of TCP migration source, use with passt-repair
+ *
+ * Copyright (c) 2025 Red Hat GmbH
+ * Author: Stefano Brivio <sbrivio@redhat.com>
+ */
+
+#include <arpa/inet.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <limits.h>
+#include <unistd.h>
+#include <netdb.h>
+#include <netinet/tcp.h>
+
+int main(int argc, char **argv)
+{
+	struct sockaddr_in a = { AF_INET, htons(atoi(argv[3])), { 0 }, { 0 } };
+	struct addrinfo hints = { 0, AF_UNSPEC, SOCK_STREAM, 0, 0,
+				  NULL, NULL, NULL };
+	struct sockaddr_un a_helper = { AF_UNIX, { 0 } };
+	int seq, s, s_helper;
+	int8_t cmd;
+	struct iovec iov = { &cmd, sizeof(cmd) };
+	char buf[CMSG_SPACE(sizeof(int))];
+	struct msghdr msg = { NULL, 0, &iov, 1, buf, sizeof(buf), 0 };
+	struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg);
+	socklen_t seqlen = sizeof(int);
+	struct addrinfo *r;
+
+	(void)argc;
+
+	if (argc != 5) {
+		fprintf(stderr, "%s DST_ADDR DST_PORT SRC_PORT HELPER_PATH\n",
+			argv[0]);
+		return -1;
+	}
+
+	strcpy(a_helper.sun_path, argv[4]);
+	getaddrinfo(argv[1], argv[2], &hints, &r);
+
+	/* Connect socket to server and send some data */
+	s = socket(r->ai_family, SOCK_STREAM, IPPROTO_TCP);
+	setsockopt(s, SOL_SOCKET, SO_REUSEADDR, &((int){ 1 }), sizeof(int));
+	bind(s, (struct sockaddr *)&a, sizeof(a));
+	connect(s, r->ai_addr, r->ai_addrlen);
+	send(s, "before migration\n", sizeof("before migration\n"), 0);
+
+	/* Wait for helper */
+	s_helper = socket(AF_UNIX, SOCK_STREAM, 0);
+	unlink(a_helper.sun_path);
+	bind(s_helper, (struct sockaddr *)&a_helper, sizeof(a_helper));
+	listen(s_helper, 1);
+	s_helper = accept(s_helper, NULL, NULL);
+
+	/* Set up message for helper, with socket */
+	cmsg->cmsg_level = SOL_SOCKET;
+	cmsg->cmsg_type = SCM_RIGHTS;
+	cmsg->cmsg_len = CMSG_LEN(sizeof(int));
+	memcpy(CMSG_DATA(cmsg), &s, sizeof(s));
+
+	/* Send command to helper: turn repair mode on, wait for reply */
+	cmd = TCP_REPAIR_ON;
+	sendmsg(s_helper, &msg, 0);
+	recv(s_helper, &((int8_t){ 0 }), 1, 0);
+
+	/* Terminate helper */
+	close(s_helper);
+
+	/* Get sending sequence */
+	seq = TCP_SEND_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	getsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, &seqlen);
+	fprintf(stdout, "%u ", seq);
+
+	/* Get receiving sequence */
+	seq = TCP_RECV_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	getsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, &seqlen);
+	fprintf(stdout, "%u\n", seq);
+}
diff --git a/doc/migration/target.c b/doc/migration/target.c
new file mode 100644
index 0000000..f7d3108
--- /dev/null
+++ b/doc/migration/target.c
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/* PASST - Plug A Simple Socket Transport
+ *  for qemu/UNIX domain socket mode
+ *
+ * PASTA - Pack A Subtle Tap Abstraction
+ *  for network namespace/tap device mode
+ *
+ * doc/migration/target.c - Mock of TCP migration target, use with passt-repair
+ *
+ * Copyright (c) 2025 Red Hat GmbH
+ * Author: Stefano Brivio <sbrivio@redhat.com>
+ */
+
+#include <arpa/inet.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <limits.h>
+#include <unistd.h>
+#include <netdb.h>
+#include <netinet/tcp.h>
+
+int main(int argc, char **argv)
+{
+	struct sockaddr_in a = { AF_INET, htons(atoi(argv[3])), { 0 }, { 0 } };
+	struct addrinfo hints = { 0, AF_UNSPEC, SOCK_STREAM, 0, 0,
+				  NULL, NULL, NULL };
+	struct sockaddr_un a_helper = { AF_UNIX, { 0 } };
+	int s, s_helper, seq;
+	int8_t cmd;
+	struct iovec iov = { &cmd, sizeof(cmd) };
+	char buf[CMSG_SPACE(sizeof(int))];
+	struct msghdr msg = { NULL, 0, &iov, 1, buf, sizeof(buf), 0 };
+	struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg);
+	struct addrinfo *r;
+
+	(void)argc;
+
+	strcpy(a_helper.sun_path, argv[4]);
+	getaddrinfo(argv[1], argv[2], &hints, &r);
+
+	if (argc != 7) {
+		fprintf(stderr,
+			"%s DST_ADDR DST_PORT SRC_PORT HELPER_PATH SSEQ RSEQ\n",
+			argv[0]);
+		return -1;
+	}
+
+	/* Prepare socket, bind to source port */
+	s = socket(r->ai_family, SOCK_STREAM, IPPROTO_TCP);
+	setsockopt(s, SOL_SOCKET, SO_REUSEADDR, &((int){ 1 }), sizeof(int));
+	bind(s, (struct sockaddr *)&a, sizeof(a));
+
+	/* Wait for helper */
+	s_helper = socket(AF_UNIX, SOCK_STREAM, 0);
+	unlink(a_helper.sun_path);
+	bind(s_helper, (struct sockaddr *)&a_helper, sizeof(a_helper));
+	listen(s_helper, 1);
+	s_helper = accept(s_helper, NULL, NULL);
+
+	/* Set up message for helper, with socket */
+	cmsg->cmsg_level = SOL_SOCKET;
+	cmsg->cmsg_type = SCM_RIGHTS;
+	cmsg->cmsg_len = CMSG_LEN(sizeof(int));
+	memcpy(CMSG_DATA(cmsg), &s, sizeof(s));
+
+	/* Send command to helper: turn repair mode on, wait for reply */
+	cmd = TCP_REPAIR_ON;
+	sendmsg(s_helper, &msg, 0);
+	recv(s_helper, &((int){ 0 }), 1, 0);
+
+	/* Set sending sequence */
+	seq = TCP_SEND_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	seq = atoi(argv[5]);
+	setsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, sizeof(seq));
+
+	/* Set receiving sequence */
+	seq = TCP_RECV_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	seq = atoi(argv[6]);
+	setsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, sizeof(seq));
+
+	/* Connect setting kernel state only, without actual SYN / handshake */
+	connect(s, r->ai_addr, r->ai_addrlen);
+
+	/* Send command to helper: turn repair mode off, wait for reply */
+	cmd = TCP_REPAIR_OFF;
+	sendmsg(s_helper, &msg, 0);
+
+	recv(s_helper, &((int8_t){ 0 }), 1, 0);
+
+	/* Terminate helper */
+	close(s_helper);
+
+	/* Send some more data */
+	send(s, "after migration\n", sizeof("after migration\n"), 0);
+}
-- 
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/* PASST - Plug A Simple Socket Transport
+ *  for qemu/UNIX domain socket mode
+ *
+ * PASTA - Pack A Subtle Tap Abstraction
+ *  for network namespace/tap device mode
+ *
+ * doc/migration/target.c - Mock of TCP migration target, use with passt-repair
+ *
+ * Copyright (c) 2025 Red Hat GmbH
+ * Author: Stefano Brivio <sbrivio@redhat.com>
+ */
+
+#include <arpa/inet.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <limits.h>
+#include <unistd.h>
+#include <netdb.h>
+#include <netinet/tcp.h>
+
+int main(int argc, char **argv)
+{
+	struct sockaddr_in a = { AF_INET, htons(atoi(argv[3])), { 0 }, { 0 } };
+	struct addrinfo hints = { 0, AF_UNSPEC, SOCK_STREAM, 0, 0,
+				  NULL, NULL, NULL };
+	struct sockaddr_un a_helper = { AF_UNIX, { 0 } };
+	int s, s_helper, seq;
+	int8_t cmd;
+	struct iovec iov = { &cmd, sizeof(cmd) };
+	char buf[CMSG_SPACE(sizeof(int))];
+	struct msghdr msg = { NULL, 0, &iov, 1, buf, sizeof(buf), 0 };
+	struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg);
+	struct addrinfo *r;
+
+	(void)argc;
+
+	strcpy(a_helper.sun_path, argv[4]);
+	getaddrinfo(argv[1], argv[2], &hints, &r);
+
+	if (argc != 7) {
+		fprintf(stderr,
+			"%s DST_ADDR DST_PORT SRC_PORT HELPER_PATH SSEQ RSEQ\n",
+			argv[0]);
+		return -1;
+	}
+
+	/* Prepare socket, bind to source port */
+	s = socket(r->ai_family, SOCK_STREAM, IPPROTO_TCP);
+	setsockopt(s, SOL_SOCKET, SO_REUSEADDR, &((int){ 1 }), sizeof(int));
+	bind(s, (struct sockaddr *)&a, sizeof(a));
+
+	/* Wait for helper */
+	s_helper = socket(AF_UNIX, SOCK_STREAM, 0);
+	unlink(a_helper.sun_path);
+	bind(s_helper, (struct sockaddr *)&a_helper, sizeof(a_helper));
+	listen(s_helper, 1);
+	s_helper = accept(s_helper, NULL, NULL);
+
+	/* Set up message for helper, with socket */
+	cmsg->cmsg_level = SOL_SOCKET;
+	cmsg->cmsg_type = SCM_RIGHTS;
+	cmsg->cmsg_len = CMSG_LEN(sizeof(int));
+	memcpy(CMSG_DATA(cmsg), &s, sizeof(s));
+
+	/* Send command to helper: turn repair mode on, wait for reply */
+	cmd = TCP_REPAIR_ON;
+	sendmsg(s_helper, &msg, 0);
+	recv(s_helper, &((int){ 0 }), 1, 0);
+
+	/* Set sending sequence */
+	seq = TCP_SEND_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	seq = atoi(argv[5]);
+	setsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, sizeof(seq));
+
+	/* Set receiving sequence */
+	seq = TCP_RECV_QUEUE;
+	setsockopt(s, SOL_TCP, TCP_REPAIR_QUEUE, &seq, sizeof(seq));
+	seq = atoi(argv[6]);
+	setsockopt(s, SOL_TCP, TCP_QUEUE_SEQ, &seq, sizeof(seq));
+
+	/* Connect setting kernel state only, without actual SYN / handshake */
+	connect(s, r->ai_addr, r->ai_addrlen);
+
+	/* Send command to helper: turn repair mode off, wait for reply */
+	cmd = TCP_REPAIR_OFF;
+	sendmsg(s_helper, &msg, 0);
+
+	recv(s_helper, &((int8_t){ 0 }), 1, 0);
+
+	/* Terminate helper */
+	close(s_helper);
+
+	/* Send some more data */
+	send(s, "after migration\n", sizeof("after migration\n"), 0);
+}
-- 
2.43.0