How to compile ngrok on a Raspberry Pi

Secure introspectable tunnels to localhost


Ngrok is a tool that let’s you create secure tunnels to localhost. It’s usefull to expose local services to the Internet without configuring firewalls.

There is an hosted version of this tool that you can use right out of the box.

In this post I’m going to explain how to compile the source code in order to generate a server and a client with a built in self-signed certificate on a Raspberry PI.

Those instructions are valid for the 1.x version of the software, since it’s currently open sourced.

All operations are performed on a fresh installation of Raspbian on a Raspberry PI B+.

For now on all operations are made on the Raspberry, so SSH into it.

Installing Go

Ngrok is built using the Go programming language, in order to compile it properly we need the version 1.4 of Go.

If you have not done yet, you need git on your system, to install it simply

sudo apt-get install -y git

To manage the installation of go we use gvm, the Go Version Manager.

bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

This command uses cURL to grab the GitHub repo and install it into your user directory. The file that this repo is placed in is ~/.gvm.

It’s also needed to install bison so let’s

sudo apt-get install bison

Next we need also to update our .bashrc file.

echo “[[ -s “$HOME/.gvm/scripts/gvm” ]] && source “$HOME/.gvm/scripts/gvm”” >> ~/.bashrc

To apply changes to the current shell session simply run

source ~/.bashrc

Now to install Go 1.4 we can

gvm install go1.4
Downloading Go source...
Installing go1.4...
* Compiling...

This process will take a while, so it’s better if you take a break while waiting.

After compiled the source code of go we need to tell to the system that we want to use this last version that we have just compiled with

gvm use go1.4
Now using version go1.4

And export the ENV variable

export GOROOT_BOOTSTRAP=$GOROOT

You may want to

go version

to check if go is installed properly.

Compiling ngrok source code

We need to install some other tools before to start:

sudo apt-get install build-essential mercurial

We can now clone the GitHub repository and start configuring the compiling process

git clone https://github.com/inconshreveable/ngrok.git ngrok
cd ngrok

Generating self-signed cert

Let me be straight, first I declare for simplicity a variable in the current shell session

NGROK_DOMAIN=”example.com”

Where example.com is your server domain name. Then you can simply past those lines to generate the self-signed cert.

openssl genrsa -out rootCA.key 2048
openssl req -x509 -new -nodes -key rootCA.key -subj “/CN=$NGROK_DOMAIN” -days 5000 -out rootCA.pem
openssl genrsa -out device.key 2048
openssl req -new -key device.key -subj “/CN=$NGROK_DOMAIN” -out device.csr
openssl x509 -req -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out device.crt -days 5000

Once the cert is generated copy them into the folder assets/client/tls/ngrokroot.crt

cp rootCA.pem assets/client/tls/ngrokroot.crt

Start the compilation

And we can start the compilation with

make release-server release-client

You will find the generated binaries into the folder ./bin .

Run client and server

To run the server

./bin/ngrokd \ 
-tlsKey=device.key -tlsCrt=device.crt \
-domain=”$NGROK_DOMAIN” \
-httpAddr=”:8000" -httpsAddr=”:8001"

To run the client we must first create a configuration file

echo -e “server_addr: $NGROK_DOMAIN:4443\ntrust_host_root_certs: false” > ngrok-config
./bin/ngrok -config=ngrok-config 80

Configuring the domain

Once you compiled everything you need to point the domain name towards your Raspberry, this process changes heavily depends on your network configuration (if the board is behind a firewall, you have a dynamic IP etc).

You must be sure that your domain supports wildcard subdomains so when the client generate a random subdomain the subdomain endpoint will be instantly available.

If your domain provider does not support wildcard DNS you can always use Cloudflare to manage DNS using the free plan.

Further readings

  • Official documentation for 1.x

If you like what you read, please hit the green “Recommend” button below so that others might stumble upon this essay. For more essay like this scroll down and follow me.

Follow me on Twitter or visit my personal blog. If you want to hear some tips from me that I do not usually share on twitter subscribe also on my Telegram channel.

Show your support

Clapping shows how much you appreciated Nicola Malizia’s story.