Upgrade Broker 2.x to 3.x

Overview

Broker 3.x replaces the Java-based 2.x broker with a single native binary. The configuration file, install locations, service name, and broker pool authentication token stay the same, and an in-place upgrade is supported on Windows (MSI) and Linux (rpm, deb). You do not need to uninstall 2.x first.

This runbook covers upgrading from 2.x to 3.1.1 or later. 3.1.1 includes installer fixes for upgrades from 2.x. If you must use 3.0.x or 3.1.0, also follow Upgrade with 3.0.x or 3.1.0 Packages.

What you’ll accomplish:

• Review the 2.x settings that no longer apply in 3.x
• Upgrade a broker in place with the rpm, deb, or MSI package
• Verify the 3.x broker is running and connected to your tenant

What Changes in 3.x

Settings That No Longer Apply

Review these before upgrading. Everything else in broker-config.yml carries over unchanged.

• CA certificates added to the Java truststore (for example, a TLS-inspecting proxy’s CA imported with keytool) are not used by 3.x. Export them as a PEM file and set ca_certificate_path in broker-config.yml, or add them to the operating system trust store. truststore_password is ignored.
• JVM options (-Dhttps.proxyHost, -Djavax.net.ssl.*, and similar) in a customized service unit or Britive Broker.ini are ignored. Use the http_proxy section or HTTPS_PROXY.
• BRITIVE_BROKER_HTTP_PROXY_* environment variables are no longer read. Use the http_proxy section of broker-config.yml or HTTPS_PROXY / NO_PROXY.
• http_proxy.connection_type is ignored. 3.x always tunnels through the proxy with HTTP CONNECT.
• Custom logback.xml settings are not used. Use the logging section of broker-config.yml instead. See Logging on Linux.

Before You Begin

systemctl cat britive-broker | head -1

Linux: rpm

For RHEL, Rocky, Amazon Linux, Fedora and other rpm-based systems. Finish every step in Before You Begin first.

sudo dnf upgrade ./britive-broker-3.1.1-1.x86_64.rpm

warning: /opt/britive-broker/config/broker-config.yml created as /opt/britive-broker/config/broker-config.yml.rpmnew
warning: /opt/britive-broker/config/logback.xml saved as /opt/britive-broker/config/logback.xml.rpmsave

Then verify the upgrade.

Linux: deb

For Debian, Ubuntu and other deb-based systems. Finish every step in Before You Begin first.

sudo apt-get install ./britive-broker_3.1.1-1_amd64.deb

Then verify the upgrade.

Windows: MSI

Finish every step in Before You Begin first.

msiexec /i "Britive Broker 3.1.1-amd64.msi" /l*v C:\temp\britive-broker-upgrade.log

Then verify the upgrade.

Verify

systemctl status britive-broker                   # active (running)
systemctl cat britive-broker | grep ExecStart     # ExecStart=/opt/britive-broker/britive-broker
pgrep -af britive-broker.jar                      # no output: no Java broker left running
tail -n 50 /var/log/britive-broker.log            # look for "Connection success"

Get-Service 'Britive Broker'                      # Status: Running
sc.exe qc "Britive Broker"                        # BINARY_PATH_NAME ends in britive-broker.exe
sc.exe qdescription "Britive Broker"              # DESCRIPTION: Britive Broker
Get-Content "C:\Program Files (x86)\Britive Inc\Britive Broker\logs\britive-broker.log" -Tail 50

After the Upgrade

• Remove Java once no broker on the server needs it and nothing else uses it. Installers never remove a shared runtime.
  • RHEL/Rocky: sudo dnf remove java-21-openjdk-headless
  • Debian/Ubuntu: sudo apt-get remove openjdk-21-jre-headless
  • Windows: uninstall Microsoft Build of OpenJDK 21 from Apps & Features.
• Remove leftover files you no longer need: config/logback.xml.rpmsave, config/logback.xml.dpkg-bak, config/broker-config.yml.rpmnew (and config/logback.xml after an upgrade with 3.0.x or 3.1.0 deb packages).
• Remove the backup once you have confirmed the broker works.

Logging on Linux

The 3.x broker writes to standard output, and the service unit sends it to /var/log/britive-broker.log and /var/log/britive-broker_error.log. This needs systemd 240 or later (check with systemctl --version). On older systemd, such as RHEL 8 (systemd 239), the logs go to the journal instead: journalctl -u britive-broker.

To also write the logs to a file of your choice, as a custom logback.xml file appender did with 2.x, set logging.file in broker-config.yml (3.1.1 and later) and restart the broker:

config:
  logging:
    file: logs/britive-broker.log   # = /opt/britive-broker/logs/britive-broker.log

The broker then writes a rotating log file there (100 MB per file, 7 days of archives in logs/archive/, about 1 GB in total by default; tune with max_size_mb, max_age_days and total_size_cap_mb), in addition to standard output. This works on any systemd version. The packages create /opt/britive-broker/logs writable by the britivebroker user; if you use another folder, make sure that user can write to it.

On 3.0.x and 3.1.0, or to redirect standard output itself to another folder on systemd 240 or later, create /etc/systemd/system/britive-broker.service.d/override.conf:

