telebit-relay.js/README.md

196 lines
5.9 KiB
Markdown
Raw Normal View History

2018-05-23 11:12:39 +00:00
# Telebit Relay
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
Friends don't let friends localhost™
A server that works in combination with [Telebit Remote](https://git.coolaj86.com/coolaj86/telebit.js)
2016-09-30 22:49:08 +00:00
to allow you to serve http and https from any computer, anywhere through a secure tunnel.
2018-05-23 11:12:39 +00:00
| Sponsored by [ppl](https://ppl.family) | **Telebit Relay** | [Telebit Remote](https://git.coolaj86.com/coolaj86/telebit.js) |
2018-05-15 07:49:27 +00:00
2018-05-23 11:12:39 +00:00
Features
========
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
* [x] Expose your bits even in the harshest of network environments
* [x] NAT, Home Routers
* [x] College Dorms, HOAs
* [x] Corporate Firewalls, Public libraries, Airports
* [x] and even Airplanes, yep
* [x] Automated HTTPS (Free SSL)
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
Install
=======
Mac & Linux
-----------
Open Terminal and run this install script:
2016-09-30 22:49:08 +00:00
```bash
2018-05-25 09:02:04 +00:00
curl -fsSL https://get.telebit.cloud/relay | bash
2016-09-30 22:49:08 +00:00
```
2018-05-25 09:02:04 +00:00
Of course, feel free to inspect the install script before you run it.
2018-06-11 17:24:57 +00:00
This will install Telebit Relay to `/opt/telebit-relay` and
put a symlink to `/opt/telebit-relay/bin/telebit-relay` in `/usr/local/bin/telebit-relay`
2018-05-23 11:12:39 +00:00
for convenience.
2017-10-04 23:37:07 +00:00
2018-05-23 11:12:39 +00:00
You can customize the installation:
2017-10-04 23:37:07 +00:00
2018-05-23 11:12:39 +00:00
```bash
2018-05-25 09:02:04 +00:00
export NODEJS_VER=v10.2
2018-06-11 17:24:57 +00:00
export TELEBIT_RELAY_PATH=/opt/telebit-relay
2018-05-25 09:02:04 +00:00
curl -fsSL https://get.telebit.cloud/relay
2018-05-23 11:12:39 +00:00
```
2018-04-24 01:49:56 +00:00
2018-05-25 09:02:04 +00:00
That will change the bundled version of node.js is bundled with Telebit Relay
2018-05-23 11:12:39 +00:00
and the path to which Telebit Relay installs.
2018-04-24 01:49:56 +00:00
2018-05-25 09:02:04 +00:00
You can get rid of the tos + email and server domain name prompts by providing them right away:
```bash
2018-06-11 17:24:57 +00:00
curl -fsSL https://get.telebit.cloud/relay | bash -- jon@example.com telebit-relay.example.com
2018-05-25 09:02:04 +00:00
```
2018-05-23 11:12:39 +00:00
Windows & Node.js
-----------------
2018-04-24 01:49:56 +00:00
2018-05-23 11:12:39 +00:00
1. Install [node.js](https://nodejs.org)
2. Open _Node.js_
2018-06-11 17:24:57 +00:00
2. Run the command `npm install -g telebit-relay`
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
**Note**: Use node.js v8.x or v10.x
2016-09-30 22:49:08 +00:00
2018-06-11 17:24:57 +00:00
There is [a bug](https://github.com/nodejs/node/issues/20241) in node v9.x that causes telebit-relay to crash.
2016-09-30 22:49:08 +00:00
2018-06-14 21:21:48 +00:00
Manually Install
-----------
```bash
git clone https://git.coolaj86.com/coolaj86/telebit-relay.js.git telebit-relay
# we're very picky to due to bugs in various versions of v8, v9, and v10
export NODEJS_VER="v10.2.1"
# We can keep everything self-contained
export NPM_CONFIG_PREFIX=/opt/telebit-relay
export NODE_PATH=/opt/telebit-relay/lib/node_modules
curl -fsSL https://bit.ly/node-installer | bash -s -- --no-dev-deps
pushd /opt/telebit-relay
bin/node bin/npm install
rsync -a examples/telebit-relay.yml etc/telebit-relay.yml
rsync -a dist/etc/systemd/system/telebit-relay.service /etc/systemd/system/telebit-relay.service
popd
2018-06-14 22:22:58 +00:00
# IMPORTANT: Season the config file to taste
# IMPORTANT: change your email address and domain
2018-06-14 21:21:48 +00:00
edit /opt/telebit-relay/etc/telebit-relay.yml
2018-06-14 21:23:08 +00:00
adduser --home /opt/telebit-relay --gecos '' --disabled-password telebit >/dev/null 2>&1
2018-06-14 22:22:58 +00:00
sudo chown -R telebit:telebit /opt/telebit-relay/
2018-06-14 21:23:08 +00:00
2018-06-14 21:21:48 +00:00
systemctl daemon-reload
systemctl restart telebit-relay
systemctl status telebit-relay
journalctl -xefu telebit-relay
```
2018-05-23 11:12:39 +00:00
Usage
====
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
```bash
2018-06-11 17:24:57 +00:00
telebit-relay --config /opt/telebit-relay/etc/telebit-relay.yml
2018-05-23 11:12:39 +00:00
```
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
Options
2016-09-30 22:49:08 +00:00
2018-06-11 17:24:57 +00:00
`/opt/telebit-relay/etc/telebit-relay.yml:`
2018-05-23 11:12:39 +00:00
```
2018-06-11 17:24:57 +00:00
email: 'jon@example.com' # must be valid (for certificate recovery and security alerts)
agree_tos: true # agree to the Telebit, Greenlock, and Let's Encrypt TOSes
community_member: true # receive infrequent relevant but non-critical updates
telemetry: true # contribute to project telemetric data
secret: '' # JWT authorization secret. Generate like so:
# node -e "console.log(crypto.randomBytes(16).toString('hex'))"
servernames: # hostnames that direct to the Telebit Relay admin console
- telebit-relay.example.com
- telebit-relay.example.net
vhost: /srv/www/:hostname # securely serve local sites from this path (or false)
# (uses template string, i.e. /var/www/:hostname/public)
2018-05-25 09:02:04 +00:00
greenlock:
2018-06-11 17:24:57 +00:00
store: le-store-certbot # certificate storage plugin
config_dir: /opt/telebit-relay/etc/acme # directory for ssl certificates
2018-05-23 11:12:39 +00:00
```
2016-09-30 22:49:08 +00:00
Security
========
The bottom line: As with everything in life, there is no such thing as anonymity
2018-05-23 11:12:39 +00:00
or absolute security. Only use Telebit Relays that you trust or self-host. :D
2016-09-30 22:49:08 +00:00
2018-05-23 11:12:39 +00:00
Even though the traffic is encrypted end-to-end, you can't just trust any Telebit Relay
2016-09-30 22:49:08 +00:00
willy-nilly.
2018-05-23 11:12:39 +00:00
A man-in-the-middle attack is possible using Let's Encrypt since an evil Telebit Relay
2018-05-31 20:17:58 +00:00
would be able to complete the http-01 challenges without a problem
2016-09-30 22:49:08 +00:00
(since that's where your DNS is pointed when you use the service).
Also, the traffic could still be copied and stored for decryption is some era when quantum
computers exist (probably never).
2018-05-23 11:12:39 +00:00
Why?
====
We created this for anyone to use on their own server or VPS,
but those generally cost $5 - $20 / month and so it's probably
2018-05-25 09:02:04 +00:00
cheaper to purchase data transfer, which is only $1/month for
most people.
In keeping with our no lock-in policy, we release a version of
the server for anyone to use independently.
2018-05-23 11:12:39 +00:00
2018-06-11 17:24:57 +00:00
TODO show how to do on
2018-05-23 11:12:39 +00:00
* Node WS Tunnel (zero setup)
* Heroku (zero cost)
* Chunk Host (best deal per TB/month)
2018-05-25 09:02:04 +00:00
Useful Tidbits
===
## As a systemd service
2018-06-11 17:24:57 +00:00
`./dist/etc/systemd/system/telebit-relay.service` should be copied to `/etc/systemd/system/telebit-relay.service`.
2018-05-23 11:12:39 +00:00
2018-05-25 09:02:04 +00:00
The user and group `telebit` should be created.
## Use privileged ports without sudo
```bash
# Linux
sudo setcap 'cap_net_bind_service=+ep' $(which node)
```
2018-08-21 02:58:04 +00:00
API
===
The authentication method is abstract so that it can easily be implemented for various users and use cases.
```
// bin/telebit-relay.js
state.authenticate() // calls either state.extensions.authenticate or state.defaults.authenticate
// which, in turn, calls Server.onAuth()
state.extensions = require('../lib/extensions');
state.extensions.authenticate({
state: state // lib/relay.js in-memory state
, auth: 'xyz.abc.123' // arbitrary token, typically a JWT (default handler)
})
// lib/relay.js
Server.onAuth(state, srv, rawAuth, validatedTokenData);
```