README.md 3.04 KB
Newer Older
1
2
3
waypipe
================================================================================

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
18
19
20
21
22
23
24
25
    waypipe ssh -C user@theserver weston-terminal

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`.

Alternatively, one can set up the local and remote processes by hand, with the
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
## Installing
34

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

Manuel Stoeckl's avatar
Manuel Stoeckl committed
37
38
39
40
    cd /path/to/waypipe/..
    mkdir build-waypipe
    meson --buildtype debugoptimized waypipe build-waypipe
    ninja -C build-waypipe install
41

Manuel Stoeckl's avatar
Manuel Stoeckl committed
42
Requirements:
43

44
* meson (build, >= 0.47. and its dependencies `ninja` and `pkg-config`)
45
* wayland (build; clients need >= 1.15 to handle absolute paths in WAYLAND_DISPLAY)
46
47
48
* wayland-protocols (build, >= 1.12, for the xdg-shell protocol, and others)
* libzstd (optional)
* liblz4 (optional)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
49
50
* libgbm (optional, to support programs using OpenGL via DMABUFs)
* libdrm (optional, same as for libgbm)
51
* ffmpeg (optional, >=3.1, needs avcodec/avutil/swscale for lossy video encoding)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
52
* scdoc (optional, to generate a man page)
53
* sys/sdt.h (optional, to provide static tracepoints for profiling)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
54
* ssh (runtime, OpenSSH >= 6.7, for Unix domain socket forwarding)
55
56
57
58
59
60

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

## Status

Manuel Stoeckl's avatar
Manuel Stoeckl committed
61
62
63
This is just a prototype right now[0]. The main development location[1],
command-line interface, and project name may yet change completely. Bug
reports and patches are always welcome.
64
65
66
67

Any of the following will crash waypipe:

* Different local/client and remote/server versions
Manuel Stoeckl's avatar
Manuel Stoeckl committed
68
69
* Applications using unexpected protocols that pass file descriptors
* Differing byte orders
70
71

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