3.5 KiB
Sunbeam TCP Relay v0.1
Elizabeth Evelene Amelia Diode, June 2019
AGPL v3
Oh no, what is it this time?
Sunbeam is a simple and fast multi-endpoint TCP relay for
for um
we swear we had a perfectly reasonable use in mind, but we honestly can't remember it now.
What it does
Sunbeam is a little tiny server that passes data between TCP connections.
Run at the command line, Sunbeam takes any number of local ports (numbers between 1 and 65535) and remote addresses (strings like [ip address]:[port]). For each address argument passed, Sunbeam attempts to connect to that address, and for each port argument, it listens for incoming connections on that port locally. Whenever it receives data over any connection, that data is promptly retransmitted to all other connections, save for two exceptions:
- Data is not passed between clients that connect to Sunbeam on the same port.
- Data is not passed between servers that Sunbeam connects to.
For example, Sunbeam can be used as a relay for an audio stream by giving it the address of the
stream server and a local port. Clients connecting to the local port will receive the stream
data, but if one client sends data back to Sunbeam, it will not interfere with other clients'
streams (it will, however, be relayed back to the source).
This behavior can be overridden with "loopback mode" in which Sunbeam always relays data to all
clients and servers except the one which originated the data. Sunbeam automatically goes into
loopback mode if no ports are specified, or if only one port and no addresses are specified. You
can also pass the -l flag to require Sunbeam to run in loopback mode.
General usage looks like the following:
sunbeam [-l] [local port] [remote address]:[port]
How to block IP addresses
It's 2019, and a server that can't filter incoming connections is a server that belongs to The
Enemy. That's why Sunbeam, minimal as it is, includes this functionality nonetheless.
You can create the file .nosunbeam in the directory where Sunbeam runs. Sunbeam will read it,
parse each line as an IP address (v4 or v6 are both fine), and immediately drop any incoming
connections from those addresses.
Why you can't give it domain names
Rust has a minimal stdlib. One consequence of this is the fact that there's no way to resolve a
domain name using only stdlib, without writing and entire DNS client yourself. We admit we don't
really understand how it all works, but it seems we only have two choices: live without domain
name resolution, or pull in some enormous DNS crate with 37 unstable dependencies. We choose the
former. As a result, you'll have to do your DNS resolution some other way, like by running dig
at the command line to look up the IP address for the domain you want. Yes, it's clunky, but
ergonomics are not really the biggest problem this program has either.
Why it's called that
This program is called "Sunbeam" because of a particular plot device that we thought was clever in the sci-fi novel The Three Body Problem by Cixin Liu. A character discovers that, due to a particular plasma-driven mechanism inside the sun, it's possible to use the sun as a gigantic radio amplifier at certain frequencies - all you have to do is launch a radio beam into the photosphere with enough intensity, and it bounces back out with orders of magnitude more power. That's basically what this program does - you just aim your transmitter at it and start talking, and it lets you communicate with other receivers that you normally couldn't reach.