Broker Release Notes
Broker 3.x is a single native binary. Broker 1.x and 2.x are Java applications that require Java 21. The configuration file, install locations, service name, and broker pool authentication token are the same across all versions, and 1.x and 2.x installs upgrade to 3.x in place. See Upgrade Broker 2.x to 3.x before upgrading from 2.x.
- 3.x
- 2.x
- 1.x
- 1.0.0 — 2025-07-11
3.1.1
Recommended for all upgrades from 2.x. This release fixes several installer problems when upgrading from the Java 2.x broker. If you upgrade from 2.x with 3.0.x or 3.1.0, follow the extra steps in Upgrading with 3.0.x or 3.1.0 packages.
Upgrade fixes
- Windows MSI
- The installer no longer fails with error 1920 (“service failed to start”) when the authentication token generator script is slow. The script now runs on the first bootstrap attempt instead of at service startup.
- The installer no longer fails when the broker hits a startup error. The service is registered before the configuration is loaded.
- A running 2.x broker is stopped before the old files are removed, so
britive-broker-<version>.jaris no longer left behind for deletion on reboot.
- Linux deb
- Upgrading from 2.x no longer stops at an interactive
dpkgprompt aboutbroker-config.yml. The package ships a starter config under/usr/share/britive-brokerand createsbroker-config.ymlonly if it does not exist. - The leftover 2.x
britive-broker-<version>.jaris removed. - The 2.x
logback.xmlis removed. If you edited it, your copy is kept aslogback.xml.dpkg-bak. - The systemd unit stays at
/lib/systemd/system, the same path as 2.x. dpkg --purgenow also removesbroker-config.yml.
- Upgrading from 2.x no longer stops at an interactive
- Linux rpm and deb
- A Java 2.x broker still running after its package was removed is stopped.
- The install warns, with fix steps, when
/etc/systemd/system/britive-broker.serviceoverrides the packaged unit. The file is never modified. - Stopping the Java broker during upgrade (exit status 143) is no longer logged as a failure.
Changes
- Service start on upgrade. If the broker service is enabled, a package upgrade now starts it even if it was stopped beforehand. A service that is not enabled is still only restarted if it was running.
- Log file on Linux. Set
logging.fileinbroker-config.ymlto also write a rotating log file, using the same rotation settings as Windows./opt/britive-broker/logsis now writable by the service user. - Startup errors are logged. Fatal startup errors (configuration load, initialization failures, crashes) are written to the log file and, on Windows, to the Windows Event Log.
- Service description. The service description is now “Britive
Broker” on Windows, whether the service was installed by the MSI or by
britive-broker.exe install, and “Britive Broker service” on Linux.
Fixes
- A script that exits or times out but leaves a child process holding its output no longer blocks the broker past the script timeout.
- Cache file paths that would resolve outside the broker’s cache folder are rejected.
3.1.0
New
- Secret verification. The broker can run verification scripts to
check that a secret is valid. Define them under
verificationsin a resource type, the same way asscansandrotates, with alocalorremotescript source. Setmax_concurrent_verifications(orBRITIVE_BROKER_MAX_CONCURRENT_VERIFICATIONS) to control how many run at once; the default is 1.
3.0.2
New
- Decoded environment logging. Set
logging.log_decoded_environment: true(orBRITIVE_BROKER_LOG_DECODED_ENVIRONMENT=true) to log request environment variable values decoded instead of base64-encoded. Use it for troubleshooting only: the values are written to the log in plaintext. Encrypted environment variables stay redacted. The broker logs a warning at startup while this is on. Off by default.
Fixes
- When the Britive platform shuts down a connection for maintenance, the broker now reconnects immediately instead of waiting.
3.0.1
Changes
- Standard proxy environment variables. If
broker-config.ymlhas nohttp_proxysection, the broker usesHTTPS_PROXYandNO_PROXYfor both bootstrap and the MQTT connection. TheBRITIVE_BROKER_HTTP_PROXY_*environment variables are no longer read.
Fixes
- The MQTT connection now goes through the configured proxy. In 3.0.0 only bootstrap used it.
- Updated the Go runtime and libraries to address published vulnerabilities.
3.0.0
The first release of the native broker.
New
- No Java required. The broker is a single native binary:
britive-brokeron Linux and macOS,britive-broker.exeon Windows. - More platforms and packages. Windows (x64, ARM64) as MSI or zip; Linux (x86_64, aarch64) as rpm, deb, apk (Alpine), pkg.tar.zst (Arch Linux), or tar.gz; macOS as tar.gz.
- Unattended Linux install. Provide the tenant subdomain and broker
pool authentication token (or a token generator script) through
BRITIVE_BROKER_*environment variables or/etc/britive-broker/install.env, and the package configures and starts the broker. Without them, the package installs the files and prints how to finish configuration. - Windows MSI registers and starts the
Britive Brokerservice, prompts for the tenant subdomain and token on first install, and keeps your existingbroker-config.ymlon upgrade. - Log rotation by file size and time, configured in the
loggingsection ofbroker-config.ymlor withBRITIVE_BROKER_LOG_*environment variables.
Changes from 2.x
- Trusted CA certificates. The Java truststore is no longer used. Put
extra CAs (for example, a TLS-inspecting proxy’s CA) in a PEM file set
by
ca_certificate_path, or in the operating system trust store.truststore_passwordis ignored. - Logging.
logback.xmlis no longer used. Configure logging inbroker-config.yml. - Proxy. JVM
-Dproxy options are ignored; use thehttp_proxysection.http_proxy.connection_typeis ignored: the broker always tunnels through the proxy with HTTP CONNECT.
2.1.1
Fixes
- Graceful shutdown. Stopping or restarting the broker now waits up to 2 minutes for requests in progress to finish and send their results. Before, the results of scripts still running at shutdown were lost.
- Environment variables in logs. Decrypted values of encrypted environment variables are no longer written to the log, and request environment variables are no longer logged at debug level.
2.1.0
New
- Configure with environment variables. Every setting in the
configsection ofbroker-config.ymlcan be set with aBRITIVE_BROKER_*environment variable, for exampleBRITIVE_BROKER_TENANT_SUBDOMAIN,BRITIVE_BROKER_AUTH_TOKEN,BRITIVE_BROKER_CA_CERTIFICATE_PATH, andBRITIVE_BROKER_HTTP_PROXY_HOST. Environment variables take precedence over the file. If bothBRITIVE_BROKER_AUTH_TOKENandBRITIVE_BROKER_AUTH_TOKEN_GENERATORare set, the token is used.broker-config.ymlis now optional, butresource_typescan only be set in the file: without it, the broker runs in demo mode. - Truststore password. Set
truststore_password(orBRITIVE_BROKER_TRUSTSTORE_PASSWORD) if the password of Java’s defaultcacertstruststore was changed.
Changes
- Windows MSI installs Microsoft Build of OpenJDK 21.0.10 (previously 21.0.3) when it is not already installed, and no longer prompts to install the JDK when it is.
Fixes
- CA certificates in
ca_certificate_pathare now also trusted for the MQTT connection. In 2.0.x they were used only for HTTPS requests. - The result of a long-running script is no longer lost when the broker replaces its MQTT connection while the script is running.
- The broker reconnects more reliably when the Britive platform shuts down a connection for maintenance.
- Absolute paths now work for
authentication_token_generator,broker_name_generator, andresources_generator. Before, they were always resolved underscripts_path. - Upgrading or reinstalling the rpm package no longer fails when the
britivebrokeruser already exists.
2.0.1
Fixes
- Scans that finish in the same second no longer overwrite each other’s results.
- In demo mode on Windows with
version: 2configuration (the Windows installer’s default), checkout and checkin scripts from Britive now run with PowerShell. - The broker now reconnects after the Britive platform shuts down a connection for maintenance.
2.0.0
New
- Secret rotation and account discovery scans. The broker runs rotation scripts that change a secret and scan scripts that discover accounts on a resource, and uploads scan results to Britive.
- Configuration version 2. Set
version: 2in theconfigsection to use the newresource_typeslayout. Each resource type lists itsscans,rotates, andpermissions. A scan or rotate has asource(localto run your ownscript, orremoteto run the script Britive sends), an optionalexecution_environment, and an optionalfile_extension. Permissions keep the 1.x settings (max_supported_version,checkout_script,checkin_script). Withoutversion, or withversion: 1, the 1.x layout still works. New Windows installs writeversion: 2. - Shared execution environment. With
version: 2, a top-levelconfig.execution_environmentapplies to every bootstrap and resource script that doesn’t set its own, and everyexecution_environmentuses<BRITIVE_SCRIPT_PLACEHOLDER>for the script path. - Concurrency limits.
max_concurrent_scansandmax_concurrent_rotatesset how many scans and rotations run at once. The default for each is 1. - Encrypted environment variables. Britive can send environment variables encrypted for the broker. The broker decrypts them and passes them to the script.
- Extra trusted CA certificates. Set
ca_certificate_pathto a file of CA certificates to trust, in addition to Java’s, for HTTPS connections (for example, through a TLS-inspecting proxy).
Changes
- Error details. When a script fails, the error details sent to Britive are the first 300 characters of the script’s standard error output (standard output if standard error is empty).
- Proxy authentication. The
http_proxysettings, including username and password, apply to all HTTPS requests the broker makes. - rpm dependency. The rpm package accepts any headless Java 21 or later
runtime (
java-headless >= 1:21) instead of requiringjava-21-openjdk.
1.0.0
The first generally available release. Requires Java 21.
- Bootstrap. The broker registers with your tenant using
tenant_subdomainand a broker pool authentication token, given directly (authentication_token) or by a script that prints it (authentication_token_generator). Optionalbroker_name_generator(defaults to the host name) andresources_generatorscripts are run fromscripts_path(defaults to thebootstrapfolder). - Checkout and checkin. Under
resource_types, each resource type and permission setsmax_supported_version:localruns your owncheckout_scriptandcheckin_script,anyruns the scripts Britive sends, and a version number runs Britive’s scripts up to that version.execution_environmentwraps the script command, for example withsudo;<BRITIVE_PERMISSION_SCRIPT>stands for the script path, and<BRITIVE_BOOTSTRAP_SCRIPT>for bootstrap scripts.file_extensionsets the extension of downloaded scripts. - Demo mode. Without
resource_types, the broker accepts any checkout or checkin and runs the script Britive sends. - HTTP proxy. Set
host,port, and optionallyusernameandpasswordin thehttp_proxysection. - Startup retry. If the broker can’t connect at startup, it keeps retrying until it connects or is stopped, doubling the wait between attempts from 1 second up to 30 minutes.
- Script errors. When a script fails, its standard error output (or standard output, if standard error is empty) is sent to Britive.
- Packages.
- Windows MSI installs Microsoft Build of OpenJDK 21 if needed and
runs the broker as the
Britive Brokerservice. It prompts for the tenant subdomain and token on first install, but not when a broker is already installed. - Linux deb and rpm install to
/opt/britive-brokerand run the broker as thebritive-brokersystemd service under thebritivebrokeruser. The deb depends onopenjdk-21-jre-headless, the rpm onjava-21-openjdk. - tar.gz and zip for manual installs.
- Windows MSI installs Microsoft Build of OpenJDK 21 if needed and
runs the broker as the
Last updated on