ngrok - HTTP and TCP tunnels [Port Forwarding]

What is ngrok?

ngrok exposes local servers behind NATs and firewalls to the public internet over secure tunnels.

How it works

You download and run a program on your machine and provide it the port of a network service, usually a web server.
It connects to the ngrok cloud service which accepts traffic on a public address and relays that traffic through to the ngrok process running on your machine and then on to the local address you specified.

What it's good for

  • Demoing web sites without deploying
  • Building webhook consumers on your dev machine
  • Testing mobile apps connected to your locally running backend
  • Stable addresses for your connected devices that are deployed in the field
  • Running personal cloud services from your home

Documentation

Expose a local web server to the internet

ngrok allows you to expose a web server running on your local machine to the internet. Just tell ngrok what port your web server is listening on.
If you don't know what port your web server is listening on, it's probably port 80, the default for HTTP.
Example: Expose a web server on port 80 of your local machine to the internet
ngrok http 80
When you start ngrok, it will display a UI in your terminal with the public URL of your tunnel and other status and metrics information about connections made over your tunnel.
The ngrok console UI
ngrok by @inconshreveable

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://92832de0.ngrok.io -> localhost:80
Forwarding                    https://92832de0.ngrok.io -> localhost:80

Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Inspecting your traffic

ngrok provides a real-time web UI where you can introspect all of the HTTP traffic running over your tunnels. After you've started ngrok, just open http://localhost:4040 in a web browser to inspect request details.
Try making a request to your public URL. After you have, look back at the inspection UI. You will see all of the details of the request and response including the time, duration, headers, query parameters and request payload as well as the raw bytes on the wire.

Installing your Authtoken

Many advanced features of the ngrok.com service described in further sections require that you sign up for an account. Once you've signed up, you need to configure ngrok with the authtoken that appears on your dashboard. This will grant you access to account-only features. ngrok has a simple 'authtoken' command to make this easy. Under the hood, all the authtoken command does is to add (or modify) the authtokenproperty in your ngrok configuration file.
Install your authtoken
ngrok authtoken <YOUR_AUTHTOKEN>

HTTP Tunnels

Custom subdomain names

ngrok assigns random hexadecimal 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
ngrok by @inconshreveable

...
Forwarding                    http://inconshreveable.ngrok.io -> 127.0.0.1:80
Forwarding                    https://inconshreveable.ngrok.io -> 127.0.0.1:80

Password protecting your tunnel

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 -auth switch. This enforces HTTP Basic Auth on all requests with the username and password you specify as an argument.
Example: Password-protect your tunnel
ngrok http -auth="username:password" 8080

Disabling Inspection

ngrok records each HTTP request and response over your tunnels for inspection and replay. While this is really useful for development, when you're running ngrok on production services, you may wish to disable it for security and performance. Use the -inspect switch to disable inspection on your tunnel.
Example: An http tunnel with no inspection
ngrok http -inspect=false 80

Tunneling only HTTP or HTTPS

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 -bind-tlsswitch.
Example: Only listen on an HTTP tunnel endpoint
ngrok http -bind-tls=false site.dev:80
Example: Only listen on an HTTPS tunnel endpoint
ngrok http -bind-tls=true site.dev:80

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

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 a Minecraft server listening on the default port
ngrok tcp 25565

Locations

ngrok runs tunnel servers in datacenters around the world. The location of the datacenter within a given region may change without notice (e.g. the European servers may move from Frankfurt to London).
  • us - United States (Ohio)
  • eu - Europe (Frankfurt)
  • ap - Asia/Pacific (Singapore)
  • au - Australia (Sydney)

Usage

If you do not explicitly pick a region, your tunnel will be hosted in the default region, the United States. Picking the region closest to you is as easy as specifying setting the -region command line flag or setting the region property in your configuration file. For example, to start a tunnel in the Europe region:
ngrok http -region eu 8080
Reserved domains and reserved addresses are allocated for a specific region (the US region by default). When you reserve a domain or address, you must select a target region. You may not bind a domain or address reserved in another region other than the one it was allocated for. Attempting to do so will yield an error and prevent your tunnel session from initializing.

Comments

Post a Comment

Popular Posts