Comment on page
Configuring NATS Server
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 NATS configuration file is parsed with UTF-8 encoding.
The NATS configuration in the file can also be rendered as a JSON object (with comments!), but to combine it with variables the variables still have to be unquoted.
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:4222
authorization: {
# BAD!
token: 3secret
}
Fixed Config:
listen: 127.0.0.1:4222
authorization: {
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. They have to be unquoted when being referenced, for example, an assignment likefoo = "$example"
will result infoo
being the literal string"$example"
. - 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
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 thatinclude
is not followed by=
or:
, as it is a directive.
auth.conf:
authorization: {
token: "f0oBar"
}
> nats-server -c server.conf
Property | Description | Default |
---|---|---|
host | Host for client connections. | 0.0.0.0 |
port | Port for client connections. | 4222 |
listen | Listen specification <host>:<port> for client connections. Either use this or the options host and/or port . | same as host , port |
client_advertise | Alternative client listen specification <host>:<port> or just <host> to advertise to clients and other server. Useful in cluster setups with NAT. | Advertise what host and port specify. |
Configuration map for tls for client and http monitoring. | | |