--- title: Upgrading TestingBot Tunnel from 4.x to 5.0 description: 'What changes when you upgrade TestingBot Tunnel from 4.x to 5.0: Java 17, loopback-only listeners, quieter request logging and stricter readiness. Existing command lines keep working.' source_url: html: https://testingbot.com/support/tunnel/upgrading md: https://testingbot.com/support/tunnel/upgrading.md --- # 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](https://testingbot.com/support/tunnel/installation#standalone) | | **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](https://testingbot.com#embedding) | ## 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: ```bash java -version ``` If you cannot upgrade Java on the machine, download the [self-contained build](https://testingbot.com/support/tunnel/installation#standalone) for Linux, macOS or Windows. It bundles a trimmed Java runtime, so nothing has to be installed. The [Docker image](https://testingbot.com/support/tunnel/installation#docker) 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. ```bash 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. ```bash # 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](https://testingbot.com/support/tunnel/logging) 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](https://testingbot.com/support/tunnel/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](https://testingbot.com/support/tunnel/embedding). ## Upgrade checklist 1. Install Java 17+, or switch to a [self-contained build](https://testingbot.com/support/tunnel/installation#standalone) or `testingbot/tunnel:5.0`. 2. If tests connect from another host, add `--bind-address 0.0.0.0` and firewall the ports. 3. If you parse the tunnel log per request, add `--log-http url`. 4. Bump Maven to `com.testingbot:TestingBotTunnel:5.0` if you embed the tunnel. 5. Run `--doctor` with your usual flags. In 5.0 it diagnoses the configuration it is actually given. ```bash java -jar testingbot-tunnel.jar --doctor ``` Then look at what 5.0 adds: [traffic rules](https://testingbot.com/support/tunnel/traffic-rules), [config files](https://testingbot.com/support/tunnel/configuration), [Kerberos proxies](https://testingbot.com/support/tunnel/authentication) and [SSH host key pinning](https://testingbot.com/support/tunnel/security#host-key). The full list is in the [changelog](https://testingbot.com/support/tunnel/changelog). ## Looking for more help? Have questions or need more information? Reach out via email or Slack. [Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)