Operations
Once Bridge is running, the work shifts from setup to day-2 operations: keeping it healthy, applying upgrades, backing up your data, and managing licenses and secrets. This page covers the practical tasks an administrator performs over the life of a deployment.
The Admin console
Bridge includes a built-in Admin console for running a deployment without touching the command line. It is restricted to users with the admin role - regular users never see it.
You open it from the floating Admin button in the web interface. It appears as a tabbed window (modal) laid over the app. Beside it is a floating search button for Activity Search, which searches activity across every session and is likewise admin-only.
Overview tab
A live picture of your deployment:
- Deployment topology - the running mode and version, plus the active proxy and session workers.
- Live session tasks - the sessions currently in flight, including how long each has been running.
- Usage statistics - activity broken down by protocol, and how much storage recordings are using.
- Activity indexing - whether session activity is fully indexed for Activity Search, and the progress of the one-time catch-up over older recordings.
License tab
Manage licensing without restarting Bridge. From here you can install, activate, and remove licenses. This is the recommended way to apply a renewal or upgrade. (For how licensing behaves, see Configuration → Licensing.)
API Tokens tab
In v3.0.2, API Tokens replaces the Service Tokens tab and contains two sections:
- Service tokens contains read-only monitoring credentials for
GET /api/statsandGET /api/cluster. See Metrics and service tokens. - Checkout tokens contains credentials for automation, scripts, and brokers to manage their own checkouts. This
section requires
server.checkout_api_tokens.enabled. See Checkout tokens.
New and replacement tokens appear once in a dialog with Copy token and Done buttons. Save the token before closing the dialog. Bridge stores only its hash. Closing the dialog with Done, Escape, or the admin panel clears its displayed value.
View Configuration tab
A read-only view of the effective configuration - the settings Bridge is actually running with after all layers (defaults, file, environment variables) have been merged. Secrets are omitted from this view, so it is safe to look at and share for troubleshooting. Use it to confirm what Bridge is really using without hunting through files and environment variables.
It also reports activity indexing and SIEM export. Export is listed twice on purpose: what the configuration asks for, and what actually got wired. Sending is best-effort and never blocks a session, so an unreachable destination would otherwise look like it was working - if the first is on and the second is off, the destination could not be established. See Activity Search & SIEM Export.
Monitoring health
Bridge exposes two HTTP health endpoints:
| Endpoint | Meaning |
|---|---|
/livez | Liveness - the process is alive. If this fails, the instance is stuck and should be restarted. |
/readyz | Readiness - the instance is ready to accept new sessions. If this fails, traffic should be steered away until it recovers. |
In a clustered deployment you don’t wire these up. The orchestrator registers and deregisters workers with the load balancer for you based on their readiness - on AWS it manages the Network Load Balancer’s target health checks, and on Kubernetes the pod readiness probes and Service do the same. You don’t point anything at these endpoints; the cluster self-manages routing.
When would you use them directly? Only in a single-server deployment where you put your own reverse proxy or load balancer in front of Bridge - there, point its health check at /readyz and your uptime monitor at /livez.
For overall cluster status - which workers exist, their roles, and whether a leader is active - use the Admin console’s Overview tab, which surfaces the orchestrator’s view visually.
Health endpoints report whether an instance is up. For counts and usage over time, scrape GET /api/stats with a read-only service token. For worker health, the leader lease, and active-session counts across the cluster, scrape GET /api/cluster with the same token. Both serve the Prometheus text exposition format.
Startup recovery in v3.0.1
The single and orchestrator roles wait for PostgreSQL to accept a connection before running migrations. Logs report datastore not reachable yet, retrying while the database is unavailable and datastore reachable when startup can continue. Rejected credentials, a missing database, or an invalid connection configuration still stop startup.
If Bridge exhausts its supervised startup retries, the container exits so the configured Docker restart policy, Kubernetes controller, or ECS service can replace it. A running companion broker no longer keeps that failed container alive. A broker failure alone does not stop Bridge.
Network Egress
Bridge makes outbound calls to the Britive platform to retrieve and renew its license, complete OAuth sign-in, and deliver explicitly enabled telemetry. If your environment routes internet traffic through a forward proxy, point Bridge at it with the standard environment variables:
| Variable | Purpose |
|---|---|
HTTPS_PROXY / https_proxy | Proxy for outbound HTTPS (what Bridge uses to reach the platform). |
HTTP_PROXY / http_proxy | Proxy for outbound HTTP. |
NO_PROXY / no_proxy | Comma-separated hosts/domains to reach directly, bypassing the proxy. |
Set these on the Bridge container (and, in a cluster, wherever the orchestrator runs). They must be present at startup.
These apply to Bridge’s own calls to Britive - not to the connections it brokers. This includes the co-located broker, which reaches the platform through these same standard variables (no broker-specific proxy settings are needed). Sessions to your target systems (SSH, RDP, databases, and so on) and the HTTP proxy feature’s own upstream requests always connect directly, never through this forward proxy. That is intentional: brokered access to your internal targets should not be re-routed through an internet egress proxy.
Behind a TLS-inspecting proxy
If your forward proxy terminates and re-signs TLS (a “MITM” / inspection proxy), Bridge must trust the proxy’s signing CA or its calls to the platform will fail certificate validation. Bridge - and the co-located broker - use the operating system’s trust store and honor the standard OpenSSL variables:
| Variable | Purpose |
|---|---|
SSL_CERT_FILE | Path to a single PEM bundle of trusted CA certificates. |
SSL_CERT_DIR | Colon-separated directories of trusted CA certificates. |
SSL_CERT_FILE replaces the default trust bundle - it does not add to it. If you
point it at only your inspection CA, Bridge will trust that CA alone and reject
everything else. Give it a bundle that contains both the public root CAs and
your inspection CA, or instead add your CA to the container’s OS trust store (bake
/usr/local/share/ca-certificates/<your-ca>.crt into a derived image and run
update-ca-certificates at build time - the runtime user is non-root).
Backend TLS is handled separately: to trust a target’s own CA (for example a
private database certificate) use the target_ca_cert, not these
variables - see the Payload reference.
Upgrading
Moving from v2 to v3? Follow Upgrade to Bridge v3. This major release requires target-trust and deployment changes, and every cluster role must be upgraded within one maintenance window. The rolling procedure below applies only to compatible releases.
Upgrading from Bridge v1? A new image is not enough. v2 needs PostgreSQL, a new configuration file, and new profile scripts. Follow Upgrade to Bridge v2.
You upgrade Bridge by deploying a new container image. How the change rolls out depends on your deployment mode:
Clustered mode. Push the new image, and the orchestrator handles the rollout for you. It cycles the proxies onto the new image and replaces idle session workers with new ones running the new image. Because it waits for workers to become idle, active sessions are not interrupted - they finish on the old workers, which are retired afterward.
The orchestrator does the same for a configuration change. On AWS it compares the task definition each worker was created from, which changes whenever the task definition does, so a changed setting rolls out the same way a changed image does. On Kubernetes it compares the image only, so a configuration change reaches a warm worker when that worker next cycles.
Single-container mode. There is no orchestrator to manage the change, so you simply restart the container on the new image. Plan this for a maintenance window, since restarting ends any sessions in progress.
Always upgrade in a way that lets you roll back. Keep the previous image tag available so you can revert quickly if needed, and confirm a healthy database backup exists before a major upgrade (see below).
Backups
Two things hold your durable data, and each is backed up differently:
- PostgreSQL is the source of truth. Checkouts, sessions, audit records, and encrypted credentials all live in the database. Back up PostgreSQL regularly using your normal database backup process (for example scheduled dumps or snapshots). If you can restore the database, you can restore Bridge’s state.
- Recordings live on the recordings volume. Session recordings are files in the directory set by
server.recording.output_dir. Back up (or snapshot) that volume to retain your recording history. In a cluster this is the shared volume all workers write to.
A complete restore therefore needs both the database backup and the recordings volume.
Rotating secrets
Periodically rotating secrets - database passwords, the LDAP bind password, and so on - is good practice. Most can be rotated by updating the corresponding environment variable (or config value) and restarting Bridge.
Service tokens and checkout tokens are held in the datastore. Rotate them in Admin > API Tokens without restarting Bridge.
BRIDGE_ENCRYPTION_KEY_B64 is the exception - it cannot be rotated by itself. This key encrypts checkout credentials stored in the database. If you change it, Bridge can no longer decrypt data written under the old key. Rotating it safely requires re-encrypting all existing checkout data with the new key as part of the change; you cannot simply swap the value and restart. Treat this key as long-lived, store it securely, and do not change it without a planned migration.
Telemetry and exports in v3
Platform telemetry is disabled by default in v3.0.1 and later. Keep it disabled until your tenant supports ingestion. To enable it, set server.telemetry.disabled: false and restart the single or orchestrator role. Existing explicit false overrides remain enabled after an upgrade.
Enabled telemetry sends session start and end events and cluster status. Review links require an authorized Bridge login and server.telemetry.review_base_url set to your public HTTPS origin. Disabling stops collection and delivery and purges pending events when the publisher starts. Local audit and recordings remain active. Platform Telemetry lists the settings and reported data.
Local cluster version reporting remains active when platform telemetry is disabled. It reflects observed running instances and can show mixed versions during an upgrade. No manual target-version setting is needed. Check telemetry delivery status in the Admin console.
CSV downloads default to spreadsheet-safe output, with formula-like text prefixed by an apostrophe. Use Raw CSV only when your downstream tool needs original values. Optional video conversion requires a separate export worker with shared recording access and writable temporary storage.