Server Configuration - NATS Server

NATS Server can be configured using configuration files, command-line flags, or a combination of both. Configuration files use a simple, JSON-like format that’s easy to read and maintain.

Configuration File Format

NATS Server configuration files use a simple syntax similar to JSON:

nats-server.conf

# Comments start with hash
port: 4222
monitor_port: 8222

server_name: my-nats-server

# Nested configuration blocks
cluster {
  port: 6222
  name: "my-cluster"
}

Key features:

Comments start with #
Key-value pairs: key: value
Nested blocks use curly braces: { }
Arrays use square brackets: [ ]
Strings can be quoted or unquoted (quotes required for special characters)
Numbers and booleans are unquoted

Configuration File Location

Default Locations

NATS Server looks for configuration files in:

Path specified with -c or --config flag
Current directory: ./nats-server.conf
User config: ~/.nats/nats-server.conf
System config: /etc/nats/nats-server.conf

Specifying Configuration

# Using command-line flag
nats-server -c /path/to/nats-server.conf

# Or with long form
nats-server --config /path/to/nats-server.conf

Basic Configuration

# Server name for identification
server_name: "my-nats-server"

# Client connection port
port: 4222

# Bind to specific interface (default: 0.0.0.0)
net: "0.0.0.0"

# HTTP monitoring port
monitor_port: 8222

# Enable debug logging
debug: false

# Enable trace logging
trace: false

# Log to file
log_file: "/var/log/nats-server.log"

# Maximum number of client connections
max_connections: 64000

# Maximum number of subscriptions per connection
max_subscriptions: 0  # unlimited

# Maximum payload size (in bytes)
max_payload: 1048576  # 1MB

Cluster Configuration

Configure NATS for clustering:

cluster.conf

port: 4222
monitor_port: 8222

cluster {
  # Cluster name (must match on all nodes)
  name: "my-nats-cluster"
  
  # Address to bind cluster connections
  host: "0.0.0.0"
  
  # Port for cluster connections
  port: 6222
  
  # Authentication for routes
  authorization {
    user: route_user
    password: T0pS3cr3t
    timeout: 2
  }
  
  # Routes to other cluster members
  routes: [
    nats-route://route_user:T0pS3cr3t@node1:6222
    nats-route://route_user:T0pS3cr3t@node2:6222
    nats-route://route_user:T0pS3cr3t@node3:6222
  ]
  
  # Connection retry settings
  connect_retries: 120
  connect_backoff: true
}

Authentication Configuration

Basic Authentication

# Single user
authorization {
  user: admin
  password: secret
  timeout: 1
}

Multiple Users

authorization {
  users = [
    {user: alice, password: foo}
    {user: bob,   password: bar}
  ]
}

Token Authentication

authorization {
  token: "my-secret-token"
}

Permissions

authorization {
  # Role definitions
  super_user = {
    publish = ">"
    subscribe = ">"
  }
  
  request_user = {
    publish = ["req.foo", "req.bar"]
    subscribe = "_INBOX.>"
  }
  
  # Users with roles
  users = [
    {user: admin, password: secret, permissions: $super_user}
    {user: client, password: pass, permissions: $request_user}
  ]
}

TLS Configuration

tls {
  # Server certificate and key
  cert_file: "/etc/nats/certs/server.pem"
  key_file: "/etc/nats/certs/key.pem"
  
  # CA certificate for client verification
  ca_file: "/etc/nats/certs/ca.pem"
  
  # Require client certificates
  verify: true
  
  # Cipher suites (optional)
  cipher_suites: [
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
  ]
  
  # Curve preferences (optional)
  curve_preferences: [
    "CurveP256"
    "CurveP384"
    "CurveP521"
  ]
  
  # TLS timeout
  timeout: 2
}

JetStream Configuration

jetstream {
  # Enable JetStream
  enabled: true
  
  # Storage directory
  store_dir: "/var/lib/nats/jetstream"
  
  # Maximum memory storage
  max_memory_store: 1GB
  
  # Maximum file storage
  max_file_store: 100GB
  
  # Domain (for multi-tenancy)
  domain: "hub"
  
  # Unique tag for this server
  unique_tag: "nats-01"
}

Common Configuration Patterns

Development Environment

dev.conf

server_name: "nats-dev"

port: 4222
monitor_port: 8222

# Enable detailed logging
debug: true
trace: true
logtime: true

# No authentication
authorization: false

# JetStream for testing
jetstream {
  store_dir: "./data"
  max_memory_store: 256MB
  max_file_store: 1GB
}

Production Environment

prod.conf

server_name: "nats-prod-01"

port: 4222
monitor_port: 8222

# Production limits
max_connections: 100000
max_payload: 8388608

# Minimal logging
debug: false
trace: false
log_file: "/var/log/nats/nats-server.log"
logtime: true

# TLS required
tls {
  cert_file: "/etc/nats/certs/server.pem"
  key_file: "/etc/nats/certs/key.pem"
  ca_file: "/etc/nats/certs/ca.pem"
  verify: true
}

# Authentication
authorization {
  users = [
    {user: app1, password: $APP1_PASSWORD}
    {user: app2, password: $APP2_PASSWORD}
  ]
}

# Clustering
cluster {
  name: "prod-cluster"
  port: 6222
  
  routes: [
    nats-route://nats-prod-01:6222
    nats-route://nats-prod-02:6222
    nats-route://nats-prod-03:6222
  ]
}

# JetStream
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 8GB
  max_file_store: 1TB
}

High Availability Setup

ha.conf

server_name: "nats-ha-01"

port: 4222
monitor_port: 8222

# Aggressive health checking
ping_interval: "30s"
ping_max: 3
write_deadline: "5s"

