1waypipe(1) General Commands Manual waypipe(1)
2
6 waypipe - A transparent proxy for Wayland applications
7
9 waypipe [options...] client
10 waypipe [options...] server -- command...
11 waypipe [options...] recon control_pipe new_socket_path
12 waypipe [options...] ssh ...
13 waypipe [options...] bench bandwidth
14
16 waypipe is a proxy for Wayland clients, with the aim of supporting
17 behavior like ssh -X.
18 When run as waypipe client, it will open a socket (by default at
20 /tmp/waypipe-client.sock) and will connect to the local Wayland compos‐
21 itor and forward all Wayland applications which were linked to it over
22 the socket by a matching waypipe server instance.
23 When run as waypipe server, it will run the command that follows in its
25 command line invocation, set up its own Wayland compositor socket, and
26 try to connect to its matching waypipe client socket (by default
27 /tmp/waypipe-server.sock) and try to forward all the Wayland clients
28 that connect to fake compositor socket to the matching waypipe client.
29 The waypipe recon mode is used to reconnect a waypipe server instance
31 which has had a control pipe (option --control) set. The new socket
32 path should indicate a Unix socket whose connections are forwarded to
33 the waypipe client that the waypipe server was initially connected to.
34 Next, prefixing an ssh ... command to become waypipe ssh ... will auto‐
36 matically set up local and remote copies of waypipe, as well as for‐
37 warding between their sockets, so that Wayland applications run
38 remotely will be displayed locally.
39 Finally, the waypipe bench mode can be used to estimate, given a spe‐
41 cific connection bandwidth in MB/sec, which compression options produce
42 the lowest latency. It tests two synthetic images, one made to be
43 roughly as compressible as images containing text, and one made to be
44 roughly as compressible as images containing pictures.
45
47 -c C, --compress C
48 Select the compression method applied to data transfers. Options
49 are none (for high-bandwidth networks), lz4 (intermediate), zstd
50 (slow connection). The default compression is none. The compression
51 level can be chosen by appending = followed by a number. For exam‐
52 ple, if C is zstd=7, waypipe will use level 7 Zstd compression.
53 -d, --debug
55 Print debug log messages.
56 -h, --help
58 Show help message and quit.
59 -n, --no-gpu
61 Block protocols like wayland-drm and linux-dmabuf which require
62 access to e.g. render nodes.
63 -o, --oneshot
65 Only permit a single connection, and exit when it is closed.
66 -s S, --socket S
68 Use S as the path for the Unix socket. The default socket path for
69 server mode is /tmp/waypipe-server.sock; for client mode, it is
70 /tmp/waypipe-client.sock; and in ssh mode, S gives the prefix used
71 by both the client and the server for their socket paths.
72 -v, --version
74 Print the version number and quit.
75 --allow-tiled
77 By default, waypipe filters out all advertised DMABUF formats which
78 have format layout modifiers, as CPU access to these formats may be
79 very slow. Setting this flag disables the filtering. Since tiled
80 images often permit faster GPU operations, most OpenGL applications
81 will select tiling modifiers when they are available.
82 --control C
84 For server or ssh mode, provide the path to the "control pipe" that
85 will be created the the server. Writing (with waypipe recon C T, or
86 instance replace all running connections with connections to the
87 new Unix socket. The new socket should ultimately forward data to
88 the same waypipe client that the server was connected to before.
89 --display D
91 For server or ssh mode, provide WAYLAND_DISPLAY and let waypipe
92 configure its Wayland display socket to have a matching path. (If D
93 is not an absolute path, the socket will be created in the folder
94 given by the environment variable XDG_RUNTIME_DIR.)
95 --drm-node R
97 Specify the path R to the drm device that this instance of waypipe
98 should use and (in server mode) notify connecting applications
99 about.
100 --remote-node R
102 In ssh mode, specify the path R to the drm device that the remote
103 instance of waypipe (running in server mode) should use.
104 --login-shell
106 Only for server mode; if no command is being run, open a login
107 shell.
108 --threads T
110 Set the number of total threads (including the main thread) which a
111 waypipe instance will create. These threads will be used to paral‐
112 lelize compression operations. This flag is passed on to waypipe
113 server when given to waypipe ssh. The flag also controls the thread
114 count for waypipe bench.
115 --unlink-socket
117 Only for server mode; on shutdown, unlink the Unix socket that
118 waypipe connects to.
119 --video
121 Compress specific DMABUF formats using a lossy video codec. Opaque,
122 10-bit, and multiplanar formats, among others, are not supported.
123 --hwvideo
125 Sets the --video option, and also specifies that hardware video
126 encoding and decoding should be used if possible. Whether this
127 option improves bandwidth use and latency is hardware dependent.
128
130 The following waypipe ssh subcommand will attempt to run weston-flower
131 on the server exserv, displaying the result on the local system.
132 waypipe ssh user@exserv weston-flower
134 One can obtain similar behavior by explictly running waypipe and ssh:
136 waypipe --socket /tmp/socket-client client &
138 ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
139 waypipe --socket /tmp/socket-server server -- weston-flower
140 kill %1
141 Waypipe may be run locally without an ssh connection by specifying
143 matching socket paths. For example:
144 waypipe --socket /tmp/waypipe.sock client &
146 waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
147 kill %1
148 rm /tmp/waypipe.sock
149 Many applications require specific environment variables to use Wayland
151 instead of X11. If ssh isn't configured to support loading ~/.ssh/envi‐
152 ronment, one can use env to set the needed variables each time; or run
153 waypipe without a command, to use the login shell environment.
154 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
156 Waypipe has support for reconnecting a waypipe client and a waypipe
158 server instance when whatever was used to transfer data between their
159 sockets fails. For this to work, waypipe must still be running on both
160 sides of the connection. As the waypipe ssh wrapper will automatically
161 close both the waypipe client and the waypipe server when the connec‐
162 tion fails, the client and server modes must be run seprately. For
163 example, to persistently forward applications running on server rserv
164 to a local Wayland compositor running on lserv, one would first set up
165 a waypipe client instance on lserv,
166 waypipe -s /tmp/waypipe.sock client &
168 and on server rserv, establish socket forwarding and run the server
170 ssh -fN -L /tmp/waypipe-lserv.sock:/tmp/waypipe.sock user@lserv
172 waypipe -s /tmp/waypipe-lserv.sock --control /tmp/ctrl-lserv.pipe \
173 --display wayland-lserv server -- sleep inf &
174 then set WAYLAND_DISPLAY=wayland-lserv and run the desired applica‐
176 tions. When the ssh forwarding breaks, on rserv, reconnect with
177 ssh -fN -L /tmp/waypipe-lserv-2.sock:/tmp/waypipe.sock user@lserv
179 waypipe recon /tmp/ctrl-lserv.pipe /tmp/waypipe-lserv-2.sock
180
182 When running as a server, by default WAYLAND_DISPLAY will be set for
183 the invoked process.
184 If the --oneshot flag is set, waypipe will instead set WAYLAND_SOCKET
186 and inherit an already connected socketpair file descriptor to the
187 invoked (child) process. Some programs open and close a Wayland connec‐
188 tion repeatedly as part of their initialization, and will not work cor‐
189 rectly with this flag.
190
192 waypipe ssh will exit with the exit status code from the remote com‐
193 mand, or with return code 1 if there has been an error.
194
196 weston(1), ssh(1)
197 2019-08-28 waypipe(1)