Sharing a database
ngstone tcp gives a service a public port on the edge. Sometimes that is more exposure than you want: a staging database a teammate needs for an afternoon should not be reachable by anyone who can guess a port. ngstone share is for that case. It hands out a link; whoever has the link runs ngstone connect and gets the database on their own loopback interface. Nothing on the edge listens for it.
Sharing#
$ ngstone share postgres --expires 2h --label "staging replica"share staging replica postgres 127.0.0.1:5432expires in 2h (14:03 UTC) policy: allow all, 16 conns, 8 connectorslink ngstone://example.com:4443/s/N7kq...Vb0Q send the link to a teammate; they run: ngstone connect <link>commands here: y <id> / n <id> (approve) kick <id> extend 1h q 14:01:02 share live id sh_7f3a...14:01:03 connector joined 203.0.113.9 alice14:01:04 conn #1 open 203.0.113.9 via alice14:05:11 conn #1 closed 4m07s 12.3 MiB up 482.0 KiB downEach positional argument is a target. postgres, mysql, redis and http are presets for ports 5432, 3306, 6379 and 8080 on 127.0.0.1; add :port or :host:port to point elsewhere, and use tcp:port for anything else. Several targets go in one link:
$ ngstone share postgres redis:6380 tcp:db.local:27017Lines typed into the sharing terminal are commands: kick alice drops a connector, extend 1h moves the expiry, y alice and n alice answer approval requests, q quits. Ctrl-C revokes the share; every connector is told within a second and told why.
Connecting#
$ ngstone connect ngstone://example.com:4443/s/N7kq...Vb0Q --as aliceconnecting to example.com:4443connected "staging replica" as alice expires in 1h58m (14:03 UTC)listening 127.0.0.1:5432 postgres -> psql "postgres://127.0.0.1:5432/"listening 127.0.0.1:6380 redis -> redis-cli -p 6380The connector listens on the loopback interface only, on each target's preset port. If a port is busy it picks a free one and says so; --port 5433 chooses for the first target and --port redis=6380 for a named one. Each local connection becomes one tunnel stream to the edge. A status line appears when activity changes, and the connector warns five minutes and one minute before the share expires.
--as gives the connector a name the sharer sees in every audit line instead of c1. It is a label, not an identity: approval mode (below) is where a human checks it.
The link carries the edge address, so the connector needs no ngstone auth and no config file. To keep the secret out of shell history, pass the link on standard input with ngstone connect - or set NGSTONE_SHARE_LINK.
. _ -; a taken name gets -2 appended.N for the first target, or preset=N / t2=N per target. Repeatable.NGSTONE_SHARE_PASSPHRASE also works.-insecure; the link never encodes it.ServerName/SNI to verify against. Defaults to the host in the link.auto, raw, websocket or quic. Share, connect and the management commands all take it; quic is never part of auto.Managing shares from anywhere#
Any terminal with the legacy shared token can see and manage every share, not only the one that started it. These open a fresh session, do one thing and exit, so they work from scripts too. A share credential manages only the shares of its own owner.
$ ngstone sharessh_7f3a... staging replica postgres,redis expires in 1h52m (14:03 UTC) policy: 16 conns, 8 connectors; 1 open connections connector alice 203.0.113.9 joined 4m ago $ ngstone extend sh_7f3a... 2h # expire two hours from now; connectors are told$ ngstone kick sh_7f3a... alice # drop one connector; it exits with status 3$ ngstone unshare sh_7f3a... # revoke; the sharing terminal says so and exits$ ngstone shares --watch # every share's audit lines, live$ ngstone shares --jsonHow it works#
Both sides dial out to the edge over TLS, exactly like a normal agent. The sharer registers the share: a label, its targets, an expiry, a policy and the SHA-256 of a 32-byte secret it minted. The link is that secret. A connector authenticates with the secret instead of the operator token and gets a session that may do one thing: open streams to its share, each tagged with a target. The edge opens a matching stream to the sharer, whose agent dials the right local address, and copies bytes both ways with the same flow control and idle timeout as a TCP tunnel.
The edge keeps shares in memory only and stores nothing but the hash. An edge restart forgets every share; the sharer re-registers on reconnect, connectors retry, and the same link keeps working. With --secret-file the link also survives restarting the sharer itself.
Policies#
-max-share-ttl (24h by default). extend moves it later while the share is live.forbidden_cidr, and the sharer sees the rejection.1 is the same as --single-use: the link locks to the first agent, which may reconnect; anyone else gets share_locked.readonly. The edge cannot enforce read-only access; a scoped database role can, and this points people at it.--allow-cidr checks the connector's address as the edge sees it
-proxy-protocol, source addresses are only trustworthy with -proxy-protocol-trusted, as for every other allowlist. See Access control.Approval and passphrases#
A link in a chat log is enough to connect. Two options raise the bar without accounts:
--passphrasemakes connectors type a second secret the link does not carry. The sharer sends the edge a digest bound to the share; the connector presents the passphrase at join; a wrong one counts against the edge's per-IP auth limiter like a bad token.--approveparks every join until the sharer typesyornin the sharing terminal, with the connector's name and address on screen. Sixty seconds without an answer refuses the connector. This is the lightest form of identity available: a human looks.
$ ngstone share postgres --approve --passphrase hunter2...14:01:03 approve? 203.0.113.9 alice wants to connect: type y alice or n alicey alice14:01:05 approved alice14:01:05 connector joined 203.0.113.9 aliceAuditing#
The sharer's terminal shows every connector joining and leaving and every connection opening and closing, with the connector's name and address, the target, duration and bytes in each direction. --audit-log PATH appends the same events as JSON Lines. ngstone shares --watch shows the same lines for every share from any terminal, and the edge can keep its own file with -share-audit-log. The secret, its hash and the passphrase never appear anywhere.
{"share_id":"sh_7f3a...","event":"conn_close","at_unix_ms":1791902431793,"connector_id":"alice","conn_id":1,"target":"t1","client_addr":"203.0.113.9:49418","duration_ms":247113,"bytes_up":12897280,"bytes_down":493568,"label":"staging replica"}Expiry, revocation and reconnects#
- Expiry. The edge closes the share at the deadline. Open connections are cut within a second, the sharer prints
share expiredand exits 0, and each connector prints why and exits with status 3. Connectors warn at five minutes and one minute;extendfrom either terminal postpones it. - Revocation. Ctrl-C on the sharer, or
ngstone unsharefrom anywhere, tells every connectorrevoked.kickdoes the same for one connector, andextend,kickandsharesreach shares held by any edge in a multi-edge deployment. Same exit codes as expiry. - Idle. With
--idle, a share with no open connection for that long closes on its own. - Sharer offline.If the sharer's session dies without a goodbye (a laptop lid), connectors are told
sharer_goneand retry quietly until the expiry they were given. The sharer re-registers the same secret when it returns. - Connector offline. Its local listeners stay up. While disconnected, new local connections are refused at once rather than queued, like a database that is down.
What it is not#
There are no named users: a connector's name is a claim for the audit trail, and identity is possession of the link plus the passphrase, network policy and approval if you set them. There is no query-level auditing or read-only enforcement; use database roles for that. And the edge terminates TLS on both sides and sees plaintext, as with every tunnel, so enable the database's own TLS when the VPS is not fully trusted. The full design, including the protocol additions, is in docs/SHARE-DESIGN.md in the repository.