Skip to main content

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.

Was this page helpful?
Last updated