Configuration

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.

For detailed examples, see the configurations section.

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.

Option	Flag	Environment Variable	Default
network.remoteURL	--remote-url	BINDPLANE_REMOTE_URL	`http://127.0.0.1:3001`

CorsAllowedOrigins

A list of origin domains allowed to make requests to BindPlane OP. 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.

Option	Flag	Environment Variable	Default
network.corsAllowedOrigins	--cors-allowed-origins	BINDPLANE_CORS_ALLOWED_ORIGINS	`*`

Logging

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

Option	Flag	Environment Variable	Default
logging.output	--logging-output	BINDPLANE_LOGGING_OUTPUT	`file`
logging.filePath	--logging-file-path	BINDPLANE_LOGGING_FILE_PATH	`~/.bindplane/bindplane.log`

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.

Tracing

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

Option	Flag	Environment Variable	Default
tracing.type	--tracing-type	BINDPLANE_TRACING_TYPE

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

Option	Flag	Environment Variable	Default
tracing.otlp.endpoint	--tracing-otlp-endpoint	BINDPLANE_TRACING_OTLP_ENDPOINT
tracing.otlp.insecure	--tracing-otlp-insecure	BINDPLANE_TRACING_OTLP_INSECURE	`FALSE`

TLS

BindPlane supports server side TLS and mutual TLS. See the tls examples
for detailed usage.

Option	Flag	Environment Variable
network.tlsCert	--tls-cert	BINDPLANE_TLS_CERT
network.tlsKey	--tls-key	BINDPLANE_TLS_KEY
network.tlsCA	--tls-ca	BINDPLANE_TLS_CA
network.tlsSkipVerify	--tls-skip-verify	BINDPLANE_TLS_SKIP_VERIFY

Server

networki.tlsCert: Enables server side TLS
network.tlsKey: Enables server side TLS
network.tlsCA: Enables mutual TLS

Client

network.tlsCA: Allows 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, bbolt and postgres.

Option	Flag	Environment Variable	Default
store.type	--store-type	BINDPLANE_STORE_TYPE	`bbolt`

BBolt

Option	Flag	Environment Variable	Default
store.bbolt.path	--store-bbolt-path	BINDPLANE_STORE_BBOLT_PATH	`~/.bindplane/storage`

Postgres

Postgres can be used as a local or remote storage backend. Postgres storage is enabled
when store.type is set to postgres.

Postgres is a BindPlane OP Enterprise feature.

Option	Flag	Environment Variable	Default
store.postgres.host	--postgres-host	BINDPLANE_POSTGRES_HOST	`localhost`
store.postgres.port	--postgres-port	BINDPLANE_POSTGRES_PORT	`5432`
store.postgres.database	--postgres-database	BINDPLANE_POSTGRES_DATABASE	`bindplane`
store.postgres.sslmode	--postgres-ssl-mode	BINDPLANE_POSTGRES_SSL_MODE	`disable`
store.postgres.username	--postgres-username	BINDPLANE_POSTGRES_USERNAME
store.postgres.password	--postgres-password	BINDPLANE_POSTGRES_PASSWORD
postgres.maxConnections	--postgres-max-connections	BINDPLANE_POSTGRES_MAX_CONNECTIONS	`100`

Example Postgres configuration:

yaml

1name: default
2apiVersion: bindplane.observiq.com/v1
3auth:
4  username: user
5  password: password
6network:
7  host: 0.0.0.0
8  port: '3001'
9  remoteURL: http://10.99.1.10:3001
10store:
11  type: postgres
12  postgres:
13    host: localhost
14    port: '5432'
15    database: bindplane
16    sslmode: disable
17    username: postgres
18    password: password
19    maxConnections: 200

Server Secret Key

A UUIDv4 used for collector authentication. This should be a new random UUIDv4. This
value should be different than auth.sessionSecret.

Option	Flag	Environment Variable
auth.secretKey	--secret-key	BINDPLANE_SECRET_KEY

Server Session Secret

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

Option	Flag	Environment Variable
auth.sessionSecret	--session-secret	BINDPLANE_SESSION_SECRET

Authentication

BindPlane supports several authentication options.

System (Basic Auth)
Active Directory (Enterprise only)
LDAP (Enterprise only)

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

Option	Description
`auth.type`	Authentication type to use (`ldap` / `active-directory` / `system` ).

System

Option	Description
`auth.username`	Basic authentication username.
`auth.password`	Basic authentication password.

LDAP / Active Directory Configuration (Enterprise)

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

Option	Description
auth.ldap.server	Hostname or IP address of the LDAP or Active Directory server.
auth.ldap.port	The TCP port to use when connecting to the authentication server.
auth.ldap.searchFilter	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).
auth.ldap.baseDN	The starting point an LDAP server uses when searching for users.
auth.ldap.bindUser	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.
auth.ldap.bindPassword	The password used to connect to the authentication server.
auth.ldap.tls.tlsCA	Path to the TLS certificate authority.
auth.ldap.tls.tlsSkipVerify	Whether or not to skip TLS verification.
auth.ldap.tls.tlsCert	Path to TLS certificate when mutual TLS is required.
auth.ldap.tls.tlsKey	Path to TLS private key when mutual TLS is required.

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

