Ubuntu Manpage: waypipe - A transparent proxy for Wayland applications

NAME

       waypipe - A transparent proxy for Wayland applications

SYNOPSIS

       waypipe [options...] ssh [ssh options] destination command...

       waypipe [options...] client
       waypipe [options...] server -- command...
       waypipe recon control_pipe new_socket_path
       waypipe bench bandwidth
       waypipe [--version] [-h, --help]

       [options...] = [-c, --compress C] [-d, --debug] [-n, --no-gpu] [-o, --oneshot] [-s, --socket S] [--allow-
       tiled]  [--control  C]  [--display  D]  [--drm-node R] [--remote-node R] [--remote-bin R] [--login-shell]
       [--threads T] [--title-prefix P] [--unlink-socket] [--video[=V]] [--vsock]

DESCRIPTION

Waypipe is a proxy for Wayland clients, with the aim of supporting behavior like ssh -X.

Prefixing an ssh ... command to become waypipe ssh ... will automatically run waypipe both locally and
remotely, and modify the ssh command to set up forwarding between the two instances of waypipe. The
remote instance will act like a Wayland compositor, letting Wayland applications that are run remotely be
displayed locally.

When run as waypipe client, it will open a socket (by default at /tmp/waypipe-client.sock) and will
connect to the local Wayland compositor and forward all Wayland applications which were linked to it over
the socket by a matching waypipe server instance.

When run as waypipe server, it will run the command that follows in its command line invocation, set up
its own Wayland compositor socket, and try to connect to its matching waypipe client socket (by default
/tmp/waypipe-server.sock) and try to forward all the Wayland clients that connect to fake compositor
socket to the matching waypipe client.

The waypipe recon mode is used to reconnect a waypipe server instance which has had a control pipe
(option --control) set. The new socket path should indicate a Unix socket whose connections are forwarded
to the waypipe client that the waypipe server was initially connected to.

The waypipe bench mode can be used to estimate, given a specific connection bandwidth in MB/sec, which
compression options produce the lowest latency. It tests two synthetic images, one made to be roughly as
compressible as images containing text, and one made to be roughly as compressible as images containing
pictures.

OPTIONS

-c C, --compress C
Select the compression method applied to data transfers. Options are none (for high-bandwidth
networks), lz4 (intermediate), zstd (slow connection). The default compression is lz4.† The
compression level can be chosen by appending = followed by a number. For example, if C is zstd=7,
waypipe will use level 7 Zstd compression.

† Unless waypipe is built without LZ4 support, in which case the default compression will be none.

-d, --debug
Print debug log messages.

-h, --help
Show help message and quit.

-n, --no-gpu
Block protocols like wayland-drm and linux-dmabuf which require access to e.g. render nodes.

-o, --oneshot
Only permit a single connection, and exit when it is closed.

-s S, --socket S
Use S as the path for the Unix socket. The default socket path for server mode is /tmp/waypipe-
server.sock; for client mode, it is /tmp/waypipe-client.sock; and in ssh mode, S gives the prefix
used by both the client and the server for their socket paths. The default prefix in ssh mode is
/tmp/waypipe.

When vsock is enabled use S to specify a CID and a port number.

--version
Briefly describe Waypipe's version and the features it was built with, then quit. Possible features:
LZ4 compression support, ZSTD compression support, ability to transfer DMABUFs, video compression
support, VAAPI hardware video de/encoding support.

--allow-tiled
By default, waypipe filters out all advertised DMABUF formats which have format layout modifiers, as
CPU access to these formats may be very slow. Setting this flag disables the filtering. Since tiled
images often permit faster GPU operations, most OpenGL applications will select tiling modifiers when
they are available.

--control C
For server or ssh mode, provide the path to the "control pipe" that will be created the the server.
Writing (with waypipe recon C T, or 'echo -n T > C') a new socket path to this pipe will make the
server instance replace all running connections with connections to the new Unix socket. The new
socket should ultimately forward data to the same waypipe client that the server was connected to
before.

--display D
For server or ssh mode, provide WAYLAND_DISPLAY and let waypipe configure its Wayland display socket
to have a matching path. (If D is not an absolute path, the socket will be created in the folder
given by the environment variable XDG_RUNTIME_DIR.)

--drm-node R
Specify the path R to the drm device that this instance of waypipe should use and (in server mode)
notify connecting applications about.

--remote-node R
In ssh mode, specify the path R to the drm device that the remote instance of waypipe (running in
server mode) should use.

--remote-bin R
In ssh mode, specify the path R to the waypipe binary on the remote computer, or its name if it is
available in PATH. It defaults to waypipe if this option isn’t passed.

