This is both usable API and CLI to gather information from ngrok client or server account.
CLI is described in this document. API should be described someday (help will be gratefully accepted).
To work with ngrok client API we need no configuration, but if you want
to get information about tunnels started under your account on some other
(inaccessable directly) computer, you must provide login information
which will be stored in configuration file ngroktool.yml
nearby ngrok.yml
.
- Get information from local instance of
ngrok
. - Get information from dashboard.ngrok.com site.
- Store several accounts of dashboard.ngrok.com site.
- Switch
accesstoken
of ngrok between saved accounts. - Specify path to configuration files
ngrok.yml
andngroktoo.yml
. - Search tunnel by protocol, name, local address and/or port.
- Create new tunnel in local instance of
ngrok
. - All features available both via CLI tool and API functions.
git clone https://github.com/pyhedgehog/ngroktool.git
First you will need to add login information to config file. There are choices:
- If you are using it with
ngrok
started on the same computer you could skip this section. - If you have created account on https://dashboard.ngrok.com/ itself, you should do:
node ngroktool.js -a yourauthname auth ngrokuser ngrokpass
- If you are using "Login with Github", you should do:
node ngroktool.js -a yourauthname auth -g githubuser githubpass
- If you are using "Sign in with Google", you should wait until it will be implemented or prepare pull request, sorry.
Global option -a yourauthname
is essential - it must be used with all other commands to indicate what account you want to use.
If you want to use local ngrok
omit it.
When you have several accounts, you can switch between them, using:
node ngroktool.js -a yourauthname switch
Display program-parsable (JSON) info for tunnels as it's returned from ngrok (format differs for local and remote operations):
node ngrok.js -a yourauthname dump -r
Display program-parsable (JSON) info for tunnels with unified field names:
node ngrok.js -a yourauthname dump
Display human-readable list of tunnels with information by columns:
node ngrok.js -a yourauthname list
Note: Remote operations can't get same ammount of information as remote - you can't retrieve local address, local port and tunnel name.
There are three subcommands to retrieve information on specific tunnel: tcp
, http
, https
.
You can select tunnels by type (name of command), tunnel name, local port and/or local host name.
However limitations on remote tunnels mentioned in [[#Display]] section also applies to these commands too.
There are several usages of this functionality.
You can also use ngroktool
as a library:
var ngroktool = require('ngroktool');
ngroktool.setconfigpath(pathtoconfig);
ngrokcfg.setauth({name:'yourauthname', login:'yourgithubname', password:'yourgithubpassword', type:'github'});
ngrokcfg.setauth({name:'otherauthname', login:'yourname', password:'yourpassword', type:'ngrok'});
ngroktool.login('yourauthname');
ngroktool.findtunnels({proto:'tcp', port:'22', name:'ssh', host:'127.0.0.1'}, function(foundtunnels, alltunnels){console.log(foundtunnels);});
ngroktool.login(null);
ngroktool.addtunnel({proto:'tcp', addr:'22', name:'ssh'});
ngroktool.addtunnel({proto:'tcp', addr:'other:22', name:'otherssh'});
You can use it directly in ssh_config
(assuming you are using cygwin, installed socat
and path to your copy of ngroktool is c:\ngroktool
):
Host home-ngrok
ProxyCommand socat - socks4a:127.0.0.1:`cd /cygdrive/c/ngroktool;node ngroktool.js -a yourauthname tcp`,socksport=9050
After that ssh home-ngrok
will connect you to computer running ngrok tcp 22
under specified account.
You can add new tunnel to running instance of ngrok
using it's API. This command only available on same computer as ngrok
(i.e. you can't pass -a
option here).
Forward local ssh:
node ngroktool.js add tcp 22
Forward web-server on computer testserver
:
node ngroktool.js add http testserver:80
Forward web-server on computer testserver
and replace tunnel ever if it's already exists (uses new ngrok subdomain):
node ngroktool.js add -f http testserver:80
# node ngroktool.js -h
usage: ngroktool.js [-h] [-v] [-c CONFIG] [-a AUTH]
{auth,switch,tcp,http,https,add,list,help,dump} ...
Get info about tunnels from either stored account of ngrok.com or from
locally started ngrok.
Optional arguments:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
-c CONFIG, --config CONFIG
Path to config file (defaults to ~/.ngrok2/ngroktool.
yml)
-a AUTH, --auth AUTH Auth synonym to use
subcommands:
{auth,switch,tcp,http,https,add,list,help,dump}
ngroktool.js help - show help for all subcommands
# node ngroktool.js help|grep usage:
usage: ngroktool.js [-h] [-v] [-c CONFIG] [-a AUTH]
usage: ngroktool.js auth [-h] [-g] [user] [password]
usage: ngroktool.js switch [-h]
usage: ngroktool.js tcp [-h] [-n NAME] [-H HOST] [port]
usage: ngroktool.js http [-h] [-n NAME] [-H HOST] [port]
usage: ngroktool.js https [-h] [-n NAME] [-H HOST] [port]
usage: ngroktool.js add [-h] [-n NAME] [-d SUBDOMAIN] [-H HOSTNAME] [-r] [-f]
usage: ngroktool.js list [-h]
usage: ngroktool.js dump [-h] [-r]
Adds new authorization synonym to config file.
usage: ngroktool.js auth [-h] [-g] [user] [password]
Add or modify saved account info
Positional arguments:
user User
password Password
Optional arguments:
-h, --help Show this help message and exit.
-g, --github Login with GitHub user
Will select authorization synonym as current for ngrok client (i.e. change authtoken
).
# node ngroktool.js switch -h
usage: ngroktool.js switch [-h]
Switch ngrok to authtoken for selected account
Optional arguments:
-h, --help Show this help message and exit.
# node ngroktool.js list -h
usage: ngroktool.js list [-h]
Lists all tunnels in columns format
Optional arguments:
-h, --help Show this help message and exit.
# node ngroktool.js dump -h
usage: ngroktool.js dump [-h] [-r]
Dump all tunnels in JSON format
Optional arguments:
-h, --help Show this help message and exit.
-r, --raw Dump all info
# node ngroktool.js tcp -h
usage: ngroktool.js tcp [-h] [-n NAME] [-H HOST] [port]
Search for tcp tunnels
Positional arguments:
port Private port to search (first found if not specified)
Optional arguments:
-h, --help Show this help message and exit.
-n NAME, --name NAME Connection name to search
-H HOST, --host HOST, --hostname HOST
Private host to search (usually 127.0.0.1)
TBD: See [API usage](#API usage) section now.