Documentation ¶
Overview ¶
Command grok provides standalone server terminating https and proxying requests in plain http over reverse ssh tunnels.
Its main use-case is the same as of the ngrok tool from <https://ngrok.com>.
Command grok listens https and ssh endpoints. On ssh connections it's looking for "tcpip-forward" request (RFC 4254, Section 7.1), once received, it establishes reverse proxy for domain derived from public key of the client.
When receiving request over https, grok inspects request domain name, if matching active tunnel is found, request is proxied over found tunnel as plain HTTP/1.1 request. Certificates for matched domains are automatically obtained from https://letsencrypt.org authority as required.
Domains are either derived from public key md5 fingerprint: hash.base.tld (where base.tld domain is set with -domain flag) or defined per-key in authorized_keys file as key option specification in form of domain=name.tld:
domain=dev1.example.com ssh-ed25519 key1... domain=dev2.example.com ssh-rsa key2...
Once set, developer may then connect to this service with ssh client setting up reverse port forwarding (i.e. to localhost:8080):
ssh -N -R 8080:localhost:8080 server.example.com
Note the notation for -R used by ssh:
-R [bind_address:]port:host:hostport
When connecting to grok only host:hostport pair is significant, since they specify where ssh client will connect on forwarded connection, the first port can be set to arbitrary value and is ignored by the server.