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
|
||||
# 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
|
||||
Project Stability: Alpha
|
||||
|
|
|
|||
|
|
@ -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