# NATS as Event Bus

{% hint style="warning" %}
**IMPORTANT**

🚧 This feature is only available in Bindplane Enterprise. Learn more [here](https://bindplane.com/solutions/).
{% endhint %}

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

## Configuration

In order to use NATS as the event bus the `eventBus.type` field must be set to `nats` and the `eventBus.nats`config must be filled out. On Linux, the path to the configuration file is `/etc/bindplane/config.yaml`.

Here is an example configuration snippet using NATS as the event bus. In this example, there are three Bindplane severs named `bindplane-0`, `bindplane-1`, and `bindplane-2`. Each Bindplane server is operating the NATS client and server. Each NATS client will connect to its local server over `localhost`. Each NATS server will connect to other servers using their hostname and port.

```yaml
eventBus:
  type: nats
  nats:
    # NATS client connects to the NATS server on the same
    # node. The client will publish and consume events
    # from the subject "bindplane-event-bus.
    client:
      endpoint: nats://localhost:4222
      subject: bindplane-event-bus

    # NATS server accepts client connections on localhost
    # and cluster connections on all interfaces.
    server:
      enable: true
      client:
        host: localhost
        port: 4222
      http:
        host: localhost
        port: 8222
      cluster:
        name: bindplane
        host: '0.0.0.0'
        port: 6222
        routes:
          - 'nats://bindplane-0.corp.net:6222'
          - 'nats://bindplane-1.corp.net:6222'
          - 'nats://bindplane-2.corp.net:6222'
```

### Configuration Parameters

NATS Event Bus can be configured with the following configuration options, flags, and environment variables.

<table><thead><tr><th width="283.015625">Option</th><th width="91.953125">Flag</th><th>Environment Variable</th></tr></thead><tbody><tr><td><a href="#client-name">eventBus.nats.client.name</a></td><td>--nats-client-name</td><td>BINDPLANE_NATS_CLIENT_NAME</td></tr><tr><td><a href="#client-endpoint">eventBus.nats.client.endpoint</a></td><td>--nats-client-endpoint</td><td>BINDPLANE_NATS_CLIENT_ENDPOINT</td></tr><tr><td><a href="#client-subject">eventBus.nats.client.subject</a></td><td>--nats-client-subject</td><td>BINDPLANE_NATS_CLIENT_SUBJECT</td></tr><tr><td><a href="#server-enable">eventBus.nats.server.enable</a></td><td>--nats-server-enable</td><td>BINDPLANE_NATS_SERVER_ENABLE</td></tr><tr><td><a href="#server-name">eventBus.nats.server.name</a></td><td>--nats-server-name</td><td>BINDPLANE_NATS_SERVER_NAME</td></tr><tr><td><a href="#server-client-host">eventBus.nats.server.client.host</a></td><td>--nats-server-client-host</td><td>BINDPLANE_NATS_SERVER_CLIENT_HOST</td></tr><tr><td><a href="#server-client-port">eventBus.nats.server.client.port</a></td><td>--nats-server-client-port</td><td>BINDPLANE_NATS_SERVER_CLIENT_PORT</td></tr><tr><td><a href="#server-http-host">eventBus.nats.server.http.host</a></td><td>--nats-server-http-host</td><td>BINDPLANE_NATS_SERVER_HTTP_HOST</td></tr><tr><td><a href="#server-http-port">eventBus.nats.server.http.port</a></td><td>--nats-server-http-port</td><td>BINDPLANE_NATS_SERVER_HTTP_PORT</td></tr><tr><td><a href="#server-cluster-name">eventBus.nats.server.cluster.name</a></td><td>--nats-server-cluster-name</td><td>BINDPLANE_NATS_SERVER_CLUSTER_NAME</td></tr><tr><td><a href="#server-cluster-host">eventBus.nats.server.cluster.host</a></td><td>--nats-server-cluster-host</td><td>BINDPLANE_NATS_SERVER_CLUSTER_HOST</td></tr><tr><td><a href="#server-cluster-port">eventBus.nats.server.cluster.port</a></td><td>--nats-server-cluster-port</td><td>BINDPLANE_NATS_SERVER_CLUSTER_PORT</td></tr><tr><td><a href="#server-cluster-a-dvertise">eventBus.nats.server.cluster.advertise</a></td><td>--nats-server-cluster-advertise</td><td>BINDPLANE_NATS_SERVER_CLUSTER_ADVERTISE</td></tr><tr><td><a href="#server-cluster-routes">eventBus.nats.server.cluster.routes</a></td><td>--nats-server-cluster-routes</td><td>BINDPLANE_NATS_SERVER_CLUSTER_ROUTES</td></tr><tr><td><a href="#tls-configuration">eventBus.nats.tls.enableTLS</a></td><td>--nats-enable-tls</td><td>BINDPLANE_NATS_ENABLE_TLS</td></tr><tr><td><a href="#tls-configuration">eventBus.nats.tls.tlsCert</a></td><td>--nats-tls-cert</td><td>BINDPLANE_NATS_TLS_CERT</td></tr><tr><td><a href="#tls-configuration">eventBus.nats.tls.tlsKey</a></td><td>--nats-tls-key</td><td>BINDPLANE_NATS_TLS_KEY</td></tr><tr><td><a href="#tls-configuration">eventBus.nats.tls.tlsCA</a></td><td>--nats-tls-ca</td><td>BINDPLANE_NATS_TLS_CA</td></tr><tr><td><a href="#tls-configuration">eventBus.nats.tls.tlsSkipVerify</a></td><td>--nats-tls-skip-verify</td><td>BINDPLANE_NATS_TLS_SKIP_VERIFY</td></tr></tbody></table>

Default installations of Bindplane will include the following configuration. Notice that the event bus\
type is `local`, NATS is disabled by default.

```yaml
eventBus:
  type: local
  nats:
    server:
      client:
        host: localhost
        port: 4222
      http:
        host: localhost
        port: 8222
      cluster:
        name: bindplane
        host: localhost
        port: 6222
    client:
      endpoint: nats://localhost:4222
      subject: bindplane-event-bus
```

#### Client Name

The NATS client name can be set with `eventBus.nats.client.name`. It is required that clients have unique names. It is safe for this value to match NATS server's name when Bindplane is operating the NATS client and server.

Default value: System's hostname.

#### Client Endpoint

The endpoint used by the client to connect to a NATS server can be set with `eventBus.nats.client.endpoint`. The endpoint should be a URI containing the `nats` scheme as well as the hostname and port of the NATS server. Generally, `localhost` is used to target the server operating on the same node.

Default value: `nats://localhost:4222`.

#### Client Subject

The `eventBus.nats.client.subject` option configures the NATS subject used to publish and consume events from the event bus. All clients should have the same subject.

Default value: `bindplane-event-bus`.

#### Server Enable

The `eventBus.nats.server.enable` option enables the embedded NATS server. For small Bindplane deployments (3 to 5 nodes), it is recommended to operate NATS client and server on all Bindplane nodes. For large deployments (> 5), it is recommended to enable NATS server on three nodes.

Default value: `false`.

#### Server Name

The NATS server name can be set with `eventBus.nats.server.name`. It is required that servers have unique names. It is safe for this value to match the NATS client's name when Bindplane is operating the NATS client and server.

Default value: System's hostname.

#### Server Client Host

The `eventBus.nats.server.client.host` option is used to configure the network interface used by the NATS server to receive incoming connections from clients. This can be `localhost` if the server is only receiving connections from the local NATS client, in situations where Bindplane is operating the client and server.

Default value: `localhost`.

#### Server Client Port

The `eventBus.nats.server.client.port` option is used to configure the TCP port used by the NATS server to receive incoming connections from clients.

Default value: `4222`

#### Server HTTP Host

The `eventBus.nats.server.http.host` option is used to configure the network interface used to expose the NATS server Monitoring API. You can find documentation for the API [here](https://docs.nats.io/running-a-nats-service/nats_admin/monitoring). This should be set to `localhost`, with any monitoring tools running on the server system.

Default value: `localhost`.

#### Server HTTP Port

The `eventBus.nats.server.http.port` option is used to configure the TCP port used by the NATS server to expose the Monitoring API.

Default value: `8222`.

#### Server Cluster Name

The `eventBus.nats.server.cluster.name` option sets the name of the NATS cluster. All nodes within\
the NATS cluster should have the same cluster name.

Default value: `bindplane`.

#### Server Cluster Host

The `eventBus.nats.server.cluster.host` option is used to configure the network interface used to expose the NATS server's cluster interface. When operating more than one NATS server, it should be set to`0.0.0.0` or a specific IP address that is reachable by all other NATS servers.

Default value: `localhost`.

#### Server Cluster Port

The `eventBus.nats.server.cluster.port`option is used to configure the TCP port used by the NATS server's cluster interface.

Default value: `6222`.

#### Server Cluster Advertise

The `eventBus.nats.server.cluster.advertise` option can be used to advertise the endpoint other servers in the cluster should use to reach the NATS server. This option should be considered advanced and is generally not required. The configured value should be of the form `host:port`, it should not contain a URI scheme.

Default value: Unset.

#### Server Cluster Routes

The `eventBus.nats.server.cluster.routes` option is used to define a list of servers that the NATS server should connect to. This list can contain the local server.

In this example, there are three Bindplane servers. All three servers will make connections to each\
endpoint in the list of routes. The servers will detect if they are connected to themselves, and\
automatically remove the route as it is unnecessary.

```yaml
nats:
  server:
    enable: true
    cluster:
      host: '0.0.0.0'
      routes:
        - 'nats://bindplane-0.corp.net:6222'
        - 'nats://bindplane-1.corp.net:6222'
        - 'nats://bindplane-2.corp.net:6222'
```

Default value: Unset.

### Authentication

Authentication is supported by configuring TLS. The NATS event bus uses mutual TLS to authenticate the client and server.

#### TLS Configuration

The following options can be set under `eventBus.nats.tls`. When TLS is enabled, NATS will use mutual TLS to authenticate the NATS clients and servers. A certificate authority file is required to enforce the use of mutual TLS.

<table><thead><tr><th width="120.5234375">Option</th><th>Description</th><th width="113.15625">Default</th></tr></thead><tbody><tr><td>enableTLS</td><td>Enable or disable TLS</td><td><code>false</code></td></tr><tr><td>tlsCert</td><td>File path to TLS x509 PEM encoded certificate</td><td>required</td></tr><tr><td>tlsKey</td><td>File path to TLS x509 PEM encoded private key</td><td>required</td></tr><tr><td>tlsCA</td><td>File path(s) to TLS x509 PEM encoded certificate authority</td><td>required</td></tr><tr><td>tlsSkipVerify</td><td>Enable or disable strict hostname verification</td><td><code>false</code></td></tr></tbody></table>

The following example enables TLS by setting `enableTLS`, `tlsCert`, `tlsKey`, and `tlsCa`.

```yaml
eventBus:
  type: nats
  nats:
    enableTLS: true
    tls:
      tlsCert: /etc/bindplane/nats.crt
      tlsKey: /etc/bindplane/nats.key
      tlsCa:
        - /etc/bindplane/ca.crt
```

**Generating Certificates**

You can use [Step CLI](https://smallstep.com/docs/step-cli/), OpenSSL, or other tools to generate certificates. Certificates do not need to be publicly signed.

The following examples will use `step` to generate a certificate authority and a signed certificate\
suitable for use with NATS.

Create the certificate authority:

```bash
step certificate create \
  ca.corp.net \
    ca.crt ca.key \
    --profile root-ca \
    --no-password \
    --insecure \
    --not-after=43800h
```

Modify the `san` flag values to the hostnames of your Bindplane servers. If you have more than three\
servers, add additional `san` flags. You can also issue unique certificates for each server.

```bash
step certificate create \
    nats \
    --san "bindplane-0.corp.net" \
    --san "bindplane-1.corp.net" \
    --san "bindplane-2.corp.net" \
    --san localhost \
    nats.crt nats.key \
    --profile leaf \
    --not-after 2160h \
    --no-password \
    --insecure \
    --ca ca.crt \
    --ca-key ca.key
```

Copy `ca.crt`, `nats.crt`, `nats.key` to `/etc/bindplane` on all of your servers. After copying them,\
set the filesystem permissions.

```bash
sudo chown bindplane:bindplane \
  /etc/bindplane/ca.crt \
  /etc/bindplane/nats.crt \
  /etc/bindplane/nats.key

sudo chmod 0400 bindplane:bindplane \
  /etc/bindplane/ca.crt \
  /etc/bindplane/nats.crt \
  /etc/bindplane/nats.key
```

Update your NATS configuration section to include the TLS options.

* `eventBus.nats.enableTLS`
* `eventBus.nats.tls.tlsCert`
* `eventBus.nats.tls.tlsKey`
* `eventBus.nats.tls.tlsCa`

```yaml
eventBus:
  type: nats
  nats:
    enableTLS: true
    tls:
      tlsCert: /etc/bindplane/nats.crt
      tlsKey: /etc/bindplane/nats.key
      tlsCa:
        - /etc/bindplane/ca.crt
```


---

# 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/nats-as-event-bus.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.