NATS.io NATS by Example Slack NATS Docs

Configuration File

You can use a configuration file to configure the options specific to the NATS Streaming Server.

Use the -sc or --stan_config command line parameter to specify the file to use.

For the embedded NATS Server, you can use another configuration file and pass it to the Streaming Server using -c or --config command line parameters.

Since most options do not overlap, it is possible to combine all options into a single file and specify this file using either the -sc or -c command line parameter.

However, the option named tls is common to NATS Server and NATS Streaming Server. If you plan to use a single configuration file and configure TLS, you should have all the streaming configuration included in a streaming map. This is actually a good practice regardless if you use TLS or not, to protect against possible addition of new options in NATS Server that would conflict with the names of NATS Streaming options.

For instance, you could use a single configuration file with such content:

# Some NATS Server TLS Configuration
listen: localhost:5222
tls: {
    cert_file: "/path/to/server/cert_file"
    key_file: "/path/to/server/key_file"
    verify: true
    timeout: 2
}

# NATS Streaming Configuration
streaming: {
    cluster_id: my_cluster

    tls: {
        client_cert: "/path/to/client/cert_file"
        client_key: "/path/to/client/key_file"
    }
}

However, if you want to avoid any possible conflict, simply use two different configuration files.

Note the order in which options are applied during the start of a NATS Streaming server:

  1. Start with some reasonable default options.

  2. If a configuration file is specified, override those options

    with all options defined in the file. This includes options that are defined

    but have no value specified. In this case, the zero value for the type of the

    option will be used.

  3. Any command line parameter override all of the previous set options.

In general the configuration parameters are the same as the command line arguments. Below is the list of NATS Streaming parameters:

Note: You may need to scroll horizontally to see all columns.

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

cluster_id

Cluster name

String, underscore possible

cluster_id: "my_cluster_name"

test-cluster

All

discover_prefix

Subject prefix for server discovery by clients

NATS Subject

discover_prefix: "_STAN.Discovery"

_STAN.discover

All

store

Store type

memory, file or sql

store: "file"

memory

All

dir

When using a file store, this is the root directory

File path

dir: "/path/to/storage

N/A

All

sd

Enable debug logging

true or false

sd: true

false

All

sv

Enable trace logging

true or false

sv: true

false

All

nats_server_url

If specified, connects to an external NATS Server, otherwise starts an embedded one

NATS URL

nats_server_url: "nats://localhost:4222"

N/A

All

secure

If true, creates a TLS connection to the server but without the need to use TLS configuration (no NATS Server certificate verification)

true or false

secure: true

false

All

tls

TLS Configuration

Map: tls: { ... }

See details below

All

store_limits

Store Limits

Map: store_limits: { ... }

See details below

All

file_options

File Store specific options

Map: file_options: { ... }

See details below

All

hb_interval

Interval at which the server sends an heartbeat to a client

Duration

hb_interval: "10s"

30s

v0.3.6

hb_timeout

How long the server waits for a heartbeat response from the client before considering it a failed heartbeat

Duration

hb_timeout: "10s"

10s

v0.3.6

hb_fail_count

Count of failed heartbeats before server closes the client connection. The actual total wait is: (fail count + 1) * (hb interval + hb timeout)

Number

hb_fail_count: 2

10

v0.3.6

ft_group

In Fault Tolerance mode, you can start a group of streaming servers with only one server being active while others are running in standby mode. This is the name of this FT group

String

ft_group: "my_ft_group"

N/A

v0.4.0

partitioning

If set to true, a list of channels must be defined in store_limits/channels section. This section then serves two purposes, overriding limits for a given channel or adding it to the partition

true or false

partitioning: true

false

v0.5.0

sql_options

SQL Store specific options

Map: sql_options: { ... }

See details below

v0.7.0

cluster

Cluster Configuration

Map: cluster: { ... }

See details below

v0.9.0

syslog_name

On Windows, when running several servers as a service, use this name for the event source

String

v0.11.0

encrypt

Specify if server should encrypt messages (only the payload) when storing them

true or false

encrypt: true

false

v0.12.0

encryption_cipher

Cipher to use for encryption. Currently support AES and CHAHA (ChaChaPoly). Defaults to AES

AES or CHACHA

encryption_cipher: "AES"

Depends on platform

v0.12.0

encryption_key

Encryption key. It is recommended to specify the key through the NATS_STREAMING_ENCRYPTION_KEY environment variable instead

String

encryption_key: "mykey"

N/A

v0.12.0

credentials

Credentials file to connect to external NATS 2.0+ Server

String

credentials: "streaming_server.creds"

N/A

v0.16.2

username

Username is used to connect to a NATS Server when authentication with multiple users is enabled

String

username: "streaming_server"

N/A

v0.19.0

password

Password used with above username

String

password: "password"

N/A

v0.19.0

token

Authentication token if the NATS Server requires a token

String

token: "some_token"

N/A

v0.19.0

nkey_seed_file

Path to an NKey seed file (1) if NKey authentication is used

