Storage and Shared Group Management

Cockpit provides interfaces to configure hypervisor datastores (storage pools) and coordinate multi-host shared storage clustering.

---

1. Datastores (Storage Pools)

Datastores store virtual disk images (.qcow2, .raw) and ISO files. Cockpit classifies storage pools by scope:

Storage Pool Scopes

• Local Scope: Storage pools bound to a single hypervisor host (e.g., directory-based pools mapped to /var/lib/libvirt/images/). Local datastores are suitable for independent host workloads or shared-nothing (block) live migrations.
• Shared Scope: Storage pools accessible concurrently by multiple hypervisor hosts. Examples include Network File System (NFS), iSCSI LUNs, Fibre Channel (FC), or clustered file systems such as OCFS2. Shared datastores enable rapid, shared-storage live VM migrations.
  • OCFS2 Clustered Datastore Lifecycle: To initialize a clustered OCFS2 datastore, the shared block device (e.g., /dev/sda) must be unmounted on all participating hosts and wiped of all previous signatures using wipefs -a. Cockpit automates OCFS2 creation by formatting the device, registering block device paths (host_devices), configuring node IP mappings (host_node_ips), selecting the heartbeat mode, and reserving cluster slots (e.g., 4).

Datastore Operations

• Capacity Monitoring: Retrieves metrics on total capacity, allocated storage, and available bytes.
• Refresh: Scans the storage pool directory to synchronize Cockpit's database with the actual files present on the host filesystem.
• Start / Stop: Controls the runtime status of the storage pool on the host. Stopping a pool disables VM disk attachments mapped to that pool.
• Delete: Removes the storage pool registration. Administrators can optionally set the delete_volumes flag (DELETE /api/v1/datastores/:id?delete_volumes=true) to erase all virtual disk files contained within the pool.

---

2. Software iSCSI Adapter Configuration (Multipathing)

For environments utilizing shared block storage over IP networks, Cockpit provides host-level proxy APIs to initialize and configure Software iSCSI adapters, set up network multipathing, discover target portals, and log into target iSCSI Qualified Names (IQNs).

Configuration Workflow

1. Adapter Initialization: Creates a software iSCSI adapter on the host (e.g., iscsi-smoke-01) with a custom Initiator IQN (e.g., iqn.2026-04.awid5.mid-7d6a2e8c:iscsi-smoke-01) and sets the startup mode (e.g., manual or automatic).
2. Network Interface Binding: Binds physical or virtual network interfaces (e.g., enp2s0 and enp3s0) to the adapter. Binding multiple interfaces enables session multipathing, providing redundancy and load balancing over the storage network.
3. Portal Discovery: Triggers SendTargets discovery against the primary storage portal IP (e.g., 192.168.242.235:3260), specifying binding portals for each network interface to establish multiple paths to the target storage server.
4. Target Session Login: Establishes active connections to the target IQN (e.g., iqn.2026-05.io.awan:storage-server). If CHAP authentication is configured, username and password credentials are supplied.
5. Session Monitoring: Verifies that the OS successfully registers all sessions and routes the target disks under multipath device mappings (e.g., /dev/sda).

Teardown & Removal

When decommissioning or modifying storage routes:

• Session Logout: Logs out of individual active session IDs.
• Forget Targets: Commands the iSCSI daemon to forget discovered portals.
• Adapter Deletion: Deletes the software iSCSI adapter config from the host.

---

3. Shared Group Management (O2CB Cluster Proxy)

To mount and use clustered filesystems (like OCFS2) concurrently on multiple hypervisor hosts, administrators must configure and maintain an O2CB (Oracle Cluster File System 2 Social Club) cluster group. In Cockpit, this coordination layer is managed via Shared Group Management.

IMPORTANT

Relationship Between Shared Datastores and Shared Groups: A shared block storage device (SAN/iSCSI) running OCFS2 allows concurrent read/write operations. However, to prevent data corruption, hosts must coordinate their lock management and heartbeats. The O2CB Shared Group manages node membership, communication ports, and heartbeats across all participating hypervisors. Attempting to mount and write to an OCFS2 datastore without an active, synchronized Shared Group on all participating hosts will result in immediate filesystem corruption.

Shared Group Configuration Parameters

• Cluster Name: An alphanumeric identifier for the O2CB cluster (e.g., ocfs2). This name must match exactly across all hosts in the datacenter.
• Node Name: The identifier for each participating host within the O2CB cluster (typically matching the host's hostname).
• Node IP & Port: The dedicated IP address and TCP port (default: 7777) used by the O2CB daemon for inter-node communication and locking protocol traffic.
• Heartbeat Mode:
  • Local: Heartbeats are written to specific disk regions on the shared storage device itself.
  • Global: Uses a dedicated cluster heartbeat service.
• Heartbeat Device Path: The block device path (e.g., /dev/mapper/mpathb) where local heartbeat signatures are written.

Operational Workflow and Actions

Cockpit automates O2CB configuration across all hosts in the datacenter:

1. Setup Shared Group (Wizard): Initiates O2CB configuration on all datacenter hosts. The wizard registers the cluster name, adds node mappings (name, IP, port) for all participating hosts, and establishes the heartbeat mode.
2. Registration Lifecycle:
   • Register all: Commands all hosts to register the O2CB cluster config into kernel space.
   • Unregister all: Safely unregisters the O2CB cluster configuration from all hosts.
3. Heartbeat Runtime Control:
   • Start heartbeat: Starts the O2CB heartbeat service across all hosts (required in global mode or before mounting storage).
   • Stop heartbeat: Stops the heartbeat service.
4. Member Management: Adds or removes member nodes from the O2CB cluster definition. Changing node membership propagates configuration updates to the configuration files of all member hosts.
5. Per-Host Status Monitoring: Monitors the O2CB kernel state on each host, displaying:
   • Cluster existence (whether the O2CB cluster is defined).
   • Online status (whether the cluster stack is active/online).
   • Active member count.
   • Configured heartbeat regions.
   • Host-level O2CB daemon logs and errors.