Setting up an NFS Share on Linux

Overview

This guide explains how to share the folder /opt/cast/shared from one Linux machine (Server) and access it from one or more other Linux machines (Clients).

A network share is required for the following components when installing CAST Imaging in a “distributed” way, i.e. with different components on dedicated machines. The following components require access to a shared network location:

  • imaging-services
  • analysis-node

CAST recommends using NFS (Network File System) (the standard Linux-to-Linux file sharing protocol) to action this. It is lightweight, straightforward to configure, and once set up the shared folder appears as a normal directory on client machines.

Where instructions differ between distributions, both variants are shown. Commands labelled Debian/Ubuntu apply to Debian, Ubuntu, and derivatives. Commands labelled RHEL apply to Red Hat Enterprise Linux, Rocky Linux etc.

Prerequisites

  • Both machines are on the same network
  • You have sudo access on both machines
  • You know the IP address of the server machine (e.g. 192.168.1.10)

Part 1 - Server Setup

One machine should be designated as the “file server”, this can be a dedicated machine just for that purpose, or you can designate a machine on which you have installed the imaging-services or analysis-node components.

Step 1 - Install the NFS server

Debian/Ubuntu:

sudo apt install nfs-kernel-server
sudo systemctl enable nfs-kernel-server
sudo systemctl start nfs-kernel-server

RHEL:

sudo dnf install nfs-utils
sudo systemctl enable nfs-server
sudo systemctl start nfs-server

Step 2 - Create the shared folder

This step is the same on all distributions:

sudo mkdir -p /opt/cast/shared
sudo chown -R $USER:$USER /opt/cast/shared
sudo chmod 755 /opt/cast/shared

Step 3 - Configure the export

Edit /etc/exports to define what is shared and who can access it. This file format is the same on all distributions:

sudo nano /etc/exports

Add the following line, replacing 192.168.1.0/24 with your actual network range:

/opt/cast/shared  192.168.1.0/24(rw,sync,no_subtree_check)

If you want to restrict access to a single client machine, use its specific IP instead:

/opt/cast/shared  192.168.1.20(rw,sync,no_subtree_check)

Export option reference:

Option Meaning
rw Read and write access (use ro for read-only)
sync Writes are confirmed before acknowledging to the client (safer)
no_subtree_check Improves reliability when sharing a subdirectory
no_root_squash Allows root on the client to act as root on the share (use with caution)
all_squash Maps all client users to the nobody user (useful for open drop folders)

Step 4 - Apply the configuration

Debian/Ubuntu:

sudo exportfs -a
sudo systemctl restart nfs-kernel-server

RHEL:

sudo exportfs -a
sudo systemctl restart nfs-server

Step 5 - Check SELinux status (RHEL only)

Skip this step on Debian/Ubuntu - SELinux is not used on those distributions.

On RHEL-based systems, SELinux is the most common reason NFS appears correctly configured but still fails. Check its current mode before proceeding:

getenforce

The output will be one of the following:

Result Meaning Action required
Enforcing SELinux is active and blocking unauthorised access Run the setsebool command below
Permissive SELinux logs violations but does not block anything No action needed, but note this for troubleshooting
Disabled SELinux is completely off No action needed

If the result is Enforcing, run the following to allow NFS to read and write:

sudo setsebool -P nfs_export_all_rw 1

The -P flag makes the change permanent so it survives reboots.

Step 6 - Configure the firewall

Debian/Ubuntu (if ufw is active):

sudo ufw allow from 192.168.1.0/24 to any port nfs
sudo ufw reload

RHEL (firewalld is active by default):

sudo firewall-cmd --permanent --add-service=nfs
sudo firewall-cmd --reload

Part 2: Client Setup

These steps should be actioned on all machines that require access to the network share created in part 1 described above.

Step 1 - Install the NFS client tools

Debian/Ubuntu:

sudo apt install nfs-common

RHEL:

sudo dnf install nfs-utils

Step 2 - Create a local mount point

This step is the same on all distributions:

sudo mkdir -p /opt/cast/shared

Step 3 - Mount the share

This command is the same on all distributions. Replace 192.168.1.10 with the actual IP address of your server hosting the share:

sudo mount 192.168.1.10:/opt/cast/shared /opt/cast/shared

Step 4 - Verify the mount

df -h | grep cast

You should see the share listed. You can now read and write to /opt/cast/shared as if it were a local folder.

Sttep 5 - Check SELinux status on the client (RHEL only)

Skip this step on Debian/Ubuntu.

Just as on the server, SELinux on a RHEL client can block access to NFS mounts even when everything else is correctly configured. First check the current mode:

getenforce

If the result is Enforcing, test that you can actually write to the share:

touch /opt/cast/shared/testfile

If you get a permission error despite your UID being correct, check what SELinux is blocking:

sudo ausearch -m avc -ts recent

The most common fixes on a client are:

# If users need access to NFS-mounted home directories
sudo setsebool -P use_nfs_home_dirs 1
 
# If general read/write access to the NFS mount is being blocked
sudo setsebool -P nfs_mount_copycerts 1

As with the server, the -P flag makes each change permanent across reboots. Use ausearch first to confirm which boolean is actually needed rather than applying both blindly.

Step 6 - Make the mount permanent (survive reboots)

Edit /etc/fstab — this is the same on all distributions:

sudo nano /etc/fstab

Add the following line:

192.168.1.10:/opt/cast/shared  /opt/cast/shared  nfs  defaults  0  0

Part 3: Permissions

NFS identifies users by their numeric UID (user ID), not by username. This means the UID of the user on the client must match the UID of the user on the server for permissions to work transparently.

Check UIDs on each machine

Run this on both the server and each client:

id

On a standard Ubuntu installation, the first created user is UID 1000. On RHEL-based systems, the first non-system user is also typically UID 1000, so this often works without any extra steps. It is worth verifying this explicitly on each machine.

If UIDs do not match

The cleanest solution is to align UIDs manually. On the client, change the user’s UID to match the server:

sudo usermod -u 1000 username

Shared group approach (multiple users)

If multiple users need write access to the share, use a shared group. These commands are the same on all distributions.

On the server:

sudo groupadd castusers
sudo usermod -aG castusers $USER
sudo chown -R $USER:castusers /opt/cast/shared
sudo chmod 775 /opt/cast/shared

On each client, create the same group with the same GID and add users to it:

sudo groupadd -g <gid> castusers
sudo usermod -aG castusers $USER

Replace <gid> with the group ID shown by getent group castusers on the server.

Troubleshooting

Permission denied when writing: Check that UIDs match on server and client (see Part 3 above). On RHEL, also check whether SELinux is blocking access:

sudo ausearch -m avc -ts recent

Mount hangs or times out: Check that the NFS server is running and that the firewall allows NFS traffic:

# Check server status
sudo systemctl status nfs-kernel-server   # Debian/Ubuntu
sudo systemctl status nfs-server          # RHEL
 
# Check firewall
sudo ufw status                           # Debian/Ubuntu
sudo firewall-cmd --list-services         # RHEL

Share not visible: Verify the server is exporting correctly:

sudo exportfs -v

You can also check from the client that the server’s exports are reachable:

showmount -e 192.168.1.10

Changes to /etc/exports not taking effect: Re-apply with:

sudo exportfs -ra