Configuration

Britive Bridge reads all of its settings from a single configuration file written in YAML - a plain-text format that uses indentation to group related settings. You point Bridge at this file once, and it controls everything: which protocols are enabled, how users log in, where session recordings are stored, and how Bridge connects to its database.

This page covers the essentials: where the config file lives, how settings are layered, and the core server.* options every deployment needs. Detailed topics - authentication, recording, licensing, and the full environment-variable reference - each have their own page, linked at the bottom.

Where the configuration file lives

A fully commented reference file is available to download: bridge.reference.yaml. It lists every available option with its default value and an explanation. It is the best starting point for building your own config - download it, then trim it down to the settings you actually need.

By default, Bridge looks for its configuration at:

/etc/britive-bridge/config.yaml

If you want to keep the file somewhere else, set the BRIDGE_CONFIG environment variable to the full path of your file. (An environment variable is a named value that the operating system hands to a program when it starts - a common way to pass settings to software running in a container without editing files inside it.)

terminal

# Tell Bridge to read a config file from a custom location
export BRIDGE_CONFIG=/opt/bridge/my-config.yaml

How settings are layered (precedence)

Bridge builds its final configuration in three layers. Each layer can override the one before it:

Built-in defaults - sensible values baked into Bridge. If you set nothing, these apply.
The YAML config file - anything you set here overrides the built-in defaults.
Environment variables - these override both the defaults and the YAML file. They are the highest priority and are ideal for secrets (passwords, keys) and per-deployment values that you would rather not commit to a file.

In short: defaults < YAML file < environment variables. If the same setting appears in more than one layer, the higher-priority layer wins.

Core server settings

These live under the server section and apply to almost every deployment.

Option	Type	Default	Description
`server.listen`	string	`"443"`	The address Bridge listens on for the web UI, browser sessions, and the admin console. A bare port (for example `"443"`) binds every network interface on the machine. You can also use `HOST:PORT` to bind a specific address. Required.
`server.log_level`	string	`"info"`	How much detail Bridge writes to its logs. One of `trace`, `debug`, `info`, `warn`, or `error`. Use `debug` when troubleshooting; `info` is right for normal operation.
`server.landing_enabled`	bool	`false`	When `true`, a public landing page is shown at `/`. When `false` (the default), visiting `/` sends users straight to their sessions page.
`server.picker_enabled`	bool	`false`	When `true`, an authenticated “picker” UI is available at `/picker` for choosing a checkout to connect to.
`server.trusted_proxies`	list of strings	`[]` (empty)	A list of upstream proxy addresses, in CIDR notation, that Bridge should trust. See below.

About `trusted_proxies` and client IP addresses

When a user connects through a load balancer or reverse proxy (a server that sits in front of Bridge and forwards traffic to it), Bridge sees the proxy’s IP address as the source of every request, not the user’s real IP. Proxies solve this by adding headers such as X-Forwarded-For that record the user’s true address - but those headers can be forged, so Bridge only honors them from sources you explicitly trust.

server.trusted_proxies is that trust list. Each entry is a CIDR - a compact way to write a range of IP addresses, like 10.0.0.0/8 (all addresses starting with 10.) or a single address such as 192.0.2.5/32. If the list is empty, Bridge trusts only the address of the machine directly connected to it and ignores forwarded-IP headers.

bridge.yaml

server:
  trusted_proxies:
    - "10.0.0.0/8"      # internal load-balancer subnet
    - "192.0.2.5/32"    # a specific proxy host

TLS (HTTPS) settings

TLS is the technology that puts the padlock in your browser - it encrypts traffic between the user and Bridge. “TLS termination” means decrypting that traffic; whoever terminates TLS holds the certificate and serves HTTPS.

Option	Type	Default	Description
`server.tls.enabled`	bool	`true`	Serve HTTPS directly on `server.listen`. Set to `false` only when something in front of Bridge already terminates TLS (see below). Can also be set with the `BRIDGE_TLS_ENABLED` environment variable.
`server.tls.cert_path`	string	`/data/certs/api-cert.pem`	Path to the TLS certificate file. If the file is missing, Bridge generates one automatically.
`server.tls.key_path`	string	`/data/certs/api-key.pem`	Path to the matching private key. Auto-generated if missing.

When should I turn TLS off? Only when Bridge runs behind a load balancer that already handles HTTPS for you - the load balancer decrypts traffic and forwards plain HTTP to Bridge on a private network. In that setup, set server.tls.enabled: false so Bridge serves plain HTTP and lets the load balancer own the certificate. In every other case, leave TLS enabled.

Datastore (PostgreSQL) settings

Bridge stores its state in a PostgreSQL database. PostgreSQL is mandatory in every deployment mode - Bridge will not run without it. It is the source of truth for checkouts, sessions, and audit data.

Option	Type	Default	Environment variable	Description
`server.datastore.host`	string	`localhost`	`BRIDGE_DATASTORE_HOST`	Hostname or IP of the PostgreSQL server.
`server.datastore.port`	int	`5432`	`BRIDGE_DATASTORE_PORT`	Database port.
`server.datastore.user`	string	`bridge`	`BRIDGE_DATASTORE_USER`	Database username.
`server.datastore.password`	string	`""`	`BRIDGE_DATASTORE_PASSWORD`	Database password. Prefer the environment variable so the secret stays out of the config file.
`server.datastore.name`	string	`bridge`	`BRIDGE_DATASTORE_NAME`	Name of the database to use.
`server.datastore.sslmode`	string	`disable`	`BRIDGE_DATASTORE_SSLMODE`	How Bridge secures the database connection. One of `disable`, `require`, `verify-ca`, or `verify-full`. Use `require` or stronger for any database reached over a network.

When using PostgreSQL you must also provide an encryption key via the BRIDGE_ENCRYPTION_KEY_B64 environment variable. This key encrypts checkout credentials before they are written to the database. It has no YAML equivalent - see the Environment Variables page.

Recording settings

Session recording is always on. The two key settings live under server.recording:

Option	Type	Default	Description
`server.recording.output_dir`	string	`/data/recordings`	Directory where recordings are written. Required. In a clustered deployment this must be a shared volume reachable by every worker.
`server.recording.redact_response_bodies`	bool	`true`	Mask secrets in recorded response/output bodies.

Recording has its own dedicated page; see Recording & Redaction for the full explanation.

Startup validation

When Bridge starts, it checks your configuration and refuses to launch if something essential is missing. The most important rules:

At least one protocol must be enabled. Every protocol is off by default, so a config with none enabled does nothing useful and is rejected.
server.listen is required.
server.recording.output_dir is required.
A protocol’s native listen port is required whenever that protocol’s native mode is enabled (browser-only protocols are exempt).
RDP native mode requires a certificate and key (tls_cert and tls_key).
If Britive login is enabled, a tenant must be set.
If LDAP login is enabled, the LDAP server, bind DN, and base DN must all be set.
cluster.role must be one of single, session, proxy, or orchestrator.