VeillaxandClaude Sonnet 5.5
9448a532e9
The edge: per-IP TCP/UDP/HTTP/HTTPS/TLS listeners with port ranges and PROXY protocol, WireGuard tunnel endpoint, logins in front of web ports (built-in proxy or Traefik), health checks and failover, and mail egress with DKIM signing and MTA-STS. Split out of the original single repository; depends on Reef for the shared types. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
52 lines
3.6 KiB
Markdown
52 lines
3.6 KiB
Markdown
# Blacktip
|
|
|
|
Blacktip runs on your public server. It owns the IP addresses and opens the TCP, UDP, HTTP and HTTPS ports you pick, including the same port on different IPs. It terminates the WireGuard tunnels, puts logins in front of websites (optionally through Traefik), checks target health, and delivers your outgoing mail with DKIM signing and MTA-STS.
|
|
|
|
Part of the sharks stack: [Hammerhead](https://git.veillax.com/Veillax/hammerhead) (control plane and dashboard) · **Blacktip** (edge) · [Bamboo](https://git.veillax.com/Veillax/bamboo) (site agent) · [Reef](https://git.veillax.com/Veillax/reef) (shared library). Everything is configured from Hammerhead's web dashboard; the full documentation lives in [its README](https://git.veillax.com/Veillax/hammerhead).
|
|
|
|
## Run it
|
|
|
|
In Hammerhead, go to Server → Edges → add an edge. The dashboard shows the exact command with your token. It looks like this:
|
|
|
|
```
|
|
blacktip -hammerhead https://hammerhead.example.com -token <edge token> -tunnel :51820 -docker
|
|
```
|
|
|
|
Open the WireGuard UDP port (default 51820) and any ports you open from the dashboard in this machine's firewall. Blacktip only needs to reach Hammerhead over HTTPS; it never needs inbound access from it.
|
|
|
|
| Flag | Environment | Meaning |
|
|
|---|---|---|
|
|
| `-hammerhead` | `BLACKTIP_HAMMERHEAD` | URL of Hammerhead |
|
|
| `-token` | `BLACKTIP_TOKEN` | the edge's token |
|
|
| `-tunnel` | `BLACKTIP_TUNNEL` | UDP listen address for WireGuard (default `:51820`) |
|
|
| `-data` | `BLACKTIP_DATA` | folder for the WireGuard key and certificates |
|
|
| `-docker` | `BLACKTIP_DOCKER=1` | report local Docker containers so they can be picked as targets |
|
|
| `-traefik` | `BLACKTIP_TRAEFIK` | path to a Traefik v3 binary, to serve http/https with Traefik |
|
|
| `-acme-dns` | `BLACKTIP_ACME_DNS` | with Traefik: DNS-challenge provider for wildcard certificates |
|
|
| `-no-acme` | | with Traefik: serve its self-signed certificate instead of Let's Encrypt |
|
|
| `-env` | | `.env` file to read (default `./.env`) |
|
|
|
|
Settings and secrets can live in a `.env` file instead of the command line; see `.env.example`. Real environment variables always win.
|
|
|
|
## What it does
|
|
|
|
- **Ports:** TCP, UDP, HTTP, HTTPS and TLS passthrough, one listener per IP and port, opened and closed live as you change them in the dashboard. Port ranges for TCP and UDP. Round-robin load balancing and failover across several targets, with health checks.
|
|
- **PROXY protocol (v1/v2)** on TCP and TLS ports, so the target sees the real client address.
|
|
- **Web:** automatic Let's Encrypt certificates, HTTP/2, websockets, and logins (account, password, PIN, emailed code, share links, path and IP rules) enforced in front of any site. Use the built-in proxy, or `-traefik` to let Traefik serve http/https (raw TCP, UDP and TLS-passthrough ports always stay with Blacktip, since Traefik can't open ports without a restart).
|
|
- **Mail egress:** delivers your mail server's outgoing mail straight to the recipient's server from a public IP you choose, with the HELO name you set, opportunistic STARTTLS, optional DKIM signing, MTA-STS enforcement, a per-minute send limit and a deliverability checklist.
|
|
- **Tunnel:** WireGuard through a userspace network stack, so no root, no kernel interface and no driver. It works on Windows, macOS and Linux, and sites behind NAT connect out to it.
|
|
|
|
## Build and test
|
|
|
|
```
|
|
go env -w GOPRIVATE=git.veillax.com # once, so Go fetches straight from this server
|
|
go build -o bin/ ./cmd/blacktip
|
|
go test ./...
|
|
```
|
|
|
|
The end-to-end tests that run Blacktip together with Hammerhead and Bamboo live in the Hammerhead repository.
|
|
|
|
## License
|
|
|
|
AGPL-3.0. See `LICENSE`.
|