> ## 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.

# Cluster Options

> Configure NATS server clustering for high availability and horizontal scaling

## Overview

Cluster options enable multiple NATS servers to communicate and share message routing information, creating a distributed system with high availability and horizontal scalability.

## Command Line Flags

<ParamField path="--cluster" type="string">
  Cluster URL for solicited routes. Format: `nats://host:port`

  ```bash theme={null}
  nats-server --cluster nats://0.0.0.0:6222
  ```
</ParamField>

<ParamField path="--cluster_listen" type="string">
  Cluster URL from which members can solicit routes.

  ```bash theme={null}
  nats-server --cluster_listen nats://0.0.0.0:6222
  ```
</ParamField>

<ParamField path="--routes" type="string">
  Comma-separated list of routes to solicit and connect to.

  ```bash theme={null}
  nats-server --routes "nats://server1:6222,nats://server2:6222"
  ```
</ParamField>

<ParamField path="--cluster_name" type="string">
  Cluster name. If not set, one will be dynamically generated.

  ```bash theme={null}
  nats-server --cluster_name "production-cluster"
  ```
</ParamField>

<ParamField path="--cluster_advertise" type="string">
  Cluster URL to advertise to other servers. Useful when behind NAT.

  ```bash theme={null}
  nats-server --cluster_advertise "nats://public.example.com:6222"
  ```
</ParamField>

<ParamField path="--no_advertise" type="boolean">
  Do not advertise known cluster information to clients.

  ```bash theme={null}
  nats-server --no_advertise
  ```
</ParamField>

<ParamField path="--connect_retries" type="integer">
  Number of connect retries for implicit routes.

  ```bash theme={null}
  nats-server --connect_retries 5
  ```
</ParamField>

## Configuration File Options

### Basic Cluster Configuration

<ParamField path="cluster.name" type="string">
  Cluster name identifier.

  ```conf theme={null}
  cluster {
    name: "production-cluster"
  }
  ```
</ParamField>

<ParamField path="cluster.host" type="string" default="0.0.0.0">
  Host address to bind for cluster connections.

  ```conf theme={null}
  cluster {
    host: "0.0.0.0"
  }
  ```
</ParamField>

<ParamField path="cluster.port" type="integer" default="6222">
  Port for cluster connections. Default is 6222.

  ```conf theme={null}
  cluster {
    port: 6222
  }
  ```
</ParamField>

<ParamField path="cluster.listen" type="string">
  Combined host:port listen specification.

  ```conf theme={null}
  cluster {
    listen: "0.0.0.0:6222"
  }
  ```
</ParamField>

### Route Configuration

<ParamField path="cluster.routes" type="array">
  Array of route URLs to connect to other cluster members.

  ```conf theme={null}
  cluster {
    routes: [
      "nats://server1.example.com:6222",
      "nats://server2.example.com:6222",
      "nats://server3.example.com:6222"
    ]
  }
  ```
</ParamField>

<ParamField path="cluster.advertise" type="string">
  URL to advertise to other servers in the cluster.

  ```conf theme={null}
  cluster {
    advertise: "nats://public.example.com:6222"
  }
  ```
</ParamField>

<ParamField path="cluster.no_advertise" type="boolean" default="false">
  Prevent advertising cluster information to clients.

  ```conf theme={null}
  cluster {
    no_advertise: true
  }
  ```
</ParamField>

### Authentication

<ParamField path="cluster.username" type="string">
  Username for route authentication.

  ```conf theme={null}
  cluster {
    username: "route_user"
  }
  ```
</ParamField>

<ParamField path="cluster.password" type="string">
  Password for route authentication.

  ```conf theme={null}
  cluster {
    password: "route_password"
  }
  ```
</ParamField>

<ParamField path="cluster.authorization" type="object">
  Route permissions configuration.

  ```conf theme={null}
  cluster {
    authorization {
      user: "route_user"
      password: "route_password"
      timeout: 2
    }
  }
  ```
</ParamField>

### Advanced Options

<ParamField path="cluster.connect_retries" type="integer" default="0">
  Number of times to retry connecting to discovered routes.

  ```conf theme={null}
  cluster {
    connect_retries: 10
  }
  ```
</ParamField>

<ParamField path="cluster.pool_size" type="integer" default="-1">
  Number of pooled connections per route. -1 means automatic.

  ```conf theme={null}
  cluster {
    pool_size: 5
  }
  ```
</ParamField>

