# TLS
Bindplane supports TLS. This guide will focus on using [Step CLI](https://smallstep.com/cli/) to create certificates, however, you can acquire certificates using your preferred method. Certificates must be x509 PEM encoded.
### TLS with Step CLI
[Step CLI](https://smallstep.com/cli/) can be used to create your own certificate authority and server certificates. Step provides an easy-to-use interface. Alternatively, you could use [OpenSSL](https://www.openssl.org/).
#### Prerequisites
This guide assumes you will be deploying Bindplane and its collectors to a network that has a working Domain Name System (DNS). It is expected that collector systems will be able to connect to Bindplane using its fully qualified domain name (FQDN).
If you do not have working DNS, it is possible to use `/etc/hosts` as a workaround. See [this guide](https://www.tecmint.com/setup-local-dns-using-etc-hosts-file-in-linux/) for details.
#### Environment
For this demonstration, we have four compute instances running on Google Cloud. The objective is to configure Bindplane to use a server TLS certificate, and have all clients and collectors connect using TLS.
The following instances are deployed:
* `bindplane`: Instance that hosts the Bindplane server.
* `collector-debian`: Debian-based instance that will host a Bindplane collector.
* `collector-centos`: CentOS-based instance that will host a Bindplane collector.
* `collector-windows`: Windows Server instance that will host a Bindplane collector.
Each instance belongs to a VPC in the project `bindplane`, which means each instance has a DNS name with the following format: `{{instance name}}.c.bindplane.internal`.
Each instance has the following fully qualified domain name (FQDN):
* bindplane: `bindplane.c.bindplane.internal`
* collector-debian: `collector-debian.c.bindplane.internal`
* collector-centos: `collector-centos.c.bindplane.internal`
* collector-windows: `collector-windows.c.bindplane.internal`
All instances within the network can resolve each other using their FQDN. DNS plays a critical role when using TLS, as it allows certificates to be verified against their hostname. If the hostname does not match the certificate, the connection will be rejected unless steps are taken to disable TLS verification.
### Deploy and Configure Bindplane
Follow the [Bindplane Server Install Guide](https://docs.bindplane.com/deployment/virtual-machine/bindplane/install-bindplane-server) to install Bindplane.
Once installed, modify the `/etc/bindplane/config.yaml` to look like this:
```yaml
name: default
apiVersion: bindplane.observiq.com/v1
auth:
# A random uuid which is used as a shared secret between bindplane and
# deployed collectors.
secretKey: ffb26038-5169-4496-b5fc-d5a185c33b96
# Basic auth should use a username other than
# admin along with a secure password.
username: admin
password: admin
# A random uuid which is used for generating web ui session cookies.
sessionSecret: 14dab09e-0ca5-4167-bde3-39c869f3fab4
network:
# Listen on port 3001, all interfaces.
host: 0.0.0.0
port: '3001'
# Endpoint for which clients and collectors will interface
# with the server's http interface.
remoteURL: http://bindplane.c.bindplane.internal:3001
store:
type: postgres
postgres:
database: bindplane
logging:
filePath: /var/log/bindplane/bindplane.log
```
Note that `auth.secretKey` and `auth.sessionSecret` should be random `uuid` values. You can generate your own with the `uuidgen` command.
Make sure `network.remoteURL` use the correct FQDN. You can check your server's FQDN using the\
hostname command:
```bash
$ hostname -f
bindplane.c.bindplane.internal
```
Once Bindplane is configured, restart the server.
```bash
sudo systemctl restart bindplane
```
Verify that Bindplane is working by connecting to the public IP address on port 3001. In this example, that would be .
### Create Certificates with Step
On the instance running your Bindplane server, install the `step` command line. Instructions\
for installing `step` can be found [here](https://smallstep.com/docs/step-cli/installation).
**Create Certificate Authority**
The following commands will write a certificate and private key to `tls-ca/ca.crt` and `tls-ca/ca.key` in your working directory.
```bash
mkdir tls-ca
step certificate create \
ca.c.bindplane.internal \
tls-ca/ca.crt tls-ca/ca.key \
--profile root-ca \
--no-password \
--insecure \
--not-after=8760h
```
**Create Bindplane Server Certificate**
The following commands will generate a server certificate signed by the CA previously\
created. The certificate and private key will be written to `/etc/bindplane/tls/bindplane.crt`\
and `/etc/bindplane/tls/bindplane.key`
```bash
sudo mkdir /etc/bindplane/tls
sudo step certificate create \
bindplane.c.bindplane.internal \
/etc/bindplane/tls/bindplane.crt /etc/bindplane/tls/bindplane.key \
--profile leaf \
--not-after 2160h \
--no-password \
--insecure \
--ca tls-ca/ca.crt \
--ca-key tls-ca/ca.key
sudo chown -R bindplane:bindplane /etc/bindplane/tls
```
### Configure Bindplane to use TLS
With the server certificate created, make the following changes to `/etc/bindplane/config.yaml`:
1. Modify `network.remoteURL` to use `https`
2. Add `tlsCert` and `tlsKey`
Your configuration will look similar to this:
```yaml
name: default
apiVersion: bindplane.observiq.com/v1
auth:
# A random uuid which is used as a shared secret between bindplane and
# deployed collectors.
secretKey: ffb26038-5169-4496-b5fc-d5a185c33b96
# Basic auth should use a username other than
# admin along with a secure password.
username: admin
password: admin
# A random uuid which is used for generating web ui session cookies.
sessionSecret: 14dab09e-0ca5-4167-bde3-39c869f3fab
network:
# Listen on port 3001, all interfaces.
host: 0.0.0.0
port: '3001'
# Endpoint for which clients and collectors will interface
# with the server's http interface.
remoteURL: https://bindplane.c.bindplane.internal:3001
tlsCert: /etc/bindplane/tls/bindplane.crt
tlsKey: /etc/bindplane/tls/bindplane.key
store:
type: postgres
postgres:
database: bindplane
logging:
filePath: /var/log/bindplane/bindplane.log
```
With the configuration updated, restart Bindplane:
```bash
sudo systemctl restart bindplane
```
To verify that Bindplane is using TLS, navigate to your server's IP address using `https`. For example, .
You should expect your browser to present a warning screen. This is because your workstation does not trust the certificate. This is expected because you have not imported the certificate authority into your trust store. At this time, it is safe to skip the warning and continue. Note that this warning should never be ignored in production, or in areas where it is not expected.
### Import Certificate Authority on Collector Systems
In all instances that will be running a Bindplane collector, we need to import the certificate authority. This will allow the collector software to trust the Bindplane server certificate.
1. Copy `tls-ca/ca.crt` to all systems that will be running a Bindplane Collector
2. Import the `ca.crt` into the trust store on all collector systems
3. Install collectors
For instructions on how to import a certificate authority, see [this blog](https://manuals.gfi.com/en/kerio/connect/content/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html).
Once all collector systems have the certificate authority imported, you can install collectors using\
the command generated in the Bindplane web interface.
Example Linux install command:
```bash
sudo sh -c "$(curl -fsSlL https://github.com/observIQ/bindplane-otel-collector/releases/download/v1.25.0/install_unix.sh)" install_unix.sh -e wss://bindplane.c.bindplane.internal:3001/v1/opamp -s ffb26038-5169-4496-b5fc-d5a185c33b96 -v 1.19.0
```
Note that the command uses the value from `server.remoteURL` in `/etc/bindplane/config.yaml` as the endpoint that the collector should connect to. The `wss` protocol indicates that TLS should be used.
Once installed, the `manager` configuration at `/opt/observiq-otel-collector/manager.yaml` will look something like this:
// cspell:ignore 01GTHN3HAD7QXFN4Z9FV625A3V
```yaml
endpoint: wss://bindplane.c.bindplane.internal:3001/v1/opamp
secret_key: ffb26038-5169-4496-b5fc-d5a185c33b96
agent_id: 01GTHN3HAD7QXFN4Z9FV625A3V
```
Finished! Collectors appear in the web interface, indicating that TLS is working.
