Re: [PATCH 3/4] docs: Document SSH proxy

Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com&gt; --- docs/docs.rst | 3 +++ docs/meson.build | 1 + docs/nss.rst | 7 ++++++ docs/ssh-proxy.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 71 insertions(+) create mode 100644 docs/ssh-proxy.rst

diff --git a/docs/ssh-proxy.rst b/docs/ssh-proxy.rst new file mode 100644 index 0000000000..8528b6b9a8 --- /dev/null +++ b/docs/ssh-proxy.rst @@ -0,0 +1,60 @@ +================= +Libvirt SSH proxy +================= + +Sometimes it's necessary to run some commands inside a gust. While libvirt

+already provides `NSS module <nss.html>`__ that can translate guest name to IP

+address it has some limitations (e.g. guest has to have a network interface +plugged into a libvirt managed network). To resolve some of these limitations, +libvirt offers SSH proxy. It consists of a SSH client config file

+(``/etc/ssh/ssh_config.d/30-libvirt-ssh-proxy.conf``) and a small binary. Both +are automatically installed by ``libvirt-client`` package. After running: + +``ssh user@qemu/virtualMachine`` + +the configuration file instructs SSH client to start the binary helper which +finds a VSOCK device inside the ``virtualMachine`` and establishes a connection +to it. + +For now, only QEMU domains are implemented and the lookup of the +``virtualMachine`` is done under ``qemu:///system`` URI first, followed by +``qemu:///session``. Accepted values for ``virtualMachine`` are: domain name +(as reported by e.g. `virsh list`), domain UUID and finally domain ID. + +Guest requirements +------------------

+ +It is obvious that SSH daemon inside the guest needs to be configured to listen

+for incoming connections on a VSOCK. There are couple of ways to achieve this: + +* Run systemd-v256 or newer inside the guest. + + In this release, systemd started to deploy ``systemd-ssh-generator`` which + should configure socket activation for SSHD automagically. + +* Set up socket activation for VSOCK. + + We can take an inspiration in the unit file generated by + ``systemd-ssh-generator``: + +:: + + [Unit] + Description=OpenSSH Server Socket (systemd-ssh-generator, AF_VSOCK) + Documentation=man:systemd-ssh-generator(8) + Wants=ssh-access.target + Before=ssh-access.target + + [Socket] + ListenStream=vsock::22 + Accept=yes + PollLimitIntervalSec=30s + PollLimitBurst=50 + +* Run a service that forwards VSOCK <=> SSHD communication + + For instance: + +:: + + socat VSOCK-LISTEN:22,reuseaddr,fork TCP:localhost:22