SYSTEMD-SSH-PROXY(1)

💅 SYSTEMD-SSH-PROXY — ok bestie, let's talk

So like, the manual page name is systemd-ssh-proxy from the systemd-ssh-proxy manual (that's the SYSTEMD-SSH-PROXY(1) thing at the top, iykyk) — and it's the SSH client plugin that lets you slide into AF_VSOCK and AF_UNIX sockets. 🦋

---

✨ NAME ✨

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

---

🎀 SYNOPSIS 🎀

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

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

---

🌸 DESCRIPTION 🌸

okay so systemd-ssh-proxy is a lil "proxy" plugin for the ssh(1) tool, and what it does is let you connect 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 this one:

Host unix/* unix%* vsock/* vsock%* vsock-mux/* 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. 💖

So with this in place, SSH connections to the host string "unix/" followed by an absolute AF_UNIX file system path to a socket get directed to that socket — and bestie, that socket must be of type SOCK_STREAM. Similar vibes: SSH connections to "vsock/" followed by an AF_VSOCK CID will result in an SSH connection made to that CID. Then "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]. 📚

Also!! Note that "%" can be used as a separator instead of "/" to be compatible with tools like "scp" and "rsync". periodt.

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

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

Example 4. Copy local 'foo' file to a local VM with CID 1348

scp foo vsock%1348:

---

👑 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

---

aaaand that's the whole page bestie, slay 💖 this was systemd 262.1 energy, SYSTEMD-SSH-PROXY(1), mwah 🎀✨