Debian Codegraph @

upstream/debian-unstable/man1/systemd-ssh-proxy.1

raw
1 '\" t
2 .TH "SYSTEMD\-SSH\-PROXY" "1" "" "systemd 261~rc3" "systemd-ssh-proxy"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-ssh-proxy \- SSH client plugin for connecting to \fBAF_VSOCK\fR and \fBAF_UNIX\fR sockets
24 .SH "SYNOPSIS"
25 .sp
26 .nf
27 Host unix/* unix%* vsock/* vsock%* vsock\-mux/* vsock\-mux%*
28 ProxyCommand /usr/lib/systemd/systemd\-ssh\-proxy %h %p
29 ProxyUseFdpass yes
30 .fi
31 .HP \w'\fB/usr/lib/systemd/systemd\-ssh\-proxy\fR\ 'u
32 \fB/usr/lib/systemd/systemd\-ssh\-proxy\fR [ADDRESS] [PORT]
33 .SH "DESCRIPTION"
34 .PP
35 \fBsystemd\-ssh\-proxy\fR
36 is a small "proxy" plugin for the
37 \fBssh\fR(1)
38 tool that allows connecting to
39 \fBAF_UNIX\fR
40 and
41 \fBAF_VSOCK\fR
42 sockets\&. It implements the interface defined by
43 ssh\*(Aqs
44 \fIProxyCommand\fR
45 configuration option\&. It\*(Aqs supposed to be used with an
46 \fBssh_config\fR(5)
47 configuration fragment like the following:
48 .sp
49 .if n \{\
50 .RS 4
51 .\}
52 .nf
53 Host unix/* unix%* vsock/* vsock%* vsock\-mux/* vsock\-mux%*
54 ProxyCommand /usr/lib/systemd/systemd\-ssh\-proxy %h %p
55 ProxyUseFdpass yes
56 CheckHostIP no
57
58 Host \&.host
59 ProxyCommand /usr/lib/systemd/systemd\-ssh\-proxy unix/run/ssh\-unix\-local/socket %p
60 ProxyUseFdpass yes
61 CheckHostIP no
62 .fi
63 .if n \{\
64 .RE
65 .\}
66 .PP
67 A configuration fragment along these lines is by default installed into
68 /etc/ssh/ssh_config\&.d/20\-systemd\-ssh\-proxy\&.conf\&.
69 .PP
70 With this in place, SSH connections to host string
71 "unix/"
72 followed by an absolute
73 \fBAF_UNIX\fR
74 file system path to a socket will be directed to the specified socket, which must be of type
75 \fBSOCK_STREAM\fR\&. Similar, SSH connections to
76 "vsock/"
77 followed by an
78 \fBAF_VSOCK\fR
79 CID will result in an SSH connection made to that CID\&.
80 "vsock\-mux/"
81 followed by an absolute
82 \fBAF_UNIX\fR
83 file system path to a socket is similar but for cloud\-hypervisor/firecracker which do not allow direct
84 \fBAF_VSOCK\fR
85 communication between the host and guests, and provide their own multiplexer over
86 \fBAF_UNIX\fR
87 sockets\&. See
88 \m[blue]\fBcloud\-hypervisor VSOCK support\fR\m[]\&\s-2\u[1]\d\s+2
89 and
90 \m[blue]\fBUsing the Firecracker Virtio\-vsock Device\fR\m[]\&\s-2\u[2]\d\s+2\&. Note that
91 "%"
92 can be used as a separator instead of
93 "/"
94 to be compatible with tools like
95 "scp"
96 and
97 "rsync"\&.
98 .PP
99 Moreover, connecting to
100 "\&.host"
101 will connect to the local host via SSH, without involving networking\&.
102 .PP
103 This tool is supposed to be used together with
104 \fBsystemd-ssh-generator\fR(8)
105 which when run inside a VM or container will bind SSH to suitable addresses\&.
106 \fBsystemd\-ssh\-generator\fR
107 is supposed to run in the container or VM guest, and
108 \fBsystemd\-ssh\-proxy\fR
109 is run on the host, in order to connect to the container or VM guest\&.
110 .SH "EXIT STATUS"
111 .PP
112 On success, 0 is returned, a non\-zero failure code otherwise\&.
113 .SH "EXAMPLES"
114 .PP
115 \fBExample\ \&1.\ \&Talk to a local VM with CID 4711\fR
116 .sp
117 .if n \{\
118 .RS 4
119 .\}
120 .nf
121 ssh vsock/4711
122 .fi
123 .if n \{\
124 .RE
125 .\}
126 .PP
127 \fBExample\ \&2.\ \&Talk to a VM guest hosted with cloud\-hypervisor/firecracker\fR
128 .sp
129 .if n \{\
130 .RS 4
131 .\}
132 .nf
133 ssh vsock\-mux/run/vm\-1234\&.sock
134 .fi
135 .if n \{\
136 .RE
137 .\}
138 .PP
139 \fBExample\ \&3.\ \&Talk to the local host via ssh\fR
140 .sp
141 .if n \{\
142 .RS 4
143 .\}
144 .nf
145 ssh \&.host
146 .fi
147 .if n \{\
148 .RE
149 .\}
150 .PP
151 or equivalent:
152 .sp
153 .if n \{\
154 .RS 4
155 .\}
156 .nf
157 ssh unix/run/ssh\-unix\-local/socket
158 .fi
159 .if n \{\
160 .RE
161 .\}
162 .PP
163 \fBExample\ \&4.\ \&Copy local \*(Aqfoo\*(Aq file to a local VM with CID 1348\fR
164 .sp
165 .if n \{\
166 .RS 4
167 .\}
168 .nf
169 scp foo vsock%1348:
170 .fi
171 .if n \{\
172 .RE
173 .\}
174 .SH "SEE ALSO"
175 .PP
176 \fBsystemd\fR(1), \fBsystemd-ssh-generator\fR(8), \fBvsock\fR(7), \fBunix\fR(7), \fBssh\fR(1), \fBsshd\fR(8)
177 .SH "NOTES"
178 .IP " 1." 4
179 cloud-hypervisor VSOCK support
180 .RS 4
181 \%https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/vsock.md
182 .RE
183 .IP " 2." 4
184 Using the Firecracker Virtio-vsock Device
185 .RS 4
186 \%https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md
187 .RE