# Lame duck mode for graceful shutdown
lame_duck_duration: "2m"

# Cluster configuration
cluster {
  name: "ha-cluster"
  port: 6222
  
  routes: [
    nats-route://nats-ha-01:6222
    nats-route://nats-ha-02:6222
    nats-route://nats-ha-03:6222
  ]
  
  connect_retries: 120
  connect_backoff: true
}

# JetStream with replication
jetstream {
  store_dir: "/var/lib/nats/jetstream"
  max_memory_store: 16GB
  max_file_store: 2TB
}

Environment Variables

Use environment variables in configuration:

port: $NATS_PORT
monitor_port: $NATS_MONITOR_PORT

authorization {
  users = [
    {user: $ADMIN_USER, password: $ADMIN_PASSWORD}
  ]
}

jetstream {
  store_dir: $JETSTREAM_DIR
}

Set environment variables before starting:

export NATS_PORT=4222
export NATS_MONITOR_PORT=8222
export ADMIN_USER=admin
export ADMIN_PASSWORD=secret
export JETSTREAM_DIR=/data/jetstream

nats-server -c nats-server.conf

Configuration Validation

Validate configuration without starting the server:

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

The -t flag performs a dry-run check:

Parses the configuration file
Validates all settings
Reports any errors
Exits without starting the server

Example output:

[1] 2026/03/04 10:00:00.000000 [INF] Starting nats-server
[1] 2026/03/04 10:00:00.000000 [INF]   Version:  2.10.0
[1] 2026/03/04 10:00:00.000000 [INF] Configuration file: nats-server.conf
[1] 2026/03/04 10:00:00.000000 [INF] Configuration is valid.

Configuration Reload

Reload configuration without restarting:

# Send SIGHUP to reload
kill -HUP $(pidof nats-server)

# Or use systemd
sudo systemctl reload nats-server

Reloadable settings:

Logging levels (debug, trace)
Log file rotation
Authentication changes
TLS certificates
Cluster routes

Some settings like ports and JetStream configuration require a restart.

Configuration vs Command-Line Flags

Command-Line Flags

Common flags:

nats-server \
  --port 4222 \
  --http_port 8222 \
  --cluster nats://0.0.0.0:6222 \
  --routes nats://other-server:6222 \
  --log /var/log/nats.log \
  --pid /var/run/nats.pid \
  -D  # Debug mode
  -V  # Trace mode
  -js # Enable JetStream
  --sd /data  # JetStream store directory

Precedence

Configuration precedence (highest to lowest):

Command-line flags
Configuration file
Default values

Example:

# Config file has port: 4222
# This will use port 4223 instead
nats-server -c nats-server.conf --port 4223

Configuration Files from Source

The NATS Server repository includes example configurations:

server_name: testing_server

listen: 127.0.0.1:4242
http: 8222

authorization {
  user:     derek
  password: porkchop
  timeout:  1
}

debug:   false
trace:   true
logtime: false

pid_file: "/tmp/nats-server/nats-server.pid"

max_connections: 100
max_subscriptions: 1000
max_payload: 65536

ping_interval: "60s"
ping_max: 3
write_deadline: "3s"

Best Practices

Use Configuration Files

Prefer configuration files over command-line flags for maintainability and version control.

Validate Before Deploy

Always test configuration with -t flag before deploying to production.

Environment Variables for Secrets

Use environment variables for sensitive data like passwords and tokens.

Version Control

Keep configuration files in version control (exclude secrets).

Troubleshooting

Configuration Parse Errors

# Use -t to identify syntax errors
nats-server -c nats-server.conf -t

Common Issues

Syntax Error:

Error: parsing configuration file: invalid character '}' looking for beginning of value

Solution: Check for missing commas, quotes, or braces. Port Already in Use:

Error: listen tcp :4222: bind: address already in use

Solution: Change port or stop conflicting service. Permission Denied:

Error: open /var/log/nats/nats-server.log: permission denied

Solution: Check file permissions and directory ownership.

Debug Configuration

Enable debug output:

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

This prints:

Configuration values
Startup sequence
Connection attempts
Protocol details

Next Steps

Docker Deployment

Deploy NATS with Docker containers

Kubernetes Deployment

Deploy NATS on Kubernetes

Get Started

Deployment

Architecture

Features

Operations

Configuration

​Configuration File Format

​Configuration File Location

​Default Locations

​Specifying Configuration

​Basic Configuration

​Cluster Configuration

​Authentication Configuration

​Basic Authentication

​Multiple Users

​Token Authentication

​Permissions

​TLS Configuration

​JetStream Configuration

​Common Configuration Patterns

​Development Environment

​Production Environment

​High Availability Setup

​Environment Variables

​Configuration Validation

​Configuration Reload

​Configuration vs Command-Line Flags

​Command-Line Flags

​Precedence

​Configuration Files from Source

​Best Practices

Use Configuration Files

Validate Before Deploy

Environment Variables for Secrets

Version Control

​Troubleshooting

​Configuration Parse Errors

​Common Issues

​Debug Configuration

​Next Steps

Docker Deployment

Kubernetes Deployment

Build docs developers (and LLMs) love

Configuration File Format

Configuration File Location

Default Locations

Specifying Configuration

Basic Configuration

Cluster Configuration

Authentication Configuration

Basic Authentication

Multiple Users

Token Authentication

Permissions

TLS Configuration

JetStream Configuration

Common Configuration Patterns

Development Environment

Production Environment

High Availability Setup

Environment Variables

Configuration Validation

Configuration Reload

Configuration vs Command-Line Flags

Command-Line Flags

Precedence

Configuration Files from Source

Best Practices

Troubleshooting

Configuration Parse Errors

Common Issues

Debug Configuration

Next Steps