README.md 3.66 KB
Newer Older
1
Waypipe
2
3
================================================================================

Manuel Stoeckl's avatar
Manuel Stoeckl committed
4
`waypipe` is a proxy for Wayland[0] clients. It forwards Wayland messages and
5
6
7
8
9
10
11
12
serializes changes to shared memory buffers over a single socket. This makes
application forwarding similar to `ssh -X` [1] feasible.

[0] [https://wayland.freedesktop.org/](https://wayland.freedesktop.org/)
[1] [https://unix.stackexchange.com/questions/12755/how-to-forward-x-over-ssh-to-run-graphics-applications-remotely](https://unix.stackexchange.com/questions/12755/how-to-forward-x-over-ssh-to-run-graphics-applications-remotely)

## Usage

Manuel Stoeckl's avatar
Manuel Stoeckl committed
13
14
15
`waypipe` should be installed on both the local and remote computers. There is
a user-friendly command line pattern which prefixes a call to `ssh` and
automatically sets up a reverse tunnel for protocol data. For example,
16

Manuel Stoeckl's avatar
Manuel Stoeckl committed
17
    waypipe ssh user@theserver weston-terminal
Manuel Stoeckl's avatar
Manuel Stoeckl committed
18
19
20
21
22
23

will run `ssh`, connect to `theserver`, and remotely run `weston-terminal`,
using local and remote `waypipe` processes to synchronize the shared memory
buffers used by Wayland clients between both computers. Command line arguments
before `ssh` apply only to `waypipe`; those after `ssh` belong to `ssh`.

Manuel Stoeckl's avatar
Manuel Stoeckl committed
24
Alternatively, one can launch the local and remote processes by hand, with the
Manuel Stoeckl's avatar
Manuel Stoeckl committed
25
following set of shell commands:
26

27
    /usr/bin/waypipe -s /tmp/socket-local client &
Manuel Stoeckl's avatar
Manuel Stoeckl committed
28
29
30
    ssh -R /tmp/socket-remote:/tmp/socket-local -t user@theserver \
        /usr/bin/waypipe -s /tmp/socket-remote server -- \
        /usr/bin/weston-terminal
31
32
    kill %1

Manuel Stoeckl's avatar
Manuel Stoeckl committed
33
34
35
36
37
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.

Manuel Stoeckl's avatar
Manuel Stoeckl committed
38
## Installing
39

Manuel Stoeckl's avatar
Manuel Stoeckl committed
40
Build with meson[0]. A typical incantation is
41

Manuel Stoeckl's avatar
Manuel Stoeckl committed
42
    cd /path/to/waypipe/ && cd ..
Manuel Stoeckl's avatar
Manuel Stoeckl committed
43
44
45
    mkdir build-waypipe
    meson --buildtype debugoptimized waypipe build-waypipe
    ninja -C build-waypipe install
46

Manuel Stoeckl's avatar
Manuel Stoeckl committed
47
Core build requirements:
48

49
50
* meson (build, >= 0.47. with dependencies `ninja`, `pkg-config`, `python3`)
* wayland (build, >= 1.10 for the `wl_surface::damage_buffer` request)
51
* wayland-protocols (build, >= 1.12, for the xdg-shell protocol, and others)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
52
53
54
55
56
57
58
59
60
61
62

Optional dependencies:

* liblz4 (for fast compression, >=1.7.0)
* libzstd (for slower compression, >= 0.4.6)
* libgbm (to support programs using OpenGL via DMABUFs)
* libdrm (same as for libgbm)
* ffmpeg (>=3.1, needs avcodec/avutil/swscale for lossy video encoding)
* libva (for hardware video encoding and decoding)
* scdoc (to generate a man page)
* sys/sdt.h (to provide static tracepoints for profiling)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
63
* ssh (runtime, OpenSSH >= 6.7, for Unix domain socket forwarding)
64
* libx264 (ffmpeg runtime, for software video decoding and encoding)
65
66
67
68
69
70

[0] [https://mesonbuild.com/](https://mesonbuild.com/)
[1] [https://git.sr.ht/~sircmpwn/scdoc](https://git.sr.ht/~sircmpwn/scdoc)

## Status

71
72
73
This is usable, but still somewhat unstable right now[0]. The main
development location[1], command-line interface, and wire format may yet
change completely. Bug reports and patches are always welcome.
74

Manuel Stoeckl's avatar
Manuel Stoeckl committed
75
76
77
The wire format most recently changed with version 0.7.0, and is not
compatible with earlier versions of Waypipe.

78
79
Any of the following may make waypipe crash with an error message. If
it segfaults, file a bug report!
80
81

* Different local/client and remote/server versions
Manuel Stoeckl's avatar
Manuel Stoeckl committed
82
* Differing byte orders
83
84
* Applications using unexpected protocols that pass file descriptors; file
  bug reports for these
85
86

[0] [https://mstoeckl.com/notes/gsoc/blog.html](https://mstoeckl.com/notes/gsoc/blog.html)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
87
[1] [https://gitlab.freedesktop.org/mstoeckl/waypipe/](https://gitlab.freedesktop.org/mstoeckl/waypipe/)