1waypipe(1)                  General Commands Manual                 waypipe(1)
2
3
4

NAME

6       waypipe - A transparent proxy for Wayland applications
7

SYNOPSIS

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

DESCRIPTION

16       waypipe is a proxy for Wayland clients, with the aim of supporting be‐
17       havior like ssh -X.
18
19       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
24       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
30       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
35       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 re‐
38       motely will be displayed locally.
39
40       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

OPTIONS

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
54       -d, --debug
55           Print debug log messages.
56
57       -h, --help
58           Show help message and quit.
59
60       -n, --no-gpu
61           Block protocols like wayland-drm and linux-dmabuf which require ac‐
62           cess to e.g. render nodes.
63
64       -o, --oneshot
65           Only permit a single connection, and exit when it is closed.
66
67       -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
73       -v, --version
74           Print the version number and quit.
75
76       --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
83       --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
90       --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
96       --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
101       --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
105       --remote-bin R
106           In ssh mode, specify the path R to the waypipe binary on the remote
107           computer, or its name if it is available in PATH. It defaults to
108           waypipe if this option isn’t passed.
109
110       --login-shell
111           Only for server mode; if no command is being run, open a login
112           shell.
113
114       --threads T
115           Set the number of total threads (including the main thread) which a
116           waypipe instance will create. These threads will be used to paral‐
117           lelize compression operations. This flag is passed on to waypipe
118           server when given to waypipe ssh. The flag also controls the thread
119           count for waypipe bench.
120
121       --unlink-socket
122           Only for server mode; on shutdown, unlink the Unix socket that
123           waypipe connects to.
124
125       --video
126           Compress specific DMABUF formats using a lossy video codec. Opaque,
127           10-bit, and multiplanar formats, among others, are not supported.
128
129       --hwvideo
130           Sets the --video option, and also specifies that hardware video en‐
131           coding and decoding should be used if possible. Whether this option
132           improves bandwidth use and latency is hardware dependent.
133

EXAMPLE

135       The following waypipe ssh subcommand will attempt to run weston-flower
136       on the server exserv, displaying the result on the local system.
137
138                waypipe ssh user@exserv weston-flower
139
140       One can obtain similar behavior by explicitly running waypipe and ssh:
141
142                waypipe --socket /tmp/socket-client client  &
143                ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
144                     waypipe --socket /tmp/socket-server server -- weston-flower
145                kill %1
146
147       Waypipe may be run locally without an ssh connection by specifying
148       matching socket paths. For example:
149
150                waypipe --socket /tmp/waypipe.sock client &
151                waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
152                kill %1
153                rm /tmp/waypipe.sock
154
155       Many applications require specific environment variables to use Wayland
156       instead of X11. If ssh isn't configured to support loading ~/.ssh/envi‐
157       ronment, one can use env to set the needed variables each time; or run
158       waypipe without a command, to use the login shell environment.
159
160                 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
161
162       Waypipe has support for reconnecting a waypipe client and a waypipe
163       server instance when whatever was used to transfer data between their
164       sockets fails. For this to work, waypipe must still be running on both
165       sides of the connection. As the waypipe ssh wrapper will automatically
166       close both the waypipe client and the waypipe server when the connec‐
167       tion fails, the client and server modes must be run seprately. For ex‐
168       ample, to persistently forward applications running on server rserv to
169       a local Wayland compositor running on lserv, one would first set up a
170       waypipe client instance on lserv,
171
172                waypipe -s /tmp/waypipe.sock client &
173
174       and on server rserv, establish socket forwarding and run the server
175
176                ssh -fN -L /tmp/waypipe-lserv.sock:/tmp/waypipe.sock user@lserv
177                waypipe -s /tmp/waypipe-lserv.sock --control /tmp/ctrl-lserv.pipe \
178                     --display wayland-lserv server -- sleep inf &
179
180       then set WAYLAND_DISPLAY=wayland-lserv and run the desired applica‐
181       tions. When the ssh forwarding breaks, on rserv, reconnect with
182
183                ssh -fN -L /tmp/waypipe-lserv-2.sock:/tmp/waypipe.sock user@lserv
184                waypipe recon /tmp/ctrl-lserv.pipe /tmp/waypipe-lserv-2.sock
185

ENVIRONMENT

187       When running as a server, by default WAYLAND_DISPLAY will be set for
188       the invoked process.
189
190       If the --oneshot flag is set, waypipe will instead set WAYLAND_SOCKET
191       and inherit an already connected socketpair file descriptor to the in‐
192       voked (child) process. Some programs open and close a Wayland connec‐
193       tion repeatedly as part of their initialization, and will not work cor‐
194       rectly with this flag.
195

EXIT STATUS

197       waypipe ssh will exit with the exit status code from the remote com‐
198       mand, or with return code 1 if there has been an error.
199

SEE ALSO

201       weston(1), ssh(1)
202
203
204
205                                  2021-01-27                        waypipe(1)
Impressum