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

-d, --debug

-h, --help

-n, --no-gpu

-o, --oneshot

-s S, --socket S

--version

--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]

--hwvideo

--vsock

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

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

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

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

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.

SEE ALSO¶

weston(1), ssh(1), socat(1), ncat(1)