Flags, files and environment

Tunnel options can be set three ways: on the command line, in a --config file, or as a TESTINGBOT_* environment variable. That lets a container or CI job be configured without assembling a long command line.

Since v5.0

Three ways, one order

When an option is set in more than one place, the command line wins, then the config file, then the environment.

# these three are equivalent
java -jar testingbot-tunnel.jar --se-port 4446

echo "se-port = 4446" > tunnel.conf
java -jar testingbot-tunnel.jar --config tunnel.conf

TESTINGBOT_SE_PORT=4446 java -jar testingbot-tunnel.jar

The environment comes last because it is the most ambient of the three, and the least likely to be what someone meant when they also typed a flag or wrote a file.

Config file

A properties file. Keys are the long option names without the leading dashes. Lines starting with # are comments.

# testingbot-tunnel.conf
# Run with: java -jar testingbot-tunnel.jar --config testingbot-tunnel.conf

tunnel-identifier = staging
se-port = 4445
metrics-port = 8003

# Upstream proxy: host:port (HTTP), http://host:port or socks5://host:port
proxy = corp-proxy.internal:8080

# Only reach these hosts; everything else gets 403
allow-hosts = staging.example.com,*.internal.example

# Domains to refuse (comma separated regular expressions).
# Backslashes must be doubled in this file.
fast-fail-regexps = .*\\.doubleclick\\.net,.*google-analytics\\.com

# Boolean options: true to enable, omit or false to leave off
shared = true
nobump = false

Boolean options accept true, yes, on or 1. Anything else, including false, leaves the option off.
A boolean set to false in the file is not overridden by the environment, so shared = false stays off even if TESTINGBOT_SHARED=true is set.
The file is read as a Java properties file, so a backslash is an escape character. Write a regular expression's \. as \\., or it reaches the tunnel as a bare ..
An unknown key stops the tunnel at startup rather than being ignored, so a typo does not silently drop a setting.
Anything given explicitly on the command line still wins over the file.
Run --help to list every option, or see the CLI reference.

When to use a file

A file is the easiest way to manage long --allow-hosts or --fast-fail-regexps lists, to keep a tunnel's setup in version control, and to share one setup between developers. Keep credentials out of it: use the environment for those.

Environment variables

Long options have a TESTINGBOT_* alias, derived from its name: upper-case it, replace dashes with underscores and prefix TESTINGBOT_. The few exceptions are listed below the table.

Option	Environment variable
--se-port	`TESTINGBOT_SE_PORT`
--tunnel-identifier	`TESTINGBOT_TUNNEL_IDENTIFIER`
--allow-hosts	`TESTINGBOT_ALLOW_HOSTS`
--bind-address	`TESTINGBOT_BIND_ADDRESS`
--log-http	`TESTINGBOT_LOG_HTTP`
--shared	`TESTINGBOT_SHARED=true`

A few options have no environment alias because they make no sense on every run: --help, --version, --doctor, --ready and --config. TESTINGBOT_AUTH is special: it takes a comma-separated list of host:port:user:password entries, one per --auth.

This is what makes the Docker image configurable from a compose file or a Kubernetes manifest:

docker run --rm \
  -e TESTINGBOT_KEY=... -e TESTINGBOT_SECRET=... \
  -e TESTINGBOT_TUNNEL_IDENTIFIER=ci-$BUILD_ID \
  -e TESTINGBOT_ALLOW_HOSTS=staging.example.com \
  testingbot/tunnel:5.0

Where the tunnel reads your key and secret

Positional arguments: java -jar testingbot-tunnel.jar KEY SECRET
client-key and client-secret in a --config file
The TESTINGBOT_KEY and TESTINGBOT_SECRET environment variables
A ~/.testingbot file containing key:secret

Get your key and secret from your account page.

Keeping credentials out of the process list

Anything on the command line is visible to other users of the machine in ps. Options that carry a secret are better set in the environment.

Option	Environment variable	Format
KEY SECRET	`TESTINGBOT_KEY`, `TESTINGBOT_SECRET`	your account credentials
--auth	`TESTINGBOT_AUTH`	`host:port:user:password`, comma-separated for several
--proxy-userpwd	`TESTINGBOT_PROXY_USERPWD`	`user:password`
--proxy-testingbot-userpwd	`TESTINGBOT_PROXY_TESTINGBOT_USERPWD`	`user:password`
--metrics-auth	`TESTINGBOT_METRICS_AUTH`	`user:password`

Positional credentials

The positional KEY SECRET form is still supported, but it puts your secret in ps for as long as the tunnel runs. On a shared machine or CI runner, prefer TESTINGBOT_KEY / TESTINGBOT_SECRET or ~/.testingbot. A flag always wins over the matching variable.