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.

nats-server -config my-server.conf

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:

listen: 127.0.0.1:4222
authorization: {
    # Bad - Number parsing error
    token: 3secret
}

Fixed Config:

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

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 like foo = "$VAR1" will result in foo 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.

# Define a variable in the config
TOKEN: "secret"

# Reference the variable
authorization {
    token: $TOKEN
}

# Define a variable in the config
# But TOKEN is never used resulting in a config parsing error
TOKEN: "secret"

# Reference the variable
authorization {
    token: "another secret"
}

unknown field "TOKEN"

A similar configuration, but this time, the variable is resolved from the environment:

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

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

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

nats-server --signal reload

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.

nats --user sys --password sys request '$SYS.REQ.SERVER.<server-id>.RELOAD' ""

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

#General settings
host: 0.0.0.0
port: 4222

# Various server level options
# ...

# The following sections are maps with a set of (nested) properties

jetstream {
    # Jetstream storage location, limits and encryption
	store_dir: nats
}

tls { 
    # Configuration map for tls parameters used for client connections, 
    # routes and https monitoring connections.
}

gateway {
    # Configuration map for gateway. Gateways are used to connected clusters.
}

leafnodes {
    # Configuration map for leafnodes. LeafNodes are lightweight clusters.
}

mqtt {
    # Configuration map for mqtt. Allow clients to connect via mqtt protocol.
} 

websocket {
    # Configuration map for websocket. Allow clients to connect via websockets.
} 

accounts {
    # List of accounts and user within accounts
    # User may have an authorization and authentication section
}

authorization { 
    # User may have an authorization and authentication section
    # This section is only useful when no accounts are defined
}

mappings {
    # Subject mappings for default account
    # When accounts are defined this section must be in the account map
}

resolver {
    # Pointer to external Authentication/Authorization resolver
    # There are multiple possible resolver type explained in their own chapters of this docuemntaion
    # memory, nats-base, url ... more may be added in the future
    # This parameter can be a value `MEMORY` for simple configuration
    # or a map of properties for connecting to the resolver
}

resolver_tls {
    # TLS configuration for an URL based resolver
}

resolver_preload {
    # List of JWT tokens to be loaded at server start.
}

Connectivity

Property	Description	Default / Example
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.	0.0.0.0:4222 Inherits from host and port
client_advertise		A list of all interfaces the the server is bound to. E.g. 127.0.0.1:4222,192.168.0.13:4222
		tls {} No tls active by default. Plain text TCP/IP.
		gateway {} None by default.
		leafnodes {} None by default.
		mqtt {} Not active by default.
		websocket {} Not active by default.

Clustering

Property	Description	Default
		cluster {} Not active by default.

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.

host: 0.0.0.0
port:4222

mappings: {
	foo: bar
}

accounts: {
    accountA: { 
	mappings: {
	    orders.acme.*: orders.$1
	}
        users: [
            {user: admin, password: admin},
            {user: user, password: user}
           ]
    },
}

Property	Description	Default
		mappings {} (none set)

Connection Timeouts

Property	Description	Default
ping_interval		"2m"
ping_max	After how many unanswered pings the server will allow before closing the connection.	2
write_deadline		"10s"

Limits

Property	Description	Default
max_connections	Maximum number of active client connections.	64K
max_control_line		4KB
max_payload		1MB
max_pending	Maximum number of bytes buffered for a connection. Applies to client connections. Note that applications can also set 'PendingLimits' (number of messages and total size) for their subscriptions.	64MB
max_subscriptions	Maximum numbers of subscriptions per client and leafnode accounts connection.	0, unlimited

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

jetstream {
  store_dir: nats

  # 1GB
  max_memory_store: 1073741824

  # 10GB
  max_file_store: 10737418240
}

Property	Description	Default	Version
store_dir	Directory to use for JetStream storage.	/tmp/nats/jetstream	2.2.0
max_memory_store	Maximum size of the 'memory' storage	75% of available memory	2.2.0
domain	Isolates the JetStream cluster to the local cluster. Recommended use with leaf nodes.	(not set)	2.2.3
max_file_store	Maximum size of the 'file' storage. For units use m mb g gb t tb	1TB	2.2.0
cipher		(not set)	2.3.0
key	The encryption key to use when encryption is enabled. A key length of at least 32 bytes is recommended. Note, this key is HMAC-256 hashed on startup which reduces the byte length to 64.	(not set)	2.3.0
max_outstanding_catchup	Max in-flight bytes for stream catch-up	32MB	2.9.0
sync_interval	Examples: 10s 1m always - Change the default fsync/sync interval for page cache in the filestore. By default JetStream relies on stream replication in the cluster to guarantee data is available after an OS crash. If you run JetStream without replication or with a replication of just 2 you may want to shorten the fsync/sync interval. - You can force an fsync after each messsage with always, this will slow down the throughput to a few hundred msg/s.	2m	2.10.0

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.

Property	Description	Default
		authorization {} (not set)
		accounts {} (not set)
		(not set) - will deny unauthorized access by default if any other users are configured.

Decentralized Authentication and Authorization

The Configuration options here refer to JWT based authentication and authorization.

Property	Description

Runtime Configuration

Property	Description	Default
disable_sublist_cache	If true disable subscription caches for all accounts. This is saves resources in situations where different subjects are used all the time.	false, cache enabled
lame_duck_duration		"2m"
lame_duck_grace_period	This is the duration the server waits, after entering lame duck mode, before starting to close client connections	"10s"

Cluster Configuration, Monitoring and Tracing

Property	Description	Default
server_name	The servers name, shows up in logging. Defaults to the server's id. When JetStream is used, within a domain, all server names need to be unique.	Generated Server ID
server_tags	A set of tags describing properties of the server. This will be exposed through /varz and can be used for system resource requests, such as placement of streams. It is recommended to use key:value style notation.	[]
trace	If true enable protocol trace log messages. Excludes the system account.	false, disabled
trace_verbose	If true enable protocol trace log messages. Includes the system account.	false, disabled
debug	If true enable debug log messages	false, disabled
logtime	If set to false, log without timestamps	true, include timestamp
log_file	Log file name, relative to...	No log file
	Size in bytes after the log file rolls over to a new one	0, unlimited
	Set the number of rotated logs to retain.	0, unlimited
max_traced_msg_len	Set a limit to the trace of the payload of a message.	0, unlimited
syslog	Log to syslog.	false, disabled
remote_syslog		(not set)
	http port for server monitoring.	(inactive)
	Listen specification <host>:<port>for server monitoring.	(inactive)
	https port for server monitoring. This is influenced by the tls property.	(inactive)
	base path for monitoring endpoints.	/
	Listen specification <host>:<port>for TLS server monitoring. Requires the tls section to be present.	(inactive)
system_account		$SYS
pid_file		(non set)
port_file_dir	Directory to write a file containing the servers open ports to, relative to ...	(not set)
connect_error_reports	Number of attempts at which a repeated failed route, gateway or leaf node connection is reported. Connect attempts are made once every second.	3600, approx every hour
reconnect_error_reports	Number of failed attempts to reconnect a route, gateway or leaf node connection. Default is to report every attempt.	1, every failed attempt