Commit c859406e authored by Manuel Stoeckl's avatar Manuel Stoeckl
Browse files

Document reconnection support

parent ac260f33
Pipeline #51625 passed with stages
in 1 minute and 1 second
......@@ -30,6 +30,11 @@ following set of shell commands:
/usr/bin/weston-terminal
kill %1
It's possible to set up the local and remote processes so that, when the
connection between the the sockets used by each end breaks, one can create
a new forwarded socket on the remote side and reconnect the two processes.
For a more detailed example, see the man page.
## Installing
Build with meson[0]. A typical incantation is
......
......@@ -67,8 +67,8 @@ static const char usage_string[] =
" a socket to a matching 'waypipe client' instance.\n"
" client Run locally to create a Unix socket to which 'waypipe server'\n"
" instances can connect.\n"
" recon C T Reconnect a broken connection; C is the control pipe, T is\n"
" the new Unix socket path. Writes null-terminated T to C.\n"
" recon C T Reconnect a 'waypipe server' instance. Writes the new Unix\n"
" socket path T to the control pipe C.\n"
"\n"
"Options:\n"
" -c, --compress C select compression method from: lz4, zstd, none\n"
......@@ -79,16 +79,16 @@ static const char usage_string[] =
" -s, --socket S set the socket path to either create or connect to:\n"
" server default: /tmp/waypipe-server.sock\n"
" client default: /tmp/waypipe-client.sock\n"
" ssh mode: sets the prefix for the socket path\n"
" ssh: sets the prefix for the socket path\n"
" -v, --version print waypipe version and exit\n"
" --control C server,ssh mode: set the reconnection pipe path\n"
" --display D server,ssh mode: set the Wayland display name or path\n"
" --control C server,ssh: set control pipe to reconnect server\n\n"
" --display D server,ssh: the Wayland display name or path\n"
" --drm-node R set the local render node. default: /dev/dri/renderD128\n"
" --remote-node R ssh mode: set the remote render node path\n"
" --remote-node R ssh: set the remote render node path\n"
" --linear-dmabuf only permit gpu buffers without modifier flags\n"
" --login-shell server mode: if server CMD is empty, run a login shell\n"
" --login-shell server: if server CMD is empty, run a login shell\n"
" --threads T set thread pool size, default=hardware threads/2\n"
" --unlink-socket server mode: unlink the socket that waypipe connects to\n"
" --unlink-socket server: unlink the socket that waypipe connects to\n"
" --video compress certain linear dmabufs only with a video codec\n"
" --hwvideo use --video, and try hardware enc/decoding if available\n"
"\n";
......
......@@ -7,7 +7,8 @@ waypipe - A transparent proxy for Wayland applications
# SYNOPSIS
*waypipe* [options...] client++
*waypipe* [options...] server -- command++
*waypipe* [options...] server -- _command..._++
*waypipe* [options...] recon _control_pipe_ _new_socket_path_++
*waypipe* [options...] ssh ...
# DESCRIPTION
......@@ -26,6 +27,11 @@ 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.
Finally, prefixing an *ssh ...* command to become *waypipe ssh ...* will
automatically set up local and remote copies of *waypipe*, as well as
forwarding between their sockets, so that Wayland applications run remotely
......@@ -60,6 +66,14 @@ will be displayed locally.
*-v, --version*
Print the version number and quit.
*--control C*
For server or ssh mode, provide the path to the "control pipe" that will
be created the the server. Writing (with *waypipe recon C T*, 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.
*--display D*
For server or ssh mode, provide _WAYLAND_DISPLAY_ and let waypipe configure
its Wayland display socket to have a matching path. (If *D* is not an
......@@ -115,7 +129,7 @@ One can obtain similar behavior by explictly running waypipe and ssh:
```
waypipe --socket /tmp/socket-client client &
ssh -R/tmp/socket-server:/tmp/socket-client user@exserv \
ssh -R /tmp/socket-server:/tmp/socket-client user@exserv \\
waypipe --socket /tmp/socket-server server -- weston-flower
kill %1
```
......@@ -139,6 +153,35 @@ a command, to use the login shell environment.
waypipe ssh user@host env XDG_SESSION_TYPE=wayland dolphin
```
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
```
# ENVIRONMENT
When running as a server, by default _WAYLAND_DISPLAY_ will be set for the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment