update docs

.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:

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 <https://webinstall.dev/golang>.
+
+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
+## White Label Builds
-
-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.
 
 ```bash
-mkdir -p tmp-app
+go generate ./...
-pushd tmp-app/
 
-cat << EOF > index.html
+VENDOR_ID="example.com"
-Hello, World!
-EOF
 
-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:

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=
+./telebit-mgmt
-
-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
 ```
 
-## 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
 ```

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"

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
+# --secret
-API_HOSTNAME=devices.example.com
+export SECRET=XxX-mgmt-secret-XxX
-LISTEN=:443
+# --api-hostname
-LOCALS=https:mgmt.devices.example.com:3010
+export API_HOSTNAME=tunnel.example.com
-VERBOSE=false
+# --listen
-
+export LISTEN=":443"
-# For Device Management & Authentication
+# --locals
-AUTH_URL=http://localhost:3010/api
+export LOCALS=https:mgmt.example.com:6468
-
+# --auth-url
-# For Let's Encrypt / ACME registration
+export AUTH_URL=http://localhost:6468/api
-ACME_AGREE=true
+# --acme-agree
-ACME_EMAIL=letsencrypt@example.com
+export ACME_AGREE=true
-
+# --acme-email
-# For Let's Encrypt / ACME challenges
+export ACME_EMAIL=telebit@example.com
-ACME_HTTP_01_RELAY_URL=http://localhost:3010/api/http
+# --acme-relay
-ACME_RELAY_URL=http://localhost:3010/api/dns
+export ACME_RELAY_URL=http://localhost:6468/api/acme-relay
-SECRET=xxxxxxxxxxxxxxxx
-GODADDY_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-GODADDY_API_SECRET=xxxxxxxxxxxxxxxxxxxxxx
 ```
 
+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 \
+curl -fsS https://webinstall.dev/serviceman | bash
-    --api-hostname $API_HOSTNAME \
-    --auth-url "$AUTH_URL" \
-    --acme-agree "$ACME_AGREE" \
-    --acme-email "$ACME_EMAIL" \
-    --secret "$SECRET" \
-    --listen "$LISTEN"
 ```
 
-### 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
+```

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" \

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" \

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