Forge Home


Installs and configures ngrok binary and tunnels


2,335 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.2.1 (latest)
  • 1.2.0
  • 1.1.1
  • 1.1.0
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Dec 30th 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 7.0.0
  • , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'gabe-ngrok', '1.2.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add gabe-ngrok
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install gabe-ngrok --version 1.2.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Tags: ngrok


gabe/ngrok — version 1.2.1 Dec 30th 2019


This module will install and configure the ngrok tunnel utility for you, and configure tunnels. By default, it places the ngrok binary in /usr/local/bin, and its configuration file in /etc/ngrok.yml. By default, it starts an ngrok process, activating all defined tunnels.

In other words, including the class and declaring a single ngrok::tunnel resource should result in that tunnel being active once the Puppet run is complete.

Class and defined type parameters match the ones you'll find in the config file, so for the most part, declaring these matches what you've been typing on the command line or in a config file.

Once ngrok is running, you can verify which tunnels are running by using the included ngrok fact.

facter -p ngrok


Single http tunnel

Suppose you simply want to tunnel an http connection to your local port 80. Include the class and declare a single tunnel.

include ngrok
ngrok::tunnel { 'web traffic':
  proto => 'http',
  addr  => '80',

Specifying an auth token and tcp

If you want to use tcp connections, you'll need to have an account on After you login there, it tells you what your token is. Armed with this, you can declare the class and a defined type for a tcp tunnel. This example would be useful on a Puppet master running code manager, to allow outside machines to hit its code deployment API.

class { 'ngrok':
  authtoken       => '0lkjaidwshytMGYT3dyy0928301983C2b7H2Mw5RnnqvZY',

ngrok::tunnel { 'webhook':
  proto => 'tcp',
  addr  => '8170',

Install and configure, but don't run

You might like to install and configure ngrok, but not start up the service. There's a parameter to the main class for that.

class { 'ngrok':
  service_manage => false,

Start ngrok, but don't start tunnels

You might want to define a bunch of tunnels, and have ngrok running, but not have it automatically start any of those tunnels. Use the service_tunnels parameter to instruct ngrok to not automatically enable any tunnels.

class { 'ngrok':
  service_tunnels => '--none',
ngrok::tunnel { 'web':
  proto => 'http',
  addr  => '80',

Tunnel to another machine

ngrok lets you use one machine to create a tunnel to another machine. To do that, specify a hostname in front of the port number.

ngrok::tunnel { 'app':
  proto => 'http',
  addr  => '',
ngrok::tunnel { 'ssh':
  proto => 'tcp',
  addr  => 'secret.bastion.local:22',




The main and only class, this installs and does the main configuration of ngrok on a system. It has sensible defaults for the location of the binary and configuration file, but you can override those.


Where to pull the zip file from. The default grabs the 64-bit Linux version.


Where to put the ngrok binary. By default, it goes in /usr/local/bin


Where to put he ngrok.yaml file. By default, drops it right in /etc

There are also a few parameters for telling Puppet what to do (or if) with the service.


Whether to even bother managing the ngrok service. Defaults to true


If we're managing the service, what state should it be in. Default: running


When activating the service, this string is tacked on to the command, to instruct ngrok which tunnels to automatically enable at that time. The default is '-all'. Note that if you don't declare any ngrok::tunnel resources, you will need to set this to '--none' as ngrok will error out if there are no tunnels defined and you say '--all'. It can also take a space-separated list of tunnel names to start. Remember, you will need an auth token (login to to see it) if you want to run tcp tunnels.


Optionally, ensure that the unzip package is installed. Default: false

Other paramters

The ngrok class also exposes parameters for each possible main configuration options. A detailed list of those options is available on the site itself at:

Defined Types


This type adds tunnel stanzas to the main ngrok configuration file. All of the attributes that it can accept match the names of options that a tunnel's yaml can contain. For a list of these, with descriptions, see the main documentation page at:



This fact lists the active tunnels, as reported by the API.


This module doesn't try to save you from invalid configurations. For instance, it's possible to omit your auth token, and then try to run some tcp tunnels, which fail without an auth token. Puppet does not know about this situation, and will quietly try to start the service on every run.

If you see the runs starting the service on every try, but the service isn't actually running, try to start ngrok by hand to see what's going on.