Configuration

Configure BindPlane OP

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.

OptionFlagEnvironment VariableDefault
network.host--hostBINDPLANE_HOST127.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.

OptionFlagEnvironment VariableDefault
network.port--portBINDPLANE_PORT3001

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.

OptionFlagEnvironment VariableDefault
network.remoteURL--remote-urlBINDPLANE_REMOTE_URLhttp://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.

OptionFlagEnvironment VariableDefault
network.corsAllowedOrigins--cors-allowed-originsBINDPLANE_CORS_ALLOWED_ORIGINS*

Logging

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

OptionFlagEnvironment VariableDefault
logging.output--logging-outputBINDPLANE_LOGGING_OUTPUTfile
logging.filePath--logging-file-pathBINDPLANE_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.

Metrics

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

yaml
1metrics:
2  interval: 1m
3  type: otlp
4  otlp:
5    endpoint: 127.0.0.1:4317
6    insecure: true

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

Metrics are sent to OpenTelemetry collectors using the gRPC protocol.

OptionFlagEnvironment VariableDefault
metrics.type--metrics-typeBINDPLANE_METRICS_TYPE
metrics.interval--metrics-intervalBINDPLANE_METRICS_INTERVAL1m0s
metrics.otlp.endpoint--metrics-otlp-endpointBINDPLANE_METRICS_OTLP_ENDPOINT
metrics.otlp.insecure--metrics-otlp-insecureBINDPLANE_METRICS_OTLP_INSECURE

Tracing

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

OptionFlagEnvironment VariableDefault
tracing.type--tracing-typeBINDPLANE_TRACING_TYPE

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

OptionFlagEnvironment VariableDefault
tracing.otlp.endpoint--tracing-otlp-endpointBINDPLANE_TRACING_OTLP_ENDPOINT
tracing.otlp.insecure--tracing-otlp-insecureBINDPLANE_TRACING_OTLP_INSECUREFALSE

TLS

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

OptionFlagEnvironment Variable
network.tlsCert--tls-certBINDPLANE_TLS_CERT
network.tlsKey--tls-keyBINDPLANE_TLS_KEY
network.tlsCA--tls-caBINDPLANE_TLS_CA
network.tlsSkipVerify--tls-skip-verifyBINDPLANE_TLS_SKIP_VERIFY

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, bbolt and postgres.

OptionFlagEnvironment VariableDefault
store.type--store-typeBINDPLANE_STORE_TYPEbbolt

BBolt

OptionFlagEnvironment VariableDefault
store.bbolt.path--store-bbolt-pathBINDPLANE_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.

OptionFlagEnvironment VariableDefault
store.postgres.host--postgres-hostBINDPLANE_POSTGRES_HOSTlocalhost
store.postgres.port--postgres-portBINDPLANE_POSTGRES_PORT5432
store.postgres.database--postgres-databaseBINDPLANE_POSTGRES_DATABASEbindplane
store.postgres.sslmode--postgres-ssl-modeBINDPLANE_POSTGRES_SSL_MODEdisable
store.postgres.username--postgres-usernameBINDPLANE_POSTGRES_USERNAME
store.postgres.password--postgres-passwordBINDPLANE_POSTGRES_PASSWORD
postgres.maxConnections--postgres-max-connectionsBINDPLANE_POSTGRES_MAX_CONNECTIONS100

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

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.

OptionFlagEnvironment Variable
eventBus.type--event-bus-typeBINDPLANE_EVENT_BUS_TYPE

The event bus type supports the following options:

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 event bus can be used when operating multiple BindPlane servers.

OptionFlagEnvironment Variable
eventBus.googlePubSub.projectID--event-bus-typeBINDPLANE_GOOGLE_PUB_SUB_PROJECT_ID
eventBus.googlePubSub.credentialsFile--google-pub-sub-credentials-fileBINDPLANE_GOOGLE_PUB_SUB_CREDENTIALS_FILE
eventBus.googlePubSub.topic--google-pub-sub-topicBINDPLANE_GOOGLE_PUB_SUB_TOPIC

When operating BindPlane on Google Compute Engine with the pub/sub" oath scopes enabled, BindPlane will handle authentication automatically.

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

yaml
1eventBus:
2  type: googlePubSub
3  googlePubSub:
4    projectID: myproject
5    topic: bindplane

When running outside of Google Cloud, or without the Pub/Sub oauth scopes, you can use a Google Service Account Credential 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
1eventBus:
2  type: googlePubSub
3  googlePubSub:
4    projectID: myproject
5    credentialsFile: /etc/bindplane/google-credentials.json
6    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.

Kafka Event Bus

Apache Kafka event bus can be used when operating multiple BindPlane servers.

note

The Kafka topic can only have 1 partition to ensure ordering. See Kafka Implementation documentation for details.

