# Configuration

All gateway configuration is done through a YAML file. There are three configuration modes depending on how the gateway is deployed:

* `Standalone` - hosts everything needed to run and manage the gateway. Security policies are installed and managed directly via `protect admin` or the protect UI.
* `Configuration Server` - centralized management for a fleet of gateways. Security policies are installed and managed here, then distributed to managed gateways. The management service runs on an external NATS server provided by the user.
* `Managed Gateway` - hosts everything needed to run the gateway, but security policies are installed and managed via a configuration server.

The mode is determined by which top-level block is present in the configuration file.

## Configuration sections

| Section                                                       | Description                                                                  |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [`name`](#name)                                               | unique instance identifier                                                   |
| [`ports`](#ports)                                             | listening ports that proxy connections to backend NATS clusters              |
| [`monitor`](#monitor)                                         | Prometheus metrics endpoint                                                  |
| [`management`](#management)                                   | admin API on an embedded NATS server (standalone and managed gateways)       |
| [`rules`](#rules)                                             | default policy behavior and trusted bundle signers                           |
| [`logger`](#logger)                                           | operational log level and format                                             |
| [`audit`](#audit)                                             | audit logging for policy decisions, API access, and connection events        |
| [`configuration_server`](#configuration_server)               | external NATS cluster for centralized management (configuration server only) |
| [`remote_configuration_server`](#remote_configuration_server) | connection to a configuration server (managed gateway only)                  |
| [`data_limits`](#data_limits)                                 | stream size and retention limits (configuration server only)                 |

## Environment variable expansion

Configuration values support environment variable expansion using `${VAR}` syntax. Default values are supported with `${VAR:-default}`:

```
name: '${GATEWAY_NAME}'

configuration_server:

  urls:

    - '${NATS_URL}'

  api_credentials:

    user_name: '${API_USER}'

    password: '${API_PASS:-changeme}'
```

## Windows paths

On Windows, use forward slashes in all path configurations. The configuration parser interprets backslashes as escape characters:

```
# correct

data_dir: C:/protect/data



# incorrect -- backslashes will be treated as escapes

data_dir: C:\protect\data
```

## Standalone gateway

A standalone gateway has its own management API, stores its own data, and operates independently.

## Configuration server

A configuration server differs from a standalone gateway in two ways:

* It has a `configuration_server` block with `api_credentials` and `data_credentials` for connecting to an external NATS cluster where the management service runs. There is no `management` block — the `protect admin` commands and the protect UI connect to the external NATS cluster using credentials for the `api_credentials` account.
* The `ports` section declares the port names managed gateways can expose. Only `name` and `kind` are allowed — setting `host`, `port`, `backend`, `tls`, or `compression` is an error. The configuration server does not listen on these ports; each managed gateway supplies the network details.

## Managed gateway

A managed gateway connects to a configuration server to receive its bundles and configuration. It reports health via heartbeats.

## Section reference

### `name`

Unique identifier for this gateway instance. Appears in logs, metrics, and the admin API. Must not contain whitespace or `.` characters.

### `ports`

A list of named listening ports. Each port proxies connections to a backend NATS cluster.

On a configuration server, only `name` and `kind` are allowed — the server declares port names for the fleet but does not listen. Setting `host`, `port`, `tls`, `backend`, or `compression` on a configuration server port is an error.

| Field              | Type     | Default     | Description                                               |
| ------------------ | -------- | ----------- | --------------------------------------------------------- |
| `name`             | string   | required    | unique port identifier (alphanumeric, `-`, `_`)           |
| `kind`             | string   | required    | `client` or `leaf`                                        |
| `host`             | string   | `127.0.0.1` | bind address                                              |
| `port`             | int      | required    | listen port (1-65535, or -1 for random)                   |
| `tls`              | tls      | -           | TLS for incoming connections                              |
| `backend`          | backend  | required    | the backend NATS cluster this port proxies to             |
| `compression`      | string   | `off`       | leaf ports only: `off`, `s2_fast`, `s2_better`, `s2_best` |
| `max_control_line` | int      | -           | max protocol control line size                            |
| `max_connections`  | int      | -           | max concurrent connections                                |
| `max_pending`      | int      | -           | max pending bytes per connection                          |
| `auth_timeout`     | duration | -           | authentication timeout                                    |

```
ports:

  - name: clients

    kind: client

    host: 0.0.0.0

    port: 4222

    max_connections: 1000

    auth_timeout: 5s

    backend:

      urls:

        - nats://backend-1:4222

        - nats://backend-2:4222

  - name: leafnodes

    kind: leaf

    host: 0.0.0.0

    port: 7422

    compression: s2_fast

    backend:

      urls:

        - nats://backend-1:7422
```

### `backend`

A backend is the destination NATS cluster that a port proxies connections to.

| Field  | Type      | Default  | Description                                    |
| ------ | --------- | -------- | ---------------------------------------------- |
| `urls` | string\[] | required | NATS server URLs                               |
| `tls`  | tls       | -        | TLS settings for the connection to the backend |

### `monitor`

Prometheus metrics endpoint served on `/metrics`.

| Field      | Type   | Default     | Description                  |
| ---------- | ------ | ----------- | ---------------------------- |
| `host`     | string | `127.0.0.1` | bind address                 |
| `port`     | int    | required    | listen port (0 = disabled)   |
| `tls`      | tls    | -           | TLS settings                 |
| `counters` | object | -           | per-subject traffic tracking |

### `monitor.counters`

| Field                              | Type      | Default | Description                              |
| ---------------------------------- | --------- | ------- | ---------------------------------------- |
| `count_message_with_subject`       | string\[] | -       | subject patterns to track message counts |
| `count_message_bytes_with_subject` | string\[] | -       | subject patterns to track byte counts    |

Subject counters are opt-in per-subject traffic tracking. Subjects in the list may not overlap and there is a maximum of 1000 entries per list. Enabling these will impact performance.

```
monitor:

  host: 0.0.0.0

  port: 8080

  counters:

    count_message_with_subject:

      - 'orders.>'

      - 'events.>'

    count_message_bytes_with_subject:

      - 'orders.>'
```

### `management`

The management service hosts the admin API. For standalone and managed gateways, it runs on an embedded NATS server and uses NKey authentication. Configuration servers do not have a `management` block — the management service runs on the external NATS cluster specified in `configuration_server.urls`, and `protect admin` / the protect UI connect using whatever credentials the external cluster requires for the API account.

| Field                     | Type      | Default     | Description                         |
| ------------------------- | --------- | ----------- | ----------------------------------- |
| `api_key`                 | string    | required    | public NKey(s) for admin API access |
| `system_key`              | string    | required    | public NKey(s) for system access    |
| `data_key`                | string    | -           | public NKey(s) for data access      |
| `host`                    | string    | `127.0.0.1` | bind address                        |
| `port`                    | int       | required    | listen port                         |
| `data_dir`                | string    | required    | JetStream data storage directory    |
| `enable_server_log`       | bool      | `false`     | log embedded NATS server output     |
| `tls`                     | tls       | -           | TLS settings                        |
| `bundle_install_timeout`  | duration  | -           | max time for bundle installation    |
| `bundle_install_max_size` | byte size | -           | max bundle file size                |
| `evaluate_timeout`        | duration  | -           | max time for rule evaluation        |

```
management:

  api_key:

    - UBZ4SGUAFFUBHNNZJ6K76SWRGC7TE7XIFMRDFHGZHTCQ2BB23FZG42L6

  system_key:

    - UD6MMRSS6DFTSXHVSV3TYELESX2E2VMCKV6XMKHIILTOXN7IZ2GQG3SY

  host: 127.0.0.1

  port: 4911

  data_dir: /var/lib/protect/data

  bundle_install_timeout: 10s

  bundle_install_max_size: 10MB
```

Gateways use NKey authentication. Each gateway generates its own internal keys. The configuration lists the public keys authorized to access each account:

* `SYSTEM` — internal system account. Access is rarely needed.
* `DATA` — stores bundles, rules, and related configuration.
* `API` — the primary admin interface. Manage bundles, define trace profiles, disconnect or suspend clients, and view server info and statistics.

### `rules`

Controls default policy behavior when no rule matches traffic. These settings apply globally to all ports unless overridden on a per-port basis.

| Field                                | Type      | Default      | Description                                                         |
| ------------------------------------ | --------- | ------------ | ------------------------------------------------------------------- |
| `default_rule_direction`             | string    | `to_backend` | direction rules evaluate unless a rule specifies its own direction  |
| `unmatched_rule_to_backend_action`   | string    | `deny`       | action when no rule matches client-to-backend traffic               |
| `unmatched_rule_from_backend_action` | string    | `deny`       | action when no rule matches backend-to-client traffic               |
| `default_suspend_timeout`            | duration  | `5m`         | how long a connection stays suspended when a rule returns `suspend` |
| `trusted_bundle_signers`             | string\[] | -            | public NKeys authorized to sign bundles                             |

When `trusted_bundle_signers` is set, the gateway only accepts bundles signed by the listed public keys. Removing a key revokes all bundles issued by that signer -- active bundles are automatically deactivated. To restore those rules, re-create the bundle with a trusted signer.

Rule direction values:

| Value          | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| `to_backend`   | rules only evaluate traffic flowing from the client/leafnode to the backend cluster |
| `from_backend` | rules only evaluate traffic flowing from the backend cluster to the client/leafnode |
| `both`         | rules evaluate traffic in both directions                                           |

Unmatched action values:

| Value     | Description                                                                                                                                                                                                                                                                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow`   | forward the traffic                                                                                                                                                                                                                                                                                                                            |
| `deny`    | reject the traffic and disconnect the client                                                                                                                                                                                                                                                                                                   |
| `suspend` | drop all traffic but respond to `PING` so the connection believes it is still alive. Requests time out, subscriptions produce no messages, and published messages are dropped. Delays the reconnect cycle — unlike `deny`, which disconnects the client immediately. The connection is released after `default_suspend_timeout` (default `5m`) |

Individual ports can override `default_rule_direction` and the two unmatched actions by adding entries under `ports`:

```
rules:

  default_rule_direction: to_backend

  unmatched_rule_to_backend_action: deny

  unmatched_rule_from_backend_action: deny

  default_suspend_timeout: 5m

  trusted_bundle_signers:

    - <public NKey>

  ports:

    - name: clients

      default_rule_direction: both

      unmatched_rule_from_backend_action: allow

    - name: leafnodes

      unmatched_rule_from_backend_action: allow
```

Each entry must reference a port `name` defined in `ports`. Only the fields you specify are overridden — the rest fall back to the global values.

### `logger`

Operational logging (not audit events).

| Field           | Type   | Default  | Description                                         |
| --------------- | ------ | -------- | --------------------------------------------------- |
| `level`         | string | required | `trace`, `debug`, `info`, `warning`, `error`        |
| `debug_traffic` | bool   | `false`  | trace protocol traffic on the embedded NATS server  |
| `file_path`     | string | -        | log file path (stdout if omitted)                   |
| `format`        | string | `nats`   | `nats` (nats-server style log format) or `standard` |

```
logger:

  level: info

  file_path: /var/log/protect/protect.log

  format: nats
```

### `audit`

Audit logging for policy decisions, API access, bundle management, and connection events. Intended for SIEM integration.

| Field              | Type   | Default  | Description                         |
| ------------------ | ------ | -------- | ----------------------------------- |
| `log_file_dir`     | string | required | directory for audit log files       |
| `client_trace_dir` | string | required | directory for client trace captures |
| `processors`       | list   | required | at least one processor              |

### `audit.processors[]`

| Field            | Type      | Default  | Description                                               |
| ---------------- | --------- | -------- | --------------------------------------------------------- |
| `name`           | string    | required | processor identifier                                      |
| `type`           | string    | required | `file`, `log`, or `nats`                                  |
| `format`         | string    | `text`   | `text`, `json`, or `cef`                                  |
| `disabled`       | bool      | `false`  | disable this processor                                    |
| `events`         | string\[] | all      | event types to capture (omit for all)                     |
| `exclude_events` | string\[] | none     | event types to exclude (mutually exclusive with `events`) |
| `config`         | object    | -        | type-specific configuration                               |

Event types:

| Event                      | Description                     |
| -------------------------- | ------------------------------- |
| `connection.start`         | connection established          |
| `connection.end`           | connection closed               |
| `policy.action`            | policy evaluation result        |
| `management.api`           | mutating management API access  |
| `management.informational` | read-only management API access |
| `management.policy`        | policy management API access    |
| `management.bundle`        | bundle management API access    |
| `log.protocol`             | raw protocol data (debugging)   |
| `trace.start`              | trace capture started           |
| `trace.end`                | trace capture ended             |

Processor config by type:

`file`:

| Field  | Type   | Description      |
| ------ | ------ | ---------------- |
| `file` | string | output file path |

`nats`:

| Field             | Type        | Description         |
| ----------------- | ----------- | ------------------- |
| `urls`            | string\[]   | NATS server URLs    |
| `credentials`     | credentials | NATS authentication |
| `default_timeout` | duration    | request timeout     |

```
audit:

  log_file_dir: /var/log/protect/audit

  client_trace_dir: /var/log/protect/traces

  processors:

    - name: all_events

      type: file

      format: text

      config:

        file: /var/log/protect/audit/audit.log

    - name: connections

      type: file

      format: cef

      events:

        - connection.start

        - connection.end

      config:

        file: /var/log/protect/audit/connections.log

    - name: policy

      type: file

      format: json

      events:

        - policy.action

      config:

        file: /var/log/protect/audit/policy.log

    - name: siem

      type: nats

      format: json

      config:

        urls:

          - nats://siem-collector:4222

        credentials:

          user_name: audit

          password: secret
```

### `tls`

TLS configuration used by ports, backends, monitor, and management. The fields are the same everywhere.

| Field         | Type     | Default | Description                            |
| ------------- | -------- | ------- | -------------------------------------- |
| `certificate` | string   | -       | path to certificate file               |
| `key`         | string   | -       | path to private key file               |
| `ca`          | string   | -       | path to CA certificate                 |
| `timeout`     | duration | `2s`    | TLS handshake timeout                  |
| `verify`      | bool     | `false` | require and verify client certificates |
| `insecure`    | bool     | `false` | skip certificate verification          |
| `min_version` | float    | -       | minimum TLS version (e.g., `1.2`)      |

```
tls:

  certificate: /etc/protect/certs/server.pem

  key: /etc/protect/certs/server.key

  ca: /etc/protect/certs/ca.pem

  verify: true

  min_version: 1.3
```

### `configuration_server`

Present only in configuration server mode.

| Field                     | Type      | Default  | Description                      |
| ------------------------- | --------- | -------- | -------------------------------- |
| `urls`                    | string\[] | required | external NATS cluster URLs       |
| `api_credentials`         | object    | required | credentials for the API account  |
| `data_credentials`        | object    | required | credentials for the data account |
| `bundle_install_timeout`  | duration  | -        | bundle installation timeout      |
| `bundle_install_max_size` | byte size | -        | max bundle size                  |
| `evaluate_timeout`        | duration  | -        | rule evaluation timeout          |

```
configuration_server:

  urls:

    - nats://nats-1:4222

    - nats://nats-2:4222

  api_credentials:

    user_name: admin

    password: secret

  data_credentials:

    user_name: data

    password: datapass

  bundle_install_max_size: 10MB
```

### `remote_configuration_server`

Present only in managed gateway mode.

| Field                | Type      | Default  | Description                       |
| -------------------- | --------- | -------- | --------------------------------- |
| `urls`               | string\[] | required | configuration server NATS URLs    |
| `data_credentials`   | object    | required | credentials to access config data |
| `heartbeat_interval` | duration  | -        | health check-in interval          |

```
remote_configuration_server:

  urls:

    - nats://config-server:4222

  data_credentials:

    user_name: gateway-01

    password: gatewaypass

  heartbeat_interval: 30s
```

### `data_limits`

Only valid when `configuration_server` is present.

| Field             | Type      | Default | Description                |
| ----------------- | --------- | ------- | -------------------------- |
| `max_stream_size` | byte size | -       | max JetStream storage size |
| `max_age`         | duration  | -       | max message retention age  |

```
data_limits:

  max_stream_size: 1GB

  max_age: 720h
```

### Credentials

Used in `configuration_server`, `remote_configuration_server`, and `nats` audit processors.

| Field       | Type   | Description         |
| ----------- | ------ | ------------------- |
| `user_name` | string | basic auth username |
| `password`  | string | basic auth password |
| `token`     | string | bearer token        |
| `nkey`      | string | NKey seed           |
| `nkey_file` | string | path to NKey file   |
| `jwt`       | string | JWT credential      |
| `jwt_file`  | string | path to JWT file    |
| `name`      | string | connection name     |

```
# using username/password

credentials:

  user_name: admin

  password: secret



# using NKey file

credentials:

  nkey_file: /etc/protect/admin.nk



# using JWT + NKey

credentials:

  jwt_file: /etc/protect/user.jwt

  nkey_file: /etc/protect/user.nk
```

### Byte size values

Fields like `bundle_install_max_size` and `max_stream_size` accept human-readable sizes:

| Suffix            | Base          | Example |
| ----------------- | ------------- | ------- |
| `k`               | 1,000         | `64k`   |
| `m`               | 1,000,000     | `10m`   |
| `g`               | 1,000,000,000 | `1g`    |
| `kb`, `ki`, `kib` | 1,024         | `64kb`  |
| `mb`, `mi`, `mib` | 1,048,576     | `10mb`  |
| `gb`, `gi`, `gib` | 1,073,741,824 | `1gb`   |

Plain integers are treated as bytes.