1name: default
2apiVersion: bindplane.observiq.com/v1
3auth:
4  type: active-directory
5  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
6  username: admin
7  password: admin
8  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
9  ldap:
10    server: dc.corp.net
11    port: '389'
12    baseDN: CN=Users,DC=corp,DC=net
13    bindUser: bindplane
14    bindPassword: complexpassword
15    searchFilter: (|(sAMAccountName=%[1]v)(userPrincipalName=%[1]v))
16network:
17  host: 0.0.0.0
18  port: '3001'
19  remoteURL: http://bindplane.corp.net:3001
20store:
21  bbolt:
22    path: /var/lib/bindplane/storage/bindplane.db
23logging:
24  filePath: /var/log/bindplane/bindplane.log

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

1name: default
2apiVersion: bindplane.observiq.com/v1
3auth:
4  type: ldap
5  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
6  username: admin
7  password: admin
8  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
9  ldap:
10    server: ldap.corp.net
11    port: '389'
12    baseDN: CN=Users,DC=corp,DC=net
13    bindUser: bindplane
14    bindPassword: complexpassword
15    searchFilter: (uid=%s)
16network:
17  host: 0.0.0.0
18  port: '3001'
19  remoteURL: http://bindplane.corp.net:3001
20store:
21  bbolt:
22    path: /var/lib/bindplane/storage/bindplane.db
23logging:
24  filePath: /var/log/bindplane/bindplane.log
25```text
26
27#### TLS
28
29This 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.
30
31```yaml
32name: default
33apiVersion: bindplane.observiq.com/v1
34auth:
35  type: ldap
36  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
37  username: admin
38  password: admin
39  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
40  ldap:
41    server: ldap.corp.net
42    port: '636'
43    baseDN: CN=Users,DC=corp,DC=net
44    bindUser: bindplane
45    bindPassword: complexpassword
46    searchFilter: (uid=%s)
47    tls:
48      tlsCa:
49        - /etc/bindplane/tls/ca.crt
50network:
51  host: 0.0.0.0
52  port: '3001'
53  remoteURL: http://bindplane.corp.net:3001
54store:
55  bbolt:
56    path: /var/lib/bindplane/storage/bindplane.db
57logging:
58  filePath: /var/log/bindplane/bindplane.log
59```text
60
61\*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.
62
63#### Mutual TLS
64
65This 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.
66
67```yaml
68name: default
69apiVersion: bindplane.observiq.com/v1
70auth:
71  type: ldap
72  secretKey: e8bfcfe0-bbe6-4ee6-bf35-72ff182d2dc5
73  username: admin
74  password: admin
75  sessionSecret: b84746f6-aca1-4b91-9ccd-d4da8d75fe4d
76  ldap:
77    server: ldap.corp.net
78    port: '636'
79    baseDN: CN=Users,DC=corp,DC=net
80    bindUser: bindplane
81    bindPassword: complexpassword
82    searchFilter: (uid=%s)
83    tls:
84      tlsCert: /etc/bindplane/tls/bindplane.crt
85      tlsKey: /etc/bindplane/tls/bindplane.key
86      tlsCa:
87        - /etc/bindplane/tls/ca.crt
88network:
89  host: 0.0.0.0
90  port: '3001'
91  remoteURL: http://bindplane.corp.net:3001
92store:
93  bbolt:
94    path: /var/lib/bindplane/storage/bindplane.db
95eventBus:
96  type: local
97logging:
98  filePath: /var/log/bindplane/bindplane.log

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

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

One finished, the server must be restarted.

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 section.

bash

1bindplane init client
2```t
3
4Once finished, the client configuration will exist in `~/.bindplane/profiles`. You
5can also run the `profile` command:
6
7```bash
8bindplane 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

1bindplane profile set remote --remote-url https://10.99.1.10:3001
2bindplane profile use remote

See bindplane profile help for more profile sub commands.

Example Configurations

The following examples assume the use of observIQ collectors.

Basic

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

Server Configuration

yaml

1name: basic
2apiVersion: bindplane.observiq.com/v1
3auth:
4  secretKey: e124852a-49db-4318-99a8-76bd4aa80ba5
5  username: myuser
6  password: mypassword
7  sessionSecret: 99112c19-9d87-4460-958c-a9affa874e21
8network:
9  host: 192.168.1.10
10  port: '3001'
11  remoteURL: http://192.168.1.10:3001
12store:
13  bbolt:
14    path: /var/lib/bindplane/storage/bindplane.db
15logging:
16  filePath: /var/log/bindplane/bindplane.log

