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.
82 --version
84 Briefly describe Waypipe's version and the features it was built
85 with, then quit. Possible features: LZ4 compression support, ZSTD
86 compression support, ability to transfer DMABUFs, video compression
87 support, VAAPI hardware video de/encoding support.
88 --allow-tiled
90 By default, waypipe filters out all advertised DMABUF formats which
91 have format layout modifiers, as CPU access to these formats may be
92 very slow. Setting this flag disables the filtering. Since tiled
93 images often permit faster GPU operations, most OpenGL applications
94 will select tiling modifiers when they are available.
95 --control C
97 For server or ssh mode, provide the path to the "control pipe" that
98 will be created the the server. Writing (with waypipe recon C T, or
99 'echo -n T > C') a new socket path to this pipe will make the
100 server instance replace all running connections with connections to
101 the new Unix socket. The new socket should ultimately forward data
102 to the same waypipe client that the server was connected to before.
103 --display D
105 For server or ssh mode, provide WAYLAND_DISPLAY and let waypipe
106 configure its Wayland display socket to have a matching path. (If D
107 is not an absolute path, the socket will be created in the folder
108 given by the environment variable XDG_RUNTIME_DIR.)
109 --drm-node R
111 Specify the path R to the drm device that this instance of waypipe
112 should use and (in server mode) notify connecting applications
113 about.
114 --remote-node R
116 In ssh mode, specify the path R to the drm device that the remote
117 instance of waypipe (running in server mode) should use.
118 --remote-bin R
120 In ssh mode, specify the path R to the waypipe binary on the remote
121 computer, or its name if it is available in PATH. It defaults to
122 waypipe if this option isn’t passed.
123 --login-shell
125 Only for server mode; if no command is being run, open a login
126 shell.
127 --threads T
129 Set the number of total threads (including the main thread) which a
130 waypipe instance will create. These threads will be used to paral‐
131 lelize compression operations. This flag is passed on to waypipe
132 server when given to waypipe ssh. The flag also controls the thread
133 count for waypipe bench. The default behavior (choosable by setting
134 T to 0) is to use half as many threads as the computer has hardware
135 threads available.
136 --unlink-socket
138 Only for server mode; on shutdown, unlink the Unix socket that
139 waypipe connects to.
140 --video[=V]
142 Compress specific DMABUF formats using a lossy video codec. Opaque,
143 10-bit, and multiplanar formats, among others, are not supported. V
144 is a comma separated list of options to control the video encoding.
145 Using the --video flag without setting any options is equivalent to
146 using the default setting of: --video=sw,bpf=120000,h264. Later op‐
147 tions supersede earlier ones.
148 sw
150 Use software encoding and decoding.
151 hw
153 Use hardware (VAAPI) encoding and decoding, if available. This
154 can be finicky and may only work with specific window buffer
155 formats and sizes.
156 h264
158 Use H.264 encoded video.
159 vp9
161 Use VP9 encoded video.
162 bpf=B
164 Set the target bit rate of the video encoder, in units of bits
165 per frame. B can be written as an integer or with exponential
166 notation; thus --video=bpf=7.5e5 is equivalent to
167 --video=bpf=750000.
168 --hwvideo
170 Deprecated option, equivalent to --video=hw .
171
173 The following waypipe ssh subcommand will attempt to run weston-flower
174 on the server exserv, displaying the result on the local system.
175 waypipe ssh user@exserv weston-flower
177 One can obtain similar behavior by explicitly running waypipe and ssh:
179 waypipe --socket /tmp/socket-client client &
181 ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
182 waypipe --socket /tmp/socket-server server -- weston-flower
183 kill %1
184 Waypipe may be run locally without an SSH connection by specifying
186 matching socket paths. For example:
187 waypipe --socket /tmp/waypipe.sock client &
189 waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
190 kill %1
191 rm /tmp/waypipe.sock
192 Using transports other than SSH is a bit more complicated. A recipe
194 with ncat to connect to remote from computer local:
195 $ waypipe --socket /tmp/waypipe-remote.sock client &
197 $ ncat --ssl -lk 12345 --sh-exec 'ncat -U /tmp/waypipe-remote.sock' &
198 $ ssh user@remote
199 > ncat -lkU /tmp/waypipe-local.sock --sh-exec 'ncat --ssl local 12345' &
201 > waypipe --display wayland-local \
202 --socket /tmp/waypipe-local.sock server -- sleep inf &
203 > WAYLAND_DISPLAY=wayland-local application
204 Given a certificate file, socat can also provide an encrypted connec‐
206 tion (remove 'verify=0' to check certificates):
207 $ waypipe --socket /tmp/waypipe-remote.sock client &
209 $ socat openssl-listen:12345,reuseaddr,cert=certificate.pem,verify=0,fork \
210 unix-connect:/tmp/waypipe-remote.sock
211 $ ssh user@remote
212 > socat unix-listen:/tmp/waypipe-local.sock,reuseaddr,fork \
214 openssl-connect:local:12345,verify=0 &
215 > waypipe --socket /tmp/waypipe-local.sock server -- application
216 Many applications require specific environment variables to use Wayland
218 instead of X11. If ssh isn't configured to support loading ~/.ssh/envi‐
219 ronment, one can use env to set the needed variables each time; or run
220 waypipe without a command, to use the login shell environment.
221 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
223 Waypipe has support for reconnecting a waypipe client and a waypipe
225 server instance when whatever was used to transfer data between their
226 sockets fails. For this to work, waypipe must still be running on both
227 sides of the connection. As the waypipe ssh wrapper will automatically
228 close both the waypipe client and the waypipe server when the connec‐
229 tion fails, the client and server modes must be run seprately. For ex‐
230 ample, to persistently forward applications running on server rserv to
231 a local Wayland compositor running on lserv, one would first set up a
232 waypipe client instance on lserv,
233 waypipe -s /tmp/waypipe.sock client &
235 and on server rserv, establish socket forwarding and run the server
237 ssh -fN -L /tmp/waypipe-lserv.sock:/tmp/waypipe.sock user@lserv
239 waypipe -s /tmp/waypipe-lserv.sock --control /tmp/ctrl-lserv.pipe \
240 --display wayland-lserv server -- sleep inf &
241 then set WAYLAND_DISPLAY=wayland-lserv and run the desired applica‐
243 tions. When the ssh forwarding breaks, on rserv, reconnect with
244 ssh -fN -L /tmp/waypipe-lserv-2.sock:/tmp/waypipe.sock user@lserv
246 waypipe recon /tmp/ctrl-lserv.pipe /tmp/waypipe-lserv-2.sock
247
249 When running as a server, by default WAYLAND_DISPLAY will be set for
250 the invoked process.
251 If the --oneshot flag is set, waypipe will instead set WAYLAND_SOCKET
253 and inherit an already connected socketpair file descriptor to the in‐
254 voked (child) process. Some programs open and close a Wayland connec‐
255 tion repeatedly as part of their initialization, and will not work cor‐
256 rectly with this flag.
257
259 waypipe ssh will exit with the exit status code from the remote com‐
260 mand, or with return code 1 if there has been an error.
261
263 File bug reports at: https://gitlab.freedesktop.org/mstoeckl/waypipe/
264 Some programs (gnome-terminal, firefox, kate, among others) have spe‐
266 cial mechanisms to ensure that only one process is running at a time.
267 Starting those programs under Waypipe while they are running under a
268 different Wayland compositor may silently open a window or tab in the
269 original instance of the program. Such programs may have a command line
270 argument to create a new instance.
271
273 weston(1), ssh(1), socat(1), ncat(1)
274 2022-07-23 waypipe(1)