# Bindplane Server (Self-Hosted)

## Options

Bindplane server configuration can be found at `/etc/bindplane/config.yaml`.

Bindplane will look for flags, environment variables, and a configuration file, with precedence: flags > environment variables > configuration file.

Server and client configurations can be bootstrapped using the `init` command. See the [initialization section](#initialization).

For detailed examples, see the [configurations section](#example-configurations).

### License

The Bindplane license key. This option is required for server startup. If you do not have a license, you can request one [here](https://bindplane.com/download).

<table><thead><tr><th width="156.9296875">Option</th><th>Environment Variable</th></tr></thead><tbody><tr><td>license</td><td>BINDPLANE_LICENSE</td></tr></tbody></table>

### Host

IP Address the Bindplane server binds to. This can be a single address or `0.0.0.0` for all interfaces.

| Option       | Flag   | Environment Variable | Default     |
| ------------ | ------ | -------------------- | ----------- |
| network.host | --host | BINDPLANE\_HOST      | `127.0.0.1` |

### Port

TCP port the Bindplane server binds to. This must be an unprivileged port when running Bindplane as a non-root user.

| Option       | Flag   | Environment Variable | Default |
| ------------ | ------ | -------------------- | ------- |
| network.port | --port | BINDPLANE\_PORT      | `3001`  |

### Remote URL

URL used to reach the Bindplane server. This must be set in all client and server configurations\
and must be a valid URL with a protocol (HTTP / HTTPS), hostname or IP address, and port.

If the server is behind a proxy or load balancer, the proxy URL can be used.

<table><thead><tr><th width="173.24609375">Option</th><th width="116.00390625">Flag</th><th width="235.5546875">Environment Variable</th><th>Default</th></tr></thead><tbody><tr><td>network.remoteURL</td><td>--remote-url</td><td>BINDPLANE_REMOTE_URL</td><td><code>http://127.0.0.1:3001</code></td></tr></tbody></table>

### Web URL

Optional URL used to override the [Remote URL](#remote-url) for interactions with the web interface. When set, some features will use the Web URL instead of the Remote URL. For example, invitation links will use Web URL.

When Web URL is not set, Remote URL is used.

<table><thead><tr><th width="175.6796875">Option</th><th width="102.67578125">Flag</th><th>Environment Variable</th><th>Default</th></tr></thead><tbody><tr><td>network.webURL</td><td>--web-url</td><td>BINDPLANE_WEB_URL</td><td><code>http://127.0.0.1:3001</code></td></tr></tbody></table>

#### **Kubernetes Example**

Bindplane is deployed to a Kubernetes cluster. Bindplane is configured with the following:

* Remote URL: `http://bindplane.default.svc.cluster.local:3001`
* Web URL: `https://bindplane.my-corp.net`

In this case, agents will connect to Bindplane using the remote URL. This allows agents to connect\
directly to Bindplane without traversing over ingress.

Invitation links for web users will use the external endpoint, `https://bindplane.my-corp.net`.

### CorsAllowedOrigins

A list of origin domains allowed to make requests to Bindplane. It should at least contain the domain of the hosted UI. An empty or null value matches all origins. A wildcard "\*" is also allowed to match all origins.

In most cases, this value can be the same as `network.remoteURL`.

<table><thead><tr><th width="232.43359375">Option</th><th width="82.421875">Flag</th><th>Environment Variable</th><th width="100">Default</th></tr></thead><tbody><tr><td>network.corsAllowedOrigins</td><td>--cors-allowed-origins</td><td>BINDPLANE_CORS_ALLOWED_ORIGINS</td><td><code>*</code></td></tr></tbody></table>

### Logging

Log output (`file` or `stdout`). When log output is set to `file`, a log file path can be specified.

<table><thead><tr><th width="150.765625">Option</th><th width="100">Flag</th><th>Environment Variable</th><th width="145.0859375">Default</th></tr></thead><tbody><tr><td>logging.output</td><td>--logging-output</td><td>BINDPLANE_LOGGING_OUTPUT</td><td><code>file</code></td></tr><tr><td>logging.filePath</td><td>--logging-file-path</td><td>BINDPLANE_LOGGING_FILE_PATH</td><td><code>~/.bindplane/bindplane.log</code></td></tr></tbody></table>

Server installations will use `/var/log/bindplane/bindplane.log`, which is set using an environment variable in the `systemd` service configuration.

Log files are rotated and gzip compressed, and cleaned up automatically by Bindplane. Log files have a max size of 100mb and up to 10 rotates or 30 days of age, whichever comes first. Using an external utility such as `logrotate` is not recommended.

### Metrics

Bindplane can be configured to forward metrics to an OpenTelemetry collector. The easiest way to get up and running is to deploy a collector on the same machine Bindplane is installed on. The collector should be configuted with the OpenTelemetry source. Configure Bindplane to send metrics over localhost.

```yaml
metrics:
  interval: 1m
  type: otlp
  otlp:
    endpoint: 127.0.0.1:4317
    insecure: true
```

Once configured, the managed collector can forward the metrics to the destination of your choice.

Metrics are sent to OpenTelemetry collectors using the `gRPC` protocol.

<table><thead><tr><th width="186.7265625">Option</th><th width="118.96875">Flag</th><th>Environment Variable</th><th width="102.140625">Default</th></tr></thead><tbody><tr><td>metrics.type</td><td>--metrics-type</td><td>BINDPLANE_METRICS_TYPE</td><td></td></tr><tr><td>metrics.interval</td><td>--metrics-interval</td><td>BINDPLANE_METRICS_INTERVAL</td><td><code>1m0s</code></td></tr><tr><td>metrics.otlp.endpoint</td><td>--metrics-otlp-endpoint</td><td>BINDPLANE_METRICS_OTLP_ENDPOINT</td><td></td></tr><tr><td>metrics.otlp.insecure</td><td>--metrics-otlp-insecure</td><td>BINDPLANE_METRICS_OTLP_INSECURE</td><td></td></tr></tbody></table>

### Tracing

Bindplane supports configuration to enable tracing. `tracing.type` can be set to `google` or `otlp`.

<table><thead><tr><th width="123.29296875">Option</th><th width="137.2109375">Flag</th><th>Environment Variable</th><th width="134.4921875">Default</th></tr></thead><tbody><tr><td>tracing.type</td><td>--tracing-type</td><td>BINDPLANE_TRACING_TYPE</td><td></td></tr></tbody></table>

When `tracing.type` is set to `otlp`, some more configuration is possible.

<table><thead><tr><th width="180.6015625">Option</th><th width="126.23046875">Flag</th><th>Environment Variable</th><th width="99.39453125">Default</th></tr></thead><tbody><tr><td>tracing.otlp.endpoint</td><td>--tracing-otlp-endpoint</td><td>BINDPLANE_TRACING_OTLP_ENDPOINT</td><td></td></tr><tr><td>tracing.otlp.insecure</td><td>--tracing-otlp-insecure</td><td>BINDPLANE_TRACING_OTLP_INSECURE</td><td><code>FALSE</code></td></tr></tbody></table>

## TLS

Bindplane supports server side TLS and mutual TLS. See [the tls examples](#tls) for detailed usage.

<table><thead><tr><th width="220.12109375">Option</th><th width="178.42578125">Flag</th><th>Environment Variable</th></tr></thead><tbody><tr><td>network.tlsCert</td><td>--tls-cert</td><td>BINDPLANE_TLS_CERT</td></tr><tr><td>network.tlsKey</td><td>--tls-key</td><td>BINDPLANE_TLS_KEY</td></tr><tr><td>network.tlsCA</td><td>--tls-ca</td><td>BINDPLANE_TLS_CA</td></tr><tr><td>network.tlsSkipVerify</td><td>--tls-skip-verify</td><td>BINDPLANE_TLS_SKIP_VERIFY</td></tr><tr><td>network.tlsMinVersion</td><td>--tls-min-version</td><td>BINDPLANE_TLS_MIN_VERSION</td></tr></tbody></table>

### Server

* `network.tlsCert`: Enables server-side TLS
* `network.tlsKey`: Enables server-side TLS
* `network.tlsCA`: Enables mutual TLS

### Client

* `network.tlsCA`: Allows the client to trust the server certificate. Not required if the host operating system already trusts the server certificate.
* `network.tlsCert`: Enables mutual TLS
* `network.tlsKey`: Enables mutual TLS
* `network.tlsSkipVerify`: Skip server certificate verification

## Storage Backend

Bindplane supports two storage backends,`postgres` and `bbolt`. Bbolt is deprecated and should\
not be used for new installations of Bindplane.

<table><thead><tr><th width="128.34375">Option</th><th width="163.8203125">Flag</th><th>Environment Variable</th><th width="100">Default</th></tr></thead><tbody><tr><td>store.type</td><td>--store-type</td><td>BINDPLANE_STORE_TYPE</td><td><code>postgres</code></td></tr></tbody></table>

### Postgres

Postgres can be used as a local or remote storage backend. Postgres storage is enabled\
when `store.type` is set to `postgres`. Configuring both authentication and TLS for Postgres is recommended.

**Postgres is a Bindplane Enterprise feature.**

<table><thead><tr><th width="226.9140625">Option</th><th width="100">Flag</th><th>Environment Variable</th><th width="109.75">Default</th></tr></thead><tbody><tr><td>store.postgres.host</td><td>--postgres-host</td><td>BINDPLANE_POSTGRES_HOST</td><td><code>localhost</code></td></tr><tr><td>store.postgres.port</td><td>--postgres-port</td><td>BINDPLANE_POSTGRES_PORT</td><td><code>5432</code></td></tr><tr><td>store.postgres.database</td><td>--postgres-database</td><td>BINDPLANE_POSTGRES_DATABASE</td><td><code>bindplane</code></td></tr><tr><td>store.postgres.sslmode</td><td>--postgres-ssl-mode</td><td>BINDPLANE_POSTGRES_SSL_MODE</td><td><code>disable</code></td></tr><tr><td>store.postgres.sslrootcert</td><td>--postgres-ssl-root-cert</td><td>BINDPLANE_POSTGRES_SSL_ROOT_CERT</td><td>Optional</td></tr><tr><td>store.postgres.sslcert</td><td>--postgres-ssl-cert</td><td>BINDPLANE_POSTGRES_SSL_CERT</td><td>Optional</td></tr><tr><td>store.postgres.sslkey</td><td>--postgres-ssl-key</td><td>BINDPLANE_POSTGRES_SSL_KEY</td><td>Optional</td></tr><tr><td>store.postgres.username</td><td>--postgres-username</td><td>BINDPLANE_POSTGRES_USERNAME</td><td></td></tr><tr><td>store.postgres.password</td><td>--postgres-password</td><td>BINDPLANE_POSTGRES_PASSWORD</td><td></td></tr><tr><td>postgres.maxConnections</td><td>--postgres-max-connections</td><td>BINDPLANE_POSTGRES_MAX_CONNECTIONS</td><td><code>100</code></td></tr><tr><td>postgres.maxIdleConnections</td><td>--postgres-max-idle-connections</td><td>BINDPLANE_POSTGRES_MAX_IDLE_CONNECTIONS</td><td><code>50</code></td></tr><tr><td>postgres.maxIdleTime</td><td>--postgres-max-idle-time</td><td>BINDPLANE_POSTGRES_MAX_IDLE_TIME</td><td><code>1m0s</code></td></tr><tr><td>postgres.maxLifetime</td><td>--postgres-max-lifetime</td><td>BINDPLANE_POSTGRES_MAX_LIFETIME</td><td><code>6h</code></td></tr><tr><td>postgres.schema</td><td>--postgres-schema</td><td>BINDPLANE_POSTGRES_SCHEMA</td><td><code>default</code></td></tr></tbody></table>

Example Postgres configuration:

```yaml
name: default
apiVersion: bindplane.observiq.com/v1
auth:
  username: user
  password: password
network:
  host: 0.0.0.0
  port: '3001'
  remoteURL: http://10.99.1.10:3001
store:
  type: postgres
  postgres:
    host: localhost
    port: '5432'
    database: bindplane
    sslmode: disable
    username: postgres
    password: password
    maxConnections: 200
```

#### **Connection Management**

Bindplane has several Postgres connection options. The most important option is max connections. You should ensure the value does not exceed the number of available connections your PostgreSQL server can accept. When operating Bindplane in [high availability](/production-checklist/bindplane/high-availability.md) it is important to consider the total number of connections that can be created across all Bindplane instances.

#### **Transport Layer Security (TLS)**

Bindplane supports connecting to Postgres using TLS. TLS can be enabled by configuring the SSL mode options.

<table><thead><tr><th width="142.83984375">SSL Mode</th><th>Description</th></tr></thead><tbody><tr><td>disable</td><td>No SSL; connection is made in plain text.</td></tr><tr><td>require</td><td>SSL is used, but the server's certificate is not verified.</td></tr><tr><td>verify-ca</td><td>SSL is used, and the server's certificate is verified against a trusted CA.</td></tr><tr><td>verify-full</td><td>SSL is used, and the server's certificate is fully verified, including hostname validation.</td></tr></tbody></table>

You can learn more about Postgres SSL modes [here](https://www.postgresql.org/docs/current/libpq-ssl.html).

When using `verify-ca` or `verify-full`, your server's operating system's trust store will be used\
to verify the Postgres certificate. Alternatively, you can configure the `store.postgres.sslrootcert`\
option.

```yaml
store:
  type: postgres
  postgres:
    host: localhost
    port: '5432'
    database: bindplane
    username: postgres
    password: password
    maxConnections: 200
    sslmode: verify-ca
    sslrootcert: /etc/bindplane/ca.crt
```

{% hint style="info" %}
**NOTE**

When configuring certificate file paths, ensure the `bindplane` user has filesystem permissions\
to read the files.
{% endhint %}

If your Postgres server is enforcing client certificate authentication (mutual TLS), you can configure\
the `sslcert` and `sslkey` options.

```yaml
store:
  type: postgres
  postgres:
    sslmode: verify-full
    sslrootcert: /etc/bindplane/ca.crt
    sslcert: /etc/bindplane/client.crt
    sslkey: /etc/bindplane/client.key
```

If you rotate your client certificates frequently, you can set the `maxLifetime` options to limit\
how long connections can live. The default value is six hours (`6h`). This means, every six hours\
connections will be replaced. When a connection is created, it reads the SSL files from disk. Make sure\
to rotate your SSL certificates before the previous certificate has expired.

## Event Bus

Bindplane uses an event bus to communicate between components within Bindplane. When operating Bindplane with multiple servers, the event bus can be used to send events between Bindplane servers.

<table><thead><tr><th width="174.8984375">Option</th><th width="188.09375">Flag</th><th>Environment Variable</th></tr></thead><tbody><tr><td>eventBus.type</td><td>--event-bus-type</td><td>BINDPLANE_EVENT_BUS_TYPE</td></tr></tbody></table>

The event bus type supports the following options:

* [local](#local-event-bus)
* [nats](#nats-event-bus)
* [googlePubSub](#google-pub-sub-event-bus)

### Local Event Bus

The local event bus is the default event bus used by Bindplane. The local event bus does not have\
a configuration. It can be used by setting the event bus type to `local`.

### Google Pub/Sub Event Bus

The [Google Pub/Sub](https://cloud.google.com/pubsub) event bus can be used when operating multiple Bindplane servers.

<table><thead><tr><th width="207.39453125">Option</th><th width="135.74609375">Flag</th><th>Environment Variable</th></tr></thead><tbody><tr><td>eventBus.googlePubSub.projectID</td><td>--event-bus-type</td><td>BINDPLANE_GOOGLE_PUB_SUB_PROJECT_ID</td></tr><tr><td>eventBus.googlePubSub.credentialsFile</td><td>--google-pub-sub-credentials-file</td><td>BINDPLANE_GOOGLE_PUB_SUB_CREDENTIALS_FILE</td></tr><tr><td>eventBus.googlePubSub.topic</td><td>--google-pub-sub-topic</td><td>BINDPLANE_GOOGLE_PUB_SUB_TOPIC</td></tr></tbody></table>

When operating Bindplane on Google Compute Engine with the [pub/sub" oath scopes](https://developers.google.com/identity/protocols/oauth2/scopes#pubsub) enabled, Bindplane will handle authentication automatically.

The configuration is simple and requires only the `projectID` and `topic` options.

```yaml
eventBus:
  type: googlePubSub
  googlePubSub:
    projectID: myproject
    topic: bindplane
```

When running outside of Google Cloud, or without the Pub/Sub oauth scopes, you can use a [Google Service Account Credential](https://cloud.google.com/iam/docs/keys-create-delete) by setting the `credentialsFile` option. This credentials file must be installed on the Bindplane server's filesystem and be readable by the `bindplane` user.

```yaml
eventBus:
  type: googlePubSub
  googlePubSub:
    projectID: myproject
    credentialsFile: /etc/bindplane/google-credentials.json
    topic: bindplane
```

Bindplane will manage its own Pub/Sub subscription. Subscriptions are created and named based on\
the server's hostname. Bindplane will attempt to clean up its subscription on shutdown. Subscriptions\
are automatically cleaned up by Google Cloud if they have been disconnected for more than one day.

### NATS Event Bus

[NATS](https://github.com/nats-io/nats-server) can be used as the event bus for Bindplane Enterprise and is a good option for distributed on-prem deployments. NATS is embedded into Bindplane and does not require external infrastructure.

See the [NATS Configuration](/configuration/bindplane/nats-as-event-bus.md) documentation for more information.

## Server Session Secret

A UUIDv4 is used for encoding web UI login cookies. This should be a new random UUIDv4. This value should be different than `auth.secretKey`.

<table><thead><tr><th width="179.5234375">Option</th><th width="164.81640625">Flag</th><th>Environment Variable</th></tr></thead><tbody><tr><td>auth.sessionSecret</td><td>--session-secret</td><td>BINDPLANE_SESSION_SECRET</td></tr></tbody></table>

## Prometheus

{% hint style="info" %}
**NOTE**

It is not necessary to make changes to the Bindplane Prometheus configuration when using Bindplane's bundled Prometheus.
{% endhint %}

### Base Configuration

<table><thead><tr><th width="262.03515625">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>prometheus.enable</code></td><td>Whether or not to enable Prometheus as the measurement backend.</td></tr><tr><td><code>prometheus.enableRemote</code></td><td>Whether or not to use a remote Prometheus instance. When disabled, Bindplane will manage a local Prometheus child process.</td></tr><tr><td><code>prometheus.localFolder</code></td><td>The directory where the Prometheus binary and dependencies are located.</td></tr><tr><td><code>prometheus.host</code></td><td>The hostname or ip address of the Prometheus instance.</td></tr><tr><td><code>prometheus.port</code></td><td>The port of the Prometheus instance's API.</td></tr><tr><td><code>prometheus.queryPathPrefix</code></td><td>The path prefix of the query endpoint. This parameter is useful if using a Prometheus compatible system such as Mimir.</td></tr></tbody></table>

### Authentication

{% hint style="info" %}
**NOTE**

Authentication is supported for remote Prometheus deployments.
{% endhint %}

Bindplane supports two authentication modes.

* No authentication
* Basic authentication

Prometheus does not use authentication by default. Follow the Prometheus [Basic Auth Password Hashing](https://prometheus.io/docs/guides/basic-auth/#hashing-a-password) documentation for more information.

<table><thead><tr><th width="254.6796875">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>prometheus.auth.type</code></td><td>The authentication type to use. Supported options are <code>none</code> and <code>basic</code> (Basic Authentication).</td></tr><tr><td><code>prometheus.auth.username</code></td><td>The username to use when basic authentication is enabled.</td></tr><tr><td><code>prometheus.auth.password</code></td><td>The password to use when basic authentication is enabled.</td></tr></tbody></table>

### TLS

Bindplane supports connecting to Prometheus with TLS and Mutual TLS.

<table><thead><tr><th width="281.4296875">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>prometheus.enableTLS</code></td><td>Whether or not to use TLS when communicating with Prometheus.</td></tr><tr><td><code>prometheus.tls.tlsSkipVerify</code></td><td>Whether or not to skip verification of the Prometheus server's TLS certificate. It is not recommended to enable this option.</td></tr><tr><td><code>prometheus.tls.tlsCa</code></td><td>The x509 PEM encoded certificate authority file to use to verify the Prometheus server's TLS certificate. Alternatively, the CA certificate can be imported into the host's trust store, instead of configuring this option.</td></tr><tr><td><code>prometheus.tls.tlsCert</code></td><td>The x509 PEM encoded client certificate file to use for mutual TLS.</td></tr><tr><td><code>prometheus.tls.tlsKey</code></td><td>The x509 PEM encoded client private key file to use for mutual TLS.</td></tr></tbody></table>

TLS example configuration.

```yaml
prometheus:
  tls:
    tlsSkipVerify: false
    tlsCA: [/etc/bindplane/tls/ca.crt]
```

Mutual TLS example configuration.

```yaml
prometheus:
  tls:
    tlsSkipVerify: false
    tlsCA: [/etc/bindplane/tls/ca.crt]
    tlsCert: /etc/bindplane/tls/bindplane.crt
    tlsKey: /etc/bindplane/tls/bindplane.key
```

### Remote Write

When using Prometheus compatible systems, such as [Mimir](https://grafana.com/oss/mimir/), you may need to define the remote write host and port, if it differs from the main host and port. Bindplane will use the remote write host and port for pushing metrics to Prometheus, and the main host and port for querying Prometheus.

If using vanilla Prometheus, these options are not required.

<table><thead><tr><th width="300.48828125">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>prometheus.remoteWrite.host</code></td><td>The hostname or ip address of the Prometheus instance for remote write. If not set, the value of <code>prometheus.host</code> will be used.</td></tr><tr><td><code>prometheus.remoteWrite.port</code></td><td>The port of the Prometheus instance for remote write. If not set, the value of <code>prometheus.port</code> will be used.</td></tr><tr><td><code>prometheus.remoteWrite.endpoint</code></td><td>The API path to use for remote write.</td></tr></tbody></table>

## Authentication

{% hint style="info" %}
Single Sign-On (SSO) Authentication is only available on Bindplane Cloud. [Read more here](broken://pages/I0GiHA3xd9AwaqTmWDoS)
{% endhint %}

Bindplane supports several authentication options.

* System (Basic Auth)
* External Auth (Enterprise & Google Editions only)
  * [Active Directory](/configuration/bindplane/authentication/active-directory-authentication.md)
  * LDAP
  * [OIDC](/configuration/bindplane/authentication/openid-connect-authentication.md)

The configuration's `auth` section contains the following authentication options.

<table><thead><tr><th width="212.83984375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>auth.type</code></td><td>Authentication type to use (<code>system</code> / <code>active-directory</code> / <code>ldap</code> / <code>oidc</code>).</td></tr></tbody></table>

### System

<table><thead><tr><th width="230.53125">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>auth.username</code></td><td>Basic authentication username.</td></tr><tr><td><code>auth.password</code></td><td>Basic authentication password.</td></tr></tbody></table>

### LDAP / Active Directory Configuration (Enterprise)

The configuration's `auth.ldap` section contains the following options for configuration LDAP and Active Directory.

<table><thead><tr><th width="215.0390625">Option</th><th>Description</th></tr></thead><tbody><tr><td>auth.ldap.server</td><td>Hostname or IP address of the LDAP or Active Directory server.</td></tr><tr><td>auth.ldap.port</td><td>The TCP port to use when connecting to the authentication server.</td></tr><tr><td>auth.ldap.searchFilter</td><td>LDAP Query for searching users based on mapping of username to a particular LDAP attribute as well as any applicable additional filters, (ex: groups in Active Directory).</td></tr><tr><td>auth.ldap.baseDN</td><td>The starting point an LDAP server uses when searching for users.</td></tr><tr><td>auth.ldap.bindUser</td><td>The username used to connect to the authentication server. For active directory, this is a username. For LDAP, this is the full DN to the user.</td></tr><tr><td>auth.ldap.bindPassword</td><td>The password used to connect to the authentication server.</td></tr><tr><td>auth.ldap.tls.tlsCA</td><td>Path to the TLS certificate authority.</td></tr><tr><td>auth.ldap.tls.tlsSkipVerify</td><td>Whether or not to skip TLS verification.</td></tr><tr><td>auth.ldap.tls.tlsCert</td><td>Path to TLS certificate when mutual TLS is required.</td></tr><tr><td>auth.ldap.tls.tlsKey</td><td>Path to TLS private key when mutual TLS is required.</td></tr></tbody></table>

See the [Active Directory documentation](/configuration/bindplane/authentication/active-directory-authentication.md) for detailed setup instructions.

### OIDC Configuration (Enterprise)

The configuration's `auth.oidc` section contains the following options for configuring an OpenID Connect provider.

<table><thead><tr><th width="271.734375">Option</th><th>Description</th></tr></thead><tbody><tr><td>auth.oidc.issuer</td><td>URL of your OIDC provider.</td></tr><tr><td>auth.oidc.oauth2ClientID</td><td>OAuth2 client ID provided by the OIDC provider.</td></tr><tr><td>auth.oidc.oauth2ClientSecret</td><td>OAuth2 client secret provided by the OIDC provider.</td></tr><tr><td>auth.oidc.scopes</td><td>List of scopes requested during authentication.</td></tr></tbody></table>

Environment variables can be used instead of the configuration file:

```
BINDPLANE_OIDC_ISSUER
BINDPLANE_OIDC_OAUTH2_CLIENT_ID
BINDPLANE_OIDC_OAUTH2_CLIENT_SECRET
BINDPLANE_OIDC_SCOPES
```

See the [OpenID Connect documentation](/configuration/bindplane/authentication/openid-connect-authentication.md) for detailed setup instructions.

#### **Active Directory Example**

Active Directory authentication is enabled by setting `auth.type` to `active-directory`.

In this example, the domain controller's hostname is `dc.corp.net`. The username `bindplane` is used to bind to Active Directory. The `searchFilter` is inserted by default when running `bindplane init server --config <path to bindplane config.yaml>`.

User login is restricted to the DN `CN=Users,DC=corp,DC=net`.

```yaml
auth:
  type: active-directory
  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
  username: admin
  password: admin
  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
  ldap:
    server: dc.corp.net
    port: '389'
    baseDN: CN=Users,DC=corp,DC=net
    bindUser: bindplane@corp.net
    bindPassword: complexpassword
    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))
```

#### **Basic Example**

In this example, the domain controller's hostname is `ldap.corp.net`. The username `bindplane` is used to bind to LDAP. The `searchFilter` is inserted by default when running `bindplane init server --config <path to bindplane config.yaml>`.

User login is restricted to the DN `CN=Users,DC=corp,DC=net`.

```yaml
auth:
  type: ldap
  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
  username: admin
  password: admin
  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
  ldap:
    server: ldap.corp.net
    port: '389'
    baseDN: CN=Users,DC=corp,DC=net
    bindUser: bindplane
    bindPassword: complexpassword
    searchFilter: (uid=%s)
```

#### **TLS**

This example is the same as the "basic" example, with TLS. The protocol has been set to `ldaps`, port to `636`, and a ca certificate is optionally\* configured.

```yaml
auth:
  type: ldap
  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
  username: admin
  password: admin
  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
  ldap:
    server: ldap.corp.net
    port: '636'
    baseDN: CN=Users,DC=corp,DC=net
    bindUser: bindplane
    bindPassword: complexpassword
    searchFilter: (uid=%s)
    tls:
      tlsCa:
        - /etc/bindplane/tls/ca.crt
```

\*CA certificate is not required if the ca is already trusted by the underlying operating system. Alternatively, `auth.ldap.tls.tlsSkipVerify: true` could be set to skip TLS verification.

#### **Mutual TLS**

This example is the same as the "TLS" example, with client TLS authentication. The `auth.ldap.tls.tlsCert` and `auth.ldap.tls.tlsKey` fields have been set.

```yaml
auth:
  type: ldap
  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
  username: admin
  password: admin
  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
  ldap:
    server: ldap.corp.net
    port: '636'
    baseDN: CN=Users,DC=corp,DC=net
    bindUser: bindplane
    bindPassword: complexpassword
    searchFilter: (uid=%s)
    tls:
      tlsCert: /etc/bindplane/tls/bindplane.crt
      tlsKey: /etc/bindplane/tls/bindplane.key
      tlsCa:
        - /etc/bindplane/tls/ca.crt
```

### Agent Versions

Bindplane can be configured to manage agent versions and upgrades. The `agentVersions` section controls how Bindplane synchronizes and manages agent version information.

<table><thead><tr><th width="200">Option</th><th width="150">Flag</th><th width="250">Environment Variable</th><th width="100">Default</th></tr></thead><tbody><tr><td>agentVersions.syncInterval</td><td>--agent-versions-sync-interval</td><td>BINDPLANE_AGENT_VERSIONS_SYNC_INTERVAL</td><td><code>1h</code></td></tr><tr><td>agentVersions.agentUpgradesFolder</td><td>--agent-versions-agent-upgrades-folder</td><td>BINDPLANE_AGENT_VERSIONS_AGENT_UPGRADES_FOLDER</td><td><code>/var/lib/bindplane/agent-upgrades</code></td></tr><tr><td>agentVersions.clients</td><td>--agent-versions-clients</td><td>BINDPLANE_AGENT_VERSIONS_CLIENTS</td><td><code>["bdot"]</code></td></tr></tbody></table>

#### Sync Interval

The interval at which Bindplane synchronizes agent version information from configured clients.

#### Agent Upgrades Folder

The path to the folder where Bindplane stores agent upgrade files. This folder is used to cache agent binaries and metadata for distribution to agents.

**Note:** This option is only used when offline agent upgrades are configured. In standard deployments, agents download updates directly from the configured clients.

#### Clients

List of version clients to use for synchronizing agent versions. Valid options are:

* `bdot` - Bindplane's official agent synchronization endpoint, `bdot.bindplane.com` (recommended)
* `github` - GitHub releases

Multiple clients can be configured by providing a comma-separated list. As of Bindplane v1.95.0, `bdot` is the default and only configured option. This is recommended for most deployments.

**Version History**

* **Bindplane v1.95.0+**: `bdot` is the default and only configured option. Bindplane syncs agent versions from `https://bdot.bindplane.com`.
* **Bindplane v1.94.0**: Introduced the Clients option and defaulted to `github`. Bindplane synced agent versions from `https://github.com/observiq/bindplane-otel-collector`.
* **Previous versions**: Used GitHub exclusively.

**Recommendations**

* **Default deployments**: Use `bdot` only. This simplifies firewall requirements by not requiring access to `github.com`.
* **Custom agent installs**: Use both `bdot` and `github` configured together to support custom agent installations while maintaining access to official releases.

The `bdot.bindplane.com` endpoint was introduced to make user firewall requirements simpler for default Bindplane installations.

**Example Configuration**

```yaml
agentVersions:
  syncInterval: 1h
  agentUpgradesFolder: /var/lib/bindplane/agent-upgrades
  clients:
    - bdot
    - github
```

## Initialization

The `init` command is useful for bootstrapping a server or client.

### Server

After installing Bindplane server, simply run the following command and follow the prompts.

```bash
sudo BINDPLANE_CONFIG_HOME=/var/lib/bindplane /usr/local/bin/bindplane init server \
  --config /etc/bindplane/config.yaml
```

Once finished, you will have the option to automatically restart the server. If the server is not\
automatically restarted, it must be restarted manually.

### Client

Client initialization will create a new profile if one is not already set. If an existing profile is in use, init will update that profile. You can learn more about profiles in the [client profiles](#client-profiles) section.

```bash
bindplane init client
```

Once finished, the client configuration will exist in `~/.bindplane/profiles`. You can also run the `profile` command:

```bash
bindplane profile --help
```

#### Client Profiles

The `profile` command offers a convenient way to create and use multiple client configurations.

In this example, it is assumed that the Bindplane server is running at `10.99.1.10` on port `3001`.

```bash
bindplane profile set remote --remote-url https://10.99.1.10:3001
bindplane profile use remote
```

See `bindplane profile help` for more profile sub-commands.

## Example Configurations

The following examples assume the use of [Bindplane collectors](https://github.com/observIQ/bindplane-otel-collector).

### Basic

This configuration assumes that the Bindplane server is running on IP address `192.168.1.10`.

#### Server Configuration

```yaml
auth:
  secretKey: e124852a-49db-4318-99a8-76bd4aa80ba5
  username: myuser
  password: mypassword
  sessionSecret: 99112c19-9d87-4460-958c-a9affa874e21
```

#### Client Profile

Create a profile named `basic`:

```bash
bindplane profile set basic \
  --username myuser \
  --password mypassword \
  --remote-url http://192.168.1.10:3001

bindplane profile use basic
```

A profile will be created at `~/.bindplane/profiles/basic.yaml`:

```yaml
name: basic
apiVersion: bindplane.observiq.com/v1
auth:
  username: myuser
  password: mypassword
network:
  remoteURL: http://192.168.1.10:3001
```

#### Collector Manager Configuration

```yaml
endpoint: http://192.168.1.10:3001/v1/opamp
secret_key: e124852a-49db-4318-99a8-76bd4aa80ba5
agent_id: ad3caa0c-ac90-4f8d-8691-2f43d9addc71
```

### TLS

Bindplane has support for server side TLS and mutual TLS.

What is a server? A server is the process running from the `bindplane serve` command.

What is a client?

* bindplane cli
* OpAMP collectors
* Web browsers

Keep in mind that all certificate files must be readable by the user running the bindplane, client,\
and collector processes.

#### Server Side TLS

**Server Configuration**

Server-side TLS is configured by setting `network.tlsCert` and `network.tlsKey` on the server.

```yaml
network:
  host: 0.0.0.0
  port: '3001'
  remoteURL: https://bindplane-op.mydomain.net:3001
  tlsCert: /etc/bindplane/tls/bindplane.crt
  tlsKey: /etc/bindplane/tls/bindplane.key
```

Note that remoteURL have a tls protocol set (`https`).

**Client Profile**

All clients must trust the certificate authority that signed the server's certificate. This can be accomplished by setting `tlsCa` on the client or by importing the certificate authority into your operating system's trust store.

Create a profile named `tls`:

```bash
bindplane profile set tls \
  --username myuser \
  --password mypassword \
  --remote-url http://192.168.1.10:3001 \
  --tls-ca /etc/bindplane/tls/my-corp-ca.crt

bindplane profile use tls
```

A profile will be created at `~/.bindplane/profiles/tls.yaml`:

```yaml
name: tls
apiVersion: bindplane.observiq.com/v1
auth:
  username: myuser
  password: mypassword
network:
  remoteURL: https://bindplane-op.mydomain.net:3001
  tlsCa:
    - /etc/bindplane/tls/my-corp-ca.crt
```

If the server's certificate authority is already imported into the client's operating system trust store, it is not required to be set in the configuration.

Browsers will show a TLS warning unless the certificate authority is trusted by your operating system.

**Collector Manager Configuration**

```yaml
endpoint: https://bindplane-op.mydomain.net:3001/v1/opamp
secret_key: e124852a-49db-4318-99a8-76bd4aa80ba5
agent_id: ad3caa0c-ac90-4f8d-8691-2f43d9addc71
tls_config:
  ca_file: /opt/observiq-otel-collector/tls/bindplane-ca.crt
```

If the server's certificate authority is already imported into the client's operating system trust store, it is not required to be set in the configuration.

#### Mutual TLS

In this example, three certificate authorities are referenced:

* `my-corp-ca.crt`: Signed the server's certificate, must be trusted by all clients/collectors
* `client-ca.crt`: Signed all client certificates, must be set in the server configuration
* `collector-ca.crt`: Signed all collector certificates, must be set in the server configuration

**Server Configuration**

Mutual TLS is configured by setting `network.tlsCert`, `network.tlsKey`, and `network.tlsCA` on the server.

```yaml
network:
  host: 0.0.0.0
  port: '3001'
  remoteURL: https://bindplane-op.mydomain.net:3001
  tlsCert: /etc/bindplane/tls/bindplane.crt
  tlsKey: /etc/bindplane/tls/bindplane.key
  # Any client / collector certificate signed by one of these
  # authorities will be trusted.
  tlsCa:
    - /etc/bindplane/tls/client-ca.crt
    - /etc/bindplane/tls/collector-ca.crt
```

Note that `remoteURL` has a TLS protocol set (`https`).

Note that multiple certificate authorities can be specified. This example will trust incoming connections from certificates signed by `client-ca` and `collector-ca`.

**Client Profile**

All clients must trust the certificate authority that signed the server's certificate. This can be accomplished by setting `network.tlsCA` on the client or by importing the certificate authority into your operating system's trust store.

Create a profile named `mtls`:

```bash
bindplane profile set mtls \
  --username myuser \
  --password mypassword \
  --remote-url http://192.168.1.10:3001 \
  --tls-cert /etc/bindplane/tls/client.crt \
  --tls-key /etc/bindplane/tls/client.key \
  --tls-ca /etc/bindplane/tls/my-corp-ca.crt

bindplane profile use mtls
```

A profile will be created at `~/.bindplane/profiles/mtls.yaml`:

```yaml
name: mtls
apiVersion: bindplane.observiq.com/v1
auth:
  username: myuser
  password: mypassword
network:
  remoteURL: https://bindplane-op.mydomain.net:3001
  tlsCert: /etc/bindplane/tls/client.crt
  tlsKey: /etc/bindplane/tls/client.key
  tlsCa:
    - /etc/bindplane/tls/my-corp-ca.crt
```

If the server's certificate authority is already imported into the client's operating system trust store, it is not required to be set in the configuration.

Browsers will show a TLS warning unless the certificate authority is trusted by your operating system.

**Collector Manager Configuration**

```yaml
endpoint: https://bindplane-op.mydomain.net:3001/v1/opamp
secret_key: e124852a-49db-4318-99a8-76bd4aa80ba5
agent_id: ad3caa0c-ac90-4f8d-8691-2f43d9addc71
tls_config:
  cert_file: /opt/observiq-otel-collector/tls/collector.crt
  key_file: /opt/observiq-otel-collector/tls/collector.crt
  ca_file: /opt/observiq-otel-collector/tls/bindplane-ca.crt
```

If the server's certificate authority is already imported into the client's operating system trust store, it is not required to be set in the configuration.

### Advanced Configuration

Bindplane has several advanced configuration options. It is unnecessary to modify advanced options unless explicitly called out in the [Prerequisites](/deployment/virtual-machine/bindplane/prerequisites.md) documentation or you are guided by Bindplane support.

#### Agent

**Telemetry Port**

Collectors managed by Bindplane expose metrics on TCP port `8888` by default. The port is now configurable globally. Modifying the port will affect all collectors connected to Bindplane.

The telemetry port can be configured under `advanced.agent.telemetryPort`.

```yaml
advanced:
  agent:
    telemetryPort: 8888
```

#### Store

**Stats**

The Prometheus measurements backend can be tuned with the options found under `advanced.store.stats`.

**Batch Flush Interval**

The batch flush interval is the duration used to batch collector management requests before flushing to the measurements backend. A higher interval will mean larger batches are published. At scale, a shorter interval can be used to reduce the payload size sent to Prometheus.

```yaml
advanced:
  store:
    stats:
      batchFlushInterval: 1s
```

**Worker Count**

The worker count is the number of workers used to publish measurement batches to Prometheus. Increasing the worker count can improve performance at high collector counts.

```yaml
advanced:
  store:
    stats:
      workerCount: 1
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/configuration/bindplane.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.