I Grok. You Grok. We All Grok For ngrok!
I have been wanting to write about ngrok for a long time but it’s a tough topic. It’s not tough because it’s complicated. It’s not tough because it’s hard to explain. It’s tough because it’s so stunningly simple that it’s hard to carve out enough words to create a post about it. It’s like explaining a coat hanger; unchanged since creation; as functional now as it was in its primordial form. But, today I am going to do it. As the (para)phrase goes “don’t mistake my simplicity for simplicity”. Or, something like that.
Before we start this journey, I want to share with you the most interesting thing I learned while writing this.
Grok/ˈɡrɒk/ is a neologism coined by American writer Robert A. Heinlein for his 1961 science fiction novel [Stranger in a Strange Land](https://en.wikipedia.org/wiki/StrangerinaStrangeLand “Stranger in a Strange Land”). – Wikipedia
Mind. Blown. The term “grok” has always been a Douglas Adams thing for me. OK, now we can move on.
What’s an ngrok?
The website describes it best. Ngrok is a tool that “exposes local servers behind NATs and firewalls to the public internet over secure tunnels.” Which sounds awesome, and it is.
You install ngrok on your system, launch it by telling it what type of tunnel you’d like (usually TCP or HTTP) and ngrok responds by giving you a publicly available URL that other folks can use to connect to your local app. It is that easy.
Why would I use it?
I am a sysadmin and as such I have a pretty broad knowledge of a lot of tools. I have a deep knowledge of a subset of those tools, but the rest…well…sysadmins are tinkerers and I’m the King Tinkerer. I can get just about anything to the “it works” phase but sometimes the end spit and polish are beyond me so I frequently have a need to hit my app from outside my local machine. And I’m lazy, so I want to do that with as little work as possible.
Collaborate
For that reason, I sometimes need to test or demo code in place, rather than going through the pain of spinning up a new server for it, or pushing it to an existing internet-connected environment. With ngrok, I can provide anyone with a temporary ngrok URL to access my local system.
This is one of the great uses of ngrok, in my opinion. If I am running a little code snippet that’s not really complete, or perhaps I haven’t gotten around to creating a safe home for it on a public server, or the corporate IT guys won’t poke a hole in the firewall for me, my colleagues can just hit the temporary ngrok URL and see my service for themselves. Home users don’t even need to muck around with port forwarding on their routers.
Special mention: Mobile testing
It is also incredibly useful for testing mobile services. It is notoriously difficult to emulate the mobile experience without actually using a mobile device. The internet is polluted with services and tools to help developers emulate the mobile experience. And, while it is possible to modify the DNS of some mobile devices to hit your service, you would have to expose it on the internet to make that happen. Using ngrok, you have none of those worries because users will simply hit a normal available URL on their phone and arrive at your internal service via the ngrok tunnel.
Inspect
When ngrok is launched, it displays your assigned URLs that can be used to access your local service. That’s awesome. But, even better, it also launches a browser-based inspection tool so you can view requests and responses. By default, the inspection tool runs on your localhost on port 4040. I ran the command ./ngrok http 80 and ngrok fired up and displayed the following useful information for me.
Ngrok gives me two public URLs in the ngrok.io domain, one for plain HTTP and one for HTTPS secured with an ngrok TLS certificate. It also tells me where requests to those URLs are going to end up. In my case, on a local copy of Nginx running on port 80.
It also provides me with a Web Interface URL which is my local traffic inspector. When requests are made to those public URLs, I can see the request, my service’s response, and some other neat things.
I can view the request in a few different ways. I usually prefer the “Raw” tab and we can see that my Nginx instance just responds with a page containing the text “Hi”.
Replay (and Modify)
This is where it gets truly interesting. See that “Replay” button? Yes, it does what you think – it just replays the last request. That is useful if you need to make a modification to the local code and don’t want to reconstruct the request again.
Now, click the down arrow on that blue button.
Replay with modifications! This is very useful if you need to make changes to the request on the client-side and don’t want to have the request reissued. Clicking the Replay with Modifications button brings up the page below which allows you to alter parts of the initial request, and then replay it back into your local service.
In my opinion, the most useful part is the ability to modify the host and quickly replay a request. Yes, you can use curl with the -H switch, but sometimes you need to hit a service with an actual browser or from an app, and modifying the request is almost always easier than mucking about on the client-side. You can also click the minus button beside each parameter to remove it entirely from the request, or lick the Add Header or Add Trailer buttons to add a new parameter. You get bonus points if you already knew about the existence of HTTP Trailers, although I strongly feel they should be named HTTP Footers to more nicely correlate to the term HTTP Headers.
Advanced uses
The list of features available in ngrok that I will probably never use is nearly endless. Here are some of the top ones that grab my attention and I think could be very useful:
Custom domains and subdomains
Whenever I fire up ngrok on my free plan, I am assigned a random subdomain. That is fine for me, but I can understand why some people would chose a paid plan to allow either personal subdomains (something.ngrok.io) or their own FDQN (myapp.com). This is especially true if your ngrok URL is buried in your code. Modifying your code every time you restart ngrok would get old fast.
TCP tunnels
Ngrok doesn’t just work with HTTP. It can start up TCP tunnels on arbitrary ports to support a wide variety of scenarios.
HTTP Basic Authentication protection
Basic Auth isn’t the best, but given that ngrok should only be used for testing and development, it’s a reasonable precaution to protect your tunnel. Paid plans also support IP whitelisting to add an additional layer of protection if desired.
You grok now?
I hope this gives you enough info to investigate ngrok. I could not hope to compile a comprehensive list of its possible uses which is how I know it is a great tool. I have used it to demo website changes to my partner, configure OSSEC SIEM integrations before pushing them live, and to debug my API code while developing. You will likely find a bunch more uses that I haven’t even thought of yet.
my shorter content on the fediverse: https://the.mayhem.academy/@jdw