Launching ngrok Agent Tunnels Automatically with systemd on Boot

ngrok-linux-systemd

In this guide, we’ll explore a streamlined approach to enhance your Linux system by configuring systemd to automatically initiate ngrok agent tunnels upon boot. Say goodbye to manual setups and hello to a seamless, efficient process that ensures your ngrok tunnels are up and running right from the start. Let’s dive in and supercharge your system with this simple yet impactful automation technique.

Install ngrok agent on your Linux machine

First create an account to ngrok.com, they have good and simple documentation to install ngrok agent on your machine. Choose your machine type(e.g., Linux, Raspberry Pi) and you will see the basic command lines. Just run those in your powerful terminal.

Get ngrok auth token

From ngrok dashboard, you will get the authtoken. Actually during installing the agent you will see the auth token and will be saved to a file ngrok.yml

After the installation is complete, look for the location of ngrok.yml file.
Different Linux distributions create this configuration file to different location. You can create your own configuration file on .config folder in the $HOME(/home/your_username/)

Customize/Create ngrok.yml file

if you know where is your ngrok.yml file, then edit it. Otherwise, follow the instruction. I will be using vim as text editor, you can use any. You are free.

$ cd $HOME/.config/
$ mkdir ngrok # if it is not here
$ cd ngrok
$ vim ngrok.yml

Edit and save your ngrok file

version: "2"
authtoken: <your_auth_token_from_ngrok_dashboard>
tunnels:
  web: 
    proto: http
    addr: 80

If you have subscription of any paid plan to ngrok website, you can add your subdomain and multiple tunnels. Free plans get random domain names.

Paid plan and multiple tunnels configuration

version: "2"
authtoken: <your_auth_token_from_ngrok_dashboard>
tunnels:
  web: 
    proto: http
    addr: 80
    domain: <your_subdomain_name>.ngrok.<app, dev, ...>
  ssh:
    proto: tcp
    addr: 22
  <your_desired_name>:
    proto: <protocol_name>
    addr: <port>
    domain: <your_subdomain_name>.ngrok.<app, dev, ...>

Our ngrok.yml configuration is complete. Let’s write the systemd service.

Configure Systemd service file

Check your ngrok executable file location.

$ which ngrok
# `/usr/local/bin/ngrok` in my raspberry pi <3

Write systemd service file.

# requires sudo power 

$ cd /etc/systemd/system/
$ sudo vim myngrok.service

[Unit]
Description=Start ngrok tunnel on startup
After=network-online.target
Wants=network-online.target systemd-networkd-wait-online.service

[Service]
ExecStart=/usr/local/bin/ngrok start --all --config /home/rpi/.config/ngrok/ngrok.yml
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
IgnoreSIGPIPE=true
Restart=always
RestartSec=3
Type=simple

[Install]
WantedBy=multi-user.target

See the ExecStart keyword,

/usr/local/bin/ngrok is ngrok executable file location
/home/rpi/.config/ngrok/ngrok.yml is the config file we just edited

/usr/local/bin/ngrok start --all --config /home/rpi/.config/ngrok/ngrok.yml

is the real command line to be executed on system boot.

Enable and start the service

As myngrok.service is a service file, we need to start/enable with systemctl command to be activated

$ sudo systemctl enable myngrok.service # to enable during the boot
$ sudo systemctl status myngrok.service  # check the status and log of the service

Reboot your Machine and Check service status

After rebooting your pc, it should start the myngrok.service .
Let’s check the status.

$ sudo systemctl status myngrok.service

If you want to check the real-time log

$ sudo journalctl -fu myngrok.service

Conclusion

In this guide, we navigated through the seamless integration of ngrok with systemd, automating the process of initializing ngrok agent tunnels on Linux boot. By configuring systemd services, we elevated the efficiency of ngrok, ensuring that tunnels are established automatically, saving time and enhancing system reliability.
Check my other development and deployment articles.