Managing the Shared Group (OCFS2)

When several hosts read and write the same block device at once, they must coordinate so they never overwrite each other's data. Cockpit handles this with the clustered filesystem OCFS2 and its cluster stack, O2CB. The shared group is that O2CB cluster: it tracks which hosts are members, checks their heartbeats, and keeps them in sync.

You manage the shared group from the Shared Group tab on a datacenter. Its scope is the whole datacenter — every host across every cluster inside it participates.

Set the group up first

An OCFS2 datastore can only be created after a shared group exists on every host that will use it. Configure the shared group here before running the Add Datastore wizard for an OCFS2 pool.

Only use a clustered datastore while its group is healthy

A clustered (OCFS2) datastore is safe to use only while its shared group is active and synchronized on all participating hosts. Do not mount or write to a clustered datastore whose group is not fully online — doing so can corrupt the data for everyone.

---

Setting up a shared group

If the datacenter has no shared group yet, the tab shows "Shared Group Not Configured" with a Setup Shared Group button. The setup wizard has three steps:

1. Basics — the cluster name and the heartbeat mode (see below).
2. Node Plan — assign each host a node name and IP address. Nodes communicate on port 7777.
3. Review — verify the plan before it is applied.

On completion Cockpit applies the configuration across all hosts: it creates the O2CB cluster, sets the heartbeat mode, registers each node, and — in global mode — starts the heartbeat service. The operations are idempotent, so re-running setup on a partially-configured fleet safely fills in what's missing.

Heartbeat modes

Mode	How it works	When to use
Local (default)	Each mounted OCFS2 device carries its own heartbeat. Simpler, with nothing extra to manage.	Most deployments.
Global	Heartbeat runs against dedicated heartbeat region devices, independent of the data LUNs, as a service you start and stop.	Larger clusters, or when you want heartbeat decoupled from individual datastores.

The Start/Stop heartbeat controls and the Heartbeat Regions section only apply in global mode.

---

Managing an existing shared group

Once configured, the tab shows an overview — discovered hosts, the effective cluster name, and the heartbeat mode — and a set of management sections.

Cluster Operations

• Register all / Unregister all — register or unregister the O2CB cluster configuration on every host. Registering dynamically synchronizes member definitions from cluster.conf into the running kernel without unmounting or downtime.
• Start heartbeat / Stop heartbeat — start or stop the heartbeat service across all hosts. Available in global mode only.
• Refresh state — re-poll every host so the displayed status matches reality.

Heartbeat Regions (global mode)

Add a device path (for example /dev/mapper/mpathb) to register it as a heartbeat region on all hosts, or remove an existing region. Configured regions are listed in a table.

Per-Host Status

A table showing the operational status of every datacenter host:

• Cluster exists — whether the cluster configuration exists in /etc/ocfs2/cluster.conf on the host.
• Online status — whether the O2CB cluster stack is active in kernel memory. Displays an out of cluster badge if configured but offline, or a ⚠ out of sync warning if the running kernel memory differs from the configuration file.
• Members & Heartbeats — counts of active nodes and heartbeat regions on this host.
• Actions:
  • Sync to kernel — performs online dynamic registration (o2cb register-cluster) to synchronize newly added nodes into live kernel memory without unmounting filesystems. Highlighted as primary action when the host is out of sync.
  • Enter maintenance / Exit maintenance — cleanly transitions the host out of or back into the active cluster.

Members

The Members section allows you to manage the individual node definitions that participate in the shared group:

Adding a Member Node

To add a new host or node to an existing shared group:

1. In the Add Member Node form, select a host from the Datacenter host dropdown to automatically populate its default node name and detected IP address (or choose Custom / Manual to specify custom endpoints).
2. Verify the Node name, Node IP, and Port (default 7777).
3. Click Add member on all hosts. Cockpit automatically:
   • Ensures the cluster definition exists on any new host.
   • Appends the node configuration across all datacenter hosts.
   • Performs online registration to immediately load the new node into the running Linux kernel configfs memory across active nodes without interrupting active I/O.

Member Table & In-Sync Status

The table lists all member nodes and their live synchronization status:

• Node & IP — the configured node identifier and IP address.
• Seen on hosts — which datacenter hosts have this node configured in their cluster.conf.
• In-sync status:
  • ✓ In Kernel (green) — the node is fully loaded and active in running kernel memory on all online hosts.
  • ⚠ Not in Kernel (X hosts) (amber) — the node exists in configuration files but is missing from running kernel memory on the listed hosts. Use Sync to kernel on the affected hosts in Per-Host Status or click Register all in Cluster Operations to resolve.
  • Offline (gray) — reporting hosts for this node are currently offline or in maintenance.
• Actions — click Remove to delete a node definition across all datacenter hosts.

---

Maintenance mode

Before you do disruptive network work on a host (that could interrupt the storage/heartbeat network), take that host cleanly out of the shared group. Otherwise the surviving nodes may fence it — a hard reset — when it appears to lose connectivity.

Enter maintenance unmounts and unregisters the host from the group in the right order, so it leaves the heartbeat and network sets together and the survivors see a clean, smaller cluster instead of a failure. When the work is done, Exit maintenance rejoins it.

Cockpit runs a pre-flight check and shows an impact assessment before you proceed:

• If taking the host out would leave no members, the action is blocked — the shared filesystem would unmount everywhere, and any VM using it must be stopped or migrated first.
• If it would drop the group below a comfortable majority, you get a warning: leaving cleanly won't fence the others, but with reduced membership a later unplanned failure is more likely to disrupt the filesystem.
• A Force option is available for cases where the pre-flight cannot complete but you need to proceed anyway.

Remove members one host at a time

Taking several hosts out at once — or forcing a host out while others are already down — is how a cluster accidentally drops below quorum and hard-resets the survivor. Enter maintenance on one host, complete the work, and let it rejoin before touching the next.

---

Related topics

• Storage & Datastores overview — local vs shared, and why scope matters.
• Creating & Managing Datastores — the Add Datastore wizard, including OCFS2 pools.
• VM DRS & High Availability — features that depend on shared storage.