--login-shell
Only for server mode; if no command is being run, open a login shell.

--threads T
Set the number of total threads (including the main thread) which a waypipe instance will create.
These threads will be used to parallelize compression operations. This flag is passed on to waypipe
server when given to waypipe ssh. The flag also controls the thread count for waypipe bench. The
default behavior (choosable by setting T to 0) is to use half as many threads as the computer has
hardware threads available.

--title-prefix P
Prepend P to any window titles specified using the XDG shell protocol. In ssh mode, the prefix is
applied only on the client side.

--unlink-socket
Only for server mode; on shutdown, unlink the Unix socket that waypipe connects to.

--video[=V]
Compress specific DMABUF formats using a lossy video codec. Opaque, 10-bit, and multiplanar formats,
among others, are not supported. V is a comma separated list of options to control the video
encoding. Using the --video flag without setting any options is equivalent to using the default
setting of: --video=sw,bpf=120000,h264. Later options supersede earlier ones.

sw
Use software encoding and decoding.

hw
Use hardware (VAAPI) encoding and decoding, if available. This can be finicky and may only work
with specific window buffer formats and sizes.

h264
Use H.264 encoded video.

vp9
Use VP9 encoded video.

bpf=B
Set the target bit rate of the video encoder, in units of bits per frame. B can be written as an
integer or with exponential notation; thus --video=bpf=7.5e5 is equivalent to --video=bpf=750000.

--hwvideo
Deprecated option, equivalent to --video=hw .

--vsock
Use vsock instead of unix sockets. This is used when waypipe is running in virtual machines. With
this option enabled specify a CID and a port number in S. CID is only used in the server mode and can
be omitted when connecting from a guest virtual machine to host.

--secctx S
Enable the Wayland security context protocol (client or ssh modes). Specify an application ID S that
will be attached to the security context.

EXAMPLE

       The  following  waypipe ssh subcommand will attempt to run weston-flower on the server exserv, displaying
       the result on the local system.

                waypipe ssh user@exserv weston-flower

       One can obtain similar behavior by explicitly running waypipe and ssh:

                waypipe --socket /tmp/socket-client client  &
                ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \
                     waypipe --socket /tmp/socket-server server -- weston-flower
                kill %1

       Waypipe may be run locally without an SSH connection by specifying matching socket paths. For example:

                waypipe --socket /tmp/waypipe.sock client &
                waypipe --socket /tmp/waypipe.sock server weston-simple-dmabuf-egl
                kill %1
                rm /tmp/waypipe.sock

       Using transports other than SSH is a bit more complicated. A recipe with ncat to connect to  remote  from
       computer local:

               $ waypipe --socket /tmp/waypipe-remote.sock client &
               $ ncat --ssl -lk 12345 --sh-exec 'ncat -U /tmp/waypipe-remote.sock' &
               $ ssh user@remote

               > ncat -lkU /tmp/waypipe-local.sock --sh-exec 'ncat --ssl local 12345' &
               > waypipe --display wayland-local \
                           --socket /tmp/waypipe-local.sock server -- sleep inf &
               > WAYLAND_DISPLAY=wayland-local application

       Given  a  certificate  file,  socat  can also provide an encrypted connection (remove 'verify=0' to check
       certificates):

               $ waypipe --socket /tmp/waypipe-remote.sock client &
               $ socat openssl-listen:12345,reuseaddr,cert=certificate.pem,verify=0,fork \
                   unix-connect:/tmp/waypipe-remote.sock
               $ ssh user@remote

               > socat unix-listen:/tmp/waypipe-local.sock,reuseaddr,fork \
                   openssl-connect:local:12345,verify=0 &
               > waypipe --socket /tmp/waypipe-local.sock server -- application

       Many applications require specific environment variables to use Wayland instead  of  X11.  If  ssh  isn't
       configured  to  support  loading  ~/.ssh/environment,  or  to  allow  specific  variables  to be set with
       AcceptEnv/SetEnv, one can run waypipe ssh without a command (and thereby open a login shell), or use  env
       to set the needed variables each time:

                 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin

       In some cases, one may wish to set environment variables for the waypipe server process itself; the above
       trick with env will not do this, because the env process will be a child of waypipe server, not the other
       way  around. Instead, one can use ~/.ssh/environment, or use the --remote-bin option to change the remote
       Waypipe instance to a shell script that sets the environment before running the actual waypipe program.

       Waypipe has support for reconnecting a waypipe client and a waypipe server  instance  when  whatever  was
       used  to  transfer  data  between their sockets fails. For this to work, waypipe must still be running on
       both sides of the connection. As the waypipe ssh wrapper will automatically close both the waypipe client
       and the waypipe server when the connection fails, the client and server modes must be run seprately.  For
       example,  to  persistently  forward  applications  running  on server rserv to a local Wayland compositor
       running on lserv, one would first set up a waypipe client instance on lserv,

                waypipe -s /tmp/waypipe.sock client &

       and on server rserv, establish socket forwarding and run the server

                ssh -fN -L /tmp/waypipe-lserv.sock:/tmp/waypipe.sock user@lserv
                waypipe -s /tmp/waypipe-lserv.sock --control /tmp/ctrl-lserv.pipe \
                     --display wayland-lserv server -- sleep inf &

       then set WAYLAND_DISPLAY=wayland-lserv and run the desired applications. When the ssh forwarding  breaks,
       on rserv, reconnect with

                ssh -fN -L /tmp/waypipe-lserv-2.sock:/tmp/waypipe.sock user@lserv
                waypipe recon /tmp/ctrl-lserv.pipe /tmp/waypipe-lserv-2.sock

   Running waypipe in virtual machines
       When  running  waypipe  in  virtual  machines  on the same host it is possible to use vsock for efficient
       inter-vm communication. The following scenarios are supported:

       •   Running applications on host from guest.

                host> waypipe --vsock -s 1234 client
                guest> waypipe --vsock -s 1234 server weston-terminal

       •   Running applications in a guest virtual machine from host.

                guest> waypipe --vsock -s 1234 client
                host> waypipe --vsock -s 3:1234 server weston-terminal

       In this example waypipe server connects to a virtual machine with CID 3 on port 1234.

       •   Running applications in a guest virtual machine from other guest virtual machines. When running  both
           client  and  server  in  virtual  machines  it  is possble to enable the VMADDR_FLAG_TO_HOST flag for
           sibling communication by prefixing the CID with an s:

                guest> waypipe --vsock -s 1234 client
                guest> waypipe --vsock -s s3:1234 server weston-terminal

       In this case all packets will be routed to host where they can be forwarded to  another  virtual  machine
       with a vhost-device-vsock device or some other utility.

