From 3c05c44acb6e4816aa6bc82d2b5e8acab585840e Mon Sep 17 00:00:00 2001
From: Dominik Heidler <dheidler@suse.de>
Date: Tue, 29 Oct 2024 11:08:50 +0100
Subject: [PATCH] Document wireguard reverse tunnel

Ticket: https://progress.opensuse.org/issues/168880
---
 docs/Installing.asciidoc | 85 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/docs/Installing.asciidoc b/docs/Installing.asciidoc
index 076d8bd265d..168d94f24be 100644
--- a/docs/Installing.asciidoc
+++ b/docs/Installing.asciidoc
@@ -1552,6 +1552,91 @@ SSH and salt, e.g. to be used with
 https://github.com/os-autoinst/salt-states-openqa/, can be found in
 https://github.com/os-autoinst/openQA/blob/master/contrib/ay-openqa-worker.xml
 
+== Special network conditions
+There might be certain situations where the openQA workers cannot reach the openQA webui directly.
+In this case a reverse connection via SSH or wireguared might be useful
+allowing the openQA webui to connect to a worker opening a backchannel.
+
+=== Wireguared
+For wireguard using wg-quick is recommended.
+
+To generate a private (first line) and a public (second line) key for each peer use this command:
+
+[source,sh]
+--------------------------------------------------------------------------------
+wg genkey | tee /dev/stderr | wg pubkey
+--------------------------------------------------------------------------------
+
+Create a config in `/etc/wireguard/openqa.conf` on the webui host:
+
+[source,ini]
+--------------------------------------------------------------------------------
+[Interface]
+Address = fd0a::1/128
+PrivateKey = +++ INSERT PRIVATE KEY of webui +++
+
+[Peer]
+# Name = worker1
+PublicKey = +++ INSERT PUBLIC KEY OF worker1 +++
+Endpoint = worker1:51820
+AllowedIPs = fd0a::2/128
+PersistentKeepalive = 60
+
+[Peer]
+# Name = worker2
+PublicKey = +++ INSERT PUBLIC KEY OF worker2 +++
+Endpoint = worker2:51820
+AllowedIPs = fd0a::3/128
+PersistentKeepalive = 60
+--------------------------------------------------------------------------------
+
+Create a config in `/etc/wireguard/openqa.conf` on the worker1 host (and analog on other worker hosts):
+
+[source,ini]
+--------------------------------------------------------------------------------
+[Interface]
+Address = fd0a::2/128
+PrivateKey = +++ INSERT PRIVATE KEY HERE +++
+ListenPort = 51820
+
+[Peer]
+# Name = webui
+PublicKey = +++ INSERT PUBLIC KEY OF webui +++
+AllowedIPs = fd0a::1/128
+--------------------------------------------------------------------------------
+
+On all peers run now:
+
+[source,sh]
+--------------------------------------------------------------------------------
+zypper -n in wireguard-tools
+systemctl enable --now wg-quick@openqa
+--------------------------------------------------------------------------------
+
+Then update `/etc/openqa/workers.ini` on the workers like this:
+
+[source,ini]
+--------------------------------------------------------------------------------
+[global]
+HOST=[fd0a::1]
+
+[[fd0a::1]]
+TESTPOOLSERVER = rsync://[fd0a::1]/tests
+--------------------------------------------------------------------------------
+
+Same for the `/etc/openqa/client.conf`
+
+[source,ini]
+--------------------------------------------------------------------------------
+[[fd0a::1]]
+key = FOO
+secret = BAR
+--------------------------------------------------------------------------------
+
+NOTE: The IPv6 address is written in square brackets as it is internally
+converted to a URL which requires this notation.
+This is also the reason why host specific the section headers need to
+have double brackets (one for the ini format, one for the IPv6 host notation).
 
 == Troubleshooting
 [id="troubleshooting"]