<ParamField path="cluster.compression" type="object">
  Compression configuration for cluster connections.

  ```conf theme={null}
  cluster {
    compression {
      mode: "s2_auto"
    }
  }
  ```

  Available modes: `s2_auto`, `s2_fast`, `s2_better`, `s2_best`, `disabled`
</ParamField>

<ParamField path="cluster.ping_interval" type="duration" default="30s">
  Interval for pinging route connections.

  ```conf theme={null}
  cluster {
    ping_interval: "30s"
  }
  ```
</ParamField>

<ParamField path="cluster.write_deadline" type="duration">
  Write deadline for route connections.

  ```conf theme={null}
  cluster {
    write_deadline: "5s"
  }
  ```
</ParamField>

## Configuration Examples

### Three-Node Cluster

**Server 1 Configuration:**

```conf theme={null}
port: 4222
server_name: "nats-1"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-2:6222",
    "nats://nats-3:6222"
  ]
}
```

**Server 2 Configuration:**

```conf theme={null}
port: 4222
server_name: "nats-2"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-1:6222",
    "nats://nats-3:6222"
  ]
}
```

**Server 3 Configuration:**

```conf theme={null}
port: 4222
server_name: "nats-3"

cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  routes: [
    "nats://nats-1:6222",
    "nats://nats-2:6222"
  ]
}
```

### Cluster with Authentication

```conf theme={null}
port: 4222
server_name: "nats-secure"

cluster {
  name: "secure-cluster"
  listen: "0.0.0.0:6222"
  
  authorization {
    user: "cluster_route"
    password: "$2a$11$3kIDaCxw.Glsl1.u5nKa6eUnNDLV5HV9tIuUp7EHhMt6Nm9myW1aS"
    timeout: 2
  }
  
  routes: [
    "nats://cluster_route:cluster_password@nats-2:6222",
    "nats://cluster_route:cluster_password@nats-3:6222"
  ]
}
```

### Cluster Behind NAT

```conf theme={null}
port: 4222
server_name: "nats-aws-1"

cluster {
  name: "cloud-cluster"
  listen: "0.0.0.0:6222"
  advertise: "nats://public-ip-1.example.com:6222"
  
  routes: [
    "nats://public-ip-2.example.com:6222",
    "nats://public-ip-3.example.com:6222"
  ]
}
```

### Cluster with Compression

```conf theme={null}
port: 4222
server_name: "nats-compressed"

cluster {
  name: "compressed-cluster"
  listen: "0.0.0.0:6222"
  
  compression {
    mode: "s2_auto"
  }
  
  routes: [
    "nats://nats-2:6222",
    "nats://nats-3:6222"
  ]
}
```

## Cluster Management

### Verifying Cluster Status

Check cluster status via monitoring endpoint:

```bash theme={null}
curl http://localhost:8222/routez
```

### Dynamic Cluster Growth

New servers can join by configuring routes to existing members:

```conf theme={null}
cluster {
  name: "production-cluster"
  listen: "0.0.0.0:6222"
  
  # Only need to route to one existing member
  routes: [
    "nats://nats-1:6222"
  ]
}
```

The new server will discover all other cluster members automatically.

## Best Practices

1. **Cluster Name**: Use consistent cluster names across all servers
2. **Full Mesh**: Configure routes to all other cluster members for fastest convergence
3. **Odd Numbers**: Use odd numbers of servers (3, 5, 7) for better consensus
4. **Authentication**: Always use authentication for route connections in production
5. **Network Isolation**: Keep cluster traffic on dedicated network interfaces when possible
6. **Compression**: Enable compression for geo-distributed clusters to reduce bandwidth
7. **Monitoring**: Monitor route connections through `/routez` endpoint
8. **DNS/Discovery**: Use DNS or service discovery for dynamic cluster membership

## Troubleshooting

### Connection Issues

* Verify firewall rules allow port 6222 (or custom cluster port)
* Check that routes are using correct URLs and authentication
* Review server logs for connection errors

### Split Brain Prevention

* Ensure consistent cluster names across all servers
* Configure routes to multiple cluster members
* Monitor cluster connectivity via `/routez`

## Related Configuration

<CardGroup cols={2}>
  <Card title="Server Options" icon="server" href="/configuration/server-options">
    Core server configuration
  </Card>

  <Card title="TLS Options" icon="lock" href="/configuration/tls-options">
    Secure cluster connections with TLS
  </Card>

  <Card title="JetStream Options" icon="database" href="/configuration/jetstream-options">
    Cluster JetStream for distributed persistence
  </Card>
</CardGroup>