HA Cluster

Overview

Nefia's HA cluster provides an active-passive configuration based on the Raft consensus algorithm. The leader node handles VPN tunnels and state mutations, and standby nodes are automatically promoted if the leader fails.

Node 1 (Leader)     Node 2 (Follower)    Node 3 (Follower)
  │ VPN tunnel        │ standby             │ standby
  │ state mutations   │ Raft replication    │ Raft replication
  │                   │                     │
  └─ Raft TCP ───────┴─────────────────────┘

Replicated State

Only the leader node can Apply() state changes. Followers receive updates through the Raft log.

Setup

cluster:
  enabled: true
  node_id: "node-1"
  bind_addr: "0.0.0.0:9700"
  advertise_addr: "10.99.0.1:9700"

cluster:
  enabled: true
  node_id: "node-2"
  bind_addr: "0.0.0.0:9700"
  advertise_addr: "10.99.0.2:9700"
  peers:
    - id: "node-1"
      address: "10.99.0.1:9700"

nefia cluster init

nefia daemon

nefia cluster add-peer --id node-2 --addr 10.99.0.2:9700
nefia cluster add-peer --id node-3 --addr 10.99.0.3:9700

Management Commands

Check Status

nefia cluster status

Node ID:    node-1
State:      Leader
Is Leader:  true
Leader ID:  node-1

List Members

nefia cluster members

ID       ADDRESS           STATE      LOCAL
node-1   10.99.0.1:9700    Leader     *
node-2   10.99.0.2:9700    Follower
node-3   10.99.0.3:9700    Follower

Remove a Peer

nefia cluster remove-peer --id node-3

Configuration Reference

cluster:
  enabled: true
  node_id: "node-1"                    # Unique node ID
  bind_addr: "0.0.0.0:9700"            # Local TCP bind address
  advertise_addr: "10.99.0.1:9700"     # Address advertised to other nodes
  data_dir: ""                          # Data directory (defaults to <state-dir>/cluster if empty)
  peers:
    - id: "node-2"
      address: "10.99.0.2:9700"

Leadership Transitions

When the leader fails, a follower is automatically promoted to leader after the Raft election timeout (1 second).

Callbacks on leadership change:

• Promoted to leader: Start VPN tunnels, start Reactor listeners
• Demoted to follower: Stop VPN tunnels, sync state from other nodes

Raft Parameters

Data Storage

Admin API

Cluster management is performed via the daemon process's Unix socket. CLI commands communicate with the daemon through this API.

Supported actions:

• status — Get node status
• members — Get member list
• add_peer — Add a peer (leader only)
• remove_peer — Remove a peer (leader only)

mTLS Transport Security

Raft cluster transport supports optional mutual TLS (mTLS) for authenticating peer-to-peer communication. When enabled, all Raft traffic (log replication, heartbeats, snapshots) is encrypted and both peers must present valid certificates signed by a shared CA.

Configuration

cluster:
  enabled: true
  node_id: "node-1"
  bind_addr: "0.0.0.0:9700"
  advertise_addr: "10.99.0.1:9700"
  tls_enabled: true
  tls_cert_file: "/etc/nefia/cluster-cert.pem"
  tls_key_file: "/etc/nefia/cluster-key.pem"
  tls_ca_file: "/etc/nefia/cluster-ca.pem"

All three file paths (tls_cert_file, tls_key_file, tls_ca_file) are required when tls_enabled is true.

Security Properties

• TLS 1.3 minimum: Only TLS 1.3 is accepted, ensuring modern cipher suites and key exchange.
• Mutual authentication: Both sides of the connection must present a certificate (RequireAndVerifyClientCert). A node cannot join the cluster without a valid certificate signed by the shared CA.
• EKU validation: Peer certificates must include both serverAuth and clientAuth Extended Key Usage (EKU) values. Certificates with ExtKeyUsageAny are also accepted.
• Forward secrecy: TLS session tickets are disabled to ensure every connection performs a full handshake, preventing session resumption attacks.

MCP Tools

AI agents can manage the Raft cluster programmatically via MCP: