How to configure GlusterFS geo-replication options

Changing GlusterFS geo-replication options affects how quickly each primary brick worker catches up, how much load replication can place on the network, and whether deleted files disappear from the secondary volume. A small option change can restart the session, so the target session and expected recovery behavior should be clear before tuning begins.

The gluster volume geo-replication … config command reads or updates settings for one primary volume and one secondary target written as user@host::volume. Run it from a primary trusted-pool node after the session exists, using the same target string that was used when the session was created.

Tune one option at a time and check status after each change on active sessions. Concurrency options such as sync-jobs can raise CPU, disk, and WAN use during backlog processing, while ignore-deletes changes the secondary from a mirror into a retention copy that keeps files deleted from the primary.

1. Check the selected geo-replication session from a primary cluster node.

   $ 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

   Use the exact user@host::volume target from the session that needs tuning.
   Related: How to check GlusterFS geo-replication status

2. List the current configuration for the session.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config
   checkpoint 0
   ignore-deletes 0
   log-level INFO
   sync-jobs 3
   timeout 120
   use-tarssh false

   Copy option names from the listing before changing values because supported keys can vary by GlusterFS release.

3. Set the sync-jobs value for the session.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config sync-jobs 6
   geo-replication config updated successfully

   sync-jobs controls how many files or directories can be synchronized at the same time. Higher values can shorten catch-up time, but they can also increase brick, CPU, and WAN load.

4. Set the timeout value when slow links need a longer transfer window.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config timeout 180
   geo-replication config updated successfully

   timeout is measured in seconds. Keep the value close to the real network behavior instead of using a large catch-all value.

5. Enable ignore-deletes only when the secondary must retain primary-side deletions.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config ignore-deletes 1
   geo-replication config updated successfully

   When ignore-deletes is 1, a file deleted on the primary is not deleted on the secondary. Confirm restore and cleanup expectations before using this mode.

6. Verify the updated configuration values.

   $ sudo gluster volume geo-replication gvol-primary \
     geoaccount@snode1.example.com::gvol-secondary config
   checkpoint 0
   ignore-deletes 1
   log-level INFO
   sync-jobs 6
   timeout 180
   use-tarssh false

7. Check detailed session status after the configuration change.

   $ 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:15:18  0      0     0     0         N/A
   pnode2        /bricks/b2     Passive  Changelog Crawl  2026-06-16 10:15:15  0      0     0     0         N/A

   Successful config changes can restart geo-replication workers. FAILURES should stay at 0 after the session settles; review logs if a row reports Faulty.
   Related: How to check GlusterFS geo-replication logs