[PATCH v3 2/3] docs: Document SSH proxy

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Michal Privoznik <mprivozn@xxxxxxxxxx>
---
 docs/docs.rst      |  3 ++
 docs/meson.build   |  1 +
 docs/nss.rst       |  7 ++++
 docs/ssh-proxy.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 96 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 2dfe98ef62..53b518f987 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..014737e967
--- /dev/null
+++ b/docs/ssh-proxy.rst
@@ -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>`__.
-- 
2.43.2
_______________________________________________
Devel mailing list -- devel@xxxxxxxxxxxxxxxxx
To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxx




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux