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.
Steps to start a GlusterFS geo-replication session:
- 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 - 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.
- 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.
- 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.
- 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.
- 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