doc: add new docs
This commit is contained in:
parent
811795d174
commit
e348ed517b
213
doc/README.md
213
doc/README.md
|
|
@ -1,209 +1,8 @@
|
||||||
Getting Started
|
# Route
|
||||||
===============
|
|
||||||
|
|
||||||
## Configuration
|
Route is a load balancer that has backends connect to the load balancer instead
|
||||||
|
of the load balancer connecting to backends. This model allows networks to be
|
||||||
|
vastly simplified, no longer having to bring in consul or another consensus layer,
|
||||||
|
no more configuration generation.
|
||||||
|
|
||||||
```shell
|
Project Stability: Alpha
|
||||||
# base configuration
|
|
||||||
BOLTDB_PATH=/routed/route.db
|
|
||||||
WEB_ADDR=:80
|
|
||||||
SSL_ADDR=:443
|
|
||||||
BACKEND_TCP_ADDR=:8757
|
|
||||||
BACKEND_KCP_ADDR=:8804
|
|
||||||
GRPC_ADDR=:7268
|
|
||||||
DOMAIN_SUFFIX=
|
|
||||||
ACME_EMAIL=
|
|
||||||
SSL_CERT_KEY=
|
|
||||||
```
|
|
||||||
|
|
||||||
Fill out the missing parts of this and save it as `.env` somewhere.
|
|
||||||
|
|
||||||
### `DOMAIN_SUFFIX`
|
|
||||||
|
|
||||||
type: string
|
|
||||||
|
|
||||||
When a domain is not supplied for a newly created route, domains will be a random
|
|
||||||
string prepended to this setting. Set up a wildcard DNS entry for this prefix pointed
|
|
||||||
to the server running routed.
|
|
||||||
|
|
||||||
Example: `.route.xeserv.us`
|
|
||||||
|
|
||||||
### `ACME_EMAIL`
|
|
||||||
|
|
||||||
type: string, email address
|
|
||||||
|
|
||||||
This email address will be used to establish an account with Let's Encrypt. By
|
|
||||||
using the ACME support route has you agree to follow all of the Let's Encrypt
|
|
||||||
terms and conditions [here][letoc].
|
|
||||||
|
|
||||||
### `SSL_CERT_KEY`
|
|
||||||
|
|
||||||
type: string, encryption key
|
|
||||||
|
|
||||||
This will be used to encrypt and decrypt all SSL certificates on the disk.
|
|
||||||
New keys can be generated by running `route generate-key`.
|
|
||||||
|
|
||||||
## Node Setup
|
|
||||||
|
|
||||||
The target node must have a direct route from the internet to TCP ports
|
|
||||||
`80`, `443`, `7268`, and `8757` and UDP port `8804`. In order they are used
|
|
||||||
for:
|
|
||||||
|
|
||||||
| kind | port | usage |
|
|
||||||
|:-- |:-- |:-- |
|
|
||||||
| tcp | `80` | plain http traffic to backends |
|
|
||||||
| tcp | `443` | https (and http/2) traffic to backends |
|
|
||||||
| tcp | `7268` | grpc interface for management |
|
|
||||||
| tcp | `8757` | backend connections |
|
|
||||||
| udp | `8804` | backend connections |
|
|
||||||
|
|
||||||
### Docker Volume Creation
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ docker volume create routed
|
|
||||||
```
|
|
||||||
|
|
||||||
### Initial Setup
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ docker run --rm -it -v routed:/routed xena/route:latest sh
|
|
||||||
(ctr)$ cd /routed
|
|
||||||
(ctr)$ route-cli token generate-root --key=<ssl cert key from above> --username=<username> --db=./route.db
|
|
||||||
Your token is e73831bc-f40a-4cd4-84a6-b6b1e4529fa2
|
|
||||||
(ctr)$ exit
|
|
||||||
```
|
|
||||||
|
|
||||||
Save this username and token as they will be very important.
|
|
||||||
|
|
||||||
### Persistent setup with runit
|
|
||||||
|
|
||||||
- Create a folder in `/etc/system` named `routed`
|
|
||||||
`# mkdir -p /etc/system/routed`
|
|
||||||
- Copy the `.env` file created above into `etc/system/routed`
|
|
||||||
- Create a file named `run` with the following contents:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
#!/bin/sh
|
|
||||||
|
|
||||||
routeVer='latest'
|
|
||||||
|
|
||||||
docker rm -f routed
|
|
||||||
sleep 2
|
|
||||||
docker run --net host --name routed --rm -it --env-file .env -v routed:/routed -e BOLTDB_PATH=/routed/route.db xena/route:$routeVer
|
|
||||||
```
|
|
||||||
|
|
||||||
```console
|
|
||||||
# chmod +X /etc/system/routed/run
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage
|
|
||||||
|
|
||||||
Change the definition of this variable as is needed for your setup. For now this must
|
|
||||||
be publicly facing but later versions of `route` will not require this. Set this in
|
|
||||||
a variable named `ROUTED_GRPC_ADDR`:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ export ROUTED_GRPC_ADDR=h.routed.xeserv.us:7268
|
|
||||||
```
|
|
||||||
|
|
||||||
Similarly, point this to the TCP backend connections port:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ export ROUTED_TCP_BACKEND_ADDR=h.routed.xeserv.us:8757
|
|
||||||
```
|
|
||||||
|
|
||||||
Next, open `~/.netrc` in your favorite editor and add the following to the end of it:
|
|
||||||
|
|
||||||
```
|
|
||||||
machine h.routed.xeserv.us:7268
|
|
||||||
login usename
|
|
||||||
password token
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Create a route
|
|
||||||
|
|
||||||
```
|
|
||||||
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create --help
|
|
||||||
‹master*!+1› »»»» ./route route create --help 0|12:57:46
|
|
||||||
usage: route route create [<flags>]
|
|
||||||
|
|
||||||
create a new route
|
|
||||||
|
|
||||||
Flags:
|
|
||||||
--help Show context-sensitive help (also try
|
|
||||||
--help-long and --help-man).
|
|
||||||
--routed-addr="127.0.0.1:7268"
|
|
||||||
routed grpc address
|
|
||||||
--netrc="/Users/xena/.netrc" netrc path
|
|
||||||
--domain=DOMAIN domain for the route (if not given one will be
|
|
||||||
generated for you)
|
|
||||||
|
|
||||||
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create
|
|
||||||
86d50f43-221d-4a57-99c9-8056dea0f12c
|
|
||||||
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route list
|
|
||||||
+--------------------------------------|--------------------------------+
|
|
||||||
| ID | HOST |
|
|
||||||
+--------------------------------------|--------------------------------+
|
|
||||||
| 86d50f43-221d-4a57-99c9-8056dea0f12c | wfall-hu-crow.routed.xeserv.us |
|
|
||||||
+--------------------------------------|--------------------------------+
|
|
||||||
$ curl -v https://wfall-hu-crow.routed.xeserv.us
|
|
||||||
> GET / HTTP/2
|
|
||||||
> Host: wfall-hu-crow.routed.xeserv.us
|
|
||||||
> User-Agent: curl/7.54.0
|
|
||||||
> Accept: */*
|
|
||||||
>
|
|
||||||
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
|
|
||||||
< HTTP/2 502
|
|
||||||
< accept: */*
|
|
||||||
< content-type: text/html; charset=utf-8
|
|
||||||
< user-agent: curl/7.54.0
|
|
||||||
< x-clacks-overhead: GNU Ashlynn
|
|
||||||
< x-forwarded-for: 24.17.183.23
|
|
||||||
< x-remote-ip: 24.17.183.23
|
|
||||||
< x-request-id: 01BVA69BJJKNSX05W4NS0PHECY
|
|
||||||
< x-request-ingress: 2017-09-30T22:05:21+02:00
|
|
||||||
< content-length: 228
|
|
||||||
< date: Sat, 30 Sep 2017 20:05:21 GMT
|
|
||||||
<
|
|
||||||
* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact
|
|
||||||
<html><head><title>no backends connected</title></head><body><h1>no backends connected</h1><p>Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.</p></body></html>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Connect a backend
|
|
||||||
|
|
||||||
In another terminal window:
|
|
||||||
```console
|
|
||||||
$ route-cli test-server
|
|
||||||
```
|
|
||||||
|
|
||||||
In yet another terminal window:
|
|
||||||
```conosle
|
|
||||||
$ route-httpagent -token=<token from above> -domain=<domain from above> -server=$ROUTED_TCP_BACKEND_ADDR
|
|
||||||
```
|
|
||||||
|
|
||||||
Now to your main terminal window:
|
|
||||||
```console
|
|
||||||
$ curl -v https://wfall-hu-crow.routed.xeserv.us
|
|
||||||
> GET / HTTP/2
|
|
||||||
> Host: wfall-hu-crow.route.xeserv.us
|
|
||||||
> User-Agent: curl/7.54.0
|
|
||||||
> Accept: */*
|
|
||||||
>
|
|
||||||
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
|
|
||||||
< HTTP/2 200
|
|
||||||
< content-type: text/plain; charset=utf-8
|
|
||||||
< date: Sat, 30 Sep 2017 20:15:59 GMT
|
|
||||||
< x-clacks-overhead: GNU Ashlynn
|
|
||||||
< x-request-id: 01BVA6WT90M20ZH6NVSKYT68SS
|
|
||||||
< content-length: 298
|
|
||||||
<
|
|
||||||
Route is go!
|
|
||||||
map[X-Forwarded-For:[24.17.183.23, 193.164.132.229] X-Request-Id:[01BVA6WT90M20ZH6NVSKYT68SS] Accept-Encoding:[gzip] User-Agent:[curl/7.54.0] Accept:[*/*] X-Remote-Ip:[24.17.183.23] X-Request-Ingress:[2017-09-30T22:15:59+02:00]]
|
|
||||||
Served by cadance-3.local running darwin
|
|
||||||
* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact
|
|
||||||
Hit count: 1617
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[letoc]: https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,209 @@
|
||||||
|
Getting Started
|
||||||
|
===============
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# base configuration
|
||||||
|
BOLTDB_PATH=/routed/route.db
|
||||||
|
WEB_ADDR=:80
|
||||||
|
SSL_ADDR=:443
|
||||||
|
BACKEND_TCP_ADDR=:8757
|
||||||
|
BACKEND_KCP_ADDR=:8804
|
||||||
|
GRPC_ADDR=:7268
|
||||||
|
DOMAIN_SUFFIX=
|
||||||
|
ACME_EMAIL=
|
||||||
|
SSL_CERT_KEY=
|
||||||
|
```
|
||||||
|
|
||||||
|
Fill out the missing parts of this and save it as `.env` somewhere.
|
||||||
|
|
||||||
|
### `DOMAIN_SUFFIX`
|
||||||
|
|
||||||
|
type: string
|
||||||
|
|
||||||
|
When a domain is not supplied for a newly created route, domains will be a random
|
||||||
|
string prepended to this setting. Set up a wildcard DNS entry for this prefix pointed
|
||||||
|
to the server running routed.
|
||||||
|
|
||||||
|
Example: `.route.xeserv.us`
|
||||||
|
|
||||||
|
### `ACME_EMAIL`
|
||||||
|
|
||||||
|
type: string, email address
|
||||||
|
|
||||||
|
This email address will be used to establish an account with Let's Encrypt. By
|
||||||
|
using the ACME support route has you agree to follow all of the Let's Encrypt
|
||||||
|
terms and conditions [here][letoc].
|
||||||
|
|
||||||
|
### `SSL_CERT_KEY`
|
||||||
|
|
||||||
|
type: string, encryption key
|
||||||
|
|
||||||
|
This will be used to encrypt and decrypt all SSL certificates on the disk.
|
||||||
|
New keys can be generated by running `route generate-key`.
|
||||||
|
|
||||||
|
## Node Setup
|
||||||
|
|
||||||
|
The target node must have a direct route from the internet to TCP ports
|
||||||
|
`80`, `443`, `7268`, and `8757` and UDP port `8804`. In order they are used
|
||||||
|
for:
|
||||||
|
|
||||||
|
| kind | port | usage |
|
||||||
|
|:-- |:-- |:-- |
|
||||||
|
| tcp | `80` | plain http traffic to backends |
|
||||||
|
| tcp | `443` | https (and http/2) traffic to backends |
|
||||||
|
| tcp | `7268` | grpc interface for management |
|
||||||
|
| tcp | `8757` | backend connections |
|
||||||
|
| udp | `8804` | backend connections |
|
||||||
|
|
||||||
|
### Docker Volume Creation
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ docker volume create routed
|
||||||
|
```
|
||||||
|
|
||||||
|
### Initial Setup
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ docker run --rm -it -v routed:/routed xena/route:latest sh
|
||||||
|
(ctr)$ cd /routed
|
||||||
|
(ctr)$ route-cli token generate-root --key=<ssl cert key from above> --username=<username> --db=./route.db
|
||||||
|
Your token is e73831bc-f40a-4cd4-84a6-b6b1e4529fa2
|
||||||
|
(ctr)$ exit
|
||||||
|
```
|
||||||
|
|
||||||
|
Save this username and token as they will be very important.
|
||||||
|
|
||||||
|
### Persistent setup with runit
|
||||||
|
|
||||||
|
- Create a folder in `/etc/system` named `routed`
|
||||||
|
`# mkdir -p /etc/system/routed`
|
||||||
|
- Copy the `.env` file created above into `etc/system/routed`
|
||||||
|
- Create a file named `run` with the following contents:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
routeVer='latest'
|
||||||
|
|
||||||
|
docker rm -f routed
|
||||||
|
sleep 2
|
||||||
|
docker run --net host --name routed --rm -it --env-file .env -v routed:/routed -e BOLTDB_PATH=/routed/route.db xena/route:$routeVer
|
||||||
|
```
|
||||||
|
|
||||||
|
```console
|
||||||
|
# chmod +X /etc/system/routed/run
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Change the definition of this variable as is needed for your setup. For now this must
|
||||||
|
be publicly facing but later versions of `route` will not require this. Set this in
|
||||||
|
a variable named `ROUTED_GRPC_ADDR`:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ export ROUTED_GRPC_ADDR=h.routed.xeserv.us:7268
|
||||||
|
```
|
||||||
|
|
||||||
|
Similarly, point this to the TCP backend connections port:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ export ROUTED_TCP_BACKEND_ADDR=h.routed.xeserv.us:8757
|
||||||
|
```
|
||||||
|
|
||||||
|
Next, open `~/.netrc` in your favorite editor and add the following to the end of it:
|
||||||
|
|
||||||
|
```
|
||||||
|
machine h.routed.xeserv.us:7268
|
||||||
|
login usename
|
||||||
|
password token
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Create a route
|
||||||
|
|
||||||
|
```
|
||||||
|
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create --help
|
||||||
|
‹master*!+1› »»»» ./route route create --help 0|12:57:46
|
||||||
|
usage: route route create [<flags>]
|
||||||
|
|
||||||
|
create a new route
|
||||||
|
|
||||||
|
Flags:
|
||||||
|
--help Show context-sensitive help (also try
|
||||||
|
--help-long and --help-man).
|
||||||
|
--routed-addr="127.0.0.1:7268"
|
||||||
|
routed grpc address
|
||||||
|
--netrc="/Users/xena/.netrc" netrc path
|
||||||
|
--domain=DOMAIN domain for the route (if not given one will be
|
||||||
|
generated for you)
|
||||||
|
|
||||||
|
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create
|
||||||
|
86d50f43-221d-4a57-99c9-8056dea0f12c
|
||||||
|
$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route list
|
||||||
|
+--------------------------------------|--------------------------------+
|
||||||
|
| ID | HOST |
|
||||||
|
+--------------------------------------|--------------------------------+
|
||||||
|
| 86d50f43-221d-4a57-99c9-8056dea0f12c | wfall-hu-crow.routed.xeserv.us |
|
||||||
|
+--------------------------------------|--------------------------------+
|
||||||
|
$ curl -v https://wfall-hu-crow.routed.xeserv.us
|
||||||
|
> GET / HTTP/2
|
||||||
|
> Host: wfall-hu-crow.routed.xeserv.us
|
||||||
|
> User-Agent: curl/7.54.0
|
||||||
|
> Accept: */*
|
||||||
|
>
|
||||||
|
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
|
||||||
|
< HTTP/2 502
|
||||||
|
< accept: */*
|
||||||
|
< content-type: text/html; charset=utf-8
|
||||||
|
< user-agent: curl/7.54.0
|
||||||
|
< x-clacks-overhead: GNU Ashlynn
|
||||||
|
< x-forwarded-for: 24.17.183.23
|
||||||
|
< x-remote-ip: 24.17.183.23
|
||||||
|
< x-request-id: 01BVA69BJJKNSX05W4NS0PHECY
|
||||||
|
< x-request-ingress: 2017-09-30T22:05:21+02:00
|
||||||
|
< content-length: 228
|
||||||
|
< date: Sat, 30 Sep 2017 20:05:21 GMT
|
||||||
|
<
|
||||||
|
* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact
|
||||||
|
<html><head><title>no backends connected</title></head><body><h1>no backends connected</h1><p>Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.</p></body></html>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Connect a backend
|
||||||
|
|
||||||
|
In another terminal window:
|
||||||
|
```console
|
||||||
|
$ route-cli test-server
|
||||||
|
```
|
||||||
|
|
||||||
|
In yet another terminal window:
|
||||||
|
```conosle
|
||||||
|
$ route-httpagent -token=<token from above> -domain=<domain from above> -server=$ROUTED_TCP_BACKEND_ADDR
|
||||||
|
```
|
||||||
|
|
||||||
|
Now to your main terminal window:
|
||||||
|
```console
|
||||||
|
$ curl -v https://wfall-hu-crow.routed.xeserv.us
|
||||||
|
> GET / HTTP/2
|
||||||
|
> Host: wfall-hu-crow.route.xeserv.us
|
||||||
|
> User-Agent: curl/7.54.0
|
||||||
|
> Accept: */*
|
||||||
|
>
|
||||||
|
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
|
||||||
|
< HTTP/2 200
|
||||||
|
< content-type: text/plain; charset=utf-8
|
||||||
|
< date: Sat, 30 Sep 2017 20:15:59 GMT
|
||||||
|
< x-clacks-overhead: GNU Ashlynn
|
||||||
|
< x-request-id: 01BVA6WT90M20ZH6NVSKYT68SS
|
||||||
|
< content-length: 298
|
||||||
|
<
|
||||||
|
Route is go!
|
||||||
|
map[X-Forwarded-For:[24.17.183.23, 193.164.132.229] X-Request-Id:[01BVA6WT90M20ZH6NVSKYT68SS] Accept-Encoding:[gzip] User-Agent:[curl/7.54.0] Accept:[*/*] X-Remote-Ip:[24.17.183.23] X-Request-Ingress:[2017-09-30T22:15:59+02:00]]
|
||||||
|
Served by cadance-3.local running darwin
|
||||||
|
* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact
|
||||||
|
Hit count: 1617
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[letoc]: https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Setup
|
||||||
|
|
||||||
|
## Common
|
||||||
|
|
||||||
|
- create `.env` file
|
||||||
|
- create database and initial token
|
||||||
|
|
||||||
|
## Alpine Linux
|
||||||
|
|
||||||
|
- add xeserv alpine repo + keys
|
||||||
|
- install routed
|
||||||
|
- set up an init script
|
||||||
|
|
||||||
|
## Docker
|
||||||
|
|
||||||
|
- create service
|
||||||
|
- put `.env` in the service
|
||||||
|
- start routed with --net=host
|
||||||
|
|
||||||
Loading…
Reference in New Issue