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