Skip to main content

BRB Agent Deployment

Owner: Anchor MSP Operations Lead Last reviewed: 2026-05-24

Purpose​

Define the procedure for deploying, registering, and configuring BRB agents on systems under Anchor managed production.

Scope​

All managed hosts designated for BRB Protocol protection during the client onboarding process.

Prerequisites​

Before deploying a BRB agent, the following must be in place:

  1. Host access — SSH access to the target host with sudo privileges.
  2. Redis connectivity — The host must be able to reach the BRB controller's Redis instance on the designated port. Verify with: redis-cli -h CONTROLLER_HOST -p CONTROLLER_PORT ping.
  3. R2 connectivity — The host must be able to upload to the brb-forensics R2 bucket. Verify with a test upload using the configured credentials.
  4. System registration — The system must be registered in the BRB controller with a system_id and client_id. The Operations Lead provisions this during onboarding.
  5. Emergency SSH user — An emergency SSH user must be configured on the host. This user is the only account that remains accessible during lockdown.
  6. Firewall rules — Port 9090 (agent health endpoint) must be accessible from the monitoring server.

Installation​

The auto-installer handles dependency installation, agent binary deployment, systemd service creation, and initial configuration.

curl -sSL https://brb.anchor.internal/install.sh | sudo bash -s -- \
  --system-id "SYSTEM_ID" \
  --client-id "CLIENT_ID" \
  --controller-url "https://brb-controller.anchor.internal" \
  --redis-host "REDIS_HOST" \
  --redis-port "REDIS_PORT"

The installer performs the following steps:

  1. Verifies system requirements (OS, architecture, dependencies).
  2. Downloads the latest BRB agent binary.
  3. Creates the /etc/brb/ configuration directory.
  4. Writes the agent configuration file (/etc/brb/agent.yaml).
  5. Creates the brb-agent systemd service.
  6. Starts the agent and verifies health.

Manual Installation​

For environments where the auto-installer cannot be used (restricted outbound access, air-gapped networks):

  1. Download the agent binary from the internal artifact repository and place it at /usr/local/bin/brb-agent.
  2. Create the configuration directory: sudo mkdir -p /etc/brb/
  3. Create the configuration file at /etc/brb/agent.yaml:
system_id: "SYSTEM_ID"
client_id: "CLIENT_ID"
controller_url: "https://brb-controller.anchor.internal"
redis:
  host: "REDIS_HOST"
  port: REDIS_PORT
  channel: "brb:commands:SYSTEM_ID"
health:
  port: 9090
forensics:
  r2_endpoint: "https://23b4ba8d8f996dfbc2eb473cb3b32582.r2.cloudflarestorage.com"
  r2_bucket: "brb-forensics"
  collection_paths:
    - /var/log/
    - /etc/
    - /tmp/brb-forensics/
emergency:
  ssh_user: "emergency"
  ssh_port: 22
  1. Create the systemd service at /etc/systemd/system/brb-agent.service:
[Unit]
Description=BRB Protocol Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/brb-agent --config /etc/brb/agent.yaml
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target
  1. Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable brb-agent
sudo systemctl start brb-agent

Registration Verification​

After installation, verify the agent is registered and communicating with the controller:

  1. Health check:
curl -s http://localhost:9090/health | jq

Expected response includes "status": "healthy", the correct system_id, and uptime > 0.

  1. Controller registration: Verify the system appears in the BRB controller dashboard (Glance) under the correct client with a "healthy" status.

  2. Redis subscription: Confirm the agent is subscribed to its command channel by checking agent logs:

journalctl -u brb-agent --since "5 minutes ago" | grep "subscribed"

Monitoring Setup​

Once the agent is deployed, configure monitoring:

  1. Add a Prometheus scrape target for the agent health endpoint (host:9090/metrics).
  2. Add an Uptime Kuma monitor for the agent health endpoint (http://host:9090/health).
  3. Create an Alertmanager rule that fires if the BRB agent health check fails for more than 2 minutes. Severity: Critical. A BRB agent being down means the system cannot be locked down in an emergency.
  4. Verify Slack notifications by checking that the agent's registration event appeared in #anchor-incidents-critical.

Agent Updates​

  1. Agent updates are deployed via the auto-installer with the --upgrade flag: curl -sSL https://brb.anchor.internal/install.sh | sudo bash -s -- --upgrade
  2. The upgrade process stops the agent, replaces the binary, and restarts the service.
  3. Agent updates follow the Production Change Policy. They are tested on a staging system before production deployment.
  4. After upgrade, re-run the health check and verify controller connectivity.

Exceptions​

None. Every system designated for BRB protection must have a functioning, monitored BRB agent. An unhealthy or unreachable agent is a Critical severity issue.