.\" Generated by scdoc 1.11.2

.\" Complete documentation for this program is not available as a GNU info page

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.nh

.ad l

.\" Begin generated content:

.TH "waypipe" "1" "2022-11-02"

.P

.SH NAME

.P

waypipe - A transparent proxy for Wayland applications

.P

.SH SYNOPSIS

.P

\fBwaypipe\fR [options.\&.\&.\&] \fBssh\fR [ssh options] \fIdestination\fR \fIcommand.\&.\&.\&\fR

.P

\fBwaypipe\fR [options.\&.\&.\&] \fBclient\fR

.br

\fBwaypipe\fR [options.\&.\&.\&] \fBserver\fR -- \fIcommand.\&.\&.\&\fR

.br

\fBwaypipe\fR \fBrecon\fR \fIcontrol_pipe\fR \fInew_socket_path\fR

.br

\fBwaypipe\fR \fBbench\fR \fIbandwidth\fR

.br

\fBwaypipe\fR [\fB--version\fR] [\fB-h\fR, \fB--help\fR]

.P

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

.P

.P

.SH DESCRIPTION

.P

Waypipe is a proxy for Wayland clients, with the aim of supporting behavior

like \fBssh -X\fR.\&

.P

Prefixing an \fBssh .\&.\&.\&\fR command to become \fBwaypipe ssh .\&.\&.\&\fR will automatically

run \fBwaypipe\fR both locally and remotely, and modify the ssh command to set up

forwarding between the two instances of \fBwaypipe\fR.\& The remote instance

will act like a Wayland compositor, letting Wayland applications that are

run remotely be displayed locally.\&

.P

When run as \fBwaypipe client\fR, it will open a socket (by default at

\fI/tmp/waypipe-client.\&sock\fR) and will connect to the local Wayland compositor

and forward all Wayland applications which were linked to it over the socket

by a matching \fBwaypipe server\fR instance.\&

.P

When run as \fBwaypipe server\fR, 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 \fBwaypipe client\fR socket (by default

\fI/tmp/waypipe-server.\&sock\fR) and try to forward all the Wayland clients

that connect to fake compositor socket to the matching \fBwaypipe client\fR.\&

.P

The \fBwaypipe recon\fR mode is used to reconnect a \fBwaypipe server\fR instance

which has had a control pipe (option \fB--control\fR) set.\& The new socket path

should indicate a Unix socket whose connections are forwarded to the \fBwaypipe

client\fR that the \fBwaypipe server\fR was initially connected to.\&

.P

The \fBwaypipe bench\fR mode can be used to estimate, given a specific

connection \fIbandwidth\fR 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.\&

.P

.SH OPTIONS

.P

\fB-c C, --compress C\fR

.RS 4

Select the compression method applied to data transfers.\& Options are

\fInone\fR (for high-bandwidth networks), \fIlz4\fR (intermediate), \fIzstd\fR

(slow connection).\& The default compression is \fInone\fR.\&† The compression

level can be chosen by appending = followed by a number.\& For example,

if \fBC\fR is \fIzstd=7\fR, waypipe will use level 7 Zstd compression.\&

.P

† In a future version, the default will change to \fIlz4\fR.\&

.P

.RE

\fB-d, --debug\fR

.RS 4

Print debug log messages.\&

.P

.RE

\fB-h, --help\fR

.RS 4

Show help message and quit.\&

.P

.RE

\fB-n, --no-gpu\fR

.RS 4

Block protocols like wayland-drm and linux-dmabuf which require access

to e.\&g.\& render nodes.\&

.P

.RE

\fB-o, --oneshot\fR

.RS 4

Only permit a single connection, and exit when it is closed.\&

.P

.RE

\fB-s S, --socket S\fR

.RS 4

Use \fBS\fR as the path for the Unix socket.\& The default socket path for

server mode is \fI/tmp/waypipe-server.\&sock\fR; for client mode, it is

\fI/tmp/waypipe-client.\&sock\fR; and in ssh mode, \fBS\fR gives the prefix used by

both the client and the server for their socket paths.\& The default prefix

in ssh mode is \fI/tmp/waypipe\fR.\&

.P

.RE

\fB--version\fR

.RS 4

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.\&

.P

.RE

\fB--allow-tiled\fR

.RS 4

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.\&

.P

.RE

\fB--control C\fR

.RS 4

For server or ssh mode, provide the path to the "control pipe" that will

