Linux

Installing Broker on Linux

This section covers installing the Britive broker on Linux from the distribution packages rpm, deb, apk, and Arch Linux pkg.tar.zst. Each package installs the broker binary at . /opt/britive-broker/, a configuration template at opt/britive-broker/config/broker-config.yml, and an init unit (systemd or OpenRC) that runs the broker as the unprivileged britivebroker user.

Make sure you have completed all generic prerequisites mentioned in the Prerequisites section.

The post-install script is fully non-interactive and never prompts; this matches the package-management conventions for rpm, apk, and pacman and treats deb the same way for consistency. Configure the broker through one of these patterns before (or after) the install:

1. Automated with environment variables: Supply the values via BRITIVE_BROKER_* environment variables exported in your config management recipe. This works on rpm, deb and Arch Linux. This pattern is not used for installing on Alpine, as environment variables do not work on Alpine.

2. Automated with an install env-file: Drop a key/value file at /etc/britive-broker/install.env before invoking the package manager. Required on Alpine (apk strips environment variables from package scriptlets) and equally valid as a uniform contract across all packagers.

3. Install first, configure later: install the package with no configuration inputs. The postinstall lays down files, leaves the broker-config.yml placeholders intact, and does not start the service; you edit the config and start the service yourself when you're ready. Also the right pattern for Dockerfile builds, image baking, or any workflow where the broker should be configured at runtime rather than at install time.

When the post-install script has the values it needs (either from env vars or from install.env), it substitutes the config file and starts the service for you. When it does not, it prints a hint message and exits successfully; the package install does not fail, you just have to finish setup manually.

Automated with environment variables

For Ansible, Puppet, Chef, Salt, cloud-init, or any pipeline that already exports environment variables, set the two BRITIVE_BROKER_* variables before invoking the package manager. The postinstall sees them, skips the prompt, substitutes the config, and starts the service.

```sh
sudo BRITIVE_BROKER_TENANT_SUBDOMAIN=acme.us-east \
     BRITIVE_BROKER_AUTH_TOKEN=<broker-pool-token> \
     dnf install -y ./britive-broker-<version>.x86_64.rpm
```

The same env vars work for apt-get install and pacman-U.

Ansible example

```yaml
- name: install britive broker
  ansible.builtin.apt:
    deb: /tmp/britive-broker_<version>_amd64.deb
  environment:
    BRITIVE_BROKER_TENANT_SUBDOMAIN: "{{ britive_tenant }}"
    BRITIVE_BROKER_AUTH_TOKEN: "{{ britive_pool_token }}"
```

ansible.builtin.dnf and community.general.pacman work the same way; both modules forward the environment: block to the package scriptlets.

Token generator scripts

If your environment retrieves the broker pool token at runtime (rotation, short-lived credentials, or vault checkout), set BRITIVE_BROKER_AUTH_TOKEN_GENERATOR to the absolute path of a script that prints the token on stdout, instead of BRITIVE_BROKER_AUTH_TOKEN:

```sh
sudo BRITIVE_BROKER_TENANT_SUBDOMAIN=acme.us-east \
     BRITIVE_BROKER_AUTH_TOKEN_GENERATOR=/opt/britive-broker/bootstrap/fetch-token.sh \
     dnf install -y ./britive-broker-<version>.x86_64.rpm
```

The postinstall writes authentication_token_generator: /opt/britive-broker/bootstrap/fetch-token.sh into broker-config.yml. The broker invokes the script on each bootstrap to obtain a fresh pool token. If both AUTHTOKEN and _AUTHTOKEN_GENERATOR are set, the token takes the precedence.

Automated install with /etc/britive-broker/install.env

Drop a key/value file /etc/britive-broker/install.env containing the same BRITIVE_BROKER_* variables, then run the install. The postinstall sources the file before doing anything else.

```sh
sudo mkdir -p /etc/britive-broker
sudo install -m 0600 -o root -g root /dev/stdin /etc/britive-broker/install.env <<'EOF'
BRITIVE_BROKER_TENANT_SUBDOMAIN=acme.us-east
BRITIVE_BROKER_AUTH_TOKEN=<broker-pool-token>
EOF

sudo apk add --allow-untrusted ./britive-broker_<version>_x86_64.apk

```

Recognized keys, all optional except where noted:

The file should be chmod 0600 since it contains the broker pool token—the post-install warns (but does not abort) if the mode is looser. You should remove the file after a successful install.

Ansible example for Alpine

```yaml
- name: stage broker install.env (Alpine)
  ansible.builtin.copy:
    dest: /etc/britive-broker/install.env
    owner: root
    group: root
    mode: '0600'
    content: |
      BRITIVE_BROKER_TENANT_SUBDOMAIN={{ britive_tenant }}
      BRITIVE_BROKER_AUTH_TOKEN={{ britive_pool_token }}
- name: install britive broker (Alpine)
  community.general.apk:
    name: /tmp/britive-broker_<version>_x86_64.apk
    state: present
    allow_untrusted: yes
- name: remove broker install.env
  ansible.builtin.file:
    path: /etc/britive-broker/install.env
    state: absent
```

Install first, configure later

To lay down the package now and configure the broker in a separate step, just run the install with no BRITIVE_BROKER_* environment variables and no /etc/britive-broker/install.env. The postinstall: installs all files (binary, unit file, config template, ownership and permissions),

• leaves broker-config.yml with the <tenant_subdomain> and  <authentication_token> placeholders intact,

• does NOT enable or start the service

• prints a hint to stderr describing how to finish the setup.

The package install itself and returns success. This is the natural state of a non-interactive package install on rpm / apk / pacman and works the same way on deb. It's the right pattern for Dockerfile builds, image baking, and any workflow that separates "install software" from "configure software."

• Red Hat / Rocky / Amazon Linux / Fedora

sudo dnf install -y ./britive-broker-<version>.x86_64.rpm

• Debian / Ubuntu

sudo DEBIAN_FRONTEND=noninteractive apt-get install -y ./britive-broker_<version>_amd64.deb

• Alpine

sudo apk add --allow-untrusted ./britive-broker_<version>_x86_64.apk

• Arch Linux

sudo pacman -U --noconfirm ./britive-broker-<version>-x86_64.pkg.tar.zst

When you're ready to configure and start the broker, edit /opt/britive-broker/config/broker-config.yml and replace the placeholders, then use the following command:

• systemd

sudo systemctl enable --now britive-broker.service

• OpenRC

sudo rc-update add britive-broker default

sudo rc-service britive-broker start

Upgrading Access Broker

1. Package upgrades are non-prompting on every packager. They:

   • replace the broker binary and the systemd/OpenRC unit,

   • reload the init system's view systemctl daemon-reload),

   • restart the service if and only if it was already running try-restart / rc-service restart),

   • Preserve your edits from /opt/britive-broker/config/broker-config.yml in place.

2. If you customised the service unit, your changes survive upgrades only if you placed them in an override at

   /etc/systemd/system/britive-broker.service.d/override.conf (systemd) or in a separate OpenRC conf file — never edit the shipped unit in place.