Upgrading from 4.x to 5.0

Tunnel 5.0 adds 28 options and removes none, so your existing command lines keep working. Six things do change. The first three are the ones most people notice.

v5.0
No options removed
Java 17

What changes

Area	4.x	5.0	To keep 4.x behaviour
Java	11	17	None: hard requirement, or use a self-contained build
What listeners bind	every interface	`127.0.0.1`	`--bind-address 0.0.0.0`
Per-request logging	one line per request	only failures and 5xx	`--log-http url`
Selenium relay logging	always logged	honours `--log-http`	`--log-http forwarder:url`
Docker image	n/a	sets `TESTINGBOT_BIND_ADDRESS=0.0.0.0`	None: published ports keep working
Embedding the JAR	Jetty 11 + Servlet API	Jetty 12 core handlers	Source change, see below

Java 17 is required

Tunnel 5.0 is built on Jetty 12, which needs Java 17. The JAR's classes cannot be loaded by an older JVM.

On an older Java the tunnel now says so plainly, instead of failing with A JNI error has occurred. Check what you have:

java -version

If you cannot upgrade Java on the machine, download the self-contained build for Linux, macOS or Windows. It bundles a trimmed Java runtime, so nothing has to be installed. The Docker image already ships Java 17.

Listeners bind loopback

In 4.x, the Selenium relay (4445), the local proxy (8087), the metrics port (8003) and --web (8080) accepted connections from any machine that could route to yours.

None of those listeners authenticates. The Selenium relay attaches your TestingBot key and secret to everything it forwards, and the local proxy will connect anywhere your machine can, including its own loopback. In 5.0 they bind 127.0.0.1.

Same machine

Nothing changes

Tests that connect to localhost:4445 on the tunnel machine work as before. This is the normal setup.

Different machine

Add --bind-address 0.0.0.0

Then restrict who can reach the ports with a firewall rule.

java -jar testingbot-tunnel.jar --bind-address 0.0.0.0

Docker

The image sets TESTINGBOT_BIND_ADDRESS=0.0.0.0 for you, because a loopback bind inside a container makes published ports unreachable. Narrow access on the host side of the publish instead: -p 127.0.0.1:4445:4445.

Successful requests no longer log

--log-http now defaults to errors: the request line and headers are logged only for failed or 5xx responses. The Selenium relay follows the same setting, where it previously logged every request.

# one line per request, as in 4.x
java -jar testingbot-tunnel.jar --log-http url

# browser traffic quiet, Selenium relay verbose
java -jar testingbot-tunnel.jar --log-http proxy:none,forwarder:url

See the logging guide for per-module levels and JSON output.

Readiness is stricter

/readyz reports ready only after the startup self-test passes, and after a reconnect only once both forwarding directions are back.

A half-working tunnel that used to look healthy now returns 503 until it can actually carry traffic. A self-test that failed for a transient reason is retried while the SSH connection stays up. If your orchestration waits on /readyz, nothing needs to change, it just becomes more accurate. See health checks.

Embedding the JAR

Only relevant if you start the tunnel from your own Java code rather than as a process.

5.0 is built on Jetty 12's core Handler API with no Servlet layer, so code that reached into the tunnel's Jetty internals needs a source change. The supported surface is boot(), awaitReady(Duration) and stop(), described in the embedding guide.

Upgrade checklist

Install Java 17+, or switch to a self-contained build or testingbot/tunnel:5.0.
If tests connect from another host, add --bind-address 0.0.0.0 and firewall the ports.
If you parse the tunnel log per request, add --log-http url.
Bump Maven to com.testingbot:TestingBotTunnel:5.0 if you embed the tunnel.
Run --doctor with your usual flags. In 5.0 it diagnoses the configuration it is actually given.

java -jar testingbot-tunnel.jar --doctor

Then look at what 5.0 adds: traffic rules, config files, Kerberos proxies and SSH host key pinning. The full list is in the changelog.