1. Patchew
  2. Libvirt
  3. [PATCH 0/4] Introduce SSH proxy
  4. View patch

[PATCH 3/4] docs: Document SSH proxy

Michal Privoznik posted 4 patches 1 year, 9 months ago
There is a newer version of this series
[PATCH 3/4] docs: Document SSH proxy
Posted by Michal Privoznik 1 year, 9 months ago 
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 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/docs.rst b/docs/docs.rst
index f57164b9e3..1a958e9cc7 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -47,6 +47,9 @@ Deployment / operation
 `Hooks <hooks.html>`__
    Hooks for system specific management
 
+`SSH Proxy <ssh-proxy.html>`__
+   Enable SSH into guests over a VSOCK
+
 `NSS module <nss.html>`__
    Enable domain host name translation to IP addresses
 
diff --git a/docs/meson.build b/docs/meson.build
index 87d728213c..2dda59f978 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -97,6 +97,7 @@ docs_rst_files = [
   'python',
   'remote',
   'securityprocess',
+  'ssh-proxy',
   'storage',
   'strategy',
   'styleguide',
diff --git a/docs/nss.rst b/docs/nss.rst
index 8f98330221..53955a3278 100644
--- a/docs/nss.rst
+++ b/docs/nss.rst
@@ -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
 provides ``libvirt_guest`` NSS module that doesn't have this limitation.
 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.
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
-- 
2.43.2
_______________________________________________
Devel mailing list -- devel@lists.libvirt.org
To unsubscribe send an email to devel-leave@lists.libvirt.org
Re: [PATCH 3/4] docs: Document SSH proxy
Posted by Daniel P. Berrangé 1 year, 9 months ago 
On Fri, Apr 19, 2024 at 12:12:32PM +0200, Michal Privoznik wrote:
> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> ---
>  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

s/gust/guest/

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

s/provides/provides a/

> +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

s/offers SSH/offers a SSH/

> +(``/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
> +------------------

s/Guest/Guest OS/

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

s/that SSH/that the SSH/

> +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


We should mention the guest XML for host to add VSOCK to QEMU, under
a "Libvirt domain XML configuration" heading

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
_______________________________________________
Devel mailing list -- devel@lists.libvirt.org
To unsubscribe send an email to devel-leave@lists.libvirt.org

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.