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
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
numbers support units such as, 1K for 1000, 1Kb for 1024
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:4222authorization: {# BAD!token: 3secret}
Fixed Config:
listen: 127.0.0.1:4222authorization: {token: "3secret"}
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 configTOKEN: "secret"​# Reference the variableauthorization {token: $TOKEN}
A similar configuration, but this time, the value is in the environment:
# TOKEN is defined in the environmentauthorization {token: $TOKEN}
export TOKEN="hello"; nats-server -c /config/file
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:4222include ./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
Property | Description | Default |
| Host for client connections. |
|
| Port for client connections. |
|
| Listen specification | same as |
| Alternative client listen specification | Advertise what |
​ | Configuration map for tls for client and http monitoring. | ​ |
​ | Configuration map for cluster. | ​ |
​ | Configuration map for gateway. | ​ |
​ | Configuration map for a leafnode. | ​ |
Property | Description | Default |
| Duration at which pings are sent to clients, leaf nodes and routes. In the presence of client traffic, such as messages or client side pings, the server will not send pings. Therefore it is recommended to keep this value bigger than what clients use. |
|
| After how many unanswered pings the server will allow before closing the connection. |
|
| Maximum number of seconds the server will block when writing. Once this threshold is exceeded the connection will be closed. See slow consumer on how to deal with this on the client. |
|
Property | Description | Default |
| Maximum number of active client connections. |
|
| Maximum length of a protocol line (including combined length of subject and queue group). Increasing this value may require client changes to be used. Applies to all traffic. |
|
| Maximum number of bytes in a message payload. Reducing this size may force you to implement chunking in your clients. Applies to client and leafnode payloads. |
|
| Maximum number of bytes buffered for a connection Applies to client connections. |
|
| Maximum numbers of subscriptions per client and leafnode accounts connection. |
|
Property | Description |
​ | Configuration map for client authentication/authorization. |
​ | Configuration map for multi tenancy via accounts. |
​ | ​Username present in the authorization block or an |
The Configuration options here refer to JWT based authentication and authorization.
Property | Description |
​ | Path to an operator JWT. |
​ | Resolver type |
​ | ​ |
​ | ​Map to preload account public keys and their corresponding JWT. Keys consist of |
Property | Description | Default |
| If |
|
| In lame duck mode the server rejects new clients and slowly closes client connections. After this duration is over the server shuts down. Start lame duck mode with: |
|
Property | Description | Default |
| The servers name, shows up in logging. Defaults to the server's id. | Generated Server ID |
| If |
|
| If |
|
| If |
|
| If set to |
|
| Log file name, relative to... | No log file |
​ | Size in bytes after the log file rolls over to a new one |
|
| Set a limit to the trace of the payload of a message. |
|
| Log to syslog. |
|
| ​Syslog server address. | ​ |
​ | http port for server monitoring. | ​ |
​ | Listen specification | ​ |
​ | https port for server monitoring. This is influenced by the tls property. | ​ |
​ | base path for monitoring endpoints. |
|
​ | Listen specification | ​ |
| Name of the system account. Users of this account can subscribe to system events. See System Accounts for more details. | ​ |
| File containing PID, relative to ... This can serve as input to nats-server --signal​ | ​ |
| Directory to write a file containing the servers open ports to, relative to ... | ​ |
| Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Connect attempts are made once every second. |
|
| Number of failed attempt to reconnect a route, gateway or leaf node connection. Default is to report every attempt. |
|
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