---
title: "Linux"
slug: "linux-broker-v301"
updated: 2026-07-20T08:15:34Z
published: 2026-07-20T08:15:34Z
canonical: "docs.britive.com/linux-broker-v301"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.britive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/broker-3-0-1#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](/v1/docs/linux-gobased-broker#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](/v1/docs/linux-gobased-broker#automated-install-with-etcbritivebrokerinstallenv): 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](/v1/docs/linux-gobased-broker#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.

```plaintext
```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

```plaintext
```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**:

```plaintext
```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* _***AUTH*TOKEN_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.

```plaintext
```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:

| Key | Required | Description |
| --- | --- | --- |
| BRITIVE_BROKER_TENANT_SUBDOMAIN | Yes | The tenant subdomain (e.g. [acme.us](http://acme.us)-east) |
| BRITIVE_BROKER_AUTH_TOKEN | one of these two | Broker pool authentication token |
| BRITIVE_BROKER_AUTH_TOKEN_GENERATOR | One of these two | Absolute path to a script that prints the broker pool token on stdout. If both are set, *AUTH*TOKEN wins |

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

```plaintext
```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

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

- Debian / Ubuntu

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

- Alpine

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

- Arch Linux

```plaintext
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

```plaintext
sudo systemctl enable --now britive-broker.service
```

- OpenRC

```plaintext
sudo rc-update add britive-broker default
```

```plaintext
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.