1waypipe(1) General Commands Manual waypipe(1)
2
6 waypipe - A transparent proxy for Wayland applications
7
9 waypipe [options...] ssh [ssh options] destination command...
10 waypipe [options...] client
12 waypipe [options...] server -- command...
13 waypipe recon control_pipe new_socket_path
14 waypipe bench bandwidth
15 waypipe [--version] [-h, --help]
16 [options...] = [-c, --compress C] [-d, --debug] [-n, --no-gpu] [-o,
18 --oneshot] [-s, --socket S] [--allow-tiled] [--control C] [--display D]
19 [--drm-node R] [--remote-node R] [--remote-bin R] [--login-shell]
20 [--threads T] [--unlink-socket] [--video[=V]]
21
23 Waypipe is a proxy for Wayland clients, with the aim of supporting be‐
24 havior like ssh -X.
25 Prefixing an ssh ... command to become waypipe ssh ... will automati‐
27 cally run waypipe both locally and remotely, and modify the ssh command
28 to set up forwarding between the two instances of waypipe. The remote
29 instance will act like a Wayland compositor, letting Wayland applica‐
30 tions that are run remotely be displayed locally.
31 When run as waypipe client, it will open a socket (by default at
33 /tmp/waypipe-client.sock) and will connect to the local Wayland compos‐
34 itor and forward all Wayland applications which were linked to it over
35 the socket by a matching waypipe server instance.
36 When run as waypipe server, it will run the command that follows in its
38 command line invocation, set up its own Wayland compositor socket, and
39 try to connect to its matching waypipe client socket (by default
40 /tmp/waypipe-server.sock) and try to forward all the Wayland clients
41 that connect to fake compositor socket to the matching waypipe client.
42 The waypipe recon mode is used to reconnect a waypipe server instance
44 which has had a control pipe (option --control) set. The new socket
45 path should indicate a Unix socket whose connections are forwarded to
46 the waypipe client that the waypipe server was initially connected to.
47 The waypipe bench mode can be used to estimate, given a specific con‐
49 nection bandwidth in MB/sec, which compression options produce the low‐
50 est latency. It tests two synthetic images, one made to be roughly as
51 compressible as images containing text, and one made to be roughly as
52 compressible as images containing pictures.
53
55 -c C, --compress C
56 Select the compression method applied to data transfers. Options
57 are none (for high-bandwidth networks), lz4 (intermediate), zstd
58 (slow connection). The default compression is none.† The compres‐
59 sion level can be chosen by appending = followed by a number. For
60 example, if C is zstd=7, waypipe will use level 7 Zstd compression.
61 † In a future version, the default will change to lz4.
63 -d, --debug
65 Print debug log messages.
66 -h, --help
68 Show help message and quit.
69 -n, --no-gpu
71 Block protocols like wayland-drm and linux-dmabuf which require ac‐
72 cess to e.g. render nodes.
73 -o, --oneshot
75 Only permit a single connection, and exit when it is closed.
76 -s S, --socket S
78 Use S as the path for the Unix socket. The default socket path for
79 server mode is /tmp/waypipe-server.sock; for client mode, it is
80 /tmp/waypipe-client.sock; and in ssh mode, S gives the prefix used
81 by both the client and the server for their socket paths. The de‐
82 fault prefix in ssh mode is /tmp/waypipe.
83 --version
85 Briefly describe Waypipe's version and the features it was built
86 with, then quit. Possible features: LZ4 compression support, ZSTD
87 compression support, ability to transfer DMABUFs, video compression
88 support, VAAPI hardware video de/encoding support.
89 --allow-tiled
91 By default, waypipe filters out all advertised DMABUF formats which
92 have format layout modifiers, as CPU access to these formats may be
93 very slow. Setting this flag disables the filtering. Since tiled
94 images often permit faster GPU operations, most OpenGL applications
95 will select tiling modifiers when they are available.
96 --control C
98 For server or ssh mode, provide the path to the "control pipe" that
99 will be created the the server. Writing (with waypipe recon C T, or
100 'echo -n T > C') a new socket path to this pipe will make the
101 server instance replace all running connections with connections to
102 the new Unix socket. The new socket should ultimately forward data
103 to the same waypipe client that the server was connected to before.
104 --display D
106 For server or ssh mode, provide WAYLAND_DISPLAY and let waypipe
107 configure its Wayland display socket to have a matching path. (If D
108 is not an absolute path, the socket will be created in the folder
109 given by the environment variable XDG_RUNTIME_DIR.)
110 --drm-node R
112 Specify the path R to the drm device that this instance of waypipe
113 should use and (in server mode) notify connecting applications
114 about.
115 --remote-node R
117 In ssh mode, specify the path R to the drm device that the remote
118 instance of waypipe (running in server mode) should use.
119 --remote-bin R
121 In ssh mode, specify the path R to the waypipe binary on the remote
122 computer, or its name if it is available in PATH. It defaults to
123 waypipe if this option isn’t passed.
124 --login-shell
126 Only for server mode; if no command is being run, open a login
127 shell.
128 --threads T
130 Set the number of total threads (including the main thread) which a
131 waypipe instance will create. These threads will be used to paral‐
132 lelize compression operations. This flag is passed on to waypipe
133 server when given to waypipe ssh. The flag also controls the thread
134 count for waypipe bench. The default behavior (choosable by setting
135 T to 0) is to use half as many threads as the computer has hardware
136 threads available.
137 --unlink-socket
139 Only for server mode; on shutdown, unlink the Unix socket that
140 waypipe connects to.
141 --video[=V]
143 Compress specific DMABUF formats using a lossy video codec. Opaque,
144 10-bit, and multiplanar formats, among others, are not supported. V
145 is a comma separated list of options to control the video encoding.
146 Using the --video flag without setting any options is equivalent to
147 using the default setting of: --video=sw,bpf=120000,h264. Later op‐
148 tions supersede earlier ones.
149 sw
151 Use software encoding and decoding.
152 hw
154 Use hardware (VAAPI) encoding and decoding, if available. This
155 can be finicky and may only work with specific window buffer
156 formats and sizes.
157 h264
159 Use H.264 encoded video.
160 vp9
162 Use VP9 encoded video.
163 bpf=B
165 Set the target bit rate of the video encoder, in units of bits
166 per frame. B can be written as an integer or with exponential
167 notation; thus --video=bpf=7.5e5 is equivalent to
168 --video=bpf=750000.
169 --hwvideo
171 Deprecated option, equivalent to --video=hw .
172
174 The following waypipe ssh subcommand will attempt to run weston-flower
175 on the server exserv, displaying the result on the local system.
176 waypipe ssh user@exserv weston-flower
178 One can obtain similar behavior by explicitly running waypipe and ssh:
180 waypipe --socket /tmp/socket-client client &
182 ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
183 waypipe --socket /tmp/socket-server server -- weston-flower
184 kill %1
185 Waypipe may be run locally without an SSH connection by specifying
187 matching socket paths. For example:
188 waypipe --socket /tmp/waypipe.sock client &
190 waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
191 kill %1
192 rm /tmp/waypipe.sock
193 Using transports other than SSH is a bit more complicated. A recipe
195 with ncat to connect to remote from computer local:
196 $ waypipe --socket /tmp/waypipe-remote.sock client &
198 $ ncat --ssl -lk 12345 --sh-exec 'ncat -U /tmp/waypipe-remote.sock' &
199 $ ssh user@remote
200 > ncat -lkU /tmp/waypipe-local.sock --sh-exec 'ncat --ssl local 12345' &
202 > waypipe --display wayland-local \
203 --socket /tmp/waypipe-local.sock server -- sleep inf &
204 > WAYLAND_DISPLAY=wayland-local application
205 Given a certificate file, socat can also provide an encrypted connec‐
207 tion (remove 'verify=0' to check certificates):
208 $ waypipe --socket /tmp/waypipe-remote.sock client &
210 $ socat openssl-listen:12345,reuseaddr,cert=certificate.pem,verify=0,fork \
211 unix-connect:/tmp/waypipe-remote.sock
212 $ ssh user@remote
213 > socat unix-listen:/tmp/waypipe-local.sock,reuseaddr,fork \
215 openssl-connect:local:12345,verify=0 &
216 > waypipe --socket /tmp/waypipe-local.sock server -- application
217 Many applications require specific environment variables to use Wayland
219 instead of X11. If ssh isn't configured to support loading ~/.ssh/envi‐
220 ronment, or to allow specific variables to be set with Ac‐
221 ceptEnv/SetEnv, one can run waypipe ssh without a command (and thereby
222 open a login shell), or use env to set the needed variables each time:
223 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
225 In some cases, one may wish to set environment variables for the wayp‐
227 ipe server process itself; the above trick with env will not do this,
228 because the env process will be a child of waypipe server, not the
229 other way around. Instead, one can use ~/.ssh/environment, or use the
230 --remote-bin option to change the remote Waypipe instance to a shell
231 script that sets the environment before running the actual waypipe pro‐
232 gram.
233 Waypipe has support for reconnecting a waypipe client and a waypipe
235 server instance when whatever was used to transfer data between their
236 sockets fails. For this to work, waypipe must still be running on both
237 sides of the connection. As the waypipe ssh wrapper will automatically
238 close both the waypipe client and the waypipe server when the connec‐
239 tion fails, the client and server modes must be run seprately. For ex‐
240 ample, to persistently forward applications running on server rserv to
241 a local Wayland compositor running on lserv, one would first set up a
242 waypipe client instance on lserv,
243 waypipe -s /tmp/waypipe.sock client &
245 and on server rserv, establish socket forwarding and run the server
247 ssh -fN -L /tmp/waypipe-lserv.sock:/tmp/waypipe.sock user@lserv
249 waypipe -s /tmp/waypipe-lserv.sock --control /tmp/ctrl-lserv.pipe \
250 --display wayland-lserv server -- sleep inf &
251 then set WAYLAND_DISPLAY=wayland-lserv and run the desired applica‐
253 tions. When the ssh forwarding breaks, on rserv, reconnect with
254 ssh -fN -L /tmp/waypipe-lserv-2.sock:/tmp/waypipe.sock user@lserv
256 waypipe recon /tmp/ctrl-lserv.pipe /tmp/waypipe-lserv-2.sock
257
259 When running as a server, by default WAYLAND_DISPLAY will be set for
260 the invoked process.
261 If the --oneshot flag is set, waypipe will instead set WAYLAND_SOCKET
263 and inherit an already connected socketpair file descriptor to the in‐
264 voked (child) process. Some programs open and close a Wayland connec‐
265 tion repeatedly as part of their initialization, and will not work cor‐
266 rectly with this flag.
267
269 waypipe ssh will exit with the exit status code from the remote com‐
270 mand, or with return code 1 if there has been an error.
271
273 File bug reports at: https://gitlab.freedesktop.org/mstoeckl/waypipe/
274 Some programs (gnome-terminal, firefox, kate, among others) have spe‐
276 cial mechanisms to ensure that only one process is running at a time.
277 Starting those programs under Waypipe while they are running under a
278 different Wayland compositor may silently open a window or tab in the
279 original instance of the program. Such programs may have a command line
280 argument to create a new instance.
281
283 weston(1), ssh(1), socat(1), ncat(1)
284 2023-09-30 waypipe(1)