Every flag, every variable
The complete commandline reference for TestingBot Tunnel. Pass credentials positionally, via environment variables, or from a .testingbot file in your $HOME.
Three ways to authenticate
Method 1
Positional args
java -jar testingbot-tunnel.jar KEY SECRET
Method 2
Env vars
TESTINGBOT_KEY + TESTINGBOT_SECRET
Method 3
.testingbot file
In $HOME, containing key:secret.
Environment variables
Use environment variables to keep sensitive credentials out of your shell history and the system process list.
| Variable |
Replaces / purpose |
| TESTINGBOT_KEY |
Your TestingBot API key. Replaces the first positional argument. |
| TESTINGBOT_SECRET |
Your TestingBot API secret. Replaces the second positional argument. |
| TESTINGBOT_AUTH |
Basic-auth credentials in the form host:port:user:password. Replaces -a. |
| TESTINGBOT_PROXY_USERPWD |
Upstream proxy credentials as user:password. Replaces -z. |
| TESTINGBOT_METRICS_AUTH |
HTTP-basic credentials for the metrics endpoint as user:password. Replaces --metrics-auth. |
| TESTINGBOT_PROXY_TESTINGBOT_USERPWD |
Credentials for --proxy-testingbot as user:password. |
Since 5.0, long options have an environment alias: --se-port reads TESTINGBOT_SE_PORT, --allow-hosts reads TESTINGBOT_ALLOW_HOSTS, and so on. The exceptions are --help, --version, --doctor, --ready and --config, which have no alias, and TESTINGBOT_AUTH, which takes a comma-separated list of --auth entries. Options can also come from a --config file. Precedence is command line, then config file, then environment. See configuration.
All command-line options
Run --help for the list your version supports. Options marked new in 5.0 need tunnel 5.0 or later.
| Option |
Description |
| -h,--help |
Display help text and exit. |
| -v,--version |
Display the tunnel version and exit. |
| --doctor |
Run diagnostics with the options given and exit: DNS, connectivity to TestingBot, free ports, upstream proxy, Kerberos and --cacert-file subjects. |
| --config <FILE> |
Read options from a properties file. Keys are long option names without dashes. New in 5.0. See configuration. |
| -i,--tunnel-identifier <id> |
Tag the tunnel with an identifier. When you have multiple tunnels, set this identifier in your test capabilities to pick which tunnel handles the test. |
| -s,--shared |
Share this tunnel with other users on your team. A tunnel started without it is only kept from colleagues when your team has a tunnel policy. |
| -P,--se-port <port> |
Local Selenium port your tests connect to. Default 4445. |
| -j,--localproxy <port> |
Port the local proxy listens on. Default 8087. |
| --bind-address <ADDRESS> |
127.0.0.1 (default) or 0.0.0.0. Interface for every local listener: the Selenium relay, local proxy, metrics port and --web. New in 5.0; 4.x bound every interface. See upgrading. |
| -p,--hubport <port> |
Hub port the tunnel server forwards your Selenium traffic to: 80 (default) or 4444. That hop starts on the tunnel server, so it needs no firewall rule on your side. |
| -x,--noproxy |
Do not start the local proxy. Requires you to run your own proxy on port 8087. |
| -q,--nocache |
Bypass the caching proxy running on the tunnel VM. Required for WebSocket and SSE proxying. |
| -w,--web <directory> |
Serve a local directory over a built-in webserver. Handy for static-file testing. |
| -f,--readyfile <FILE> |
Touch this file when the tunnel is ready. Prefer --ready for health checks. |
Traffic rules, headers and site auth
| Option |
Description |
| --allow-hosts <HOST,*.HOST> |
Only reach these hosts; everything else is refused with 403. *.suffix matches subdomains. New in 5.0.
|
| -F,--fast-fail-regexps <LIST> |
Comma-separated regular expressions for hosts the tunnel should refuse. Prefix an entry with ! to make an exception, e.g. .*,!ok\.com. |
| --localhost-policy <allow|deny> |
Whether tunnel traffic may reach this machine's loopback interface. Default allow. New in 5.0.
|
| --connect-to <H1:P1:H2:P2> |
Dial H2:P2 for requests to H1:P1, keeping the URL, Host header and TLS SNI. Comma separated. New in 5.0.
|
| --dns <server[,server]> |
Resolve hostnames with these DNS servers, host or host:port. The first is primary, the rest are fallbacks. |
| --dns-round-robin |
Spread queries across the --dns servers instead of using the first as primary. |
| --dns-timeout <seconds> |
Timeout per DNS server. Default 5. |
| --http-dial-timeout <seconds> |
TCP connect timeout to targets and upstream proxies. Default 5 for the API, 15 for tunnelled connections. |
| --http-idle-timeout <seconds> |
Close connections idle this long. Default 120 for HTTP, 300 for CONNECT. |
| -a,--auth <host:port:user:passwd> |
Perform HTTP Basic Authentication for specific hosts. Plain HTTP only. See authentication. |
| --krb5-hosts <HOST,HOST> |
Send Kerberos (SPNEGO) credentials to these sites. Never wildcarded. Plain HTTP only. |
| --header <RULE> |
Edit a request header: name: value sets, name; empties, -name removes, -name* removes by prefix. Repeatable. Plain HTTP only. See header rewriting. |
| --response-header <RULE> |
Edit a response header, same grammar as --header. For example -Content-Security-Policy. |
| --extra-headers <JSON> |
Add request headers from a JSON object. |
| --pac <url> |
PAC URL for the remote browser to use. Not the same as --pac-local. |
Upstream proxy
| Option |
Description |
| -Y,--proxy <[scheme://]host:port> |
Upstream proxy for egress: host:port, http://host:port or socks5://host:port. Also used for the connection to TestingBot unless --proxy-testingbot is set. |
| -z,--proxy-userpwd <user:pwd> |
Credentials for --proxy. Env: TESTINGBOT_PROXY_USERPWD. |
| --proxy-auth-scheme <basic|negotiate> |
How to authenticate to the upstream proxy. negotiate is Kerberos/SPNEGO. |
| --proxy-spn <SPN> |
Service principal for Negotiate. Default HTTP/<proxy-host>. |
| --krb5-keytab <FILE> |
Keytab for unattended Kerberos. Requires --krb5-principal. |
| --krb5-principal <PRINCIPAL> |
Principal to log in as with the keytab. |
| --proxy-testingbot <host:port> |
Separate proxy for reaching TestingBot itself: the API and the SSH connection. |
| --proxy-testingbot-userpwd <user:pwd> |
Credentials for --proxy-testingbot. Not inherited from --proxy-userpwd. |
| --pac-local <FILE|URL> |
Choose this tunnel's egress per destination from a PAC file. A plain http:// URL needs --pac-local-sha256. See PAC files. |
| --pac-local-sha256 <HEX> |
SHA-256 the PAC document must have. |
| --pac-test <URL> |
Evaluate --pac-local for one URL, print the result and exit. |
| --ws-proxy-mode <connect|get> |
How a ws:// upgrade traverses --proxy. Default connect. |
TLS and SSH
| Option |
Description |
| -b,--nobump |
Do not perform SSL bumping. Required for WebSocket and SSE proxying. See SSL bumping. |
| --nobump-domains <HOST,HOST> |
Do not perform SSL bumping for these hosts (comma separated), while still bumping everything else. Use it when one environment behind the tunnel presents a certificate that cannot be re-signed. Ignored when --nobump is given. |
| --cacert-file <FILE> |
Trust an additional CA (PEM), for proxies that intercept TLS. Repeatable. Added to the platform trust store. |
| --ssh-host-key <SHA256:...> |
Pin the SHA-256 fingerprint the tunnel server's SSH host key must have. Repeatable. See security. |
| --ssh-host-key-policy <warn|require> |
Without a fingerprint: warn (default) connects and says so, require refuses. |
Logging and health
| Option |
Description |
| -l,--logfile <FILE> |
Write logs to a file in addition to stdout. |
| --log-level <level> |
One of error, warn, info (default), debug, trace. |
| -d,--debug |
Alias for --log-level debug. |
| --log-http <MODE> |
none, url, headers or errors (default). Per module: proxy:none,forwarder:headers. See logging. |
| --log-format <text|json> |
One JSON object per record with json. |
| --request-id-header <NAME> |
Correlation id header. Default X-Request-Id. |
| --metrics-port <port> |
Port for the JSON status, Prometheus /metrics, /healthz and /readyz. Default 8003. |
| --metrics-auth <user:password> |
Protect /metrics with HTTP Basic Authentication. Health endpoints stay open. |
| --ready |
Query a running tunnel's /readyz and exit 0 (ready) or 1. See health checks. |
See practical configurations on the examples page, or the full installation guide for Docker, Maven and the NodeJS launcher.