How to configure GlusterFS client quorum

A replica outage can leave a GlusterFS client writing to too small a brick set unless the volume has client quorum enabled. Client quorum makes a replica subvolume unavailable when reachable bricks cannot satisfy the configured count, which protects the write path from split-brain during brick failures or network partitions.

Client quorum applies to replicated, distributed-replicated, and arbiter volumes through the AFR replicate layer. The cluster.quorum-type option accepts none, auto, and fixed; auto uses the replica majority rule, while fixed uses cluster.quorum-count as the minimum active brick count for each replica set.

Use auto for normal replica 3 and arbiter designs unless a documented runbook requires an explicit count. On replica 2 volumes, quorum protection removes write availability during common single-brick failures, so plan the maintenance boundary before enabling it and keep cluster.quorum-count at 2 if fixed is used to avoid allowing minority writes.

1. Check the volume layout before changing quorum.

   $ sudo gluster volume info volume1
   Volume Name: volume1
   Type: Distributed-Replicate
   Status: Started
   Number of Bricks: 2 x 3 = 6
   Transport-type: tcp
   Bricks:
   Brick1: node1:/srv/gluster/brick1
   Brick2: node2:/srv/gluster/brick1
   Brick3: node3:/srv/gluster/brick1
   Brick4: node4:/srv/gluster/brick1
   Brick5: node5:/srv/gluster/brick1
   Brick6: node6:/srv/gluster/brick1

   Client quorum is meaningful for replicated, distributed-replicated, and arbiter layouts. Plain distributed volumes do not gain quorum semantics from this setting.

2. Check the current client quorum policy.

   $ sudo gluster volume get volume1 cluster.quorum-type
   Option               Value
   ------               -----
   cluster.quorum-type  none

3. Set automatic client quorum for the volume.

   $ sudo gluster volume set volume1 cluster.quorum-type auto
   volume set: success

   auto allows writes only when a replica-set majority is reachable. For an even replica count, the first brick must also be reachable when exactly half the bricks are up.

4. Use a fixed quorum policy only when the volume design requires an explicit brick count.

   $ sudo gluster volume set volume1 cluster.quorum-type fixed
   volume set: success

   Skip this step when auto is the intended policy. fixed requires cluster.quorum-count and should be documented in the volume runbook before production use.

5. Set the fixed quorum count when cluster.quorum-type is fixed.

   $ sudo gluster volume set volume1 cluster.quorum-count 2
   volume set: success

   Set cluster.quorum-count to the safe replica majority, such as 2 for replica 2 or replica 3. A lower count can allow writes on a minority brick set and recreate the split-brain risk quorum is meant to prevent.

6. Verify the saved quorum policy.

   $ sudo gluster volume get volume1 cluster.quorum-type
   Option               Value
   ------               -----
   cluster.quorum-type  auto

7. Verify the saved fixed count when using fixed.

   $ sudo gluster volume get volume1 cluster.quorum-count
   Option                Value
   ------                -----
   cluster.quorum-count  2

   cluster.quorum-count has no effect when cluster.quorum-type is auto.

8. Check brick status after the change.

   $ sudo gluster volume status volume1
   Status of volume: volume1
   Gluster process                             TCP Port  RDMA Port  Online  Pid
   ------------------------------------------------------------------------------
   Brick node1:/srv/gluster/brick1             49152     0          Y       1844
   Brick node2:/srv/gluster/brick1             49153     0          Y       1901
   Brick node3:/srv/gluster/brick1             49154     0          Y       1968
   Brick node4:/srv/gluster/brick1             49155     0          Y       2034
   Brick node5:/srv/gluster/brick1             49156     0          Y       2097
   Brick node6:/srv/gluster/brick1             49157     0          Y       2159

   Related: How to check GlusterFS volume status

9. Reconnect one non-critical client mount before judging the policy from that client.

   $ sudo umount /mnt/gluster-volume1

   Reconnect test clients during a maintenance window if they mounted the volume before the quorum change. Long-running clients can otherwise make validation harder to interpret.

10. Mount the volume again from the same test client.

    $ sudo mount -t glusterfs node1:/volume1 /mnt/gluster-volume1

    Related: How to mount a GlusterFS volume in Linux

11. Create a small test file through the client mount while all required bricks are online.

    $ touch /mnt/gluster-volume1/quorum-check.txt

12. Verify the test file through the client mount.

    $ stat /mnt/gluster-volume1/quorum-check.txt
      File: /mnt/gluster-volume1/quorum-check.txt
      Size: 0          Blocks: 0          IO Block: 131072 regular empty file
    Access: (0644/-rw-r--r--)
    ##### snipped #####

    A successful client write proves the volume is usable while quorum is met. Test the outage-failure path only in a planned maintenance window or a lab cluster.

13. Remove the temporary quorum test file.

    $ rm /mnt/gluster-volume1/quorum-check.txt