Skip to main content

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​

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http

Custom Domain​

ssh -R example.ngrok.app:443:localhost:80 v2@connect.ngrok-agent.com http

Basic Auth​

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http \
  --basic-auth "username1:password1" \
  --basic-auth "username2:password2"

OAuth​

ssh -R 443:localhost:80 v2@connect.ngrok-agent.com http --oauth=google

Forward to non-local service​

ssh -R 0:192.168.1.2:80 v2@connect.ngrok-agent.com http

Random TCP Endpoint​

ssh -R 0:localhost:22 v2@connect.ngrok-agent.com tcp

Fixed TCP Endpoint​

ssh -R 1.tcp.eu.ngrok.io:12345:localhost:3389 connect.eu.ngrok-agent.com tcp

TLS Endpoint​

ssh -R app.example.com:443:localhost:443 v2@connect.ngrok-agent.com tls

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.

ssh -R 443:localhost:80 v2@connect.eu.ngrok-agent.com http

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:

cat ~/.ssh/id_rsa.pub | pbcopy

or:

cat ~/.ssh/id_ed25519.pub | pbcopy

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.

ssh -R \
  app.example.com:443:127.0.0.1:8080 \
  v2@connect.ngrok-agent.com \
  http --basic-auth 'user:password'

An ssh -R command has the following components:

ssh -R \
  "<remote name>:<remote port>:<local name>:<local port>" \
  <user>@connect.ngrok-agent.com \
  <command> [flags]

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.