How to configure GlusterFS bitrot scrub settings

Bitrot scrubbing helps detect silent corruption on a GlusterFS volume, but an untuned scrubber can compete with client traffic during busy periods. Setting the scrub throttle and frequency lets the volume keep checking signed files while leaving enough disk and CPU capacity for the workload.

When bitrot is enabled, GlusterFS runs a signer that records checksums and a scrubber that later compares file data with those signatures. The frequency setting controls when scheduled scrub cycles run, and the throttle setting controls how quickly objects are verified during a scrub.

Scrub settings are stored per volume, so a busy application volume can use a lower impact schedule while a colder archive volume can scrub more often or more aggressively. Pausing the scrubber stops the scan loop only; signing remains active while bitrot detection is enabled.

1. List volumes to confirm the target volume name.

   $ sudo gluster volume list
   volume1
   volume2

   gluster commands can be run from any node in the trusted storage pool.

2. Confirm bitrot detection is enabled on the volume.

   $ sudo gluster volume get volume1 features.bitrot
   Option                                  Value
   ------                                  -----
   features.bitrot                         on

   If the value is off or disable, enable bitrot before configuring scrub behavior.
   Related: How to enable GlusterFS bitrot detection

3. Set the scrub throttle mode for the volume.

   $ sudo gluster volume bitrot volume1 scrub-throttle normal
   volume bitrot: success

   Use lazy for the lowest scrub impact, normal for a balanced scan rate, or aggressive only when the volume can absorb heavier background I/O.

4. Set the scrub frequency for the volume.

   $ sudo gluster volume bitrot volume1 scrub-frequency weekly
   volume bitrot: success

   Common supported values are daily, weekly, biweekly, and monthly. Some GlusterFS 11.x packages also list hourly; confirm with gluster volume bitrot help before using it on older packages.

5. Check the stored scrub throttle value.

   $ sudo gluster volume get volume1 features.scrub-throttle
   Option                                  Value
   ------                                  -----
   features.scrub-throttle                 normal

   Related: How to list GlusterFS volume options

6. Check the stored scrub frequency value.

   $ sudo gluster volume get volume1 features.scrub-freq
   Option                                  Value
   ------                                  -----
   features.scrub-freq                     weekly

7. Pause the scrubber during a high-traffic window when needed.

   $ sudo gluster volume bitrot volume1 scrub pause
   volume bitrot: success

   Pausing the scrubber stops scheduled scanning, but it does not stop bitrot signing while features.bitrot remains enabled.

8. Resume the scrubber after the high-traffic window.

   $ sudo gluster volume bitrot volume1 scrub resume
   volume bitrot: success

9. Check the scrub status for the volume.

   $ sudo gluster volume bitrot volume1 scrub status
   Volume name: volume1
   State of scrub: Active (Idle)
   Scrub impact: normal
   Scrub frequency: weekly
   Bitrot error log location: /var/log/glusterfs/bitd.log
   Scrubber error log location: /var/log/glusterfs/scrub.log
   =========================================================
   Node: node1
   Number of Scrubbed files: 1246
   Number of Skipped files: 0
   Last completed scrub time: Scrubber pending to complete.
   Duration of last scrub (D:M:H:M:S): 0:0:0:0
   Error count: 0
   Corrupted objects:
   None

   Active (Idle) means the scrubber is enabled and waiting for the next run. Scrub impact and Scrub frequency should match the values configured above.