[Service]
StandardOutput=append:/opt/britive-broker/logs/britive-broker.log
StandardError=append:/opt/britive-broker/logs/britive-broker_error.log

Then create the folder and restart:

sudo mkdir -p /opt/britive-broker/logs
sudo systemctl daemon-reload
sudo systemctl restart britive-broker

If you change the log location, update /etc/logrotate.d/britive-broker to match.

Troubleshoot

When contacting Britive support, include:

• Linux: the package-manager output, systemctl status britive-broker, systemctl cat britive-broker, the broker logs, and systemctl --version.
• Windows: the MSI log from /l*v, the Application event log entries from the Britive Broker source, and logs\britive-broker.log.
• broker-config.yml with the broker pool authentication token and any passwords removed.

Roll Back

If 3.x doesn’t work and you can’t fix it quickly, go back to 2.x:

• rpm: sudo rpm -Uvh --oldpackage ./britive-broker-2.1.0-1.noarch.rpm (Java 21 must be installed). On current RHEL/Rocky 9, the Java 21 package no longer satisfies the 2.x package’s java-headless requirement; if rpm reports that dependency as missing while Java 21 is installed, add --nodeps.
• deb: sudo apt-get install --allow-downgrades ./britive-broker_2.1.0_all.deb
• Windows: uninstall Britive Broker from Apps & Features, then install the 2.x MSI. It installs Java 21 if it’s missing.

Then restore broker-config.yml (and any other files you changed) from your backup, and restart the service.

Upgrade with 3.0.x or 3.1.0 Packages

3.0.x and 3.1.0 packages are missing the 3.1.1 upgrade fixes. If you must use them, change the steps above as follows.

rpm and deb packages

• The upgrade only restarts the broker if it was running. If the service was stopped, start it afterwards with sudo systemctl enable --now britive-broker.
• If you removed the 2.x package (rpm -e / dpkg -r) instead of upgrading in place, its Java process keeps running. Stop it with sudo systemctl stop britive-broker (or sudo pkill -f britive-broker.jar) before installing 3.x. 3.1.1 and later do this automatically.
• There is no warning for a copy of the unit in /etc. The service-unit check in Before You Begin is required.
• When the upgrade stops the Java broker, the journal may show Failed with result 'exit-code' (exit status 143). You can ignore it.

deb packages only

• The upgrade stops to ask whether to replace broker-config.yml, and fails when run unattended. Keep your file by running:

  sudo apt-get install -o Dpkg::Options::=--force-confold ./britive-broker_<version>-1_amd64.deb

  If you see the prompt, answer N.

• The old /opt/britive-broker/britive-broker.jar isn’t removed. Once 3.x is running and pgrep -af britive-broker.jar returns nothing, delete it.

• If a copy of the unit in /etc is left in place, the server keeps running 2.x after the upgrade without any error. The pgrep check in Verify catches this.

• dpkg may print dpkg: warning: unable to delete old directory '/lib/systemd/system': Directory not empty. This is harmless.

• config/logback.xml is left in place but no longer used; you can delete it. (Upgrading later to 3.1.1 or newer removes it.)

Windows MSI package

• If the config uses authentication_token_generator, check how long the script takes before upgrading. These versions run the script before the service registers with Windows, which allows about 30 seconds. If the script takes longer, the service fails to start, the installer shows the “failed to start” error with only Retry and Cancel, and the upgrade can’t complete. Time it as SYSTEM on the server, for example from a SYSTEM PowerShell prompt:

  Measure-Command { powershell.exe -File "<install folder>\bootstrap\<token script>" }

  If it takes more than about 20 seconds, upgrade to 3.1.1 or later (which runs the script after the service has started), or temporarily replace authentication_token_generator with a literal authentication_token for the upgrade.

• britive-broker-<version>.jar may be left in the install folder. If the 2.x Java broker takes longer than about 30 seconds to stop during the upgrade, Windows schedules the jar for deletion at the next reboot instead of deleting it. It isn’t used by 3.x; delete it or let the next reboot remove it. 3.1.1 and later stop the Java broker before the old version is removed, so the jar is deleted during the upgrade.

• If the broker can’t start, the installer stops with an error (“Service ‘Britive Broker’ failed to start. Verify that you have sufficient privileges to start system services”). The message is generic and almost never a permissions problem. The dialog offers only Retry and Cancel:

  • Find the cause by running .\britive-broker.exe run from the install folder in an elevated prompt (startup errors aren’t written to the Windows Event Log in these versions). If you can fix it now (for example, an error in broker-config.yml), fix it and choose Retry.
  • If you choose Cancel, the installer rolls back 3.x but can’t restore 2.x, which leaves the server with no broker installed. Fix the cause, then run the MSI again; it installs as a fresh install and prompts for the tenant subdomain and token, so have your broker-config.yml backup ready to copy back.

• A service registered with britive-broker.exe install (zip package) has the description “Britive on-premise broker agent”. Running the MSI over it changes the description to “Britive Broker” and points the service at the install folder. The service name is “Britive Broker” either way.

Next Steps

• Access Broker Deployment — overview of the broker and container-based deployment options
• Deploy on ECS Fargate — if you’d rather move the broker to a container than keep it on a host