How to mount a GlusterFS volume in Linux

Mounting a GlusterFS volume on a Linux client gives applications a normal local directory backed by the distributed volume. Verify the volume and the first manual mount before adding it to boot configuration, because a wrong hostname, stopped volume, or blocked brick port can leave the client waiting on network storage.

The native client uses FUSE and the glusterfs filesystem type. The server name in the mount command supplies the volume file at mount time, then the client connects to the brick hosts named in that volume file for actual reads and writes.

Use a started volume, a reachable trusted-pool node, and client-side name resolution that matches the names stored in the volume definition. Persistent mounts belong in /etc/fstab only after the manual mount works, with _netdev so boot treats the volume as network storage and optional x-systemd.automount when first-access mounting fits the host.

1. Open a terminal on a trusted-pool node.
2. List the available GlusterFS volumes.

   $ sudo gluster volume list
   gvol-data

3. Confirm that the target volume is started.

   $ sudo gluster volume info gvol-data
   
   Volume Name: gvol-data
   Type: Replicate
   Volume ID: 53dc227f-05be-407d-a4f3-b27cdf2c8e98
   Status: Started
   Snapshot Count: 0
   Number of Bricks: 1 x 2 = 2
   Transport-type: tcp
   Bricks:
   Brick1: node1:/srv/gluster/brick1
   Brick2: node2:/srv/gluster/brick1
   ##### snipped #####

   Client mounts should use a volume that is Started. Check brick online state before troubleshooting the client when the volume is stopped or degraded.
   Related: How to check GlusterFS volume status

4. Open a terminal on the Linux client.
5. Confirm that the client resolves the GlusterFS node names.

   $ getent hosts node1 node2
   192.0.2.11   node1
   192.0.2.12   node2

   Use names that resolve from the client and match the names the volume file sends back. Static /etc/hosts entries are acceptable for small fixed clusters, but DNS is easier to maintain across many clients.

6. Install the native GlusterFS client package on Debian or Ubuntu.

   $ sudo apt install --assume-yes glusterfs-client
   Reading package lists... Done
   Building dependency tree... Done
   Reading state information... Done
   The following NEW packages will be installed:
     glusterfs-client glusterfs-common
   ##### snipped #####
   Setting up glusterfs-client (11.2-2) ...

   RPM-family distributions usually provide the native mount helper in glusterfs-fuse. Keep client and server major versions aligned when the distribution offers multiple GlusterFS streams.

7. Create the client mount point.

   $ sudo mkdir -p /mnt/gvol-data

8. Mount the volume manually from a reachable node.

   $ sudo mount -t glusterfs -o backupvolfile-server=node2 node1:/gvol-data /mnt/gvol-data

   node1 is used to fetch the volume file. The backupvolfile-server option gives the mount helper another trusted-pool node to try if the first node is unavailable.

9. Verify the mounted filesystem type and source.

   $ findmnt --target /mnt/gvol-data --output SOURCE,FSTYPE,TARGET
   SOURCE           FSTYPE         TARGET
   node1:/gvol-data fuse.glusterfs /mnt/gvol-data

10. Create a harmless test file through the mount.

    $ sudo touch /mnt/gvol-data/client-smoke.txt

    Use a dedicated test path or maintenance window when applications watch the mounted directory.

11. Confirm that the test file is visible through the mounted path.

    $ ls -l /mnt/gvol-data/client-smoke.txt
    -rw-r--r-- 1 root root 0 Jun 16 09:45 /mnt/gvol-data/client-smoke.txt

12. Remove the test file.

    $ sudo rm /mnt/gvol-data/client-smoke.txt

13. Unmount the manual test mount.

    $ sudo umount /mnt/gvol-data

14. Add the persistent mount entry to /etc/fstab.

    node1:/gvol-data  /mnt/gvol-data  glusterfs  defaults,_netdev,backupvolfile-server=node2  0 0

    An incorrect /etc/fstab entry can delay boot or drop the host into emergency mode. Keep a console or recovery path available before changing boot mounts. On systemd hosts, add x-systemd.automount when the volume should mount on first access instead of during early boot.

15. Mount the /etc/fstab entry without rebooting.

    $ sudo mount /mnt/gvol-data

16. Verify the persistent mount entry.

    $ findmnt --target /mnt/gvol-data --output SOURCE,FSTYPE,TARGET,OPTIONS
    SOURCE           FSTYPE         TARGET          OPTIONS
    node1:/gvol-data fuse.glusterfs /mnt/gvol-data rw,relatime,default_permissions,allow_other

    The source and filesystem type confirm that the /etc/fstab entry mounted the native GlusterFS client, not an unrelated local directory or export.