SSH Reverse Tunnel Agent
Overview
SSH reverse tunneling (ssh -R
) is an alternative mechanism deliver services
via ngrok without running an ngrok agent or Agent
SDK.
The SSH reverse tunnel agent should not be confused with creating remote access to an SSH server via ngrok. If you want to use ngrok to create access to your own SSH server for remote access, please refer to the using ngrok with ssh documentation.
You should only ngrok via SSH if you really can't use an Agent or Agent SDK. The SSH reverse tunnel agent has many functional limitations compared to the ngrok agent.
Example Usage
Random HTTP Endpoint
Loading…
Custom Domain
Loading…
Basic Auth
Loading…
OAuth
Loading…
Forward to non-local service
Loading…
Random TCP Endpoint
Loading…
Fixed TCP Endpoint
Loading…
TLS Endpoint
Loading…
Explicit Region Selection
Normally you will connect to ngrok's closest point of present via Global Server Load Balancing, but you can also explicitly choose a region.
Loading…
Authentication
Instead of an ngrok authtoken, when you use ngrok via the SSH reverse tunnel agent, it uses a public key for authentication. You'll first need to upload yours to the SSH Public Keys page on your ngrok dashboard.
Copy your default SSH public key with:
- Mac OS
- Linux
Loading…
or:
Loading…
Loading…
or:
Loading…
ngrok's SSH public key fingerprints
Public key fingerprints can be used to validate a connection to the ngrok point of presence you're connecting through. These are our RSA public key fingerprints:
- connect.ap.ngrok-agent.com:
SHA256:K/3UwSeIg0JVf9uLVfl4QLEY11tyON/d+QmLfIU0fmk
- connect.au.ngrok-agent.com:
SHA256:RpCOpodROXqXy4d0SIm7rAqwEUsmmUHA6NAQ6T4EHXY
- connect.eu.ngrok-agent.com:
SHA256:OeywYk1/2w9cOg8Q3FjbsMOe2Hc9CvxbyBhDdUBBOlQ
- connect.in.ngrok-agent.com:
SHA256:acotuxa/+tJY2vmK+VeLQIoVOJLQz/VLTmHTJ/0LPaI
- connect.jp.ngrok-agent.com:
SHA256:/6j2cYqVbjO9YvEKKXTOqHlND72fCms0sdVWClHJAks
- connect.sa.ngrok-agent.com:
SHA256:Wh3W1ub0J/eda2QcEPbrVgS6mdGxIUrbao9G5zMBvdc
- connect.us-cal-1.ngrok-agent.com:
SHA256:UwLN719B+xJVKMtcsZL3cqiuY7iYpoxLNg1k5Pqdf2g
- connect.us.ngrok-agent.com:
SHA256:WuVeeGNOGVrcMe/GcdsTUB135MFCe1/aaVYXrpCxSEM
Command Syntax
ngrok does its best to honor the syntax of ssh -R
. You may wish to consult
man ssh
, and the section devoted to the -R
option for additional details.
ngrok uses additional command line options to implement features that are not
otherwise available via the -R
syntax.
Let's break down the following command.
Loading…
An ssh -R
command has the following components:
Loading…
In our example:
- Remote Name:
app.example.com
. ngrok will listen on the domain 'app.example.com'. You may omit this value. If you do, ngrok chooses a random endpoint name. - Remote Port:
443
. ngrok will listen for HTTPS traffic on port 443. The only valid values for HTTP endpoints are 80 and 443. For TLS endpoints it must be 443. You may0
and ngrok will simply choose the appropriate port for you. - Local Name:
127.0.0.1
. This is the local hostname or IP address that traffic will be sent to. It's most commonlylocalhost
. - Local Port:
8080
. This is the local port that traffic will be sent to. - User:
v2
. ngrok uses the user portion of the command to version the command options. You may omit this value. If you do, ngrok will use the latest version. - Command:
http
. This the type of endpoint to create. ngrok accepts eitherhttp
,tls
ortcp
. This value is required. - Flags:
--basic-auth 'user:password'
. Run the same command with the--help
flag to get the list of supported flags or consult the Agent CLI reference.
Versioning
ngrok uses the user portion of the SSH command to version the CLI syntax. The
latest version is v2
.
Differences from the Agent
When you use ngrok via SSH reverse tunnel, you will need to upload an SSH public key to authenticate with instead of using an ngrok authtoken like the agent.
Additionally, you'll find that using ngrok via SSH has many functional limitations compared to the experience with the agent. An incomplete list of differences from the ngrok agent includes:
- Your endpoints won't automatically reconnect if there is a network interruption
- There is no equivalent to the agent's traffic inspection interface
- You can't create endpoints for multiple services with the same command
- You can't forward to upstream https services
- You can't create multiple endpoints over the same connection
- You can't serve file system directories with the
file://
protocol - You can't terminate TLS at the agent when doing zero-knowledge TLS
- You can't run labeled tunnels for use with Edges.
Pricing
The SSH reverse tunnel agent is available to all ngrok users at no additional charge. You only incur costs if resources you provision via its usage incur a cost.