How to stop a GlusterFS geo-replication session

Stopping a GlusterFS geo-replication session freezes the disaster-recovery copy at the last synchronized point while the primary volume continues accepting writes. Use the stop operation for maintenance, planned cutovers, or fault isolation when new changes must not reach the secondary site until replication is started again.

Geo-replication is addressed by the primary volume plus the secondary target in the form user@host::volume. The stop command terminates the selected gsyncd workers and leaves the session definition, SSH trust, checkpoints, and sync marker in place, so the same pairing can be started later without recreating it.

The secondary volume falls behind as new primary writes accumulate after the stop. Confirm the exact target before running the command, record LAST_SYNCED for the handoff, and reserve stop force for cases where the ordinary stop cannot complete because a participating node is unavailable or the session state cannot be staged cleanly.

1. List the geo-replication sessions from a primary cluster node.

   $ sudo gluster volume geo-replication status
   PRIMARY NODE  PRIMARY VOL   PRIMARY BRICK  SECONDARY USER  SECONDARY                          SECONDARY NODE  STATUS   CRAWL STATUS     LAST_SYNCED
   pnode1        gvol-primary  /bricks/b1     geoaccount      snode1.example.com::gvol-secondary  snode1          Active   Changelog Crawl  2026-06-16 10:22:30
   pnode2        gvol-primary  /bricks/b2     geoaccount      snode1.example.com::gvol-secondary  snode2          Passive  Changelog Crawl  2026-06-16 10:22:28

   Use the primary volume name and the full user@host::volume secondary target from this output in the stop command.
   Related: How to check GlusterFS geo-replication status

2. Stop the selected session from the primary cluster.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary stop
   Stopping geo-replication session between gvol-primary & geoaccount@snode1.example.com::gvol-secondary has been successful

   Stopping replication prevents new primary changes from reaching the secondary volume until the session is started again.

3. Use force only when the ordinary stop cannot stage on every participating node.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary stop force
   Stopping geo-replication session between gvol-primary & geoaccount@snode1.example.com::gvol-secondary has been successful

   stop force can leave the handoff dependent on post-stop status checks because it is meant for unavailable nodes or inactive session states.

4. Confirm that every worker row reports Stopped.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary status
   PRIMARY NODE  PRIMARY VOL   PRIMARY BRICK  SECONDARY USER  SECONDARY                          SECONDARY NODE  STATUS   CRAWL STATUS  LAST_SYNCED
   pnode1        gvol-primary  /bricks/b1     geoaccount      snode1.example.com::gvol-secondary  snode1          Stopped  N/A           2026-06-16 10:22:30
   pnode2        gvol-primary  /bricks/b2     geoaccount      snode1.example.com::gvol-secondary  snode2          Stopped  N/A           2026-06-16 10:22:28

   Stopped means the session still exists but is no longer syncing. Record LAST_SYNCED before starting maintenance or a cutover.

5. Check detailed status when a row does not stop cleanly.

   $ 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     Stopped  N/A           2026-06-16 10:22:30  0      0     0     0         N/A
   pnode2        /bricks/b2     Stopped  N/A           2026-06-16 10:22:28  0      0     0     0         N/A

   If a row reports Faulty or FAILURES increases, inspect the geo-replication log on the affected primary node before trusting the stopped state.
   Related: How to check GlusterFS geo-replication logs