Skip to main content

​
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

Cluster Options

Configure server clustering and routes

JetStream Options

Enable and configure JetStream persistence

TLS Options

Secure connections with TLS

Build docs developers (and LLMs) love

Get started for freeTalk to us