diff --git a/.gitignore b/.gitignore index f3b5d93..195d446 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ /waypipe-v0.7.1.tar.gz /waypipe-v0.8.0.tar.gz /waypipe-v0.8.2.tar.gz +/waypipe-v0.8.4.tar.gz diff --git a/sources b/sources index 61607c4..38b180c 100644 --- a/sources +++ b/sources @@ -1 +1 @@ -SHA512 (waypipe-v0.8.2.tar.gz) = c942b04a1f8cea60b226533b3c300120257d1264e3c0ed929cc79e35a3d8ba7ca215e52b46fc004a042016f5d492fa0291cec3a547b696fad4c99ae7bf5544bf +SHA512 (waypipe-v0.8.4.tar.gz) = f0b1091b396b19bde519f008ae15e68b566201a110d439172f4d328576af145b94d43caed4c8744dbd71ba253a9d2275c52933ae28be12c74939dfe2123b3966 diff --git a/waypipe.1 b/waypipe.1 index d989e95..cc0ec6b 100644 --- a/waypipe.1 +++ b/waypipe.1 @@ -1,11 +1,11 @@ -.\" Generated by scdoc 1.11.1 +.\" 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" "2021-02-19" +.TH "waypipe" "1" "2022-11-02" .P .SH NAME .P @@ -13,21 +13,32 @@ waypipe - A transparent proxy for Wayland applications .P .SH SYNOPSIS .P -\fBwaypipe\fR [options.\&.\&.\&] client +\fBwaypipe\fR [options.\&.\&.\&] \fBssh\fR [ssh options] \fIdestination\fR \fIcommand.\&.\&.\&\fR +.P +\fBwaypipe\fR [options.\&.\&.\&] \fBclient\fR .br -\fBwaypipe\fR [options.\&.\&.\&] server -- \fIcommand.\&.\&.\&\fR +\fBwaypipe\fR [options.\&.\&.\&] \fBserver\fR -- \fIcommand.\&.\&.\&\fR .br -\fBwaypipe\fR [options.\&.\&.\&] recon \fIcontrol_pipe\fR \fInew_socket_path\fR +\fBwaypipe\fR \fBrecon\fR \fIcontrol_pipe\fR \fInew_socket_path\fR .br -\fBwaypipe\fR [options.\&.\&.\&] ssh .\&.\&.\& +\fBwaypipe\fR \fBbench\fR \fIbandwidth\fR .br -\fBwaypipe\fR [options.\&.\&.\&] bench \fIbandwidth\fR +\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 +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 @@ -44,12 +55,7 @@ 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 +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 @@ -61,10 +67,12 @@ compressible as images containing pictures.\& .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 +(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 @@ -92,12 +100,16 @@ Only permit a single connection, and exit when it is closed.\& 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.\& +both the client and the server for their socket paths.\& The default prefix +in ssh mode is \fI/tmp/waypipe\fR.\& .P .RE -\fB-v, --version\fR +\fB--version\fR .RS 4 -Print the version number and quit.\& +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 @@ -113,7 +125,7 @@ when they are available.\& .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 +\&'\&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.\& @@ -156,7 +168,9 @@ Only for server mode; if no command is being run, open a login shell.\& 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.\& +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 @@ -164,18 +178,46 @@ ssh\fR.\& The flag also controls the thread count for \fBwaypipe bench\fR.\& Only for server mode; on shutdown, unlink the Unix socket that waypipe connects to.\& .P .RE -\fB--video\fR +\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.\& +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 -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 +Deprecated option, equivalent to --video=hw .\& .P .RE .SH EXAMPLE @@ -200,7 +242,7 @@ One can obtain similar behavior by explicitly running waypipe and ssh: .fi .RE .P -Waypipe may be run locally without an ssh connection by specifying matching +Waypipe may be run locally without an SSH connection by specifying matching socket paths.\& For example: .P .nf @@ -212,10 +254,43 @@ socket paths.\& For example: .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, -one can use \fIenv\fR to set the needed variables each time; or run waypipe without -a command, to use the login shell environment.\& +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 @@ -223,6 +298,13 @@ a command, to use the login shell environment.\& .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.\& @@ -273,6 +355,17 @@ of their initialization, and will not work correctly with this flag.\& \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) +\fBweston\fR(1), \fBssh\fR(1), \fBsocat(1)\fR, \fBncat(1)\fR diff --git a/waypipe.spec b/waypipe.spec index 5f1071c..26494e4 100644 --- a/waypipe.spec +++ b/waypipe.spec @@ -1,6 +1,6 @@ Name: waypipe -Version: 0.8.2 -Release: 2%{?dist} +Version: 0.8.4 +Release: 1%{?dist} Summary: Wayland forwarding proxy License: MIT @@ -59,6 +59,9 @@ install -m 644 %{SOURCE1} %{buildroot}%{_mandir}/man1/ %changelog +* Wed Nov 02 2022 Olivier Fourdan - 0.8.4-1 +- Update to 0.8.4 + * Sat Jul 23 2022 Fedora Release Engineering - 0.8.2-2 - Rebuilt for https://fedoraproject.org/wiki/Fedora_37_Mass_Rebuild