How to start a GlusterFS geo-replication session

A created GlusterFS geo-replication session does not move data until its workers are started on the primary volume. Starting the session turns the saved primary-to-secondary pairing into an active asynchronous replication stream, so the secondary volume can begin catching up for disaster recovery or offsite recovery use.

The start command runs from a node in the primary trusted pool and names the secondary target as user@host::volume. GlusterFS starts gsyncd workers for the selected session; in replica layouts one worker may show Active while its partner remains Passive because the active worker owns synchronization for that replica pair.

The first start can trigger Hybrid Crawl or Changelog Crawl work across a large namespace, so start during a window where extra disk and network load is acceptable. Use force only when restarting a known partial or failed worker state, because it can report success after starting as many eligible workers as possible instead of every worker in the primary volume.

1. Check the saved session before changing its state.

   $ 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          Created  N/A           N/A
   pnode2        gvol-primary  /bricks/b2     geoaccount      snode1.example.com::gvol-secondary  snode2          Created  N/A           N/A

   Created means the session exists but has not been started. Stopped means it can be started again without recreating the relationship.
   Related: How to check GlusterFS geo-replication status

2. Start the geo-replication session from the primary cluster.

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

   Initial synchronization can increase disk I/O and network utilization on both clusters.

3. Wait for the workers to leave the initialization phase.

   Initializing can appear briefly after the start command while GlusterFS checks the session. Recheck status after a short delay before treating the start as failed.

4. Check the session status after workers initialize.

   $ 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          Active   Changelog Crawl  2026-06-16 10:12:44
   pnode2        gvol-primary  /bricks/b2     geoaccount      snode1.example.com::gvol-secondary  snode2          Passive  Changelog Crawl  2026-06-16 10:12:41

   Active means a gsyncd worker is syncing data. Passive can be normal for the inactive member of a replica pair.

5. Check detailed counters for failures and pending work.

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

   FAILURES should stay at 0 during an ordinary start. ENTRY, DATA, and META can be nonzero while the session drains backlog.

6. Get the session log path if a worker reports Faulty or the failure count increases.

   $ 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

   Open the log on the primary node that owns the affected worker.
   Related: How to check GlusterFS geo-replication logs