配置 NATS服务

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.

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.

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!
    token: 3secret
}

Fixed Config:

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

Variables

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

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 Properties

Connectivity

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.
tls	Configuration map for tls for client and http monitoring.
gateway	Configuration map for gateway.
leafnode	Configuration map for a leafnode.
mqtt	Configuration map for mqtt.
websocket	Configuration map for websocket.

Clustering

Property	Description	Default
cluster	Configuration map for cluster.

Connection Timeouts

Property	Description	Default
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

Property	Description	Default
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 or smaller to 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).

Property	Description	Default	Version
store_dir	Directory to use for JetStream storage.	/tmp/nats/jetstream	2.2+
max_memory_store	Maximum size of the 'memory' storage	75% of available memory	2.2+
max_file_store	Maximum size of the 'file' storage	Up to 1TB if available	2.2+
max_outstanding_catchup	Max in-flight bytes for stream catch-up	32MB	2.9+

Here's an example minimal file that will store data in a local "nats" directory with some limits.

$ nats-server -c js.conf

# js.conf
jetstream {
   store_dir=nats

   // 1GB
   max_memory_store: 1073741824

   // 10GB
   max_file_store: 10737418240
}

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 nats-server should use its own individual storage directory.

Authentication and Authorization

Centralized Authentication and Authorization

Property	Description
authorization	Configuration map for client authentication/authorization.
accounts	Configuration map for multi tenancy via accounts.
no_auth_user	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.

Decentralized Authentication and Authorization

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

Runtime Configuration

Monitoring and Tracing

Configuration Reloading

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