Configuration reference

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

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.

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.

monitor

Prometheus metrics endpoint served on /metrics.

monitor.counters

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.

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.

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:

Unmatched action values:

Individual ports can override the global defaults by adding entries under ports:

rules:
  default_rule_direction: to_backend
  unmatched_rule_to_backend_action: deny
  unmatched_rule_from_backend_action: deny
  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).

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.

audit.processors[]

Event types:

Processor config by type:

file:

nats:

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.

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.

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.

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.

data_limits:
  max_stream_size: 1GB
  max_age: 720h

Credentials

Used in configuration_server, remote_configuration_server, and nats audit processors.

# 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:

Plain integers are treated as bytes.