From 0d02769ff0cf0fbc74ceedccb07e8d9d0d99803a Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Fri, 13 Nov 2020 04:26:25 -0700 Subject: [PATCH] update docs --- .goreleaser.yml | 2 + README.md | 94 ++++++++++++++--- cmd/mgmt/README.md | 180 +++++++++++++++++++++++---------- cmd/signjwt/signjwt.go | 4 +- cmd/telebit/README.md | 98 +++++++++++++----- examples/mgmt-add-device.sh | 2 +- examples/mgmt-remove-device.sh | 2 +- examples/mgmt.env | 6 +- 8 files changed, 285 insertions(+), 103 deletions(-) diff --git a/.goreleaser.yml b/.goreleaser.yml index 32cd2ae..3dd900d 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -38,6 +38,8 @@ archives: format_overrides: - goos: windows format: zip +env_files: + github_token: ~/.config/goreleaser/github_token.txt checksum: name_template: 'checksums.txt' snapshot: diff --git a/README.md b/README.md index f20af92..40a18ac 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,11 @@ export ACME_EMAIL=johndoe@example.com # --vendor-id export VENDOR_ID=example.com # --secret -export SECRET=QQgPyfzVdxJTcUc1ceot3pgJFKtWSHMQ +export SECRET=YY-device-shared-secret-YY # --tunnel-relay export TUNNEL_RELAY_URL=https://tunnel.example.com/ +# --locals +export LOCALS=https:*:3000 # --tls-locals export TLS_LOCALS=https:*:3000 ``` @@ -34,21 +36,79 @@ See [`examples/client.env`][client-env] for detail explanations. [client-env]: /tree/master/examples/client.env +### System Services + +You can use `serviceman` to run `postgres`, `telebit`, and `telebit-mgmt` as system services + +```bash +curl -fsS https://webinstall.dev/serviceman | bash +``` + +See the Cheat Sheet at https://webinstall.dev/serviceman + +You can, of course, configure systemd (or whatever) by hand if you prefer. + +## Example Local Web Application + +The simplest way to test the tunnel is with a local web server. + +```bash +mkdir -p tmp-app +pushd tmp-app/ + +cat << EOF > index.html +Hello, World! +EOF +``` + +### Ex: Caddy + +```bash +curl -sS https://webinstall.dev/caddy | bash +``` + +```bash +caddy file-server --browse --listen :3000 +``` + +### Ex: Python 3 + +```bash +python3 -m http.server 3000 +``` + # Build +```bash +git clone ssh://git@git.rootprojects.org:root/telebit.git +pushd telebit/ +``` + +You can build with `go build`: + +```bash +go build -mod vendor -race -o telebit cmd/telebit/telebit.go +``` + +Or with `goreleaser`: + ```bash goreleaser --rm-dist --skip-publish --snapshot ``` ## Install Go -Installs Go to `~/.local/opt/go` for MacOS and Linux: +To install Go (on any of Windows, Mac, or Linux), see . + +Installs Go to `~/.local/opt/go`. + +**Mac, Linux**: ```bash curl -fsS https://webinstall.dev/golang | bash ``` -Windows 10: +**Windows 10**: ```bash curl.exe -fsSA "MS" https://webinstall.dev/golang | powershell @@ -73,25 +133,27 @@ The binary can be built with `VENDOR_ID` and `CLIENT_SECRET` built into the bina You can also change the `serviceName` and `serviceDescription` at build time. See `examples/run-as-client.sh`. -## Local Web Application - -Currently only raw TCP is tunneled. - -This means that either the application must handle and terminate encrypted TLS connections, or use HTTP (instead of HTTPS). -This will be available in the next release. +## White Label Builds ```bash -mkdir -p tmp-app -pushd tmp-app/ +go generate ./... -cat << EOF > index.html -Hello, World! -EOF +VENDOR_ID="example.com" -python3 -m http.server 3000 +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build \ + -mod=vendor \ + -ldflags="-X 'main.VendorID=$VENDOR_ID'" \ + -o telebit-debug.exe \ + ./cmd/telebit/telebit.go + +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build \ + -mod=vendor \ + -ldflags "-H windowsgui -X 'main.VendorID=$VENDOR_ID'" \ + -o telebit-windows.exe \ + ./cmd/telebit/telebit.go ``` -## Help +# Help ``` Usage of telebit: diff --git a/cmd/mgmt/README.md b/cmd/mgmt/README.md index e543196..3352c9a 100644 --- a/cmd/mgmt/README.md +++ b/cmd/mgmt/README.md @@ -1,65 +1,116 @@ # Telebit Mgmt -# Config +| [Telebit Client](../../) | [Telebit Relay](../telebit) | **Telebit Mgmt** | + +Device Management, Authorization, and ACME Relay Server. + +# Usage + +This does not need to be on a public port for client devices, +but it must be directly accessible by the telebit relay. + +It must also run on port 80 if HTTP-01 challenges are being relayed. + +This should be https-enabled unless on localhost behind the telebit relay. ```bash -VERBOSE= - -PORT=6468 - -# JWT Verification Secret -#SECRET=XxxxxxxxxxxxxxxX - -DB_URL=postgres://postgres:postgres@localhost:5432/postgres -DOMAIN=mgmt.example.com -TUNNEL_DOMAIN=tunnel.example.com - -NAMECOM_USERNAME=johndoe -NAMECOM_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +./telebit-mgmt ``` -## API +```bash +# allow access to privileged ports +sudo setcap 'cap_net_bind_service=+ep' ./telebit-mgmt +``` + +Command-line flags or `.env` may be used. + +```bash +# --secret +export SECRET=XxX-mgmt-secret-XxX +# --domain +export DOMAIN=devices.example.com +# --tunnel-domain +export TUNNEL_DOMAIN=tunnel.example.com +# --db-url +export DB_URL=postgres://postgres:postgres@localhost:5432/postgres +# --port +export PORT=6468 +``` + +See `./telebit --help` for all options. \ +See [`examples/mgmt.env`][mgmt-env] for detail explanations. + +[mgmt-env]: /../../examples/mgmt.env + +## System Services + +You can use `serviceman` to run `postgres`, `telebit`, and `telebit-mgmt` as system services + +```bash +curl -fsS https://webinstall.dev/serviceman | bash +``` + +See the Cheat Sheet at https://webinstall.dev/serviceman + +You can, of course, configure systemd (or whatever) by hand if you prefer. + +## Install Postgres + +Install postgres and start it as a service on MacOS and Linux: + +```bash +curl -sS https://webinstall.dev/postgres | bash +``` + +```bash +sudo env PATH="$PATH" \ + serviceman add --system --username $(whoami) --name postgres -- \ + postgres -D "$HOME/.local/share/postgres/var" -p 5432 +``` + +See the Cheat Sheet at https://webinstall.dev/postgres + +## Create Admin Token + +The admin token can be used to interact with the server. + +```bash +VENDOR_ID="example.com" +MGMT_SECRET=XxX-mgmt-secret-XxX +ADMIN_TOKEN=$(go run cmd/signjwt/signjwt.go \ + --debug \ + --expires-in 15m \ + --vendor-id $VENDOR_ID \ + --secret $MGMT_SECRET \ + --machine-ppid $MGMT_SECRET +) +``` + +## Register New Device + +This will return a new shared secret that can be used to register a new client device. + +```bash +my_subdomain="foobar" +my_mgmt_host=https://mgmt.example.com + +curl -X POST $my_mgmt_host/api/devices \ + -H "Authorization: Bearer ${ADMIN_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ "slug": "'$my_subdomain'" }' +``` + +# API ```bash my_subdomain="ruby" -curl -X DELETE http://mgmt.example.com:3010/api/subscribers/ruby" -H "Authorization: Bearer ${TOKEN}" +curl -X DELETE http://mgmt.example.com:6468/api/subscribers/ruby" -H "Authorization: Bearer ${TOKEN}" ``` ```json { "success": true } ``` -# Build - -```bash -go generate -mod vendor ./... - -pushd cmd/mgmt - go build -mod vendor -o telebit-mgmt -popd -``` - -## Management Server - -```bash -go generate ./... - -CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o mgmt-server-linux ./cmd/mgmt/*.go -CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o mgmt-server-macos ./cmd/mgmt/*.go -CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o mgmt-server-windows-debug.exe ./cmd/mgmt/*.go -CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o mgmt-server-windows.exe ./cmd/mgmt/*.go -``` - -### Example - -```bash -./telebit-mgmt --domain devices.example.com --port 3010 -``` - -Copy `examples/mgmt.env` as `.env` in the working directory. - -### Device Management API - Create a token with the same `SECRET` used with the `mgmt` server, and add a device by its `subdomain`. @@ -86,7 +137,7 @@ Authorize a device: ```bash my_subdomain="xxxx" -my_mgmt_host=http://mgmt.example.com:3010 +my_mgmt_host=http://mgmt.example.com:6468 curl -X POST $my_mgmt_host/api/devices \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ @@ -101,7 +152,7 @@ Show data of a single device ```bash my_subdomain="xxxx" -curl -L http://mgmt.example.com:3010/api/devices/${my_subdomain} -H "Authorization: Bearer ${TOKEN}" +curl -L http://mgmt.example.com:6468/api/devices/${my_subdomain} -H "Authorization: Bearer ${TOKEN}" ``` ```json @@ -111,7 +162,7 @@ curl -L http://mgmt.example.com:3010/api/devices/${my_subdomain} -H "Authorizati Get a list of connected devices: ```bash -curl -L http://mgmt.example.com:3010/api/devices -H "Authorization: Bearer ${TOKEN}" +curl -L http://mgmt.example.com:6468/api/devices -H "Authorization: Bearer ${TOKEN}" ``` ```json @@ -121,12 +172,37 @@ curl -L http://mgmt.example.com:3010/api/devices -H "Authorization: Bearer ${TOK Get a list of disconnected devices: ```bash -curl -L http://mgmt.example.com:3010/api/devices?inactive=true -H "Authorization: Bearer ${TOKEN}" +curl -L http://mgmt.example.com:6468/api/devices?inactive=true -H "Authorization: Bearer ${TOKEN}" ``` Deauthorize a device: ```bash my_subdomain="xxxx" -curl -L -X DELETE http://mgmt.example.com:3010/api/devices/${my_subdomain} -H "Authorization: Bearer ${TOKEN}" +curl -L -X DELETE http://mgmt.example.com:6468/api/devices/${my_subdomain} -H "Authorization: Bearer ${TOKEN}" +``` + +# Build + +You can build with `go build`: + +```bash +go build -mod vendor -race -o telebit-mgmt cmd/mgmt/mgmt.go +``` + +Or with `goreleaser`: + +```bash +goreleaser --rm-dist --skip-publish --snapshot +``` + +Or cross-compile: + +```bash +go generate ./... + +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o telebit-mgmt-linux ./cmd/mgmt/*.go +CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o telebit-mgmt-macos ./cmd/mgmt/*.go +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o telebit-mgmt-windows-debug.exe ./cmd/mgmt/*.go +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o telebit-mgmt-windows.exe ./cmd/mgmt/*.go ``` diff --git a/cmd/signjwt/signjwt.go b/cmd/signjwt/signjwt.go index d1019d5..ebe97bf 100644 --- a/cmd/signjwt/signjwt.go +++ b/cmd/signjwt/signjwt.go @@ -11,9 +11,9 @@ import ( "strconv" "time" - telebit "git.rootprojects.org/root/telebit" + "git.rootprojects.org/root/telebit" "git.rootprojects.org/root/telebit/dbg" - "git.rootprojects.org/root/telebit/mgmt/authstore" + "git.rootprojects.org/root/telebit/internal/mgmt/authstore" "github.com/denisbrodbeck/machineid" _ "github.com/joho/godotenv/autoload" diff --git a/cmd/telebit/README.md b/cmd/telebit/README.md index e7cb464..37678cf 100644 --- a/cmd/telebit/README.md +++ b/cmd/telebit/README.md @@ -2,45 +2,62 @@ | [Telebit Client](../../) | **Telebit Relay** | [Telebit Mgmt](../mgmt) | -### Example +Secure tunnel, relay, and reverse-proxy server. + +# Usage + +**Only** port 443 must be public. + +```bash +./telebit-relay --acme-http-01 +``` + +```bash +# allow access to privileged ports +sudo setcap 'cap_net_bind_service=+ep' ./telebit-relay +``` Copy `examples/relay.env` as `.env` in the working directory. ```bash -# For Tunnel Relay Server -API_HOSTNAME=devices.example.com -LISTEN=:443 -LOCALS=https:mgmt.devices.example.com:3010 -VERBOSE=false - -# For Device Management & Authentication -AUTH_URL=http://localhost:3010/api - -# For Let's Encrypt / ACME registration -ACME_AGREE=true -ACME_EMAIL=letsencrypt@example.com - -# For Let's Encrypt / ACME challenges -ACME_HTTP_01_RELAY_URL=http://localhost:3010/api/http -ACME_RELAY_URL=http://localhost:3010/api/dns -SECRET=xxxxxxxxxxxxxxxx -GODADDY_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -GODADDY_API_SECRET=xxxxxxxxxxxxxxxxxxxxxx +# --secret +export SECRET=XxX-mgmt-secret-XxX +# --api-hostname +export API_HOSTNAME=tunnel.example.com +# --listen +export LISTEN=":443" +# --locals +export LOCALS=https:mgmt.example.com:6468 +# --auth-url +export AUTH_URL=http://localhost:6468/api +# --acme-agree +export ACME_AGREE=true +# --acme-email +export ACME_EMAIL=telebit@example.com +# --acme-relay +export ACME_RELAY_URL=http://localhost:6468/api/acme-relay ``` +See `./telebit-relay --help` for all options. \ +See [`examples/relay.env`][relay-env] for detail explanations. + +[relay-env]: /tree/master/examples/relay.env + Note: It is not necessary to specify the `--flags` when using the ENVs. +## System Services + +You can use `serviceman` to run `postgres`, `telebit`, and `telebit-mgmt` as system services + ```bash -./telebit \ - --api-hostname $API_HOSTNAME \ - --auth-url "$AUTH_URL" \ - --acme-agree "$ACME_AGREE" \ - --acme-email "$ACME_EMAIL" \ - --secret "$SECRET" \ - --listen "$LISTEN" +curl -fsS https://webinstall.dev/serviceman | bash ``` -### API +See the Cheat Sheet at https://webinstall.dev/serviceman + +You can, of course, configure systemd (or whatever) by hand if you prefer. + +# API List all connected devices @@ -77,3 +94,28 @@ Force a device to disconnect: ```bash bash examples/admin-disconnect-device.sh ``` + +# Build + +You can build with `go build`: + +```bash +go build -mod vendor -race -o telebit-relay cmd/telebit/telebit.go +``` + +Or with `goreleaser`: + +```bash +goreleaser --rm-dist --skip-publish --snapshot +``` + +Or cross-compile: + +```bash +go generate ./... + +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o telebit-relay-linux ./cmd/telebit/*.go +CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o telebit-relay-macos ./cmd/telebit/*.go +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o telebit-relay-windows-debug.exe ./cmd/telebit/*.go +CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o telebit-relay-windows.exe ./cmd/telebit/*.go +``` diff --git a/examples/mgmt-add-device.sh b/examples/mgmt-add-device.sh index 697ed04..7882da1 100644 --- a/examples/mgmt-add-device.sh +++ b/examples/mgmt-add-device.sh @@ -13,7 +13,7 @@ TOKEN=$(go run cmd/signjwt/*.go \ --machine-ppid "$RELAY_SECRET" ) -MGMT_URL=${MGMT_URL:-"http://mgmt.example.com:3010/api"} +MGMT_URL=${MGMT_URL:-"http://mgmt.example.com:6468/api"} CLIENT_SUBJECT=${CLIENT_SUBJECT:-"newbie"} curl -X POST "$MGMT_URL/devices" \ diff --git a/examples/mgmt-remove-device.sh b/examples/mgmt-remove-device.sh index 987dcbe..33fd647 100644 --- a/examples/mgmt-remove-device.sh +++ b/examples/mgmt-remove-device.sh @@ -7,7 +7,7 @@ TOKEN=$(go run cmd/signjwt/*.go \ --machine-ppid "$RELAY_SECRET" ) -MGMT_URL=${MGMT_URL:-"http://mgmt.example.com:3010/api"} +MGMT_URL=${MGMT_URL:-"http://mgmt.example.com:6468/api"} CLIENT_SUBJECT=${CLIENT_SUBJECT:-"newbie"} curl -X DELETE "$MGMT_URL/devices/$CLIENT_SUBJECT" \ diff --git a/examples/mgmt.env b/examples/mgmt.env index c27e954..1d7843e 100644 --- a/examples/mgmt.env +++ b/examples/mgmt.env @@ -5,10 +5,10 @@ DOMAIN=devices.example.com # TUNNEL_DOMAIN # This is the domain that will be used for the wss:// connection URL. -TUNNEL_DOMAIN=new.telebit.cloud +TUNNEL_DOMAIN=tunnel.example.com # For mgmt server itself -#SECRET=XxxxxxxxxxxxxxxX +SECRET=XxxxxxxxxxxxxxxX DB_URL=postgres://postgres:postgres@localhost:5432/postgres # PORT @@ -19,7 +19,7 @@ PORT=6468 # alternative to PORT, including address #LISTEN=localhost:6468 -DUCKDNS_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX +#DUCKDNS_TOKEN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX #NAMECOM_USERNAME=johndoe #NAMECOM_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx