Configuration

While the NATS server has many flags that allow for simple testing of features, the NATS server products provide a flexible configuration format that combines the best of traditional formats and newer styles such as JSON and YAML.

The NATS configuration file supports the following syntax:

  • Lines can be commented with # and //

  • Values can be assigned to properties with:

    • Equals sign: foo = 2

    • Colon: foo: 2

    • Whitespace: foo 2

  • Arrays are enclosed in brackets: ["a", "b", "c"]

  • Maps are enclosed in braces: {foo: 2}

  • Maps can be assigned with no key separator

  • Semicolons can be used as terminators

Strings and Numbers

The configuration parser is very forgiving, as you have seen:

  • values can be a primitive, or a list, or a map

  • strings and numbers typically do the right thing

String values that start with a digit can create issues. To force such values as strings, quote them.

BAD Config:

listen: 127.0.0.1:4222
authorization: {
# BAD!
token: 3secret
}

Fixed Config:

listen: 127.0.0.1:4222
authorization: {
token: "3secret"
}

Variables

Server configurations can specify variables. Variables allow you to reference a value from one or more sections in the configuration.

Variables:

  • Are block-scoped

  • Are referenced with a $ prefix.

  • Can be resolved from environment variables having the same name

If the environment variable value begins with a number you may have trouble resolving it depending on the server version you are running.

# Define a variable in the config
TOKEN: "secret"
# Reference the variable
authorization {
token: $TOKEN
}

A similar configuration, but this time, the value is in the environment:

# TOKEN is defined in the environment
authorization {
token: $TOKEN
}

export TOKEN="hello"; nats-server -c /config/file

Include Directive

The include directive allows you to split a server configuration into several files. This is useful for separating configuration into chunks that you can easily reuse between different servers.

Includes must use relative paths, and are relative to the main configuration (the one specified via the -c option):

server.conf:

listen: 127.0.0.1:4222
include ./auth.conf

Note that include is not followed by = or :, as it is a directive.

auth.conf:

authorization: {
token: "f0oBar"
}
> nats-server -c server.conf

Configuration Properties

Property

Description

authorization

Configuration map for client authentication/authorization

cluster

Configuration map for clustering configuration

connect_error_reports

Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Default is 3600, approx every hour.

debug

If true enable debug log messages

gateway

Gateway configuration map

host

Host for client connections

http_port

http port for server monitoring

https_port

https port for server monitoring

leafnode

Leafnode configuration map

listen

Host/port for client connections

max_connections

Maximum number of active client connections

max_control_line

Maximum length of a protocol line (including subject length)

max_payload

Maximum number of bytes in a message payload

max_pending

Maximum number of bytes buffered for a connection

max_subscriptions

Maximum numbers of subscriptions for a client connection

max_traced_msg_len

Set a limit to the trace of the payload of a message

disable_sublist_cache

Disable sublist cache globally for accounts.

operator

Path to an operator JWT

ping_interval

Interval in seconds in which the server checks if a connection is active

port

Port for client connections

reconnect_error_reports

Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt.

resolver

Resolver type MEMORY or URL for account JWTs

tls

Configuration map for tls for client and http monitoring

trace

If true enable protocol trace log messages

write_deadline

Maximum number of seconds the server will block when writing a to a client (slow consumer)

Configuration Reloading

A server can reload most configuration changes without requiring a server restart or clients to disconnect by sending the nats-server a signal:

> nats-server --signal reload