diff --git a/doc/README.md b/doc/README.md index 992bf14..a1dbfee 100644 --- a/doc/README.md +++ b/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= --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 [] - -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 -no backends connected

no backends connected

Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.

-``` - -#### Connect a backend - -In another terminal window: -```console -$ route-cli test-server -``` - -In yet another terminal window: -```conosle -$ route-httpagent -token= -domain= -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 diff --git a/doc/quickstart.md b/doc/quickstart.md new file mode 100644 index 0000000..992bf14 --- /dev/null +++ b/doc/quickstart.md @@ -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= --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 [] + +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 +no backends connected

no backends connected

Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.

+``` + +#### Connect a backend + +In another terminal window: +```console +$ route-cli test-server +``` + +In yet another terminal window: +```conosle +$ route-httpagent -token= -domain= -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 diff --git a/doc/setup.md b/doc/setup.md new file mode 100644 index 0000000..87d4e03 --- /dev/null +++ b/doc/setup.md @@ -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 +