README.md 2.76 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

Manuel Stoeckl's avatar
Manuel Stoeckl committed
44
45
* meson (>= 0.46 or possibly earlier. a backend for it (i.e, ninja) is
  also needed)
46
* wayland (>= 1.15, to support absolute paths in WAYLAND_DISPLAY)
Manuel Stoeckl's avatar
Manuel Stoeckl committed
47
48
49
50
* wayland-protocols (>= 1.12, for the xdg-shell protocol, and others)
* libffi
* scdoc (optional, to generate a man page)
* ssh (runtime, OpenSSH >= 6.7, for Unix domain socket forwarding)
51
52
53
54
55
56

[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
57
58
59
This is just a prototype right now[0]. The source code[1], command-line
interface, project name, primary branch, and git history may yet change
completely. Bug reports and patches are always welcome.
60
61
62
63

Any of the following will crash waypipe:

* Different local/client and remote/server versions
Manuel Stoeckl's avatar
Manuel Stoeckl committed
64
65
* Applications using unexpected protocols that pass file descriptors
* Differing byte orders
66
67

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