Skip to content

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.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>.jar is no longer left behind for deletion on reboot.
  • Linux deb
    • Upgrading from 2.x no longer stops at an interactive dpkg prompt about broker-config.yml. The package ships a starter config under /usr/share/britive-broker and creates broker-config.yml only if it does not exist.
    • The leftover 2.x britive-broker-<version>.jar is removed.
    • The 2.x logback.xml is removed. If you edited it, your copy is kept as logback.xml.dpkg-bak.
    • The systemd unit stays at /lib/systemd/system, the same path as 2.x.
    • dpkg --purge now also removes broker-config.yml.
  • 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.service overrides 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.file in broker-config.yml to also write a rotating log file, using the same rotation settings as Windows. /opt/britive-broker/logs is 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 verifications in a resource type, the same way as scans and rotates, with a local or remote script source. Set max_concurrent_verifications (or BRITIVE_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 (or BRITIVE_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.yml has no http_proxy section, the broker uses HTTPS_PROXY and NO_PROXY for both bootstrap and the MQTT connection. The BRITIVE_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-broker on Linux and macOS, britive-broker.exe on 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 Broker service, prompts for the tenant subdomain and token on first install, and keeps your existing broker-config.yml on upgrade.
  • Log rotation by file size and time, configured in the logging section of broker-config.yml or with BRITIVE_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_password is ignored.
  • Logging. logback.xml is no longer used. Configure logging in broker-config.yml.
  • Proxy. JVM -D proxy options are ignored; use the http_proxy section. http_proxy.connection_type is 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 config section of broker-config.yml can be set with a BRITIVE_BROKER_* environment variable, for example BRITIVE_BROKER_TENANT_SUBDOMAIN, BRITIVE_BROKER_AUTH_TOKEN, BRITIVE_BROKER_CA_CERTIFICATE_PATH, and BRITIVE_BROKER_HTTP_PROXY_HOST. Environment variables take precedence over the file. If both BRITIVE_BROKER_AUTH_TOKEN and BRITIVE_BROKER_AUTH_TOKEN_GENERATOR are set, the token is used. broker-config.yml is now optional, but resource_types can only be set in the file: without it, the broker runs in demo mode.
  • Truststore password. Set truststore_password (or BRITIVE_BROKER_TRUSTSTORE_PASSWORD) if the password of Java’s default cacerts truststore 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_path are 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, and resources_generator. Before, they were always resolved under scripts_path.
  • Upgrading or reinstalling the rpm package no longer fails when the britivebroker user 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: 2 configuration (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: 2 in the config section to use the new resource_types layout. Each resource type lists its scans, rotates, and permissions. A scan or rotate has a source (local to run your own script, or remote to run the script Britive sends), an optional execution_environment, and an optional file_extension. Permissions keep the 1.x settings (max_supported_version, checkout_script, checkin_script). Without version, or with version: 1, the 1.x layout still works. New Windows installs write version: 2.
  • Shared execution environment. With version: 2, a top-level config.execution_environment applies to every bootstrap and resource script that doesn’t set its own, and every execution_environment uses <BRITIVE_SCRIPT_PLACEHOLDER> for the script path.
  • Concurrency limits. max_concurrent_scans and max_concurrent_rotates set 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_path to 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_proxy settings, 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 requiring java-21-openjdk.

1.0.0

The first generally available release. Requires Java 21.

  • Bootstrap. The broker registers with your tenant using tenant_subdomain and a broker pool authentication token, given directly (authentication_token) or by a script that prints it (authentication_token_generator). Optional broker_name_generator (defaults to the host name) and resources_generator scripts are run from scripts_path (defaults to the bootstrap folder).
  • Checkout and checkin. Under resource_types, each resource type and permission sets max_supported_version: local runs your own checkout_script and checkin_script, any runs the scripts Britive sends, and a version number runs Britive’s scripts up to that version. execution_environment wraps the script command, for example with sudo; <BRITIVE_PERMISSION_SCRIPT> stands for the script path, and <BRITIVE_BOOTSTRAP_SCRIPT> for bootstrap scripts. file_extension sets 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 optionally username and password in the http_proxy section.
  • 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 Broker service. 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-broker and run the broker as the britive-broker systemd service under the britivebroker user. The deb depends on openjdk-21-jre-headless, the rpm on java-21-openjdk.
    • tar.gz and zip for manual installs.
Last updated on