OptionFlagEnvironment Variable
eventBus.kafka.brokers--kafka-auth-typeBINDPLANE_KAFKA_BROKERS
eventBus.kafka.protocolVersion--kafka-protocol-versionBINDPLANE_KAFKA_PROTOCOL_VERSION
eventBus.kafka.topic--kafka-topicBINDPLANE_KAFKA_TOPIC
eventBus.kafka.authType--kafka-auth-typeBINDPLANE_KAFKA_AUTH_TYPE

The Kafka event bus base configuration looks like this:

yaml
1eventBus:
2  type: kafka
3  kafka:
4    brokers:
5      - kafka-0.corp.net:9092
6      - kafka-1.corp.net:9092
7      - kafka-2.corp.net:9092
8    protocolVersion: '3.5.0'
9    topic: bindplane
10    authType: none

Kafka Authentication

The Kafka event bus supports plain text and SASL authentication options.

| eventBus.kafka.plainText.username | --kafka-plain-text-username | BINDPLANE_KAFKA_PLAIN_TEXT_USERNAME | | eventBus.kafka.plainText.password | --kafka-plain-text-password | BINDPLANE_KAFKA_PLAIN_TEXT_PASSWORD | | eventBus.kafka.sasl.username | --kafka-sasl-username | BINDPLANE_KAFKA_SASL_USERNAME | | eventBus.kafka.sasl.password | --kafka-sasl-password | BINDPLANE_KAFKA_SASL_PASSWORD | | eventBus.kafka.sasl.mechanism | --kafka-sasl-mechanism | BINDPLANE_KAFKA_SASL_MECHANISM | | eventBus.kafka.sasl.version | --kafka-sasl-version | BINDPLANE_KAFKA_SASL_VERSION |

Plaintext configuration looks like this:

yaml
1eventBus:
2  type: kafka
3  kafka:
4    brokers:
5      - kafka-0.corp.net:9092
6      - kafka-1.corp.net:9092
7      - kafka-2.corp.net:9092
8    protocolVersion: '3.5.0'
9    topic: bindplane
10    authType: plainText
11    plainText:
12      username: kafka-user
13      password: kafka-password

SASL configuration looks like this:

yaml
1eventBus:
2  type: kafka
3  kafka:
4    brokers:
5      - kafka-0.corp.net:9092
6      - kafka-1.corp.net:9092
7      - kafka-2.corp.net:9092
8    protocolVersion: '3.5.0'
9    topic: bindplane
10    authType: sasl
11    sasl:
12      username: admin
13      password: password
14      mechanism: scramSHA512
15      version: 1

Kafka TLS

| eventBus.kafka.enableTLS | --kafka-enable-tls | BINDPLANE_KAFKA_ENABLE_TLS | | eventBus.kafka.tls.tlsCert | --kafka-tls-cert | BINDPLANE_KAFKA_TLS_CERT | | eventBus.kafka.tls.tlsKey | --kafka-tls-key | BINDPLANE_KAFKA_TLS_KEY | | eventBus.kafka.tls.tlsCa | --kafka-tls-ca | BINDPLANE_KAFKA_TLS_CA | | eventBus.kafka.tlsSkipVerify | --kafka-tls-skip-verify | BINDPLANE_KAFKA_TLS_SKIP_VERIFY |

TLS can be enabled by setting enableTLS to true and optionally configuring a certificate authority. The certificate authority should be configured if the BindPlane server host does not already contain the certificate authority in its trust store.

yaml
1eventBus:
2  type: kafka
3  kafka:
4    brokers:
5      - kafka-0.corp.net:9092
6      - kafka-1.corp.net:9092
7      - kafka-2.corp.net:9092
8    protocolVersion: '3.5.0'
9    topic: bindplane
10    authType: none
11    enableTLS: true
12    tls:
13      tlsCa:
14        - /etc/bindplane/kafka-ca.crt
15      tlsSkipVerify: false

Mutual TLS can be enabled by configuring a client key pair (tlsCert and tlsKey).

yaml
1eventBus:
2  type: kafka
3  kafka:
4    brokers:
5      - kafka-0.corp.net:9092
6      - kafka-1.corp.net:9092
7      - kafka-2.corp.net:9092
8    protocolVersion: '3.5.0'
9    topic: bindplane
10    authType: none
11    enableTLS: true
12    tls:
13      tlsCert: /etc/bindplane/kafka-client.crt
14      tlsKey: /etc/bindplane/kafka-client.key
15      tlsCa:
16        - /etc/bindplane/kafka-ca.crt
17      tlsSkipVerify: false

Server Secret Key

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

OptionFlagEnvironment Variable
auth.secretKey--secret-keyBINDPLANE_SECRET_KEY

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.

OptionFlagEnvironment Variable
auth.sessionSecret--session-secretBINDPLANE_SESSION_SECRET

Prometheus

note

It is not necessary to make changes to the BindPlane Prometheus configuration when using BindPlane's bundled Prometheus.

