ngrok Secure Tunnels

What are ngrok Secure Tunnels?

ngrok Secure Tunnels allow you to instantly open access to remote systems without touching any of your network settings or opening any ports on your router. This means you get a secure, reliable tunnel for your developer box, IoT device, or just about anything that has access to the internet.

Using ngrok Secure Tunnels means that you can treat every device as being local, even if it's on the other side of the globe.

How secure tunnels works

ngrok Secure Tunnels work by using a locally installed ngrok agent to establish a connection to the ngrok service. Once the connection is established, you get a public endpoint that you or others can use to access your local service.

When a user hits the public ngrok endpoint, the ngrok edge figures out where to route the request to and forwards it over an encrypted connection to the locally running ngrok agent. From there, the local ngrok agent takes care of sending traffic to your upstream service. The communication between the ngrok edge and agent is secure and encrypted. Traffic from the user to the ngrok edge, and from the ngrok agent to the upstream service rely on the protocol you are using for encryption. For protocols that support end to end encryption using TLS, we provide a TLS tunnel option.

Integrating with Cloud Edge

ngrok Secure Tunnels are designed to integrate seamlessly into your ngrok Cloud Edge. Each edge has one or more backends which determine how to handle requests to that edge. The Tunnel Group Backend is responsible for forwarding requests to one or more tunnels in the group. A group is created based on a set of labels, where every tunnel with the same set of labels will have requests load balanced across them.

Labeled Tunnels

Labeled tunnels are just another tunnel type in the ngrok agent, similar to HTTP or TCP tunnels. When you create a new labeled tunnel, you define the set of labels that identify that tunnel and/or the device it's running on. When you create an edge that includes a tunnel group backend, and configure the tunnel group to look for tunnels matching specific labels, it will find and route traffic to your labeled tunnel.

See our ngrok agent reference for Labeled Tunnels for a complete set of options and examples.

ngrok Agent

