DocsGuidesSharing a database

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:5432
expires in 2h (14:03 UTC) policy: allow all, 16 conns, 8 connectors
link 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 alice
14:01:04 conn #1 open 203.0.113.9 via alice
14:05:11 conn #1 closed 4m07s 12.3 MiB up 482.0 KiB down

Each 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:27017

Lines 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 alice
connecting to example.com:4443
connected "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 6380

The 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.

--asstring
Connector name shown to the sharer. Letters, digits, . _ -; a taken name gets -2 appended.
--port, -pstring
N for the first target, or preset=N / t2=N per target. Repeatable.
--passphrasestring
Passphrase the share requires. Prompted for when stdin is a terminal; NGSTONE_SHARE_PASSPHRASE also works.
--insecurebooldefault: false
Dial the edge in plaintext. Only for links from an edge running with -insecure; the link never encodes it.
--server-namestring
TLS ServerName/SNI to verify against. Defaults to the host in the link.
--pinstring
Optional SPKI pin, checked in addition to normal chain validation.
--transportstringdefault: auto
Control transport: 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 shares
sh_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 --json

How 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#

--expiresdurationdefault: 1h
Share lifetime. The edge enforces it and caps it with -max-share-ttl (24h by default). extend moves it later while the share is live.
--allow-cidrstring
Comma-separated CIDRs connectors must come from. A connector outside the list is refused at join time with forbidden_cidr, and the sharer sees the rejection.
--max-connsintdefault: 16
Concurrent relayed connections across all connectors. The edge allows at most 64.
--max-connectorsintdefault: 8
Concurrent connector agents. The edge allows at most 32.
--max-usesintdefault: 0
How many connector agents may ever join. 1 is the same as --single-use: the link locks to the first agent, which may reconnect; anyone else gets share_locked.
--idledurationdefault: 0
Close the share after this long with no open connection, for sharers who forget Ctrl-C. Minimum 30s.
--userstring
A database user for the hint connectors see, such as 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

Behind a front proxy with -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.
  • --approve parks every join until the sharer types y or nin 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 alice
y alice
14:01:05 approved alice
14:01:05 connector joined 203.0.113.9 alice

Auditing#

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 expired and exits 0, and each connector prints why and exits with status 3. Connectors warn at five minutes and one minute; extend from either terminal postpones it.
  • Revocation. Ctrl-C on the sharer, or ngstone unshare from anywhere, tells every connector revoked. kick does the same for one connector, and extend, kick and shares reach 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_gone and 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.