Base Configuration.

OptionDescription
prometheus.enableWhether or not to enable Prometheus as the measurement backend.
prometheus.enableRemoteWhether or not to use a remote Prometheus instance. When disabled, BindPlane will manage a local Prometheus child process.
prometheus.localFolderThe directory where the Prometheus binary and dependencies are located.
prometheus.hostThe hostname or ip address of the Prometheus instance.
prometheus.portThe port of the Prometheus instance's API.
prometheus.queryPathPrefixThe path prefix of the query endpoint. This parameter is useful if using a Prometheus compatible system such as Mimir.

Authentication.

note

Authentication is supported for remote Prometheus deployments.

BindPlane OP supports two authentication modes.

  • No authentication
  • Basic authentication

Prometheus does not use authentication by default. Follow the Prometheus Basic Auth Password Hashing documentation for more information.

OptionDescription
prometheus.auth.typeThe authentication type to use. Supported options are none and basic (Basic Authentication).
prometheus.auth.usernameThe username to use when basic authentication is enabled.
prometheus.auth.passwordThe password to use when basic authentication is enabled.

TLS

BindPlane supports connecting to Prometheus with TLS and Mutual TLS.

OptionDescription
prometheus.enableTLSWhether or not to use TLS when communicating with Prometheus.
prometheus.tls.tlsSkipVerifyWhether or not to skip verification of the Prometheus server's TLS certificate. It is not recommended to enable this option.
prometheus.tls.tlsCaThe 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.
prometheus.tls.tlsCertThe x509 PEM encoded client certificate file to use for mutual TLS.
prometheus.tls.tlsKeyThe x509 PEM encoded client private key file to use for mutual TLS.

TLS example configuration.

yaml
1prometheus:
2  tls:
3    tlsSkipVerify: false
4    tlsCA: [/etc/bindplane/tls/ca.crt]

Mutual TLS example configuration.

yaml
1prometheus:
2  tls:
3    tlsSkipVerify: false
4    tlsCA: [/etc/bindplane/tls/ca.crt]
5    tlsCert: /etc/bindplane/tls/bindplane.crt
6    tlsKey: /etc/bindplane/tls/bindplane.key

Remote Write

When using Prometheus compatible systems, such as 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.

OptionDescription
prometheus.remoteWrite.hostThe hostname or ip address of the Prometheus instance for remote write. If not set, the value of prometheus.host will be used.
prometheus.remoteWrite.portThe port of the Prometheus instance for remote write. If not set, the value of prometheus.port will be used.
prometheus.remoteWrite.endpointThe API path to use for remote write.

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.

OptionDescription
auth.typeAuthentication type to use (ldap / active-directory / system ).

System

OptionDescription
auth.usernameBasic authentication username.
auth.passwordBasic authentication password.

LDAP / Active Directory Configuration (Enterprise)

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

OptionDescription
auth.ldap.serverHostname or IP address of the LDAP or Active Directory server.
auth.ldap.portThe TCP port to use when connecting to the authentication server.
auth.ldap.searchFilterLDAP 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.baseDNThe starting point an LDAP server uses when searching for users.
auth.ldap.bindUserThe 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.bindPasswordThe password used to connect to the authentication server.
auth.ldap.tls.tlsCAPath to the TLS certificate authority.
auth.ldap.tls.tlsSkipVerifyWhether or not to skip TLS verification.
auth.ldap.tls.tlsCertPath to TLS certificate when mutual TLS is required.
auth.ldap.tls.tlsKeyPath 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

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
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: '636'
12    baseDN: CN=Users,DC=corp,DC=net
13    bindUser: bindplane
14    bindPassword: complexpassword
15    searchFilter: (uid=%s)
16    tls:
17      tlsCa:
18        - /etc/bindplane/tls/ca.crt
19network:
20  host: 0.0.0.0
21  port: '3001'
22  remoteURL: http://bindplane.corp.net:3001
23store:
24  bbolt:
25    path: /var/lib/bindplane/storage/bindplane.db
26logging:
27  filePath: /var/log/bindplane/bindplane.log

*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
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: '636'
12    baseDN: CN=Users,DC=corp,DC=net
13    bindUser: bindplane
14    bindPassword: complexpassword
15    searchFilter: (uid=%s)
16    tls:
17      tlsCert: /etc/bindplane/tls/bindplane.crt
18      tlsKey: /etc/bindplane/tls/bindplane.key
19      tlsCa:
20        - /etc/bindplane/tls/ca.crt
21network:
22  host: 0.0.0.0
23  port: '3001'
24  remoteURL: http://bindplane.corp.net:3001
25store:
26  bbolt:
27    path: /var/lib/bindplane/storage/bindplane.db
28eventBus:
29  type: local
30logging:
31  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

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

bash
1bindplane init client

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

bash
1bindplane 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 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
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.