ngrok lets you expose a locally running web service to the internet. Just tell ngrok which port your web server is running on. Let's try opening port 80 to the internet.
$ ngrok 80
ngrok Tunnel Status online Version 1.3/1.3 Forwarding http://3a4bfceb.ngrok.com -> 127.0.0.1:80 Forwarding https://3a4bfceb.ngrok.com -> 127.0.0.1:80 Web Interface http://127.0.0.1:4040 # Conn 0 Avg Conn Time 0.00ms
When you run ngrok, it will display a UI in your terminal with the current status of the tunnel. This includes the public URL it has allocated to you which will forward to your local web service: https://3a4bfceb.ngrok.com.
ngrok captures all of the HTTP traffic that runs through it and provides a real-time web UI where you can introsepct the requests in more detail. After starting ngrok, open http://localhost:4040. Make a request to your tunnel and you should see the web UI update with detailed information about the request including the time, duration, headers, form and query parameters as well access to examine the raw bytes sent over the wire.
ngrok's web interface allows detailed introspection of HTTP requests and responses
ngrok has special support for the most common data interchange formats in use on the web. Any XML or JSON data is automatically pretty-printed for you and checked for syntax errors.
ngrok highlighting the location of a JSON syntax error
ngrok allows you to replay any http request that has been made through the tunnel. Click the Replay button at the top-right of any request in the web UI and ngrok will replay it to your server.
Replay any request with a single click
By default, ngrok tunnels do not require any username or password to access them. This means anyone who knows or guesses the URL or your tunnel can make requests to it. You can secure your tunnels with a username and password by specifying the
-httpauth option when creating your tunnel. This will force HTTP basic authentication on all incoming requests to your tunnels and require that the credentials match those you specify on the command line.
$ ngrok -httpauth="helmet:12345" 80
$ curl -u "helmet:12345" https://3a4bfceb.ngrok.com
ngrok assigns random hexadecimal names like https://3a4bfceb.ngrok.com to the tunnels it opens for you. For one-time personal use tunnels, this is OK. However, if you are displaying this URL at a public event like a hackathon, or you've set this URL as a webhook for some third-party application, it can be frustrating if the tunnel name changes or is difficult to read. ngrok allows you to open a tunnel with a custom subdomain of your choosing with the
-subdomain option. Let's try opening a tunnel on the example subdomain.
$ ngrok -subdomain=example 80
ngrok ... Forwarding https://example.ngrok.com -> 127.0.0.1:80 ...
Are you developing a service that runs on IRC, SMTP, SIP, POP3, XML-RPC or even a custom network protocol that isn't HTTP? ngrok can still expose this service to the internet for you by running in TCP mode! When you run ngrok in TCP mode, it will allocate a port for you on ngrok.com and forward all traffic on that port to your local service. Unfortunately, when you run in TCP mode, ngrok does not know how to understand and parse your traffic, so its diagnostic and debugging tools are much more primitive when operating in this mode.
$ ngrok -proto=tcp 22
ngrok ... Forwarding tcp://ngrok.com:50612 -> 127.0.0.1:22 ...
ngrok can also be used to forward traffic to services behind a NAT or firewall even if that service is not on the same machine. Forwarding traffic to another machine is as simple as adding an ip address or name before the port.
$ ngrok 192.168.0.1:80
ngrok has a
-hostname option which allows you to forward traffic from your own domains without running your own ngrok server. For example, if you want ngrok to create a tunnel for
dev.example.com, you must:
dev.example.comthat points to
ngrok.comusing whatever DNS management you have for
-hostnameoption like so:
$ ngrok -hostname dev.example.com 80
-hostnameoption, you may still access your tunnel over SSL, but the certificate will not match.
The ngrok configuration file is a completely optional very simple YAML file that allows you to use some of ngrok's more advanced features like:
-configcommand line switch.
To run multiple tunnels, you need to configure each tunnel in the configuration file using the
tunnels parameter. The tunnels parameter takes a dictionary of names to tunnel configurations. As an example, let's define the configuration for three different tunnels. The first will be a tunnel for a client site that we're working on that only runs https traffic and has authentication. The second will be the configuration for a tunnel to allow us to access our own machine remotely via SSH by tunneling to port 22. And lastly, we'll create a tunnel that will run on my own custom domain for showing off projects at a hackathon.
tunnels: client: auth: "user:password" proto: https: 8080 ssh: proto: tcp: 22 hacks.inconshreveable.com: proto: http: 9090
We can then start all three tunnels simultaneously by using the
ngrok start command followed by the names of the tunnels we want to start:
ngrok start client ssh hacks.inconshreveable.com
The terminal should then look something like:
ngrok Tunnel Status online Version 1.3/1.3 Forwarding https://client.ngrok.com -> 127.0.0.1:8080 Forwarding http://hacks.inconshreveable.com -> 127.0.0.1:9090 Forwarding tcp://ngrok.com:44764 -> 127.0.0.1:22 ...
Each configured tunnel may specify any of five parameters:
remote_port. Every tunnel must have a
proto section defined which is a dictionary of protocol to local forwarding address. The
auth parameter is the optional authentication used for http/https tunnels. The
remote_port parameter is the optional port to bind on the remote server and is only used for tcp tunnels. ngrok uses the name of the tunnel as the subdomain or hostname for the tunnel it creates, but you can override this:
tunnels: client: subdomain: "example" auth: "user:password" proto: https: 8080
Now when you
ngrok start client it will forward
example.ngrok.com -> 127.0.0.1:8080. Similarly, this works
for custom hostnames, which can let you alias them to something shorter to type:
tunnels: hacks: hostname: "hacks.inconshreveable.com" proto: http: 9090
For TCP tunnels, you may optionally request a specific port from the server with the
remote_port parameter. If not specified, the server will assign you a random port.
tunnels: ssh: remote_port: 60123 proto: tcp: 22
The ngrok configuration file additionally lets you tweak some less-common configuration settings by specifying additional top-level parameters in the config file. For example, you may explicitly set the authtoken used when validating to ngrok.com with the
authtoken parameter. You may also change the address that ngrok binds with to serve its web inspection interface by setting
authtoken: abc123 inspect_addr: "0.0.0.0:8888" tunnels: ...
ngrok supports connecting to another ngrokd server not hosted by ngrok.com. First, you must obviously set up your own ngrokd server. Instructions on how to run your own ngrokd are posted here: Running your own ngrokd server. When you run your own ngrokd server, you need to configure two configuration parameters to let ngrok connect securely to your custom server. First you'll set
server_addr to point ngrok at your custom server and then
trust_host_root_certs to make sure your TLS connections are trusted.
server_addr: "example.com:4443" trust_host_root_certs: true tunnels: ...
Lastly, you can configure ngrok to run behind an http proxy server, which is sometimes necessary when you're on restrictive corporate networks. ngrok respects the standard unix environment variable
http_proxy, but you can also specify it explicitly by setting the parameter
http_proxy in the configuration file:
http_proxy: "http://user:email@example.com:3128" tunnels: ...