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