The ngrok agent is usually installed on the same device where the service you are trying to tunnel is located (but it doesn't have to). Each agent leverages a Tunnel Authtoken Credential (tunnel credential in the API) to connect to the ngrok cloud and connect to a specific user account.

See our ngrok agent reference for a complete set of commands and examples.

Tunnel Authtokens

Once you've signed up for an ngrok account, you need to configure ngrok with the authtoken that appears on your dashboard. This will grant you access to all the features of ngrok. ngrok has a simple ngrok config add-authtoken command to make installing the authtoken simple. Under the hood, all the command does is to add (or modify) the authtoken property in your ngrok configuration file.

Install your authtoken
ngrok config add-authtoken <YOUR_AUTHTOKEN>

Authtoken ACL Enforcement

Authtoken Credential ACLs describe what an ngrok agent that connects with a given authtoken is allowed to do. For example, you may want to restrict each agent to only have permission to bind a specific set of tunnel endpoints. When you create an authtoken credential, specify a list of ACL behaviors are allowed for any agent connecting with that authtoken.

Generating authtoken credentials with ACLs is only available via the create credential API at the moment.

Per Agent Authtokens

Each account may have many Authtokens, and we recommend configuring a new Authtoken for each agent you configure. This is because this configuration allows the most flexibility if an Authtoken is compromised as well as allowing you to set ACLs per ngrok agent.

You can use the ngrok Dashboard to create new Authtokens or you can use the ngrok API. The ngrok API is useful if you want to build this into a provisioning script. See the ngrok api credentials command in the ngrok agent or the ngrok API for creating new credentials.

In both the UI and API, the full Authtoken you generate will only be shown once, immediately after creation!

Installation and Supported Platforms

The ngrok agent runs on all major platforms including Linux, MacOS, Windows. For a full list of the platforms we support, please see our ngrok agent download page.

If for some reason your platform is unsupported, you can still take advantage of the SSH Reverse Tunnel Agent since it only requires ssh to be installed.

Shell Autocompletion

Shell autocompletion for the ngrok agent makes it extremely easy to navigate all the command and flags by hitting tab in your terminal. It is available on Linux and MacOS operating systems and can be enabled for Bash or ZSH shells. See the ngrok agent reference for the completion command for information on setting this up.

ngrok Agent API Access

The ngrok agent has its own REST API that can be used to view, manage, start and stop tunnels on the agent. It is available by default at http://localhost:4040. For more information about using the local ngrok agent API, see out ngrok agent API reference documentation.

ngrok Agent Configuration File

For a full list of configuration options, see the ngrok agent configuration reference documentation.

Sometimes your configuration for ngrok is too complex to be expressed in command line options or you need to open many tunnels at the same time. ngrok supports an optional YAML configuration file that provides you with the power to run multiple tunnels simultaneously as well as to tweak some of ngrok's more advanced settings.

ngrok Agent Web Inspection Interface

The ngrok agent ships with a realtime inspection interface which allows you to see what traffic is sent to your application server and what responses your server is returning.

Inspecting requests

Every HTTP request through your tunnels will be displayed in the inspection interface. After you start the ngrok agent, open http://localhost:4040 in a browser on the same machine. You will see all of the details of every request and response including the time, duration, source IP, headers, query parameters, request payload and response body as well as the raw bytes on the wire.

The inspection interface has a few limitations. If an entity-body is too long, ngrok may only capture the initial portion of the request body. Furthermore, ngrok does not display provisional 100 responses from a server.

Inspection is only supported for HTTP tunnels. TCP and TLS tunnels do not support any inspection and will not show up in the inspection interface.
Detailed introspection of HTTP requests and responses

Request body validation

ngrok has special support for the most common data interchange formats in use on the web. Any XML or JSON data in request or response bodies is automatically pretty-printed and checked for syntax errors.

The location of a JSON syntax error is highlighted

Filtering requests

Your application server may receive many requests, but you are often only interested in inspecting some of them. You can filter the requests that ngrok displays to you. You can filter based on the request path, response status code, size of the response body, duration of the request and the value of any header.

Click the filter bar for filtering options


You may specify multiple filters. If you do, requests will only be shown if they much all filters.

Filter requests by path and status code

Replaying requests

Developing for webhooks issued by external APIs can often slow down your development cycle by requiring you do some work, like dialing a phone, to trigger the hook request. ngrok allows you to replay any request with a single click, dramatically speeding up your iteration cycle. Click the Replay button at the top-right corner of any request on the web inspection UI to replay it.

Replay any request against your tunneled web server with one click

Replaying modified requests

Sometimes you want to modify a request before you replay it to test a new behavior in your application server.

Click the dropdown arrow on the 'Replay' button to modify a request before it is replayed


The replay editor allows you to modify every aspect of the http request before replaying it, including the method, path, headers, trailers and request body.

The request replay modification editor

ngrok Agent Status Page

ngrok's local web interface has a dedicated status page that shows configuration and metrics information about the running ngrok process. You can access it at http://localhost:4040/status.

The status page displays the configuration of each running tunnel and any global configuration options that ngrok has parsed from its configuration file.

Tunnel and global configuration


The status page also display metrics about the traffic through each tunnel. It display connection rates and connection duration percentiles for all tunnels. For http tunnels, it also displays http request rates and http response duration percentiles.

Tunnel traffic metrics

Diagnose Command

The ngrok diagnose command is available in the ngrok agent and runs a series of tests to diagnose potential issues when starting a tunnel. For more information, check out the ngrok agent reference for the diagnose command.

$ ngrok diagnose
Testing ngrok connectivity...

Internet Connectivity
  Name Resolution                           [ OK ]
  TCP                                       [ OK ]
  TLS                                       [ OK ]
Ngrok Connectivity
  Name Resolution                           [ OK ]
  TCP                                       [ OK ]
  TLS                                       [ OK ]
  Tunnel Protocol                           [ OK ]

Successfully established ngrok connection! (region: 'us', latency: 112.461875ms)

Automatic Updates

The ngrok agent can be configured to automatically update to the latest version when available. You can configure how the upgrades work and which channel (stable, unstable, beta) to update from using the ngrok agent configuration file.

ngrok as a Background Service

The ngrok agent includes additional functionality that makes it easy to install and manage itself as a native operating system service on Windows, MacOS and Linux. This makes it extraordinarily easy to set up ngrok in a production configuration that will cause it to start on machine boot, restart after crashes, and integrate with the native tools system administrators are familiar with to manage and inspect its state.

When running as a service, the ngrok agent configures itself from its configuration file and starts all tunnels defined in the configuration file. When ngrok runs as a service, it executes the equivalent behavior of running ngrok start --all.

Note: Installing ngrok as a service requires admin or sudo permissions in most cases.

Windows

On Windows, the ngrok agent installs itself as a Windows service. It can be managed via Windows Services and it logs all errors and warnings to the Windows event log.

MacOS

On MacOS Darwin, the ngrok agent creates an appropriate plist file and installs itself to run via launchd. Warnings and errors are logged via syslog.

Linux

On Linux, only systems with upstart or systemd installed are supported for service installation. If neither is installed, you will need to set up your own management of the ngrok process as a service. Warnings and errors are logged via syslog.

Installation

Installing ngrok as a system service is the same on all on operating systems. First, create a configuration file somewhere on your machine. For this example, let's assume it's in C:\ngrok\ngrok.yml. In your configuration file, make sure you include an authtoken and define all of the tunnels that you want to start. Then run:

ngrok service install --config C:\ngrok\ngrok.yml

This will validate that the configuration file is valid, and if so, install ngrok as a service using the given configuration file. The service installation includes the location of the ngrok binary, so don't move or delete it after you've installed the service.

Management

After your service is installed, you probably want to start it. You can easily do that with:

ngrok service start

ngrok exposes the following commands to make service administration easy. The commands take no arguments and do what you would expect.

Remote Management

The ngrok agent can be stopped, restarted, or upgraded remotely using the Tunnel Sessions API. You can also perform these actions from the ngrok Dashboard.

WARNING: Use this with caution if you have made changes to the config file. If for some reason ngrok cannot restart, you may lose access to the agent completely.

SSH Reverse Tunnel Agent

SSH reverse tunneling is an alternative mechanism to start an ngrok tunnel without needing to download or run the ngrok agent. You can start tunnels via SSH without downloading an ngrok agent by running an SSH reverse tunnel command.

The SSH gateway functionality should not be confused with exposing an SSH server via ngrok. If you want to expose your own SSH server for remote access, please refer to the using ngrok with ssh section of the documentation.

The main features you miss out on when using the SSH Reverse Tunnel Agent instead of the ngrok agent is the ability to run multiple tunnels at the same time and the resiliency features for automatically reconnecting in case of network outages. At this point in time, the reverse tunnel agent does not support the latest capabilities found in the ngrok agent, although we plan to support that in the future.

Uploading a Public Key

Before you can start a tunnel via the SSH gateway, you'll need to upload your SSH public key. To upload your SSH public key, open the file ~/.ssh/id_rsa.pub and copy its contents. Then go to the Auth tab on your dashboard and paste the contents into the SSH Key input and optionally enter a human description (like the name of your machine). You should now be able to start SSH tunnels!

Copy your SSH public key on MacOS
cat ~/.ssh/id_rsa.pub | pbcopy
Add your SSH key by pasting it into the ngrok dashboard.

Examples

ngrok tries to honor the syntax of ssh -R for all of the tunnel commands in its SSH gateway. 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.

The following examples demonstrate how to use the SSH gateway and provide the equivalent ngrok agent command to help you understand how to achieve similar functionality.

Note that following examples use the US region for agent ingress (tunnel.us.ngrok.com). There are agent ingress URLs for each of the available regions.

Start an http tunnel forwarding to port 80
# equivalent: `ngrok http 80`
ssh -R 80:localhost:80 tunnel.us.ngrok.com http
Start an http tunnel on a custom subdomain forwarding to port 8080
# equivalent: `ngrok http --subdomain=custom-subdomain 8080`
ssh -R custom-subdomain.ngrok.io:80:localhost:8080 tunnel.us.ngrok.com http
Start an http tunnel on a custom domain with auth
# equivalent: `ngrok http --hostname=example.com --basic-auth "user:password" 8080`
ssh -R example.com:80:localhost:8080 tunnel.us.ngrok.com http -auth="user:password"
Start a TCP tunnel
# equivalent: `ngrok tcp 22`
ssh -R 0:localhost:22 tunnel.us.ngrok.com tcp 22
Start a TCP tunnel on a reserved address
# equivalent: `ngrok tcp --remote-addr=1.tcp.ngrok.io:24313 22`
ssh -R 1.tcp.ngrok.io:24313:localhost:22 tunnel.us.ngrok.com tcp
Start a TLS tunnel
# equivalent: `ngrok tls 8443`
ssh -R 443:localhost:8443 tunnel.us.ngrok.com tls
Start a tunnel in a different region
# equivalent: `ngrok http --region=eu 80`
ssh -R 80:localhost:80 tunnel.eu.ngrok.com http

HTTP Tunnels

ngrok HTTP tunnels allow you to route HTTP protocols quickly and easily. These include websites, RESTful APIs, web servers, websockets, and much more.

Starting an HTTP tunnel is a easy as ngrok http 80, or whatever local port your service is running on. For a full list of options for starting HTTP tunnels, see our ngrok agent HTTP Tunnel reference.

Custom subdomains

ngrok assigns random names to the HTTP tunnels it opens for you. This is okay for one-time personal uses. But if you're displaying the URL at a hackathon or integrating with a third-party webhook, it can be frustrating if the tunnel name changes or is difficult to read. You can specify a custom subdomain for your tunnel URL with the --subdomain switch.

Example: Open a tunnel with the subdomain 'inconshreveable'
ngrok http --subdomain=inconshreveable 80

Password protecting your tunnel with Basic Auth

Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password. You can make your tunnels secure with the --basic-auth flag. This enforces HTTP Basic Auth on all requests with the username and password you specify as an argument. You can include multiple --basic-auth flags to allow multiple users.

Example: Password-protect your tunnel
ngrok http --basic-auth="username:password" 8080

Tunnels on custom branded domains

Instead of your tunnel appearing as a subdomain of ngrok.io, you can connect ngrok tunnels to your custom domains. To run a tunnel over dev.example.com, follow these steps:

  1. Navigate to the Domains tab of your ngrok.com dashboard and click 'Add a domain'. Enter dev.example.com as a Reserved Domain. This guarantees that no one else can hijack your domain name with their own tunnel.
  2. On your dashboard, click on the 'CNAME' icon to copy your CNAME target.
  3. Create a DNS CNAME record from dev.example.com to your CNAME target. In this example, we would point the CNAME record to 2w9c34maz.cname.ngrok.io
  4. Invoke ngrok with the --hostname switch and specify the name of your custom domain as an argument. Make sure the --region you specify matches the region in which you reserved your domain.
    Example: Run a tunnel over a custom domain
    ngrok http --region=us --hostname=dev.example.com 8000

Local HTTPS servers

ngrok assumes that the server it is forwarding to is listening for unencrypted HTTP traffic, but if your server is listening for encrypted HTTPS traffic, you can specify a URL with an https:// scheme to request that ngrok speak HTTPS to your local server.

Forward to an https server by specifying the https:// scheme
ngrok http https://localhost:8443

As a special case, ngrok assumes that if you forward to port 443 on any host that it should send HTTPS traffic and will act as if you specified an https:// URL.

Forward to the default https port on localhost
ngrok http 443
ngrok assumes that your local network is private and it does not do any validation of the TLS certificate presented by your local server.

Rewriting the Host header

When forwarding to a local port, ngrok does not modify the tunneled HTTP requests at all, they are copied to your server byte-for-byte as they are received. Some application servers like WAMP and MAMP and use the Host header for determining which development site to display. For this reason, ngrok can rewrite your requests with a modified Host header. Use the --host-header switch to rewrite incoming HTTP requests.

If rewrite is specified, the Host header will be rewritten to match the hostname portion of the forwarding address. Any other value will cause the Host header to be rewritten to that value.

Rewrite the Host header to 'site.dev'
ngrok http --host-header=rewrite site.dev:80
Rewrite the Host header to 'example.com'
ngrok http --host-header=example.com 80

Serving local directories with ngrok's built-in file server

ngrok can serve local file system directories by using its own built-in file server, no separate server needed. You can serve files using the file:// scheme when specifying the forwarding URL.

All paths must be specified as absolute paths, the file:// URL scheme has no notion of relative paths.

Share a folder on your computer with authentication
ngrok http --basic-auth="user:password" file:///Users/alan/share

File URLs can look a little weird on Windows, but they work the same:

Share a folder on your Windows computer
ngrok http "file:///C:\Users\alan\Public Folder"

Tunneling to HTTP or HTTPS only

By default, when ngrok runs an HTTP tunnel, it opens endpoints for both HTTP and HTTPS traffic. If you wish to only forward HTTP or HTTPS traffic, but not both, you can toggle this behavior with the --scheme flag.

Example: Only listen on an HTTP tunnel endpoint
ngrok http --scheme=http site.dev:80
Example: Only listen on an HTTPS tunnel endpoint
ngrok http --scheme=https site.dev:80

HTTP Tunnel Examples

ngrok http 8080                             # forwards provided ngrok URL to port 80
ngrok http example.com:9000                 # forward traffic to example.com:9000
ngrok http --subdomain=bar 80               # request subdomain name: 'bar.ngrok.io'
ngrok http --hostname=www.ex.com 1234       # request tunnel 'ex.com' (DNS CNAME)
ngrok http --basic-auth='falken:joshua' 80  # enforce basic auth on tunnel endpoint
ngrok http --host-header=ex.com 80          # rewrite the Host header to 'ex.com'
ngrok http file:///var/log                  # serve local files in /var/log
ngrok http https://localhost:8443           # forward to a local https server

HTTP Tunnel Configuration Options

For a full list of options for configuring HTTP tunnels, see our ngrok agent HTTP Tunnel reference.

TLS Tunnels

HTTPS tunnels terminate all TLS (SSL) traffic at the ngrok.com servers using ngrok.com certificates. For production-grade services, you'll want your tunneled traffic to be encrypted with your own TLS key and certificate. ngrok makes this extraordinarily easy with TLS tunnels.

Check out the ngrok agent TLS tunnel documentation for the complete details for starting a TLS Tunnel.

Forward TLS traffic to a local HTTPS server on port 443
ngrok tls --subdomain=encrypted 443

Once your tunnel is running, try accessing it with curl.

curl --insecure https://encrypted.ngrok.io

TLS Tunnels without certificate warnings

Notice that --insecure option in the previous curl command example? You need to specify that because your local HTTPS server doesn't have the TLS key and certificate necessary to terminate traffic for any ngrok.io subdomains. If you try to load up that page in a web browser, you'll notice that it tells you the page could be insecure because the certificate does not match.

If you want your certificates to match and be protected from man-in-the-middle attacks, you need two things. First, you'll need to buy an SSL (TLS) certificate for a domain name that you own and configure your local web server to use that certificate and its private key to terminate TLS connections. How to do this is specific to your web server and SSL certificate provider and beyond the scope of this documentation. For the sake of example, we'll assume that you were issued an SSL certificate for the domain secure.example.com.

Once you have your key and certificate and have installed them properly, it's now time to run a TLS tunnel on your own custom domain name. The instructions to set this up are identical to those described in the HTTP tunnels section: Tunnels on custom domains. The custom domain you register should be the same as the one in your SSL certificate (-hostname argument to start the TLS tunnel on your own domain.

Forward TLS traffic over your own custom domain
ngrok tls --region=us --hostname=secure.example.com 443

Terminating TLS connections

It's possible that the service you're trying to expose may not have the capability to terminate TLS connections. The ngrok agent can do this for you so that you can encrypt your traffic end-to-end but not have to worry about whether the local service has TLS support. Specify both the -crt and -key command line options to specify the filesystem paths to your TLS certificate and key and the ngrok agent will take care of terminating TLS connections for you.

Offload TLS Termination to the ngrok Agent
ngrok tls --region=us --hostname secure.example.com --key /path/to/tls.key --crt /path/to/tls.crt 80

Running non-HTTP services over TLS tunnels

ngrok TLS tunnels make no assumptions about the underlying protocol being transported. All examples in this documentation use HTTPS because it is the most common use case, but you can run run any TLS-wrapped protocol over a TLS tunnel (e.g. IMAPS, SMTPS, SIPS, SRTP, etc) without any changes.

Compatible Clients

TLS tunnels work by inspecting the data present in the Server Name Information (SNI) extension on incoming TLS connections. Not all clients that initiate TLS connections support setting the SNI extension data. These clients will not work properly with ngrok's TLS tunnels. Fortunately, nearly all modern browsers use SNI. Some modern software libraries do not though. The following list of clients do not support SNI and will not work with TLS tunnels:

A more complete list can be found on the Server Name Indication page on Wikipedia

TLS Tunnel Examples

# forward TLS traffic for www.example.com to port 443 (requires CNAME)
ngrok tls --hostname=www.example.com 443

# forward TLS traffic on subdomain (mismatch certificate warning)
ngrok tls 1234

# terminate TLS traffic for t.co before forwarding
ngrok tls --hostname=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443

TLS Tunnel Configuration Options

Check out the ngrok agent TLS tunnel documentation for all the configuration options for TLS tunnels.

TCP Tunnels

Not all services you wish to expose are HTTP or TLS based. ngrok TCP tunnels allow you to expose any networked service that runs over TCP. This is commonly used to expose SSH, game servers, databases and more. Starting a TCP tunnel is easy.

Expose a TCP based service running on port 1234
ngrok tcp 1234

Reserved TCP Addresses

Normally, the remote address and port is assigned randomly each time you start a TCP tunnel. For production services (and convenience) you often want a stable, guaranteed remote address. To do this, first, log in to your ngrok.com dashboard and click "Reserve Address" in the "Reserved TCP Addresses" section. Then use the --remote-addr option when invoking ngrok to bind a tunnel on your reserved TCP address. Make sure the --region you specify matches the region in which you reserved your address.

Bind a TCP tunnel on a reserved remote address
ngrok tcp --region=us --remote-addr 1.tcp.ngrok.io:20301 22

TCP Tunnel Examples

Expose an SSH server listening on the default port
ngrok tcp 22
Expose a Postgres server listening on the default port
ngrok tcp 5432
Expose an RDP server listening on the default port
ngrok tcp 3389

TCP Tunnel Configuration Options

Check out the ngrok agent TCP tunnel documentation for all the configuration options for TCP tunnels.

Agent ingress

Agent ingress refers to the specific URL that the ngrok agent attempts to connect through to send requests. By default, that ingress URL is tunnel.[region].ngrok.io:443 but it can be customized with your own custom ingress URL if needed.

You can do this by adding the server_addr option to the ngrok configuration file. Setting up your own custom domain for agent ingress involves changing your nameservers for the domain to allow ngrok to manage though routes. You can configure this yourself in the ngrok Dashboard. Once this process is completed, you will configure the agent to connect to server_addr: tunnel.[region].ingress.example.com:443 assuming you had registered ingress.example.com as your custom ingress URL.

Forwarding to servers on a different machine (non-local services)

ngrok can forward to services that aren't running on your local machine. Instead of specifying a port number, just specify a network address and port instead.

Example: Forward to a web server on a different machine
ngrok http 192.168.1.1:8080