How to set a GlusterFS geo-replication checkpoint

A GlusterFS geo-replication checkpoint provides a point-in-time marker that proves the secondary volume has received changes up to a specific moment. That marker is useful for planned cutovers, disaster-recovery drills, and audits where readiness needs a clear boundary.

Geo-replication runs as a session between a primary volume and a secondary volume, synchronizing changes asynchronously in the background. When a checkpoint is set, the session records a checkpoint time, and the detailed status output reports that time alongside whether replication has progressed far enough to satisfy the checkpoint.

An existing geo-replication session must already be configured and active, and checkpoint completion depends on the crawl continuing to make forward progress. On low-activity volumes, a checkpoint can remain incomplete until a new change is detected and replicated, so completion must be confirmed before any failover work proceeds.

1. Set a checkpoint for the geo-replication session from a primary node.

   $ sudo gluster volume geo-replication gvol-primary geoaccount@snode1.example.com::gvol-secondary config checkpoint now

   Replace the volume and secondary identifiers to match the configured session.
   No output indicates the checkpoint was recorded.

2. Create a small file on the primary mount to generate a new change entry when the workload is idle.

   $ sudo touch /mnt/volume1/.geo-rep-checkpoint

   Skip this step when the primary volume is already receiving continuous writes.

   Related: How to access GlusterFS volume from Linux

3. Verify the checkpoint has completed in the detailed session status output.

   $ sudo gluster volume geo-replication gvol-primary geoaccount@snode1.example.com::gvol-secondary status detail
   PRIMARY NODE    PRIMARY VOL    PRIMARY BRICK    SECONDARY USER    SECONDARY                         SECONDARY NODE    STATUS    CRAWL STATUS       LAST_SYNCED            CHECKPOINT TIME       CHECKPOINT COMPLETED  CHECKPOINT COMPLETION TIME
   mnode1          gvol-primary    /bricks/b1      geoaccount        snode1.example.com::gvol-secondary  snode1            Active    Changelog Crawl    2025-01-10 12:05:14    2025-01-10 12:00:00   Yes                  2025-01-10 12:05:14
   ##### snipped #####

   Proceed only when CHECKPOINT COMPLETED is Yes for every row and CHECKPOINT COMPLETION TIME is populated.