Skip to main content

SSH Reverse Tunnel Agent

Overview​

SSH reverse tunneling (ssh -R) is an alternative mechanism to 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…

Create the oauth-policy.yml file:

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 presence via the Global Load Balancer, 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:

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 may 0 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 commonly localhost.
  • 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 either http, tls or tcp. 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:

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.