Mount NFS on OpenMediaVault

Tutorial

This guide shows how to prepare a disk on an NFS server, export it with nfs-kernel-server, troubleshoot common permission problems, and mount the remote NFS share from an OpenMediaVault client using the official Remote Mount plugin.

On the NFS Server

Mount the Disk by UUID

First, identify the UUID of the disk or partition you want to mount:

sudo blkid

Example output:

root@orangepi3:~# sudo blkid
/dev/mmcblk2p1: UUID="600d3790-5661-48e4-b40f-16356b83183d" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="b0d8b10d-01"
/dev/sdb1: UUID="4fe6face-5253-486d-9c6c-c6658ea036ba" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="ccc2e70a-a1f9-49d6-aecf-36e13ba0a9d4"
/dev/mmcblk0p1: UUID="0463846f-1aa0-42b9-bc76-92a8d366d6ed" BLOCK_SIZE="4096" TYPE="ext4"
/dev/zram1: LABEL="log2ram" UUID="1514a966-ac2d-4275-9822-f95aee88050f" BLOCK_SIZE="4096" TYPE="ext4"
/dev/sda1: UUID="6600936a-8024-462d-a92a-96ce2b73c2c7" BLOCK_SIZE="4096" TYPE="ext4" PARTUUID="62fce7c6-3580-a242-bc44-84255f16efb6"
/dev/zram0: UUID="11e281ee-50ce-452d-8e35-bef71510b09d" TYPE="swap"

Create the mount point if it does not already exist:

sudo mkdir -p /mnt/4tb

Edit /etc/fstab:

sudo nano /etc/fstab

Add a line like this, replacing the UUID and mount path with your own values if needed:

UUID=6600936a-8024-462d-a92a-96ce2b73c2c7   /mnt/4tb   ext4   defaults,nofail   0   0

Reload systemd and mount everything defined in /etc/fstab:

sudo systemctl daemon-reload
sudo mount -a

Verify the disk is mounted:

findmnt /mnt/4tb

Set Up the NFS Server

Install the NFS server package:

sudo apt update
sudo apt install nfs-kernel-server

Set ownership and permissions for the exported directory:

sudo chown nobody:nogroup /mnt/4tb
sudo chmod 777 /mnt/4tb

Edit /etc/exports:

sudo nano /etc/exports

Add the export rule. Replace 10.10.0.10 with the IP address of your OpenMediaVault client:

/mnt/4tb 10.10.0.10(rw,sync,no_subtree_check,crossmnt,anonuid=1000,anongid=100)

Apply and verify the export:

sudo exportfs -ra
sudo exportfs -v

Troubleshooting: NFS Mount Does Not Show Data Correctly

Symptoms

The server exports the NFS share successfully, and the client mounts it without errors. However, when you open the mounted directory, file and directory names appear as ?????????, and reading the content fails with Permission denied.

Investigation

  1. Check whether the data really exists on the server. In this case, it does: directories such as data, docker, and .recycle are present.

  2. Check whether a missing crossmnt option is the problem. This can happen when a subdirectory is a separate mount point. Use findmnt to verify it:

    findmnt /mnt/4tb/data

    In this case, data is not a separate mount point, so missing crossmnt is not the root cause. Keeping crossmnt is still useful in case child mount points are added later.

  3. The actual root cause is directory permissions. The data directory on the server has permissions like this:

    drwxrwsr--

    This means other only has read permission (r--) and does not have execute permission (x). For directories, execute permission is required to enter and traverse the directory.

By default, NFS uses root_squash. This means that even if the client accesses the mount as root, that root user is mapped to nobody:nogroup on the server. As a result, the client falls into the other permission class and does not have enough permission to access the files inside the directory.

Solution

Use these permissions on the exported root directory:

sudo chown nobody:nogroup /mnt/4tb
sudo chmod 777 /mnt/4tb

Then add anonuid=1000,anongid=100 to the NFS export:

/mnt/4tb 10.10.0.10(rw,sync,no_subtree_check,crossmnt,anonuid=1000,anongid=100)

This maps squashed users to the real UID and GID that own the data on the server. In this example:

  • anonuid=1000 maps anonymous NFS access to UID 1000.
  • anongid=100 maps anonymous NFS access to GID 100, usually the users group on many Debian-based systems.
  • crossmnt allows child mount points under the exported directory to be visible through the export if you add them later.

Reload the export after changing /etc/exports:

sudo exportfs -ra
sudo exportfs -v

Mount the NFS Share on an OpenMediaVault Client

To mount an external NFS share onto an OpenMediaVault system, use the official openmediavault-remotemount plugin through the OMV web interface. This integrates the remote storage cleanly into OpenMediaVault, allowing you to manage it, assign permissions, create shared folders, and pass it to Docker containers.

