175 lines
4.6 KiB
Markdown
175 lines
4.6 KiB
Markdown
# Telebit
|
|
|
|
A secure, end-to-end Encrypted tunnel.
|
|
|
|
Because friends don't let friends localhost.
|
|
|
|
## Install Go
|
|
|
|
Installs Go to `~/.local/opt/go` for MacOS and Linux:
|
|
|
|
```bash
|
|
curl https://webinstall.dev/golang | bash
|
|
```
|
|
|
|
For Windows, see https://golang.org/dl
|
|
|
|
**Note**: The _minimum required go version_ is shown in `go.mod`. DO NOT use with `GOPATH`!
|
|
|
|
## Relay Server
|
|
|
|
All dependencies are included, at the correct version in the `./vendor` directory.
|
|
|
|
```bash
|
|
go generate ./...
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o telebit-relay-linux ./cmd/telebit-relay/*.go
|
|
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o telebit-relay-macos ./cmd/telebit-relay/*.go
|
|
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o telebit-relay-windows-debug.exe ./cmd/telebit-relay/*.go
|
|
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o telebit-relay-windows.exe ./cmd/telebit-relay/*.go
|
|
```
|
|
|
|
### Configure
|
|
|
|
Command-line flags or `.env` may be used.
|
|
|
|
See `./telebit-relay --help` for all options, and `examples/relay.env` for their corresponding ENVs.
|
|
|
|
### Example
|
|
|
|
```bash
|
|
./telebit-relay --acme-agree=true --auth-url=http://localhost:3010/api
|
|
```
|
|
|
|
Copy `examples/relay.env` as `.env` in the working directory.
|
|
|
|
## Management Server
|
|
|
|
```bash
|
|
pushd mplexy/
|
|
|
|
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`.
|
|
|
|
```bash
|
|
SECRET="xxxxxxxxxxx"
|
|
TOKEN=$(go run -mod=vendor cmd/signjwt/*.go $SECRET)
|
|
```
|
|
|
|
Authorize a device:
|
|
|
|
```bash
|
|
my_subdomain="xxxx"
|
|
my_mgmt_host=http://mgmt.example.com:3010
|
|
curl -X POST $my_mgmt_host/api/devices \
|
|
-H "Authorization: Bearer ${TOKEN}" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "slug": "'$my_subdomain'" }'
|
|
```
|
|
|
|
```json
|
|
{ "shared_key": "ZZZZZZZZ" }
|
|
```
|
|
|
|
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}"
|
|
```
|
|
|
|
```json
|
|
{ "subdomain": "sub1", "updated_at": "2020-05-20T12:00:01Z" }
|
|
```
|
|
|
|
Get a list of connected devices:
|
|
|
|
```bash
|
|
curl -L http://mgmt.example.com:3010/api/devices -H "Authorization: Bearer ${TOKEN}"
|
|
```
|
|
|
|
```json
|
|
[{ "subdomain": "sub1", "updated_at": "2020-05-20T12:00:01Z" }]
|
|
```
|
|
|
|
Get a list of disconnected devices:
|
|
|
|
```bash
|
|
curl -L http://mgmt.example.com:3010/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}"
|
|
```
|
|
|
|
## Relay Client
|
|
|
|
All dependencies are included, at the correct version in the `./vendor` directory.
|
|
|
|
```bash
|
|
pushd mplexy/
|
|
|
|
go generate ./...
|
|
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o telebit-client-linux ./cmd/telebit/*.go
|
|
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o telebit-client-macos ./cmd/telebit/*.go
|
|
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o telebit-client-windows-debug.exe ./cmd/telebit/*.go
|
|
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o telebit-client-windows.exe ./cmd/telebit/*.go
|
|
```
|
|
|
|
### Configure
|
|
|
|
Command-line flags or `.env` may be used.
|
|
|
|
See `./telebit-client --help` for all options, and `examples/client.env` for their corresponding ENVs.
|
|
|
|
### Example
|
|
|
|
```bash
|
|
./telebit-client --acme-agree=true \
|
|
--relay wss://devices.example.com \
|
|
--app-id test-id --secret ZR2rxYmcKJcmtKgmH9D5Qw \
|
|
--acme-relay http://mgmt.example.com:3010/api/dns \
|
|
--auth-url http://mgmt.example.com:3010/api \
|
|
--locals http://xxx.devices.example.com:8080,https://xxx.devices.example.com:8080
|
|
```
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
mkdir -p tmp-app
|
|
pushd tmp-app/
|
|
|
|
cat << EOF > index.html
|
|
Hello, World!
|
|
EOF
|
|
|
|
python3 -m http.server 3000
|
|
```
|