Server Options

Core NATS server configuration options for connections, limits, and network settings

Overview

Core server options control fundamental NATS server behavior including network binding, connection limits, payload sizes, and timeouts.

Command Line Flags

Network Configuration

-a, --addr, --net · string · default: "0.0.0.0"

Bind to host address. Specifies the network interface the server will listen on.

nats-server -a 127.0.0.1

-p, --port · integer · default: "4222"

Port for client connections. The default NATS protocol port is 4222.

nats-server -p 4222

-n, --name, --server_name · string · default: "auto"

Server name for identification in cluster. If not specified, a unique name is automatically generated.

nats-server --server_name "nats-prod-01"

--client_advertise · string

Client URL to advertise to other servers. Useful when running behind NAT or load balancers.

nats-server --client_advertise "nats://public.example.com:4222"

Connection Limits

max_connections · integer

Maximum number of concurrent client connections.

Config file:

max_connections: 1000

max_subscriptions · integer

Maximum number of subscriptions per connection.

Config file:

max_subscriptions: 0  # unlimited

Payload and Performance

max_payload · integer · default: "1048576"

Maximum message payload size in bytes. Default is 1MB.

Config file:

max_payload: 1048576  # 1 MB

max_pending · integer · default: "67108864"

Maximum number of bytes buffered for a connection. Default is 64MB.

Config file:

max_pending: 67108864  # 64 MB

write_deadline · duration

Maximum time to wait when writing to a client connection.

Config file:

write_deadline: "2s"

Monitoring

-m, --http_port · integer

HTTP port for monitoring endpoints.

nats-server -m 8222

-ms, --https_port · integer

HTTPS port for monitoring with TLS.

nats-server -ms 8222

Other Options

-P, --pid · string

File path to store process ID.

nats-server -P /var/run/nats.pid

-c, --config · string

Path to configuration file.

nats-server -c /etc/nats/nats-server.conf

-t · boolean

Test configuration file and exit without starting server.

nats-server -c nats.conf -t

--ports_file_dir · string

Directory where a ports file will be created containing the server’s listening ports. File format: <executable_name>_<pid>.ports.

nats-server --ports_file_dir /var/run/nats

Configuration File Example

# Basic Server Configuration
host: "0.0.0.0"
port: 4222
server_name: "nats-prod-01"

# Connection Limits
max_connections: 1000
max_payload: 1048576     # 1 MB
max_pending: 67108864    # 64 MB
max_subscriptions: 0     # unlimited

# Timeouts
write_deadline: "2s"
ping_interval: "2m"
ping_max: 2

# Monitoring
http_port: 8222

# Logging
log_file: "/var/log/nats-server.log"
logtime: true

Complete Server Example

Here’s a production-ready configuration combining multiple server options:

# Production NATS Server Configuration

# Network
host: "0.0.0.0"
port: 4222
server_name: "nats-prod-01"
client_advertise: "nats://public.example.com:4222"

# Limits
max_connections: 5000
max_payload: 2097152        # 2 MB
max_pending: 134217728      # 128 MB
max_control_line: 4096

# Timeouts
write_deadline: "5s"
ping_interval: "30s"
ping_max: 3

# Monitoring
http_port: 8222

# Logging
log_file: "/var/log/nats/nats-server.log"
log_size_limit: 104857600   # 100 MB
logtime: true
debug: false
trace: false

# PID file
pid_file: "/var/run/nats/nats-server.pid"

Runtime Configuration

Testing Configuration

Validate your configuration before starting the server:

nats-server -c nats-server.conf -t

Starting with Options

Combine command line flags with a configuration file:

nats-server -c nats-server.conf -p 4223 -D -V

Command line flags override configuration file values.

Best Practices

1. Connection Limits: Set max_connections based on expected load and system resources
2. Payload Size: Increase max_payload if your application sends large messages
3. Write Deadline: Tune write_deadline based on network latency and client behavior
4. Monitoring: Always enable monitoring with http_port for production deployments
5. Server Name: Use descriptive server names in clusters for easier troubleshooting
6. Client Advertise: Configure when behind NAT or load balancers

Related Configuration

Cluster Options

Configure server clustering and routes

JetStream Options

Enable and configure JetStream persistence

TLS Options

Secure connections with TLS