Step 1: Install the Remote Mount Plugin

If OMV-Extras is not installed yet, install it first so you can access community plugins.

  1. Log in to the OpenMediaVault Web GUI.
  2. Go to System > Plugins.
  3. Search for openmediavault-remotemount.
  4. Select the checkbox next to it and click Install.
  5. After the installation finishes, click the yellow Apply banner at the top of the interface.

Step 2: Add the NFS Remote Mount

  1. Go to Storage > Remote Mounts.
  2. Click + Add.
  3. Fill in the mount configuration:
    • Mount Type: Select NFS.
    • Name: Enter a custom name, such as Remote_NAS.
    • Server: Enter the IP address of the NFS server, such as 10.10.0.1 or 192.168.1.50.
    • Share: Enter the exported path from the server, such as /mnt/4tb.
    • Options: Leave this as defaults, or add specific tuning options if your setup requires them.
  4. Click Save.
  5. Click the yellow Apply banner to finalize the changes.
  6. Select the new mount and click Mount if it does not automatically become active.

Note: With NFSv4, the share path may be shorter depending on the server’s NFSv4 pseudo-root configuration. With NFSv3, you usually use the full exported path, such as /mnt/4tb or /export/Media.

Fix NFS Recovery After the Server Restarts

If OpenMediaVault mounts an NFS remote share from another server, the mount can stop showing data after the NFS server restarts. In this state, OMV may not recover the connection automatically, and the data only appears again after rebooting the OMV machine.

The usual cause is that the mount is using soft behavior, either explicitly or through defaults. When the NFS connection drops, a soft mount returns an error to the client and can leave the mount unusable instead of continuing to wait for the server to come back.

Solution

Change the default mount options from:

rsize=8192,wsize=8192,timeo=14,nofail

to:

rsize=8192,wsize=8192,timeo=14,hard,_netdev,nofail

The important option is hard. With a hard mount, read and write operations keep retrying until the NFS server becomes available again, instead of failing and effectively dropping the mount. This is the main change that avoids needing to reboot OMV after the NFS server restarts.

The other options are still useful:

  • timeo=14 controls the retry timeout and works together with hard.
  • _netdev tells the system this mount depends on the network, so it should wait for networking during boot.
  • nofail prevents OMV from getting stuck during boot if the remote share is temporarily unavailable.

Apply and Test

  1. Update the options in Storage > Remote Mounts, then click Save and Apply.
  2. Test the real failure case: restart the NFS server, wait a few minutes, then check the mounted directory on OMV without rebooting the OMV machine. The data should appear again automatically after the NFS server is back online.

Step 3: Register the Remote Mount as an OMV Shared Folder

OMV services such as SMB, Plex, and Docker cannot use a disk or remote mount properly unless it is registered as an OMV shared folder.

  1. Go to Storage > Shared Folders.
  2. Click + Create.
  3. Set a Name for the shared folder.
  4. In the File System dropdown, select the newly mounted NFS share. It should appear using the custom name you configured in Remote Mounts.
  5. Set the Path. Usually / is enough if you want to expose the root of the remote share.
  6. Click Save.
  7. Click Apply to commit the configuration.

Your remote NFS share is now mounted, recognized by OpenMediaVault, and ready to be used like a local storage folder.

Alternative: Test the NFS Mount from the CLI

If you want to test the mount through SSH first, or if the OMV web interface reports an error, mount it manually from the terminal:

# 1. Create a temporary local mount directory
sudo mkdir -p /mnt/test_nfs

# 2. Mount the NFS share. Adjust the IP address and path for your setup.
sudo mount -t nfs 192.168.1.50:/export/Media /mnt/test_nfs

# 3. Verify that files are visible
ls -la /mnt/test_nfs

If you receive Permission denied or Protocol not supported, check the following:

  • The OpenMediaVault client IP is allowed in the server’s /etc/exports file.
  • The export was reloaded with sudo exportfs -ra.
  • The server firewall allows NFS traffic.
  • The NFS server package is installed and running.
  • The exported directory permissions allow the mapped NFS user to traverse and read the directory.

Quick Checklist

On the server:

sudo blkid
sudo nano /etc/fstab
sudo systemctl daemon-reload
sudo mount -a
sudo apt install nfs-kernel-server
sudo chown nobody:nogroup /mnt/4tb
sudo chmod 777 /mnt/4tb
sudo nano /etc/exports
sudo exportfs -ra
sudo exportfs -v

On OpenMediaVault:

  1. Install openmediavault-remotemount.
  2. Add the NFS share under Storage > Remote Mounts.
  3. Mount it.
  4. Register it under Storage > Shared Folders.
  5. Use the shared folder with OMV services or Docker containers.