Browse Source

update docs

master
AJ ONeal 3 years ago
parent
commit
0d02769ff0
  1. 2
      .goreleaser.yml
  2. 94
      README.md
  3. 150
      cmd/mgmt/README.md
  4. 4
      cmd/signjwt/signjwt.go
  5. 98
      cmd/telebit/README.md
  6. 2
      examples/mgmt-add-device.sh
  7. 2
      examples/mgmt-remove-device.sh
  8. 6
      examples/mgmt.env

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

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

150
cmd/mgmt/README.md

@ -1,64 +1,115 @@
# Telebit Mgmt
# Config
| [Telebit Client](../../) | [Telebit Relay](../telebit) | **Telebit Mgmt** |
```bash
VERBOSE=
Device Management, Authorization, and ACME Relay Server.
# Usage
PORT=6468
This does not need to be on a public port for client devices,
but it must be directly accessible by the telebit relay.
# JWT Verification Secret
#SECRET=XxxxxxxxxxxxxxxX
It must also run on port 80 if HTTP-01 challenges are being relayed.
DB_URL=postgres://postgres:postgres@localhost:5432/postgres
DOMAIN=mgmt.example.com
TUNNEL_DOMAIN=tunnel.example.com
This should be https-enabled unless on localhost behind the telebit relay.
NAMECOM_USERNAME=johndoe
NAMECOM_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```bash
./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
my_subdomain="ruby"
curl -X DELETE http://mgmt.example.com:3010/api/subscribers/ruby" -H "Authorization: Bearer ${TOKEN}"
# --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
```
```json
{ "success": true }
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
```
# Build
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
go generate -mod vendor ./...
curl -sS https://webinstall.dev/postgres | bash
```
pushd cmd/mgmt
go build -mod vendor -o telebit-mgmt
popd
```bash
sudo env PATH="$PATH" \
serviceman add --system --username $(whoami) --name postgres -- \
postgres -D "$HOME/.local/share/postgres/var" -p 5432
```
## Management Server
See the Cheat Sheet at https://webinstall.dev/postgres
```bash
go generate ./...
## Create Admin Token
The admin token can be used to interact with the server.
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
```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
)
```
### Example
## Register New Device
This will return a new shared secret that can be used to register a new client device.
```bash
./telebit-mgmt --domain devices.example.com --port 3010
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'" }'
```
Copy `examples/mgmt.env` as `.env` in the working directory.
# API
```bash
my_subdomain="ruby"
curl -X DELETE http://mgmt.example.com:6468/api/subscribers/ruby" -H "Authorization: Bearer ${TOKEN}"
```
### Device Management API
```json
{ "success": true }
```
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
```

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

98
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
```

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

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

6
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

Loading…
Cancel
Save