README
¶
Command grok provides standalone server terminating https and proxying requests in plain http over reverse ssh tunnels.
The main goal is the same as for ngrok tool from https://ngrok.com:
I want to expose a local server behind a NAT or firewall to the internet.
See https://pkgo.dev/github.com/artyom/grok#section-documentation for details.
Documentation
¶
Overview ¶
Command grok provides a standalone server that terminates HTTPS connections and proxies requests as plain HTTP over reverse SSH tunnels.
Its main use-case is similar to the ngrok tool (https://ngrok.com), allowing developers to expose local services through a public HTTPS endpoint.
The server operates by listening on two endpoints:
- HTTPS: For incoming web requests
- SSH: For tunnel establishment
When receiving SSH connections, grok looks for "tcpip-forward" requests (RFC 4254, Section 7.1). Once received, it establishes a reverse proxy for a domain that is either derived from the client's public key fingerprint (hash.base.tld), or explicitly defined in the authorized_keys file.
For HTTPS requests, grok matches the request's domain name against active tunnels. If a match is found, the request is proxied over the tunnel as a plain HTTP/1.1 request. TLS certificates for matched domains are automatically obtained from Let's Encrypt as needed.
Domain Configuration ¶
There are two ways to configure domains:
Explicit domain per key in authorized_keys:
domain=dev1.example.com ssh-ed25519 key1... domain=dev2.example.com ssh-rsa key2...
Auto-derived domain from key hash:
ssh-ed25519 key3... # Results in <hash>.example.com
where <hash> is derived from the key's fingerprint and domain is set via the -domain flag
Usage Example ¶
To expose a local development server running on port 8080:
ssh -N -R 8080:localhost:8080 <SERVER>
Note on SSH -R syntax:
-R [bind_address:]port:host:hostport
The bind_address and first port are ignored by grok; only the host:hostport pair is used to determine where the SSH client will connect for forwarded connections.
Source Files