The latest ngrok agent is packed with a ton of new capability but because it is a major release of the agent, there are also some breaking changes to watch out for.
Configuration file - The older configuration file is not compatible with the latest ngrok agent without a few changes. We've automated the process to upgrade so all you need to do is run the new upgrade command.
ngrok config upgrade
Unrecognized configuration parameters - The previous ngrok agent silently ignored any config parameters it didn't understand. This means that you could have a configuration file with parameters that you thought were doing something, but they really weren't. This is also true for the ngrok agent API. The latest ngrok agent will explicitly error when it sees a configuration parameter that it doesn't recognize. It's a good idea to run a check after upgrading to find incompatible arguments.
ngrok config check
This will automatically add version
and
region
options as well as convert the names of legacy options
to their new format. If you're only using ngrok with a configuration file,
there's nothing else to do. For more information about the changes to the
config file, see the
following section.
Only HTTPS tunnels by default - ngrok agent HTTP tunnels by default
will only open a single HTTPS endpoint for your upstream service instead
of both an HTTP and HTTPS endpoint. To enable both, you will need to add
--scheme http --scheme https
to your ngrok agent command or
configuration file.
Automation using the ngrok agent - If you have written any scripts or built wrappers around the ngrok agent using command line flags, there are additional changes you will need to make.
ngrok config add-authtoken TOKEN
. Check out the
ngrok config reference documentation
for more information.
--
and will error if a single hyphen is used. When updating
your scripts, ensure things like --hostname
and
--host-header
are using double hyphens.
-auth
->
--basic-auth
-bind-tls
->
--scheme
For a full list of changes to the agent for v3, see the changelog.
The ngrok agent v3 changes the default region you connect to when opening
a tunnel. Instead of choosing the us region, the ngrok agent will attempt
to connect to the best region for you, usually the one geographically
closest to you. If you run the ngrok config upgrade
command,
it will automatically add a region: us
if your config file
was missing it, since that was previously the default. Check out the
full list of supported regions.
If you configure ngrok to start with a configuration file, the ngrok agent
v3 makes it extremely easy to upgrade by providing the
ngrok config upgrade
command. Running this command will
automatically migrate your configuration file to the latest format.
version
field which is now required and
identifies the configuration version to use. The latest is
version: 2
bind_tls
and auth
, to their updated names
$ ngrok config upgrade -h
NAME:
upgrade - auto-upgrade configuration file
USAGE:
ngrok config upgrade [version] [flags]
DESCRIPTION:
Upgrade a configuration file to a version. The default configuration
file is located at /home/ubuntu/.config/ngrok/ngrok.yml
A backup file will be created with your original configuration file in
the same directory.
You can optionally pass a version to upgrade to. If the configuration file
version is missing, the upgrade command will add it. It also applies all
automatic transformations when upgrading versions. Attempting to downgrade
will result in an error.
By default this command will apply the transformations and display the
final file. Use --dry-run to preview changes before applying
OPTIONS:
--config string upgrade this config file (default /home/ubuntu/.config/ngrok/ngrok.yml)
--dry-run preview the proposed changes
-h, --help help for upgrade
--log string path to log file, 'stdout', 'stderr' or 'false' (default "false")
--log-format string log record format: 'term', 'logfmt', 'json' (default "term")
--log-level string logging level: 'debug', 'info', 'warn', 'error', 'crit' (default "info")
--relocate relocates the config file to the default location
The ngrok config upgrade
command also includes a flag
--relocate
which will move your configuration file to the
updated default location for ngrok agent v3. We follow the
XDG specification
for storing configuration files.
Once you run that command, you should be ready to go with the latest ngrok agent v3.
The latest version of the ngrok agent includes an updated command line argument parser which introduces a few breaking changes.
ngrok config add-authtoken TOKEN
--
and will error if a single hyphen is used. When updating
your scripts, ensure things like --hostname
and
--host-header
are using double hyphens.
-auth
->
--basic-auth
-bind-tls
->
--scheme
Now that you've upgraded to the latest configuration file, you're ready to
start the latest ngrok agent. There's a lot of new stuff in there, but
your old commands should work as well (with the changes from above). Run
ngrok -h
for help or check out the
ngrok agent reference documentation.