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
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
Alternative client listen specification <host>:<port>
or just <host>
to advertise to clients and other server. Advertising is only active in cluster setups with NAT. Explicitly setting the URL is useful when the server is situated behind a load balancer and/or TLS server authentication requires the correct DNS name to be presented. To completely disable client_advertise
please set no_advertise: true
in the cluster configuration section.
A list of all interfaces the the server is bound to. E.g. 127.0.0.1:4222,192.168.0.13:4222
Configuration map for tls parameters used for client connections, routes and https monitoring connections.
tls {}
No tls active by default. Plain text TCP/IP.
Configuration map for gateway. Gateways are used to connected clusters into superclusters.
gateway {}
None by default.
Configuration map for leafnodes. LeafNodes are lightweight clusters.
leafnodes {}
None by default.
Configuration map for mqtt. Allow clients to connect via mqtt protocol.
mqtt {}
Not active by default.
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.
Configuration map for mapping subject. Allows for subjects aliasing and patterns based translation. Can be used to great effect in supercluster and leafnode configuration and when sourcing streams.
mappings {}
(none set)
Connection Timeouts
ping_interval
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.
"2m"
ping_max
After how many unanswered pings the server will allow before closing the connection.
2
write_deadline
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.
"10s"
Limits
max_connections
Maximum number of active client connections.
64K
max_control_line
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.
4KB
max_payload
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. It is not recommended to use values over 8MB but max_payload
can be set up to 64MB. The max payload must be equal to or smaller than the max_pending
value.
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
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
Set to enable storage-level encryption at rest. Choose either chachapoly
or aes
.
(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
.
Configuration map for client authentication/authorization. List of user and their auth setting. This section is used when only the default account ($G) is active.
authorization {}
(not set)
Configuration map for multi tenancy via accounts. A list of accounts each with its own users and their auth settings. Each acount forms its own subject and stream namespace, with not data shared unless explicit import
and export
is configured.
accounts {}
(not set)
Username present in the authorization block or an account
. A client connecting without any form of authentication will be associated with this user, its permissions and account.
(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.
The Json Web Token of the auth operator.
The built-in NATS resolver
, MEMORY
for static or URL(<url>)
to use an external account server. (When the operator JWT contains an account URL, it will be used as default. In this case resolver
is only needed to overwrite the default.)
tls
configuration map for tls connections to the resolver. (This is for an outgoing connection and therefore does not use timeout
, verify
and map_and_verify
)
Map to preload account public keys and their corresponding JWT. Keys consist of <account public nkey>
, value is the <corresponding jwt>
.
Runtime Configuration
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
In lame duck mode the server rejects new clients and slowly closes client connections. After this duration is over the server shuts down. This value cannot be set lower than 30 seconds. Start lame duck mode with: nats-server --signal ldm
.
"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
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
max_traced_msg_len
Set a limit to the trace of the payload of a message.
0
, unlimited
syslog
Log to syslog.
false
, disabled
Listen specification <host>:<port>
for TLS server monitoring. Requires the tls
section to be present.
(inactive)
system_account
Name of the system account. Users of this account can subscribe to system events. See System Accounts for more details.
$SYS
pid_file
File containing PID, relative to ... This can serve as input to nats-server --signal
(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
Last updated