Provide a pre-built man page on RHEL
to avoid pulling scdoc.
This commit is contained in:
Olivier Fourdan
parent
fff5a6fc4b
commit
0877ab49dc
278
waypipe.1
Normal file
278
waypipe.1
Normal file
@ -0,0 +1,278 @@
|
||||
.\" Generated by scdoc 1.11.1
|
||||
.\" 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" "2021-02-19"
|
||||
.P
|
||||
.SH NAME
|
||||
.P
|
||||
waypipe - A transparent proxy for Wayland applications
|
||||
.P
|
||||
.SH SYNOPSIS
|
||||
.P
|
||||
\fBwaypipe\fR [options.\&.\&.\&] client
|
||||
.br
|
||||
\fBwaypipe\fR [options.\&.\&.\&] server -- \fIcommand.\&.\&.\&\fR
|
||||
.br
|
||||
\fBwaypipe\fR [options.\&.\&.\&] recon \fIcontrol_pipe\fR \fInew_socket_path\fR
|
||||
.br
|
||||
\fBwaypipe\fR [options.\&.\&.\&] ssh .\&.\&.\&
|
||||
.br
|
||||
\fBwaypipe\fR [options.\&.\&.\&] bench \fIbandwidth\fR
|
||||
.P
|
||||
.SH DESCRIPTION
|
||||
.P
|
||||
waypipe is a proxy for Wayland clients, with the aim of supporting behavior
|
||||
like \fBssh -X\fR.\&
|
||||
.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
|
||||
Next, prefixing an \fBssh .\&.\&.\&\fR command to become \fBwaypipe ssh .\&.\&.\&\fR will
|
||||
automatically set up local and remote copies of \fBwaypipe\fR, as well as
|
||||
forwarding between their sockets, so that Wayland applications run remotely
|
||||
will be displayed locally.\&
|
||||
.P
|
||||
Finally, 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
|
||||
.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.\&
|
||||
.P
|
||||
.RE
|
||||
\fB-v, --version\fR
|
||||
.RS 4
|
||||
Print the version number and quit.\&
|
||||
.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.\&
|
||||
.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\fR
|
||||
.RS 4
|
||||
Compress specific DMABUF formats using a lossy video codec.\& Opaque, 10-bit, and
|
||||
multiplanar formats, among others, are not supported.\&
|
||||
.P
|
||||
.RE
|
||||
\fB--hwvideo\fR
|
||||
.RS 4
|
||||
Sets the \fB--video\fR option, and also specifies that hardware video encoding and decoding
|
||||
should be used if possible.\& Whether this option improves bandwidth use and latency
|
||||
is hardware dependent.\&
|
||||
.P
|
||||
.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
|
||||
Many applications require specific environment variables to use Wayland instead
|
||||
of X11.\& If ssh isn't configured to support loading \fI~/.\&ssh/environment\fR,
|
||||
one can use \fIenv\fR to set the needed variables each time; or run waypipe without
|
||||
a command, to use the login shell environment.\&
|
||||
.P
|
||||
.nf
|
||||
.RS 4
|
||||
waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
|
||||
.fi
|
||||
.RE
|
||||
.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 SEE ALSO
|
||||
.P
|
||||
\fBweston\fR(1), \fBssh\fR(1)
|
||||
16
waypipe.spec
16
waypipe.spec
@ -1,15 +1,20 @@
|
||||
Name: waypipe
|
||||
Version: 0.7.1
|
||||
Release: 2%{?dist}
|
||||
Release: 3%{?dist}
|
||||
Summary: Wayland forwarding proxy
|
||||
|
||||
License: MIT
|
||||
URL: https://gitlab.freedesktop.org/mstoeckl/%{name}
|
||||
Source0: https://gitlab.freedesktop.org/mstoeckl/%{name}/-/archive/v%{version}/%{name}-v%{version}.tar.gz
|
||||
%if 0%{?rhel}
|
||||
Source1: waypipe.1
|
||||
%endif
|
||||
|
||||
BuildRequires: gcc
|
||||
BuildRequires: meson
|
||||
%if !0%{?rhel}
|
||||
BuildRequires: scdoc
|
||||
%endif
|
||||
BuildRequires: pkgconfig(gbm)
|
||||
BuildRequires: pkgconfig(libdrm)
|
||||
BuildRequires: pkgconfig(liblz4)
|
||||
@ -30,12 +35,16 @@ application forwarding similar to "ssh -X" feasible.
|
||||
|
||||
|
||||
%build
|
||||
%meson -Dwith_video=disabled -Dwerror=false
|
||||
%meson -Dwith_video=disabled -Dwerror=false %{?rhel:-Dman-pages=disabled}
|
||||
%meson_build
|
||||
|
||||
|
||||
%install
|
||||
%meson_install
|
||||
%if 0%{?rhel}
|
||||
mkdir -p %{buildroot}%{_mandir}/man1/
|
||||
install -m 644 %{SOURCE1} %{buildroot}%{_mandir}/man1/
|
||||
%endif
|
||||
|
||||
|
||||
%check
|
||||
@ -50,6 +59,9 @@ application forwarding similar to "ssh -X" feasible.
|
||||
|
||||
|
||||
%changelog
|
||||
* Fri Feb 19 2021 Olivier Fourdan <ofourdan@redhat.com> - 0.7.1-3
|
||||
- Provide a pre-built man page on RHEL to avoid pulling scdoc
|
||||
|
||||
* Wed Jan 27 2021 Fedora Release Engineering <releng@fedoraproject.org> - 0.7.1-2
|
||||
- Rebuilt for https://fedoraproject.org/wiki/Fedora_34_Mass_Rebuild
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user