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