root
/
telebit
mirror of https://github.com/therootcompany/telebit.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update docs

This commit is contained in:
AJ ONeal 2020-11-13 04:26:25 -07:00
parent 6acda301b0
commit 0d02769ff0
8 changed files with 285 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.goreleaser.yml
View File

@ -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
View File

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

180
cmd/mgmt/README.md
View File

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

4
cmd/signjwt/signjwt.go
View File

@ -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
View File

@ -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
View File

@ -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
View File

@ -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
View File

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