NAME

ocifbsd-cluster — run an ocifbsd cluster node (gossip membership and Raft consensus)

SYNOPSIS

DESCRIPTION

ocifbsd-cluster runs a single node of an ocifbsd cluster. Nodes discover one another through a UDP gossip protocol with SWIM-style failure detection, and agree on a replicated log through the Raft consensus algorithm: leader election, log replication with commit on a quorum, crash-durable persistence, dynamic membership, and log compaction with snapshots.

The options are as follows:

-p, --port port

UDP port for gossip and consensus traffic. The default is 6789. All nodes in a cluster must use the same port.

-P, --peer host@ip

A seed peer, given as its node name and reachable IP address (for example db1@192.0.2.11). Repeat for each seed peer. A newly started node announces itself to its seed peers, so a running cluster learns of it automatically.

-s, --state statefile

Path to the Raft state file. When set, the current term, the vote, and the log are persisted here so the node recovers its state across a restart; when unset, state is kept only in memory.

-n, --name name

Override this node's identifier. The default is the host's name.

-i, --interval interval

Print a status line every interval seconds. The default is 0, which prints only when the role, term, or leader changes.

The run operand starts the node and runs until it receives SIGINT or SIGTERM. Sending SIGINFO (Ctrl-T) prints the node's current status on demand.

EXAMPLES

Start a three-node cluster, one command per host, all on the default port with persistent state:

# on n1 (192.0.2.10)
ocifbsd-cluster -s /var/db/ocifbsd/raft \
    -P n2@192.0.2.11 -P n3@192.0.2.12 run

# on n2 (192.0.2.11)
ocifbsd-cluster -s /var/db/ocifbsd/raft \
    -P n1@192.0.2.10 -P n3@192.0.2.12 run

# on n3 (192.0.2.12)
ocifbsd-cluster -s /var/db/ocifbsd/raft \
    -P n1@192.0.2.10 -P n2@192.0.2.11 run

SEE ALSO

ocifbsd(8)

AUTHORS

This software was developed by REVYTECH, Inc.

SECURITY CONSIDERATIONS

Cluster traffic is carried over UDP on the configured port; restrict that port to the trusted cluster network with the host firewall. Raft state files contain the replicated log and should be readable only by the account that runs the node.