Overlay networks based on WebRTC.
weron provides lean, fast & secure overlay networks based on WebRTC.
It enables you to:
You can add weron to your Go project by running the following:
$ go get github.com/pojntfx/weron/...@latest
You can get the OCI image like so:
$ podman pull ghcr.io/pojntfx/weron
Static binaries are available on GitHub releases.
On Linux, you can install them like so:
$ curl -L -o /tmp/weron "https://github.com/pojntfx/weron/releases/latest/download/weron.linux-$(uname -m)"
$ sudo install /tmp/weron /usr/local/bin
$ sudo setcap cap_net_admin+ep /usr/local/bin/weron # This allows rootless execution
On macOS, you can use the following:
$ curl -L -o /tmp/weron "https://github.com/pojntfx/weron/releases/latest/download/weron.darwin-$(uname -m)"
$ sudo install /tmp/weron /usr/local/bin
On Windows, the following should work (using PowerShell as administrator):
PS> Invoke-WebRequest https://github.com/pojntfx/weron/releases/latest/download/weron.windows-x86_64.exe -OutFile \Windows\System32\weron.exe
You can find binaries for more operating systems and architectures on GitHub releases.
TL;DR: Join a layer 3 (IP) overlay network on the hosted signaling server with
sudo weron vpn ip --community mycommunity --password mypassword --key mykey --ips 2001:db8::1/32,192.0.2.1/24
and a layer 2 (Ethernet) overlay network withsudo weron vpn ethernet --community mycommunity --password mypassword --key mykey
weron signaler
The signaling server connects peers with each other by exchanging connection information between them. It also manages access to communities through the --password
flag of clients and can maintain persistent communities even after all peers have disconnected.
While it is possible and reasonably private (in addition to TLS, connection information is encrypted using the --key
flag of clients) to use the hosted signaling server at wss://weron.up.railway.app/
, hosting it yourself has many benefits, such as lower latency and even better privacy.
The signaling server can use an in-process broker with an in-memory database or Redis and PostgreSQL; for production use the latter configuration is strongly recommended, as it allows you to easily scale the signaling server horizontally. This is particularly important if you want to scale your server infrastructure across multiple continents, as intra-cloud backbones usually have lower latency than residential connections, which reduces the amount of time required to connect peers with each other.
It should now be reachable on ws://localhost:1337/
.
To use it in production, put this signaling server behind a TLS-enabled reverse proxy such as Caddy or Traefik. You may also either want to keep API_PASSWORD
empty to disable the management API completely or use OpenID Connect to authenticate instead; for more information, see the signaling server reference. You can also embed the signaling server in your own application using it's Go API.
weron manager
While it is possible to create ephemeral communities on a signaling server without any kind of authorization, you probably want to create a persistent community for most applications. Ephemeral communities get created and deleted automatically as clients join or leave, persistent communities will never get deleted automatically. You can manage these communities using the manager CLI.
If you want to work on your self-hosted signaling server, first set the remote address:
$ export WERON_RADDR='http://localhost:1337/'
Next, set the API password using the API_PASSWORD
env variable:
$ export API_PASSWORD='myapipassword'
If you use OIDC to authenticate, you can instead set the API password using goit like so:
$ export OIDC_CLIENT_ID='Ab7OLrQibhXUzKHGWYDFieLa2KqZmFzb' OIDC_ISSUER='https://pojntfx.eu.auth0.com/' OIDC_REDIRECT_URL='http://localhost:11337'
$ export API_KEY="$(goit)"
If we now list the communities, we see that none currently exist:
$ weron manager list
id,clients,persistent
We can create a persistent community using weron create
:
$ weron manager create --community mycommunity --password mypassword
id,clients,persistent
mycommunity,0,true
It is also possible to delete communities using weron delete
, which will also disconnect all joined peers:
$ weron manager delete --community mycommunity
For more information, see the manager reference. You can also embed the manager in your own application using its Go API.
weron chat
If you want to work on your self-hosted signaling server, first set the remote address:
$ export WERON_RADDR='ws://localhost:1337/'
The chat is an easy way to test if everything is working correctly. To join a chatroom, run the following:
$ weron chat --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
On another peer, run the following (if your signaling server is public, you can run this anywhere on the planet):
$ weron chat --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
.wss://weron.up.railway.app/
user2!
+user1@one
+user1@two
+user1@three
user2>
You can now start sending and receiving messages or add new peers to your chatroom to test the network.
For more information, see the chat reference. You can also embed the chat in your own application using its Go API.
weron utility latency
An insightful metric of your network is its latency, which you can measure with this utility; think of this as ping
, but for WebRTC. First, start the latency measurement server like so:
$ weron utility latency --community mycommunity --password mypassword --key mykey --server
On another peer, launch the client, which should start measuring the latency immediately; press CTRL C to stop it and get the total statistics:
$ weron utility latency --community mycommunity --password mypassword --key mykey
# ...
128 B written and acknowledged in 110.111µs
128 B written and acknowledged in 386.12µs
128 B written and acknowledged in 310.458µs
128 B written and acknowledged in 335.341µs
128 B written and acknowledged in 264.149µs
^CAverage latency: 281.235µs (5 packets written) Min: 110.111µs Max: 386.12µs
For more information, see the latency measurement utility reference. You can also embed the utility in your own application using its Go API.
weron utility throughput
If you want to transfer large amounts of data, your network's throughput is a key characteristic. This utility allows you to measure this metric between two nodes; think of it as iperf
, but for WebRTC. First, start the throughput measurement server like so:
$ weron utility throughput --community mycommunity --password mypassword --key mykey --server
On another peer, launch the client, which should start measuring the throughput immediately; press CTRL C to stop it and get the total statistics:
$ weron utility throughput --community mycommunity --password mypassword --key mykey
# ...
97.907 MB/s (783.253 Mb/s) (50 MB read in 510.690403ms)
64.844 MB/s (518.755 Mb/s) (50 MB read in 771.076908ms)
103.360 MB/s (826.881 Mb/s) (50 MB read in 483.745832ms)
89.335 MB/s (714.678 Mb/s) (50 MB read in 559.692495ms)
85.582 MB/s (684.657 Mb/s) (50 MB read in 584.233931ms)
^CAverage throughput: 74.295 MB/s (594.359 Mb/s) (250 MB written in 3.364971672s) Min: 64.844 MB/s Max: 103.360 MB/s
For more information, see the throughput measurement utility reference. You can also embed the utility in your own application using it's Go API.
weron vpn ip
If you want to join multiple nodes into an overlay network, the IP VPN is the best choice. It works similarly to i.e. Tailscale/WireGuard and can either dynamically allocate an IP address from a CIDR notation or statically assign one for you. On Windows, make sure to install TAP-Windows first. Also note that due to technical limitations, only one IPv4 or IPv6 network and only one VPN instance at a time is supported on Windows; on macOS, only IPv6 networks are supported and IPv4 networks are ignored. To get started, launch the VPN on the first peer:
$ sudo weron vpn ip --community mycommunity --password mypassword --key mykey --ips 2001:db8::1/64,192.0.2.1/24
{"level":"info","addr":"wss://weron.up.railway.app/","time":"2022-05-06T22:20:51+02:00","message":"Connecting to signaler"}
{"level":"info","id":"[\"2001:db8::6a/64\",\"192.0.2.107/24\"]","time":"2022-05-06T22:20:56+02:00","message":"Connected to signaler"}
On another peer, launch the VPN as well:
$ sudo weron vpn ip --community mycommunity --password mypassword --key mykey --ips 2001:db8::1/64,192.0.2.1/24
{"level":"info","addr":"wss://weron.up.railway.app/","time":"2022-05-06T22:22:30+02:00","message":"Connecting to signaler"}
{"level":"info","id":"[\"2001:db8::b9/64\",\"192.0.2.186/24\"]","time":"2022-05-06T22:22:36+02:00","message":"Connected to signaler"}
{"level":"info","id":"[\"2001:db8::6a/64\",\"192.0.2.107/24\"]","time":"2022-05-06T22:22:36+02:00","message":"Connected to peer"}
You can now communicate between the peers:
$ ping 2001:db8::b9
PING 2001:db8::b9(2001:db8::b9) 56 data bytes
64 bytes from 2001:db8::b9: icmp_seq=1 ttl=64 time=1.07 ms
64 bytes from 2001:db8::b9: icmp_seq=2 ttl=64 time=1.36 ms
64 bytes from 2001:db8::b9: icmp_seq=3 ttl=64 time=1.20 ms
64 bytes from 2001:db8::b9: icmp_seq=4 ttl=64 time=1.10 ms
^C
--- 2001:db8::b9 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3002ms
rtt min/avg/max/mdev = 1.066/1.180/1.361/0.114 ms
If you temporarily lose the network connection, the network topology changes etc. it will automatically reconnect. For more information and limitations on proprietary operating systems like macOS, see the IP VPN reference. You can also embed the utility in your own application using its Go API.
weron vpn ethernet
If you want more flexibility or work on non-IP networks, the Ethernet VPN is a good choice. It works similarly to n2n
or ZeroTier. Due to API restrictions, this VPN type is not available on macOS; use Asahi Linux, a computer that respects your freedoms or the layer 3 (IP) VPN instead. To get started, launch the VPN on the first peer:
$ sudo weron vpn ethernet --community mycommunity --password mypassword --key mykey
{"level":"info","addr":"wss://weron.up.railway.app/","time":"2022-05-06T22:42:10+02:00","message":"Connecting to signaler"}
{"level":"info","id":"fe:60:a5:8b:81:36","time":"2022-05-06T22:42:11+02:00","message":"Connected to signaler"}
If you want to add an IP address to the TAP interface, do so with iproute2
or your OS tools:
$ sudo ip addr add 192.0.2.1/24 dev tap0
$ sudo ip addr add 2001:db8::1/32 dev tap0
On another peer, launch the VPN as well:
$ sudo weron vpn ethernet --community mycommunity --password mypassword --key mykey
{"level":"info","addr":"wss://weron.up.railway.app/","time":"2022-05-06T22:52:56+02:00","message":"Connecting to signaler"}
{"level":"info","id":"b2:ac:ae:b6:32:8c","time":"2022-05-06T22:52:57+02:00","message":"Connected to signaler"}
{"level":"info","id":"fe:60:a5:8b:81:36","time":"2022-05-06T22:52:57+02:00","message":"Connected to peer"}
And add the IP addresses:
$ sudo ip addr add 192.0.2.2/24 dev tap0
$ sudo ip addr add 2001:db8::2/32 dev tap0
You can now communicate between the peers:
$ ping 2001:db8::2
PING 2001:db8::2(2001:db8::2) 56 data bytes
64 bytes from 2001:db8::2: icmp_seq=1 ttl=64 time=1.20 ms
64 bytes from 2001:db8::2: icmp_seq=2 ttl=64 time=1.14 ms
64 bytes from 2001:db8::2: icmp_seq=3 ttl=64 time=1.24 ms
^C
--- 2001:db8::2 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2002ms
rtt min/avg/max/mdev = 1.136/1.193/1.239/0.042 ms
If you temporarily lose the network connection, the network topology changes etc. it will automatically reconnect. You can also embed the utility in your own application using its Go API.
wrtcconn
It is almost trivial to build your own distributed applications with weron, similarly to how PeerJS works. Here is the core logic behind a simple echo example:
// ...
for {
select {
case id := <-ids:
log.Println("Connected to signaler", id)
case peer := <-adapter.Accept():
log.Println("Connected to peer", peer.PeerID, "and channel", peer.ChannelID)
go func() {
defer func() {
log.Println("Disconnected from peer", peer.PeerID, "and channel", peer.ChannelID)
}()
reader := bufio.NewScanner(peer.Conn)
for reader.Scan() {
log.Printf("%s", reader.Bytes())
}
}()
go func() {
for {
if _, err := peer.Conn.Write([]byte("Hello!\n")); err != nil {
return
}
time.Sleep(time.Second)
}
}()
}
}
You can either use the minimal adapter or the named adapter; the latter negotiates a username between the peers, while the former does not check for duplicates. For more information, check out the Go API and take a look at the provided examples, utilities and services in the package for examples.
🚀 That's it! We hope you enjoy using weron.
$ weron --help
Overlay networks based on WebRTC.
Find more information at:
https://github.com/pojntfx/weron
Usage:
weron [command]
Available Commands:
chat Chat over the overlay network
completion Generate the autocompletion script for the specified shell
help Help about any command
manager Manage a signaling server
signaler Start a signaling server
utility Utilities for overlay networks
vpn Join virtual private networks built on overlay networks
Flags:
-h, --help help for weron
-v, --verbose int Verbosity level (0 is disabled, default is info, 7 is trace) (default 5)
Use "weron [command] --help" for more information about a command.
All command line arguments described above can also be set using environment variables; for example, to set --max-retries
to 300
with an environment variable, use WERON_MAX_RETRIES=300
.
To contribute, please use the GitHub flow and follow our Code of Conduct.
To build and start a development version of weron locally, run the following:
$ git clone https://github.com/pojntfx/weron.git
$ cd weron
$ make depend
$ make && sudo make install
$ weron signaler # Starts the signaling server
# In another terminal
$ weron chat --raddr ws://localhost:1337 --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
# In another terminal
$ weron chat --raddr ws://localhost:1337 --community mycommunity --password mypassword --key mykey --names user1,user2,user3 --channels one,two,three
Have any questions or need help? Chat with us on Matrix!
weron (c) 2024 Felicitas Pojtinger and contributors
SPDX-License-Identifier: AGPL-3.0