be created the the server.\& Writing (with \fBwaypipe recon C T\fR, 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.\&

.P

.RE

\fB--display D\fR

.RS 4

For server or ssh mode, provide \fIWAYLAND_DISPLAY\fR and let waypipe configure

its Wayland display socket to have a matching path.\& (If \fBD\fR is not an

absolute path, the socket will be created in the folder given by the

environment variable \fIXDG_RUNTIME_DIR\fR.\&)

.P

.RE

\fB--drm-node R\fR

.RS 4

Specify the path \fBR\fR to the drm device that this instance of waypipe should

use and (in server mode) notify connecting applications about.\&

.P

.RE

\fB--remote-node R\fR

.RS 4

In ssh mode, specify the path \fBR\fR to the drm device that the remote instance

of waypipe (running in server mode) should use.\&

.P

.RE

\fB--remote-bin R\fR

.RS 4

In ssh mode, specify the path \fBR\fR to the waypipe binary on the remote

computer, or its name if it is available in \fIPATH\fR.\& It defaults to

\fBwaypipe\fR if this option isn’t passed.\&

.P

.RE

\fB--login-shell\fR

.RS 4

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

.P

.RE

\fB--threads T\fR

.RS 4

Set the number of total threads (including the main thread) which a \fBwaypipe\fR

instance will create.\& These threads will be used to parallelize compression

operations.\& This flag is passed on to \fBwaypipe server\fR when given to \fBwaypipe

ssh\fR.\& The flag also controls the thread count for \fBwaypipe bench\fR.\& The default

behavior (choosable by setting \fBT\fR to \fI0\fR) is to use half as many threads

as the computer has hardware threads available.\&

.P

.RE

\fB--unlink-socket\fR

.RS 4

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

.P

.RE

\fB--video[=V]\fR

.RS 4

Compress specific DMABUF formats using a lossy video codec.\& Opaque, 10-bit, and

multiplanar formats, among others, are not supported.\& \fBV\fR is a comma separated 

list of options to control the video encoding.\& Using the \fB--video\fR flag without

setting any options is equivalent to using the default setting of:

\fB--video=sw,bpf=120000,h264\fR.\& Later options supersede earlier ones.\&

.P

\fBsw\fR

.RS 4

Use software encoding and decoding.\&

.P

.RE

\fBhw\fR

.RS 4

Use hardware (VAAPI) encoding and decoding, if available.\& This can be finicky

and may only work with specific window buffer formats and sizes.\&

.P

.RE

\fBh264\fR

.RS 4

Use H.\&264 encoded video.\&

.P

.RE

\fBvp9\fR

.RS 4

Use VP9 encoded video.\&

.P

.RE

\fBbpf=B\fR

.RS 4

Set the target bit rate of the video encoder, in units of bits per frame.\&

\fBB\fR can be written as an integer or with exponential notation; thus

\fB--video=bpf=7.\&5e5\fR is equivalent to \fB--video=bpf=750000\fR.\&

.P

.RE

.RE

\fB--hwvideo\fR

.RS 4

Deprecated option, equivalent to --video=hw .\&

.P

.RE

.SH EXAMPLE 

.P

The following \fBwaypipe ssh\fR subcommand will attempt to run \fBweston-flower\fR on

the server \fIexserv\fR, displaying the result on the local system.\&

.P

.nf

.RS 4

	waypipe ssh user@exserv weston-flower

.fi

.RE

.P

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

.P

.nf

.RS 4

	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

.fi

.RE

.P

Waypipe may be run locally without an SSH connection by specifying matching

socket paths.\& For example:

.P

.nf

.RS 4

	waypipe --socket /tmp/waypipe\&.sock client &

	waypipe --socket /tmp/waypipe\&.sock server weston-simple-dmabuf-egl

	kill %1

	rm /tmp/waypipe\&.sock

.fi

.RE

.P

Using transports other than SSH is a bit more complicated.\& A recipe with ncat

to connect to \fIremote\fR from computer \fIlocal\fR:

.P

.nf

.RS 4

    $ 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

.fi

.RE

.P

Given a certificate file, socat can also provide an encrypted connection

(remove '\&verify=0'\& to check certificates):

.P

.nf

.RS 4

    $ 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

.fi

.RE

.P

Many applications require specific environment variables to use Wayland instead

of X11.\& If ssh isn'\&t configured to support loading \fI~/.\&ssh/environment\fR, or

to allow specific variables to be set with \fIAcceptEnv\fR/\fISetEnv\fR, one can run

\fBwaypipe ssh\fR without a command (and thereby open a login shell), or use \fBenv\fR

to set the needed variables each time:

.P

.nf

.RS 4

	 waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin

.fi

.RE

.P

In some cases, one may wish to set environment variables for the \fBwaypipe

server\fR process itself; the above trick with \fBenv\fR will not do this, because the

\fBenv\fR process will be a child of \fBwaypipe server\fR, not the other way around.\&

Instead, one can use \fI~/.\&ssh/environment\fR, or use the \fB--remote-bin\fR option to

change the remote Waypipe instance to a shell script that sets the environment

before running the actual \fBwaypipe\fR program.\&

.P

Waypipe has support for reconnecting a \fBwaypipe client\fR and a \fBwaypipe server\fR

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 \fBwaypipe ssh\fR wrapper will automatically close both the \fBwaypipe client\fR

and the \fBwaypipe server\fR when the connection fails, the client and server modes

must be run seprately.\& For example, to persistently forward applications running

on server \fIrserv\fR to a local Wayland compositor running on \fIlserv\fR, one would

first set up a waypipe client instance on \fIlserv\fR,

.P

.nf

.RS 4

	waypipe -s /tmp/waypipe\&.sock client &

.fi

.RE

.P

and on server \fIrserv\fR, establish socket forwarding and run the server

.P

.nf

.RS 4

	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 &

.fi

.RE

.P

then set \fIWAYLAND_DISPLAY=wayland-lserv\fR and run the desired applications.\&

When the ssh forwarding breaks, on \fIrserv\fR, reconnect with

.P

.nf

.RS 4

	ssh -fN -L /tmp/waypipe-lserv-2\&.sock:/tmp/waypipe\&.sock user@lserv

	waypipe recon /tmp/ctrl-lserv\&.pipe /tmp/waypipe-lserv-2\&.sock

.fi

.RE

.P

.SH ENVIRONMENT

.P

When running as a server, by default \fIWAYLAND_DISPLAY\fR will be set for the

invoked process.\&

.P

If the \fB--oneshot\fR flag is set, waypipe will instead set \fIWAYLAND_SOCKET\fR 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.\&

.P

.SH EXIT STATUS

.P

\fBwaypipe ssh\fR will exit with the exit status code from the remote command, or

with return code 1 if there has been an error.\&

.P

.SH BUGS

.P

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

.P

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.\&

.P

.SH SEE ALSO

.P

\fBweston\fR(1), \fBssh\fR(1), \fBsocat(1)\fR, \fBncat(1)\fR