docs: Document SSH proxy

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Michal Privoznik 2024-04-18 10:39:18 +02:00
parent 0287b5dfd2
commit 6f31f18673
4 changed files with 96 additions and 0 deletions

View File

@ -47,6 +47,9 @@ Deployment / operation
`Hooks <hooks.html>`__ `Hooks <hooks.html>`__
Hooks for system specific management Hooks for system specific management
`SSH Proxy <ssh-proxy.html>`__
Enable SSH into guests over a VSOCK
`NSS module <nss.html>`__ `NSS module <nss.html>`__
Enable domain host name translation to IP addresses Enable domain host name translation to IP addresses

View File

@ -97,6 +97,7 @@ docs_rst_files = [
'python', 'python',
'remote', 'remote',
'securityprocess', 'securityprocess',
'ssh-proxy',
'storage', 'storage',
'strategy', 'strategy',
'styleguide', 'styleguide',

View File

@ -152,3 +152,10 @@ If there's no record for either of the aforementioned commands, it's very likely
that NSS module won't find anything and vice versa. As of ``v3.0.0`` libvirt that NSS module won't find anything and vice versa. As of ``v3.0.0`` libvirt
provides ``libvirt_guest`` NSS module that doesn't have this limitation. provides ``libvirt_guest`` NSS module that doesn't have this limitation.
However, the statement is still true for the ``libvirt`` NSS module. However, the statement is still true for the ``libvirt`` NSS module.
Alternatives
------------
As of ``v10.3.0`` libvirt implements an `SSH proxy <ssh-proxy.html>`__ which
doesn't require any network interface to SSH into the guest as SSH flows
through a VSOCK device.

85
docs/ssh-proxy.rst Normal file
View File

@ -0,0 +1,85 @@
=================
Libvirt SSH proxy
=================
Sometimes it's necessary to run some commands inside a guest. While libvirt
already provides a `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 a 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-ssh-proxy`` package which is dragged
in by ``libvirt-client``, ``libvirt-daemon-qemu`` and/or ``daemon-kvm`` RPM
packages. After running either of:
::
ssh user@qemu:system/virtualMachine
ssh user@qemu:session/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 for ``qemu:system`` or
under ``qemu:///session`` URI for ``qemu:session``.
For convenience, there's also another alternative:
::
ssh user@qemu/virtualMachine
where the ``virtualMachine`` is looked up under ``qemu:///system`` first,
possibly followed by ``qemu:///session`` (for cases where ssh client runs as
non-root, since there's no ``qemu:///session`` for root).
Accepted values for ``virtualMachine`` are: domain name (as reported by e.g.
`virsh list`), domain UUID and finally domain ID.
Guest OS requirements
---------------------
It is obvious that the 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
Libvirt domain XML configuration
--------------------------------
Since the SSH proxy uses a VSOCK to communicate with the SSH daemon running
inside the guest, it is a must to configure VSOCK in the `domain XML
<formatdomain.html#vsock>`__.