telebit/README.md

215 lines
5.4 KiB
Markdown

# Telebit
| **Telebit Client** | [Telebit Relay](/cmd/telebit) | [Telebit Mgmt](/cmd/mgmt) |
A secure, end-to-end Encrypted tunnel.
Because friends don't let friends localhost.
# Usage
```bash
telebit --env ./.env --verbose
```
Command-line flags or `.env` may be used.
```bash
# --acme-agree
export ACME_AGREE=true
# --acme-email
export ACME_EMAIL=johndoe@example.com
# --vendor-id
export VENDOR_ID=example.com
# --secret
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
```
See `./telebit --help` for all options. \
See [`examples/client.env`][client-env] for detail explanations.
[client-env]: /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 generate -mod=vendor -tags postgres ./...
go build -mod vendor -tags postgres -race -o telebit cmd/telebit/*.go
```
Or with `goreleaser`:
```bash
goreleaser --rm-dist --skip-publish --snapshot
```
See https://webinstall.dev/goreleaser for cheat sheet.
## Install Go
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**:
```bash
curl.exe -fsSA "MS" https://webinstall.dev/golang | powershell
```
**Note**: The _minimum required go version_ is shown in `go.mod`. DO NOT use with `GOPATH`!
## Building Telebit
All dependencies are included, at the correct version in the `./vendor` directory.
```bash
go generate -mod vendor ./...
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod vendor -o telebit-linux ./cmd/telebit/*.go
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -mod vendor -o telebit-macos ./cmd/telebit/*.go
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -o telebit-windows-debug.exe ./cmd/telebit/*.go
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -mod vendor -ldflags "-H windowsgui" -o telebit-windows.exe ./cmd/telebit/*.go
```
The binary can be built with `VENDOR_ID` and `CLIENT_SECRET` built into the binary.
You can also change the `serviceName` and `serviceDescription` at build time.
See `examples/run-as-client.sh`.
# Help
```
Usage of telebit:
ACME_AGREE
--acme-agree
agree to the terms of the ACME service provider (required)
--acme-directory string
ACME Directory URL
ACME_EMAIL
--acme-email string
email to use for Let's Encrypt / ACME registration
--acme-http-01
enable HTTP-01 ACME challenges
ACME_HTTP_01_RELAY_URL
--acme-http-01-relay-url string
the base url of the ACME HTTP-01 relay, if not the same as the DNS-01 relay
--acme-relay-url string
the base url of the ACME DNS-01 relay, if not the same as the tunnel relay
--acme-staging
get fake certificates for testing
--acme-storage string
path to ACME storage directory (default "./acme.d/")
--acme-tls-alpn-01
enable TLS-ALPN-01 ACME challenges
API_HOSTNAME
--api-hostname string
the hostname used to manage clients
--auth-url string
the base url for authentication, if not the same as the tunnel relay
DEBUG
--debug
show debug output (default true)
--dns-01-delay duration
add an extra delay after dns self-check to allow DNS-01 challenges to propagate
--dns-resolvers string
a list of resolvers in the format 8.8.8.8:53,8.8.4.4:53
--env string
path to .env file
--exit-after string (such as "12h")
forcefully exit after the given duration
--exit-at string (such as "15:04")
forcefully exit at the given wall clock time
--leeway duration
allow for time drift / skew (hard-coded to 15 minutes) (default 15m0s)
LISTEN
--listen string
list of bind addresses on which to listen, such as localhost:80, or :443
LOCALS
--locals string
a list of <from-domain>:<to-port>
PORT_FORWARD
--port-forward string
a list of <from-port>:<to-port> for raw port-forwarding
SECRET
--secret string
the same secret used by telebit-relay (used for JWT authentication)
--spf-domain string
domain with SPF-like list of IP addresses which are allowed to connect to clients
TLS_LOCALS
--tls-locals string
like --locals, but TLS will be used to connect to the local port
--token string
an auth token for the server (instead of generating --secret); use --token=false to ignore any $TOKEN in env
TUNNEL_RELAY_URL
--tunnel-relay-url string
the websocket url at which to connect to the tunnel relay
VENDOR_ID
--vendor-id string
a unique identifier for a deploy target environment
VERBOSE
VERBOSE_BYTES
VERBOSE_RAW
--verbose
log excessively
```