ENVIRONMENT

       When running as a server, by default WAYLAND_DISPLAY will be set for the invoked process.

       If  the  --oneshot  flag is set, waypipe will instead set WAYLAND_SOCKET and inherit an already connected
       socketpair file descriptor to the invoked (child)  process.  Some  programs  open  and  close  a  Wayland
       connection repeatedly as part of their initialization, and will not work correctly with this flag.

EXIT STATUS

       waypipe  ssh  will exit with the exit status code from the remote command, or with return code 1 if there
       has been an error.

SECURITY

Waypipe does not provide any strong security guarantees, and connecting to untrusted servers is not
recommended. It does not filter which Wayland protocols the compositor makes available to the client
(with a few exceptions for protocols that require file descriptors which Waypipe cannot yet handle). For
example, if a Wayland compositor gives all its clients access to a screenshot or lock-screen protocol,
then proxied clients run under Waypipe can also make screenshots or lock the screen.

In general, applications are not well tested against malicious compositors, and compositors are not well
tested against malicious clients. Waypipe can connect the two, and may blindly forward denial-of-service
and other attacks.

Waypipe itself is written in C and links to compression, graphics, and video libraries; both it and these
libraries may have security bugs. Some risk can be avoided by building Waypipe with DMABUF support turned
off, or running Waypipe with the --no-gpu flag so that it does not expose graphics libraries.

waypipe ssh has no explicit protections against timing attacks; an observer to the resulting network
traffic may, by studying the size and timing of packets, learn information about the user's interaction
with a Wayland client proxied through waypipe ssh. For example: a lack of activity suggests the user is
not currently using the application, while an intermittant stream of messages from the compositor to the
client may indicate mouse movement (or maybe something else: the contents of the messages are protected
by ssh.)

The memory used by Waypipe processes may, at a given time, include Wayland messages encoding user input,
and the contents of current and recent frames drawn for application windows. Swap should be encrypted to
prevent this data from being leaked to disk.

BUGS

       File bug reports at: https://gitlab.freedesktop.org/mstoeckl/waypipe/

       Some  programs  (gnome-terminal, firefox, kate, among others) have special mechanisms to ensure that only
       one process is running at a time. Starting those programs under Waypipe while they are  running  under  a
       different  Wayland  compositor may silently open a window or tab in the original instance of the program.
       Such programs may have a command line argument to create a new instance.