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