Client Profile

Create a profile named basic:

bash

1bindplane profile set basic \
2  --username myuser \
3  --password mypassword \
4  --remote-url http://192.168.1.10:3001
5
6bindplane profile use basic

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

yaml

1name: basic
2apiVersion: bindplane.observiq.com/v1
3auth:
4  username: myuser
5  password: mypassword
6network:
7  remoteURL: http://192.168.1.10:3001

Collector Manager Configuration

yaml

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

TLS

BindPlane OP 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

1name: default
2apiVersion: bindplane.observiq.com/v1
3auth:
4  secretKey: e124852a-49db-4318-99a8-76bd4aa80ba5
5  username: myuser
6  password: mypassword
7  sessionSecret: 99112c19-9d87-4460-958c-a9affa874e21
8network:
9  host: 0.0.0.0
10  port: '3001'
11  remoteURL: https://bindplane-op.mydomain.net:3001
12  tlsCert: /etc/bindplane/tls/bindplane.crt
13  tlsKey: /etc/bindplane/tls/bindplane.key
14store:
15  type: bbolt
16  bbolt:
17    path: /var/lib/bindplane/storage/bindplane.db
18logging:
19  filePath: /var/log/bindplane/bindplane.log

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

1bindplane profile set tls \
2  --username myuser \
3  --password mypassword \
4  --remote-url http://192.168.1.10:3001 \
5  --tls-ca /etc/bindplane/tls/my-corp-ca.crt
6
7bindplane profile use tls

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

yaml

1name: tls
2apiVersion: bindplane.observiq.com/v1
3auth:
4  username: myuser
5  password: mypassword
6network:
7  remoteURL: https://bindplane-op.mydomain.net:3001
8  tlsCa:
9    - /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

1endpoint: https://bindplane-op.mydomain.net:3001/v1/opamp
2secret_key: e124852a-49db-4318-99a8-76bd4aa80ba5
3agent_id: ad3caa0c-ac90-4f8d-8691-2f43d9addc71
4tls_config:
5  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

1name: tls
2apiVersion: bindplane.observiq.com/v1
3auth:
4  secretKey: e124852a-49db-4318-99a8-76bd4aa80ba5
5  username: myuser
6  password: mypassword
7  sessionSecret: 99112c19-9d87-4460-958c-a9affa874e21
8network:
9  host: 0.0.0.0
10  port: '3001'
11  remoteURL: https://bindplane-op.mydomain.net:3001
12  tlsCert: /etc/bindplane/tls/bindplane.crt
13  tlsKey: /etc/bindplane/tls/bindplane.key
14  # Any client / collector certificate signed by one of these
15  # authorities will be trusted.
16  tlsCa:
17    - /etc/bindplane/tls/client-ca.crt
18    - /etc/bindplane/tls/collector-ca.crt
19store:
20  type: bbolt
21  bbolt:
22    path: /var/lib/bindplane/storage/bindplane.db
23logging:
24  filePath: /var/log/bindplane/bindplane.log

Note that remoteURL have 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

1bindplane profile set mtls \
2  --username myuser \
3  --password mypassword \
4  --remote-url http://192.168.1.10:3001 \
5  --tls-cert /etc/bindplane/tls/client.crt \
6  --tls-key /etc/bindplane/tls/client.key \
7  --tls-ca /etc/bindplane/tls/my-corp-ca.crt
8
9bindplane profile use mtls

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

yaml

1name: mtls
2apiVersion: bindplane.observiq.com/v1
3auth:
4  username: myuser
5  password: mypassword
6network:
7  remoteURL: https://bindplane-op.mydomain.net:3001
8  tlsCert: /etc/bindplane/tls/client.crt
9  tlsKey: /etc/bindplane/tls/client.key
10  tlsCa:
11    - /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

1endpoint: https://bindplane-op.mydomain.net:3001/v1/opamp
2secret_key: e124852a-49db-4318-99a8-76bd4aa80ba5
3agent_id: ad3caa0c-ac90-4f8d-8691-2f43d9addc71
4tls_config:
5  cert_file: /opt/observiq-otel-collector/tls/collector.crt
6  key_file: /opt/observiq-otel-collector/tls/collector.crt
7  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.

Configure BindPlane OP

Options

Host

Port

Remote URL

CorsAllowedOrigins

Logging

Tracing

TLS

Server

Client

Storage Backend

BBolt

Postgres

Server Secret Key

Server Session Secret

Authentication

System

LDAP / Active Directory Configuration (Enterprise)

Active Directory Example

Basic Example

Initialization

Server

Client

Client Profiles

Example Configurations

Basic

Server Configuration

Client Profile

Collector Manager Configuration

TLS

Server Side TLS

Server Configuration

Client Profile

Collector Manager Configuration

Mutual TLS

Server Configuration

Client Profile

Collector Manager Configuration