> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Configuration

> Configure NATS Server with files, environment variables, and command-line flags

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:

```conf nats-server.conf theme={null}
# 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:

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

### Specifying Configuration

```bash theme={null}
# 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

<CodeGroup>
  ```conf Simple Configuration theme={null}
  # 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
  ```

  ```conf Production Configuration theme={null}
  server_name: "nats-prod-01"

  port: 4222
  monitor_port: 8222

  # Connection limits
  max_connections: 100000
  max_control_line: 4096
  max_payload: 8388608  # 8MB
  max_pending: 67108864  # 64MB

  # Client timeouts
  ping_interval: "2m"
  ping_max: 2
  write_deadline: "10s"

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

  # Lame duck mode
  lame_duck_duration: "2m"

  # PID file
  pid_file: "/var/run/nats/nats-server.pid"
  ```
</CodeGroup>

## Cluster Configuration

Configure NATS for clustering:

```conf cluster.conf theme={null}
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

```conf theme={null}
# Single user
authorization {
  user: admin
  password: secret
  timeout: 1
}
```

### Multiple Users

```conf theme={null}
authorization {
  users = [
    {user: alice, password: foo}
    {user: bob,   password: bar}
  ]
}
```

### Token Authentication

```conf theme={null}
authorization {
  token: "my-secret-token"
}
```

### Permissions

```conf theme={null}
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

```conf theme={null}
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

```conf theme={null}
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

```conf dev.conf theme={null}
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

```conf prod.conf theme={null}
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

```conf ha.conf theme={null}
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:

```conf theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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

<Warning>
  Some settings like ports and JetStream configuration require a restart.
</Warning>

## Configuration vs Command-Line Flags

### Command-Line Flags

Common flags:

```bash theme={null}
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):

1. Command-line flags
2. Configuration file
3. Default values

Example:

```bash theme={null}
# 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:

<CodeGroup>
  ```conf Basic Server theme={null}
  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"
  ```

  ```conf Cluster Setup theme={null}
  port: 4242
  net: 127.0.0.1

  cluster {
    host: 127.0.0.1
    port: 4244
    name: "abc"
    
    authorization {
      user: route_user
      password: top_secret
      timeout: 1
    }
    
    routes = [
      nats-route://foo:bar@127.0.0.1:4245
      nats-route://foo:bar@127.0.0.1:4246
    ]
    
    connect_retries: 2
    connect_backoff: true
  }
  ```

  ```conf Docker Default theme={null}
  # Client port
  port: 4222

  # HTTP monitoring port
  monitor_port: 8222

  # Clustering
  cluster {
    port: 6222
    
    authorization {
      user: ruser
      password: T0pS3cr3t
      timeout: 2
    }
    
    routes = []
  }
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Configuration Files" icon="file-code">
    Prefer configuration files over command-line flags for maintainability and version control.
  </Card>

  <Card title="Validate Before Deploy" icon="check">
    Always test configuration with `-t` flag before deploying to production.
  </Card>

  <Card title="Environment Variables for Secrets" icon="key">
    Use environment variables for sensitive data like passwords and tokens.
  </Card>

  <Card title="Version Control" icon="code-branch">
    Keep configuration files in version control (exclude secrets).
  </Card>
</CardGroup>

## Troubleshooting

### Configuration Parse Errors

```bash theme={null}
# 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:

```bash theme={null}
nats-server -c nats-server.conf -D -V
```

This prints:

* Configuration values
* Startup sequence
* Connection attempts
* Protocol details

## Next Steps

<CardGroup cols={2}>
  <Card title="Docker Deployment" icon="docker" href="/deployment/docker">
    Deploy NATS with Docker containers
  </Card>

  <Card title="Kubernetes Deployment" icon="dharmachakra" href="./kubernetes">
    Deploy NATS on Kubernetes
  </Card>
</CardGroup>