Configuring NATS Server
While the NATS server has many flags that allow for simple testing of features from command line. The standard way of configuring the NATS server product is through a configuration file. We use a simple configuration format that combines the best of traditional formats and newer styles such as JSON and YAML.
The NATS configuration supports the following syntax:
Lines can be commented with
#
and//
Values can be assigned to properties with delimiters:
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 delimiter
accounts { SYS {...}, cloud-user {...} }
Semicolons can be optionally used as terminators
host: 127.0.0.1; port: 4222;
The NATS configuration file is parsed with UTF-8 encoding.
We strongly recommend using only ASCII for names and values, limiting the use of Unicode, no ASCII text to comments.
Note
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.
JSON config files should be limited machine generated configuration files
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
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:
Fixed Config:
Variables
Server configurations can specify variables. Variables allow you to reference a value from one or more sections in the configuration.
Variables syntax:
Are block-scoped
Are referenced with a
$
prefix. Variables in quotes blocks are ignored. For example, a usage likefoo = "$VAR1"
will result infoo
being the literal string"$VAR1"
.Variables MUST be used to be recognized as such. The config parser will distinguish
unknown field
from variable by finding a reference to the variable.Variable reference which are not defined will be resolved from environment variables.
Variable resolution sequence:
Look for variable in same scope
Look for variable in parent scopes
Look for variable in enviroment variables
If not found stop server startup with the error below
nats-server: variable reference for 'PORT' on line 5 can not be found
If the environment variable value begins with a number you may have trouble resolving it depending on the server version you are running.
A similar configuration, but this time, the variable is resolved from the environment:
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:
Note that
include
is not followed by=
or:
, as it is a directive.
auth.conf:
Configuration Reloading
The config file is being read by the server on startup and is not re-scanned for changes and not locked.
A server can reload most configuration changes without requiring a server restart or clients to disconnect by sending the nats-server a signal:
As of NATS v2.10.0, a reload signal can be sent on a NATS service using a system account user, where <server-id>
is the unique ID of the server be targeted.
Configuration Properties
Config files have the following structure (in no specific order). All blocks and properties are optional (except host and port).
Please see sections below for links to detailed explanations of each configuration block
Connectivity
Clustering
Subject Mappings
Note that each accounts forms its own subject namespace. Therefore the mappings
section can appear on the server level (applying to the default account) or on the account level.
Connection Timeouts
Limits
JetStream
You can enable JetStream in the server's configuration by simply adding a jetstream {}
map. By default, the JetStream subsystem will store data in the /tmp directory, but you can specify the directory to use via the store_dir
, as well as the limits for JetStream storage (a value of 0 means no limit).
Normally JetStream will be run in clustered mode and will replicate data, so the best place to store JetStream data would be locally on a fast SSD. One should specifically avoid NAS or NFS storage for JetStream.
Note that each JetStream enabled server MUST use its own individual storage directory. Jetstream replicates data between cluster nodes (up to 5 replicas), achieving redundancy and availability through this.
Jetstream does not implement standby and fault tolerance through a shared file system. If a standby server shares a storage dir with an active server, you must make sure only one is active at any time. Access conflicts are not detected. We do not recommend such a setup.
Here's an example minimal file that will store data in a local "nats" directory with some limits.
$ nats-server -c js.conf
Authentication and Authorization
Centralized Authentication and Authorization
A default nats server will have no authentication or authorization enabled. This is useful for development and simple embedded use cases only. The default account is $G
.
Once at least one user is configured in the authorization or accounts sections the default $G account an no-authentication user are disabled. You can restore no authentication access by setting the no_auth_user
.
Decentralized Authentication and Authorization
The Configuration options here refer to JWT based authentication and authorization.
Runtime Configuration
Cluster Configuration, Monitoring and Tracing
Last updated