How to set a GlusterFS geo-replication checkpoint

Set a GlusterFS geo-replication checkpoint before a cutover, disaster-recovery drill, or recovery audit when the secondary volume must be proven current to a known point in time. The checkpoint gives operators a concrete synchronization boundary instead of relying only on an Active worker state or a recent LAST_SYNCED timestamp.

Geo-replication checkpoints are stored on an existing primary-to-secondary session. The config checkpoint now command records the checkpoint time, and status detail later shows whether each primary brick worker has synchronized every change that existed before that time.

Run the checkpoint from a primary trusted-pool node after the session is started and the secondary target is reachable. An idle volume may need a harmless metadata update on the primary mount before the checkpoint changes from No to Yes, and any Faulty row or nonzero failure count needs log review before failover planning continues.

1. Check the geo-replication session before setting the checkpoint.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary status detail
   PRIMARY NODE  PRIMARY BRICK  STATUS   CRAWL STATUS     LAST_SYNCED          ENTRY  DATA  META  FAILURES  CHECKPOINT COMPLETED
   pnode1        /bricks/b1     Active   Changelog Crawl  2026-06-16 10:12:44  0      0     0     0         N/A
   pnode2        /bricks/b2     Passive  Changelog Crawl  2026-06-16 10:12:41  0      0     0     0         N/A

   Use a session whose rows are Active or expected Passive, with 0 under FAILURES. Fix Created, Stopped, Faulty, or failed rows before recording a checkpoint.
   Related: How to check GlusterFS geo-replication status

2. Set the checkpoint for the current time.

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

   No output normally means the checkpoint time was recorded for that session.

3. Touch the primary mount when the volume has no current writes.

   $ sudo touch /mnt/gvol-primary

   GlusterFS recommends touching the primary mount so an idle volume still produces a change for geo-replication to process. Use the actual client mount path for the primary volume.
   Related: How to mount a GlusterFS volume in Linux

4. Check the checkpoint fields in detailed status output.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary status detail
   PRIMARY NODE  PRIMARY BRICK  STATUS   LAST_SYNCED          FAILURES  CHECKPOINT TIME      CHECKPOINT COMPLETED  CHECKPOINT COMPLETION TIME
   pnode1        /bricks/b1     Active   2026-06-16 10:18:09  0         2026-06-16 10:15:00  Yes                   2026-06-16 10:18:09
   pnode2        /bricks/b2     Passive  2026-06-16 10:18:07  0         2026-06-16 10:15:00  Yes                   2026-06-16 10:18:07

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

5. Get the session log path when any checkpoint row stays incomplete.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config log-file
   /var/log/glusterfs/geo-replication/gvol-primary/gsyncd.log

   Review the log on the primary node that owns the affected worker before treating the secondary as ready.
   Related: How to check GlusterFS geo-replication logs