File Path

nkey_seed_file: "/path/to/some/seedfile"

N/A

v0.19.0

replace_durable

Replace the existing durable subscription instead of reporting a duplicate durable error

true or false

replace_durable: true

false

v0.20.0

Notes:

(1) The seed file contains the NKey seed from which the Streaming server can extract the public key and the private key used to sign the nonce sent by the NATS Server when accepting connections from the Streaming server. The file is read during the connection process, the key is used to sign but then wiped from memory. The file must contain the seed file with the following format:

-----BEGIN USER NKEY SEED-----
SU<rest of the seed>
------END USER NKEY SEED------

TLS Configuration

Note that the Streaming Server uses a connection to a NATS Server, and so the NATS Streaming TLS Configuration is in fact a client-side TLS configuration.

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

client_cert

Client key for the streaming server

File path

client_cert: "/path/to/client/cert_file"

N/A

All

client_key

Client certificate for the streaming server

File path

client_key: "/path/to/client/key_file"

N/A

All

client_ca

Client certificate CA for the streaming server

File path

client_ca: "/path/to/client/ca_file"

N/A

All

server_name

Expected hostname returned in the NATS Server certificate

String

server_name: "theserverhostname"

N/A

v0.17.0

insecure

Skips the NATS server's certificate chain and host name verification. Should not be used in production

true or false

insecure: true

false

v0.17.0

Store Limits Configuration

{
    streaming: {
        cluster_id: my_cluster
        store_limits {
            max_msgs: 10000
        }
    }
}
ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

max_channels

Maximum number of channels, 0 means unlimited

Number >= 0

max_channels: 100

100

All

max_subs

Maximum number of subscriptions per channel, 0 means unlimited

Number >= 0

max_subs: 100

1000

All

max_msgs

Maximum number of messages per channel, 0 means unlimited

Number >= 0

max_msgs: 10000

1000000

All

max_bytes

Total size of messages per channel, 0 means unlimited

Number >= 0

max_bytes: 1GB

1GB

All

max_age

How long messages can stay in the log

Duration

max_age: "24h"

Unlimited

All

max_inactivity

How long without any subscription and any new message before a channel can be automatically deleted

Duration

max_inactivity: "24h"

Unlimited

v0.9.0

channels

A map of channel names with specific limits

Map: channels: { ... }

See details below

All

Channels

The channels section is a map with the key being the channel name. For instance:

{
    streaming: {
        cluster_id: my_cluster
        store_limits {
            channels: {
                "foo": {
                    max_msgs: 100
                }
            }
        }
    }
}

For a given channel, the possible parameters are:

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

max_subs

Maximum number of subscriptions per channel, 0 means unlimited

Number >= 0

max_subs: 100

Inherit from global settings

All

max_msgs

Maximum number of messages per channel, 0 means unlimited

Number >= 0

max_msgs: 10000

Inherit from global settings

All

max_bytes

Total size of messages per channel, 0 means unlimited

Bytes

max_bytes: 1GB

Inherit from global settings

All

max_age

How long messages can stay in the log

Duration

max_age: "24h"

Inherit from global settings

All

max_inactivity

How long without any subscription and any new message before a channel can be automatically deleted

Duration

max_inactivity: "24h"

Inherit from global settings

v0.9.0

File Options Configuration

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

compact

Enable/disable file compaction. Only some of the files (clients.dat and subs.dat) are subject to compaction

true or false

compact: true

true

All

compact_fragmentation

Compaction threshold (in percentage)

Number >= 0

compact_fragmentation: 50

50

All

compact_interval

Minimum interval between attempts to compact files

Expressed in seconds

compact_interval: 300

300

All

compact_min_size

Minimum size of a file before compaction can be attempted

Bytes

compact_min_size: 1GB

1MB

All

buffer_size

Size of buffers that can be used to buffer write operations

Bytes

buffer_size: 2MB

2MB

All

crc

Define if CRC of records should be computed on reads

true or false

crc: true

true

All

crc_poly

You can select the CRC polynomial. Note that changing the value after records have been persisted would result in server failing to start complaining about data corruption

Number >= 0

crc_poly: 3988292384

3988292384

All

sync_on_flush

Define if server should perform "file sync" operations during a flush

true or false

sync_on_flush: true

true

All

slice_max_msgs

Define the file slice maximum number of messages. If set to 0 and a channel count limit is set, then the server will set a slice count limit automatically

Number >= 0

slice_max_msgs: 10000

automatic

v0.3.4

slice_max_bytes

Define the file slice maximum size (including the size of index file). If set to 0 and a channel size limit is set, then the server will set a slice bytes limit automatically

Bytes

slice_max_bytes: 64MB

64MB

v0.3.4

slice_max_age

Define the period of time covered by a file slice, starting at when the first message is stored. If set to 0 and a channel age limit is set, then the server will set a slice age limit automatically

Duration

slice_max_age: "24h"

automatic

v0.3.4

slice_archive_script

