75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# shark-expose
|
|
|
|
`shark expose 3000`: put a local port on the internet through your own [Hammerhead](https://git.veillax.com/Veillax/hammerhead) and [Blacktip](https://git.veillax.com/Veillax/blacktip), the way ngrok does, with nothing to clean up afterwards.
|
|
|
|
```
|
|
$ shark expose 3000 --password s3cret
|
|
|
|
shark http://demo-4f2a.dev.example.com -> 127.0.0.1:3000
|
|
|
|
Visitors must sign in.
|
|
Press Ctrl+C to stop.
|
|
```
|
|
|
|
One command asks Hammerhead for a short-lived site and a public name or port, brings up the WireGuard tunnel from your machine (it embeds the [Bamboo](https://git.veillax.com/Veillax/bamboo) agent, so there is nothing else to install or run), prints the address, and keeps it alive. On Ctrl+C it deletes everything it created. If shark is killed or loses the network, Hammerhead removes the exposure itself once its TTL runs out (5 minutes unless you say otherwise).
|
|
|
|
## Install
|
|
|
|
```
|
|
go env -w GOPRIVATE=git.veillax.com
|
|
go install git.veillax.com/Veillax/shark-expose/cmd/shark@latest
|
|
```
|
|
|
|
## Sign in
|
|
|
|
Make an API key under **Access** in the Hammerhead dashboard, then:
|
|
|
|
```
|
|
shark login --hammerhead https://hammerhead.example.com --token hhk_...
|
|
```
|
|
|
|
This checks the key and saves it to your user config folder (`shark/config.json`, readable by you only; `SHARK_CONFIG` picks another file). `SHARK_HAMMERHEAD` and `SHARK_TOKEN` override it, which suits CI.
|
|
|
|
An API key belongs to one organization and can manage its settings, so treat it like a password. Exposures are made in that organization.
|
|
|
|
## Use
|
|
|
|
```
|
|
shark expose 3000 website on <random>.<one of your domains>
|
|
shark expose https 3000 the same over HTTPS (Blacktip gets the certificate)
|
|
shark expose 3000 --name demo demo-<random>.<domain>
|
|
shark expose 3000 --hostname me.dev.example.com
|
|
shark expose 192.168.1.20:8080 something else on your network
|
|
shark expose tcp 25565 raw TCP on a free public port (20000-29999)
|
|
shark expose tcp 22 --port 20022 ...on the port you pick
|
|
shark ls what is exposed in your organization right now
|
|
```
|
|
|
|
| Flag | |
|
|
|---|---|
|
|
| `--password P`, `--pin N`, `--sso` | Put a login in front of a website: a shared password (6+ characters), a PIN (4-12 digits), or a Hammerhead account. Can be combined; `SHARK_PASSWORD` avoids putting the password on the command line. |
|
|
| `--ttl 10m` | How long Hammerhead keeps it if shark goes quiet (30s to 24h). shark renews every third of that while it runs. |
|
|
| `--name`, `--hostname`, `--port`, `--edge` | Choose the label, the full public name, the public port, or the edge. |
|
|
| `--verbose` | Show the tunnel agent's log. |
|
|
|
|
For websites Hammerhead needs a domain to put the name under (**Domains** in the dashboard), with a wildcard DNS record pointing at the edge. TCP needs no domain: it uses the edge's address and a free port in 20000-29999, which has to be open in the edge's firewall. Login protection is for websites only.
|
|
|
|
## How it works
|
|
|
|
1. `POST /api/orgs/-/expose` makes an *ephemeral* site and mapping tagged `ephemeral` and returns the public address and the site's token.
|
|
2. shark runs Bamboo in-process with that token. It dials out to the edge, so your machine needs no inbound ports.
|
|
3. When the edge reports the port listening, shark prints the address.
|
|
4. `POST .../renew` every TTL/3. A 404 means Hammerhead dropped it, and shark exits with an error; renewals failing for longer than the TTL end it too.
|
|
5. `DELETE` on exit. The site, port, login secrets and tunnel address all go with it.
|
|
|
|
The API is documented in Hammerhead's README ("Ephemeral exposures"). It currently lives on Hammerhead's `feature/ephemeral-expose` branch.
|
|
|
|
## Development
|
|
|
|
```
|
|
go test ./... # unit tests, with a fake Hammerhead
|
|
cd e2e && go test ./... # shark against a real Hammerhead + Blacktip + Bamboo in one process
|
|
```
|
|
|
|
`e2e` is its own module so the CLI does not depend on Hammerhead. Its `go.mod` has a `replace` pointing at `../../hammerhead-expose`, a checkout of the Hammerhead branch above; change it once that is merged and released.
|