plucky (1) systemd-ssh-proxy.1.gz

Provided by: systemd_257.2-3ubuntu1_amd64 bug

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


SYNOPSIS
       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
       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 don't 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
       On success, 0 is returned, a non-zero failure code otherwise.


EXAMPLES
       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
       systemd(1), systemd-ssh-generator(8), vsock(7), unix(7), ssh(1), sshd(8)


NOTES
        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