man7.org > Linux > man-pages

Linux/UNIX system programming training

systemd-ssh-proxy(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | SEE ALSO | NOTES | COLOPHON 

SYSTEMD-SSH-PROXY(1)        systemd-ssh-proxy        SYSTEMD-SSH-PROXY(1)

NAME         top

       systemd-ssh-proxy - SSH client plugin for connecting to AF_VSOCK
       and AF_UNIX sockets

SYNOPSIS         top

       Host unix/* vsock/* vsock-mux/*
           ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p
           ProxyUseFdpass yes

       /usr/lib/systemd/systemd-ssh-proxy [ADDRESS] [PORT]

DESCRIPTION         top

       systemd-ssh-proxy is a small "proxy" plugin for the ssh(1) tool
       that allows connecting to AF_UNIX and AF_VSOCK sockets. It
       implements the interface defined by ssh's ProxyCommand
       configuration option. It's supposed to be used with an
       ssh_config(5) configuration fragment like the following:

           Host unix/* vsock/* vsock-mux/*
               ProxyCommand /usr/lib/systemd/systemd-ssh-proxy %h %p
               ProxyUseFdpass yes
               CheckHostIP no

           Host .host
               ProxyCommand /usr/lib/systemd/systemd-ssh-proxy unix/run/ssh-unix-local/socket %p
               ProxyUseFdpass yes
               CheckHostIP no

       A configuration fragment along these lines is by default installed
       into /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf.

       With this in place, SSH connections to host string "unix/"
       followed by an absolute AF_UNIX file system path to a socket will
       be directed to the specified socket, which must be of type
       SOCK_STREAM. Similar, SSH connections to "vsock/" followed by an
       AF_VSOCK CID will result in an SSH connection made to that CID.
       "vsock-mux/" followed by an absolute AF_UNIX file system path to a
       socket is similar but for cloud-hypervisor/firecracker which do
       not allow direct AF_VSOCK communication between the host and
       guests, and provide their own multiplexer over AF_UNIX sockets.
       See cloud-hypervisor VSOCK support[1] and Using the Firecracker
       Virtio-vsock Device[2].

       Moreover, connecting to ".host" will connect to the local host via
       SSH, without involving networking.

       This tool is supposed to be used together with
       systemd-ssh-generator(8) which when run inside a VM or container
       will bind SSH to suitable addresses.  systemd-ssh-generator is
       supposed to run in the container or VM guest, and
       systemd-ssh-proxy is run on the host, in order to connect to the
       container or VM guest.

EXIT STATUS         top

       On success, 0 is returned, a non-zero failure code otherwise.

EXAMPLES         top

       Example 1. Talk to a local VM with CID 4711

           ssh vsock/4711

       Example 2. Talk to a VM guest hosted with
       cloud-hypervisor/firecracker

           ssh vsock-mux/run/vm-1234.sock

       Example 3. Talk to the local host via ssh

           ssh .host

       or equivalent:

           ssh unix/run/ssh-unix-local/socket

SEE ALSO         top

       systemd(1), systemd-ssh-generator(8), vsock(7), unix(7), ssh(1),
       sshd(8)

NOTES         top

        1. cloud-hypervisor VSOCK support
           https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/vsock.md

        2. Using the Firecracker Virtio-vsock Device
           https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a
       bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2025-02-02.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2025-02-02.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there is
       a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

systemd 258~devel                                    SYSTEMD-SSH-PROXY(1)

Pages that refer to this page: systemd.directives(7),  systemd.index(7),  systemd-ssh-generator(8)

HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface.

For details of in-depth Linux/UNIX system programming training courses that I teach, look here.

Hosting by jambit GmbH.

Cover of TLPI