Define the location and name of a script to be invoked when the server discards a file slice due to limits. The script is invoked with the name of the channel, the name of data and index files. It is the responsibility of the script to then remove the unused files

File path

slice_archive_script: "/home/nats-streaming/archive/script.sh"

N/A

v0.3.4

file_descriptors_limit

Channels translate to sub-directories under the file store's root directory. Each channel needs several files to maintain the state so the need for file descriptors increase with the number of channels. This option instructs the store to limit the concurrent use of file descriptors. Note that this is a soft limit and there may be cases when the store will use more than this number. A value of 0 means no limit. Setting a limit will probably have a performance impact

Number >= 0

file_descriptors_limit: 100

unlimited

v0.4.0

parallel_recovery

When the server starts, the recovery of channels (directories) is done sequentially. However, when using SSDs, it may be worth setting this value to something higher than 1 to perform channels recovery in parallel

Number >= 1

parallel_recovery: 4

1

v0.5.0

read_buffer_size

Size of buffers used to read ahead from message stores. This can significantly speed up sending messages to consumers after messages have been published. Default is 2MB. Set to 0 to disable

Bytes

read_buffer_size: 2MB

2MB

v0.16.0

auto_sync

Interval at which the store should be automatically flushed and sync'ed on disk. Default is every minute. Set to <=0 to disable

Duration

auto_sync: "2m"

1m

v0.16.0

Cluster Configuration

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

node_id

ID of the node within the cluster if there is no stored ID

String (no whitespace)

node_id: "node-a"

N/A

v0.9.0

bootstrap

Bootstrap the cluster if there is no existing state by electing self as leader

true or false

bootstrap: true

false

v0.9.0

peers

List of cluster peer node IDs to bootstrap cluster state

List of node IDs

peers: ["node-b", "node-c"]

N/A

v0.9.0

log_path

Directory to store log replication data

File path

log_path: "/path/to/storage"

N/A

v0.9.0

log_cache_size

Number of log entries to cache in memory to reduce disk IO

Number >= 0

log_cache_size: 1024

512

v0.9.0

log_snapshots

Number of log snapshots to retain

Number >= 0

log_snapshots: 1

2

v0.9.0

trailing_logs

Number of log entries to leave after a snapshot and compaction

Number >= 0

trailing_logs: 256

10240

v0.9.0

sync

Do a file sync after every write to the replication log and message store

true or false

sync: true

false

v0.9.0

raft_logging

Enable logging from the Raft library (disabled by default)

true or false

raft_logging: true

false

v0.9.0

raft_heartbeat_timeout

Specifies the time in follower state without a leader before attempting an election

Duration

raft_heartbeat_timeout: "2s"

2s

v0.11.2

raft_election_timeout

Specifies the time in candidate state without a leader before attempting an election

Duration

raft_election_timeout: "2s"

2s

v0.11.2

raft_lease_timeout

Specifies how long a leader waits without being able to contact a quorum of nodes before stepping down as leader

Duration

raft_lease_timeout: "1s"

1s

v0.11.2

raft_commit_timeout

Specifies the time without an Apply() operation before sending an heartbeat to ensure timely commit. Due to random staggering, may be delayed as much as 2x this value

Duration

raft_commit_timeout: "100ms"

100ms

v0.11.2

proceed_on_restore_failure

Allow a non leader node to proceed with restore failures, do not use unless you understand the risks!

true or false

proceed_on_restore_failure: true

false

v0.17.0

allow_add_remove_node

Enable the ability to send NATS requests to the leader to add/remove cluster nodes

true or false

allow_add_remove_node: true

false

v0.19.0

bolt_free_list_sync

Causes the RAFT log to synchronize the free list on write operations. Reduces performance at runtime, but makes the recovery faster

true or false

bolt_free_list_sync: true

false

v0.21.0

bolt_free_list_map

Sets the backend freelist type to use a map instead of the default array type. Improves performance for large RAFT logs, with fragmented free list

true or false

bolt_free_list_map: true

false

v0.21.0

nodes_connections

Enable creation of dedicated NATS connections to communicate with other nodes

true or false

nodes_connections: true

false

v0.21.0

SQL Options Configuration

ParameterMeaningPossible ValuesUsage ExampleDefault ValueSince

driver

Name of the SQL driver to use

mysql or postgres

driver: "mysql"

N/A

v0.7.0

source

How to connect to the database. This is driver specific

String

source: "ivan:pwd@/nss_db"

N/A

v0.7.0

no_caching

Enable/Disable caching for messages and subscriptions operations.

true or false

no_caching: false

false (caching enabled)

v0.7.0

max_open_conns

Maximum number of opened connections to the database. Value <= 0 means no limit.

Number

max_open_conns: 5

unlimited

v0.7.0

bulk_insert_limit

Maximum number of messages stored with a single SQL "INSERT" statement. The default behavior is to send individual insert commands as part of a SQL transaction.

Number

bulk_insert_limit: 1000

0 (not enabled)

v0.20.0

PreviousStore LimitsNextSecuring