Clustering

../../../_images/aeo-cluster.png

Atomic OSSEC supports manager high availability with a read/write master and one or more read-oriented worker nodes. Clustering is implemented by the Go ac_cluster stack (ac-cluster, ac-relayd, and ossec-ac-clusterd), configured from the Hub UI.

The master is the source of truth for agent keys, shared agent configuration, and cluster-wide settings. Workers synchronize from the master over TLS. Agents should register to the master (TCP 1515). Agents may send events to a master or worker (TCP/UDP 1514). Workers forward alerts to the master through ac-relayd (not rsyslog).

Architecture

  • Master: runs ac-cluster listening on TCP 31000 (cluster control) and 31100 (ac-interface). Holds /var/ossec/ac-cluster/etc/.comms.key.

  • Worker: runs ac-cluster, ac-relayd, and ossec-ac-clusterd. Connects to the master’s IP on TCP 31000 and obtains the shared communications key during handshake.

  • Configuration is written to /var/ossec/etc/ossec.conf as an <ac_cluster> stanza. Do not use a legacy <cluster> stanza; that blocks the Go cluster daemon.

What synchronizes

  • Agent authentication keys (client.keys)

  • Integrity-listed rules and decoders

  • Shared agent configurations under /var/ossec/etc/shared/

  • Agent group assignments

  • Alerts generated on workers (relayed to the master)

Configuring a Cluster (Master)

Step 1: On the master Hub UI, open Hub Configuration → Hub Configuration → Clustering.

Step 2: Set:

  • Enable Clustering (OSSEC_CLUSTER): on (yes / enabled also accepted)

  • Cluster Mode (CLUSTER_MODE): master

  • Cluster master ip (CLUSTER_MASTER_IP): leave empty on the master

Step 3: Save changes and allow the Hub to apply OSSEC configuration.

Step 4: Verify on the master host:

  • systemctl is-active ac-cluster reports active

  • ss -lntp | grep 31000 shows ac-cluster listening

  • /var/ossec/etc/ossec.conf contains <ac_cluster> with <node_type>master</node_type>

  • /var/ossec/ac-cluster/etc/.comms.key exists

Configuring a Cluster (Worker)

Step 1: On the worker Hub UI, open Hub Configuration → Hub Configuration → Clustering.

Step 2: Set:

  • Enable Clustering (OSSEC_CLUSTER): on

  • Cluster Mode (CLUSTER_MODE): worker

  • Cluster master ip (CLUSTER_MASTER_IP): the reachable IP address of the master Hub (for example 192.168.100.222). Do not use localhost, 0.0.0.0, or a placeholder hostname such as master.

Step 3: Save changes and allow the Hub to apply OSSEC configuration.

Step 4: Verify on the worker host:

  • systemctl is-active ac-cluster ac-relayd ossec-ac-clusterd reports active

  • /var/ossec/etc/ossec.conf contains <ac_cluster> with node_type worker, master_ip set to the master IP, and client_dst_port 31000

  • /var/ossec/ac-cluster/etc/.comms.key matches the master (same file contents)

  • /var/ossec/ac-cluster/logs/ac-cluster.log shows a successful connection to the master

Network requirements

Between workers and the master, allow:

  • TCP 31000 — cluster control / sync (required)

  • TCP 31100 — ac-interface (optional; used for cluster interface tooling)

Agent connectivity is unchanged: TCP 1515 (registration, typically master) and TCP/UDP 1514 (agent events). The legacy rsyslog cluster port TCP 6514 is not used.

Disabling clustering

Set Enable Clustering to off, save changes, and confirm <ac_cluster> is removed from ossec.conf and that ac-cluster / ac-relayd are stopped (or masked).

Notes

  • /var/ossec/queue/sockets/queue is a unix domain socket used by analysisd. A directory at /var/ossec/queue/queue is not part of normal clustering.

  • Empty /var/ossec/queue/cluster/ may exist from package install layout and is unused by ac_cluster.