NgrokLinkify

A tool to expose your Ngrok URLs in an easy-to-access way. This tool uses the Ngrok free plan to get public URLs for your internal services and expose them. You can either use a telegram bot to get the public URLs or use redirection on Github pages to get a permanent URL to access your tunnels.

• Expose your tunnels public URL conveniently for your friends
• No need for setting up port forwarding on your system
• Relatively safe, no hardening needed
• Two choices to expose URLs: Telegram bot and Github pages
• Setup as a systemd service to do this on boot

Related Libraries

• Ngrok
• PyGitHub

Installation

Dependencies

1. You'll have to install Ngrok by downloading it from here. For ease of use you can create a config file similar to the one below

authtoken: TOKEN_ID 
region: in # Set the region to closest one from your location
log_level: info
log_format: json
log: /var/log/ngrok.log
tunnels:
        jupyter: # Name of the tunnel
                proto: http
                addr: 1234 # Port number of the service
                bind_tls: true
        file-download:
                proto: http
                addr: 5678
                bind_tls: true
        heimdall:
                proto: http
                addr: 1111
                bind_tls: true

The name of your tunnel will be the path to the redirect link on Github pages. For ex. to visit the jupyter service you need to visit https://<github-username>.github.io/jupyter. You'll be redirected to the tunnel and should be able access your service.

2. You'll also need to install these dependencies

pip install PyGithub python-telegram-bot

Install NgrokLinkify

pip install NgrokLinkify

Once you install the tool you'll need to create a config file. The basic structure of the config file is available in the package as example-cfg.ini. You can copy the file and edit it according to your system.

[Default]
NgrokUrl = http://127.0.0.1:4040/api/tunnels #API endpoint for Ngrok, this is the default value
LogFile = /var/log/NgrokLinkify.log #Location of the Log File
[Git]
RepoPath = /path/to/github-pages/repo #Change this to the path to your local git pages repo
CommitComment = Committed URL at {0} # Commit Message when committing Github Pages
PagesContent = ---\ntitle: {0}\nredirect_to: {1}\n---\n #The content of the redirect file, I use https://github.com/jekyll/jekyll-redirect-from. You can use raw HTML by following https://stackoverflow.com/questions/5411538/redirect-from-an-html-page and replacing the URL by {0} 
[Telegram]
FailureMsg = The server is not running currently! Ping @username #The Failure message to return when Ngrok isn't running
SuccessMsg = The public urls are \n ---------------------- \n{0} #The success message, {0} here contains tunnel name and public url
BotToken = 123123123 #The Bot token for telegram bot

Setup github repo

To ensure that you can update githuba pages without entering username or password. Enable ssh login to github by following this guide. Once done create and pull your github pages repo to the location mentioned in the config file.

Once you've enabled ssh access to your repo, set the upstream branch with ssh using the following command in the repo directory. Note the URL has to be a ssh url.

git remote set-url origin git@github.com:bagdeabhishek/bagdeabhishek.github.io.git 

Usage

You can directly run the utility by using linkify command

Simple command line usage

linkify -config /path/to/config/file

You can choose to enable telegram bot or update the github page with redirection. use the -h flag to get help

Use it programmatically inside python script

from NgrokLinkify.linkify import Linkify 
Linkify(start_telegram_bot=False ,update_github_pages=True,config_file="/home/abhishek/linkify.ini")

Options

The command line utility accepts the following arguments

--config CONFIG_FILE_LOCATION

Path to the configuration file

--exclude-telegram

Don't run telegram bot

--exclude-gh-pages

Do not update github pages

Persist the services using systemd

The package contains example service file for both NgrokLinkify and Ngrok. You can copy them to /etc/systemd/system/ location.

Ngrok systemd service file

[Unit]                                                                                                                  Description=Ngrok                                                                                                       After=network.service                                                                                                                                                                                                                           [Service]                                                                                                               Type=simple                                                                                                             User=user-name                                                                                                           WorkingDirectory=/home/abhishek                                                                                         ExecStart=/path/to/ngrok start --all --config=".ngrok2/ngrok.yml"                                       Restart=on-failure                                                                                                                                                                                                                              [Install]                                                                                                               WantedBy=multi-user.target 

Enable at boot

Create save this file as ngrok.service in /etc/systemd/system/ location. Run the following commands to enable Ngrok at boot

sudo systemctl daemon-reload;
sudo systemctl enable ngrok.service; 

NgrokLinkify systemd service

You can run NgrokLinkify as a service using the following example

[Unit]                                                                                                                  Description=Telegram bot to return URLs                                                                                 After=ngrok.service network.target network-online.target                                                                PartOf=ngrok.service                                                                                                                                                                                                                            [Service]                                                                                                               Type=simple                                                                                                             User=username                                                                                                           ExecStart=/home/username/miniconda3/bin/linkify --config /home/username/linkify.ini                Restart=on-failure                                                                                                                                                                                                                              [Install]                                                                                                               WantedBy=multi-user.target 

Save this file as NgrokLinkify.service in /etc/systemd/system/ location. Enable the service at boot using the follwing commands

sudo systemctl daemon-reload;
sudo systemctl enable ngrok.service;