Version: 4.3.0

NFS client

SaunaFS implements a File System Abstraction Layer (FSAL) for NFS Ganesha to allow connecting NFS clients to the cluster.

NFS-Ganesha is an NFS v3, v4 and v4.1 fileserver that runs in user mode on most UNIX/Linux systems. NFS-Ganesha is used by SaunaFS for offering NFS v3 and v4 services.

SaunaFS FSAL is compatible with most of the features provided by Ganesha and is capable of managing classical goal replication and erasure coding. In the following sections will be covered the most important steps to setup SaunaFS FSAL and basic Ganesha settings.

More information and documentation to setup other specific options and advanced setups for NFS-Ganesha are available in the following link: https://github.com/nfs-ganesha/nfs-ganesha/wiki/Configurationfile

Installing NFS-Ganesha

Ubuntu LTS 22.04

SaunaFS FSAL was developed for NFS-Ganesha v4.3. In the future, the goal is to add support for NFS-Ganesha v5.5.

The package nfs-ganesha v4.3 is available in Ubuntu 23.04 (lunar) repositories. The easiest way to install this package is to add (temporarily) Ubuntu 23.04 repositories to the file /etc/apt/sources.list and install this package. After installing NFS-Ganesha, we recommend removing Ubuntu 23.04 repositories to avoid conflicts with possibly outdated packages.

Below there is a list of Ubuntu 23.04 repositories that were tested in our environment to install nfs-ganeshav4.3.

# Repos Lunar Official #REMOVE it after installing nfs-ganesha & nfs-ganesha-vfs packages
deb http://archive.ubuntu.com/ubuntu lunar main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu lunar-security main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu lunar-updates main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu lunar-proposed main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu lunar-backports main restricted universe multiverse

After updating the repositories, we update the packages of new repositories and install nfs-ganesha package with the following commands:

apt update
apt install nfs-ganesha

Note

We recommend removing Ubuntu 23.04 repositories from /etc/apt/sources.list to avoid conflicts with possibly outdated packages or accidental unwanted system upgrade.

Hint

It is recommended to install another FSAL like VFS (nfs-ganesha-vfs) to create the library folder where the FSAL should be copied before starting nfs-ganesha.

Ubuntu LTS 24.04

apt update
apt install nfs-ganesha

Hint

It is recommended to install another FSAL like VFS (nfs-ganesha-vfs) to create the library folder where the FSAL should be copied before starting nfs-ganesha.

In case it’s not possible to install nfs-ganesha from Ubuntu repositories, we need to download the source code of Ganesha v4.3 from the official repository and build the binaries before installing. In that case, the file COMPILING_HOWTO.txt can be useful for the building process.

Installing and setup SaunaFS FSAL

The next step is to install the packages for SaunaFS FSAL and its dependencies:

apt install saunafs-lib-client saunafs-nfs-ganesha

Hint

SaunaFS FSAL library (libfsalsaunafs.so) should be installed in Ganesha library path (/usr/lib/x86_64-linux-gnu/ganesha/ in Ubuntu 22.04). Otherwise, when starting nfs-ganesha, SaunaFS FSAL will not be loaded and NFS clients will not be capable of connecting to SaunaFS cluster.

Below there is a basic /etc/ganesha/ganesha.conf example file to use SaunaFS FSAL:

###################################################
# The ganesha node connects to the saunafs master server
# with the ip address 192.168.99.100:
#
# To work correctly, all that is required is an EXPORT
###################################################

EXPORT
{
    # Export Id (mandatory, each EXPORT must have a unique Export_Id)
    Export_Id = 77;

    # Exported path (mandatory)
    Path = "/";

    # Pseudo Path (required for NFS v4)
    Pseudo = "/";

    # Required for access (default is None)
    # Could use CLIENT blocks instead
    Access_Type = RW;
    Squash = None;
    Attr_Expiration_Time = 0;

    # Exporting FSAL
    FSAL {
        Name = SaunaFS;
        # The address of the SaunaFS Master Server or Floating IP if using uRaft
        hostname = "192.168.99.100";
        # The port to connect to on the Master Server
        port = "9421";
        # How often to retry to connect
        io_retries = 5;
        cache_expiration_time_ms = 2500;
    }

    # Which NFS protocols to provide
    Protocols = 3, 4;
}

One important aspect to consider is the 'Name' value must be set to SaunaFS. Otherwise nfs-ganesha will not use SaunaFS FSAL.

After finishing the setup of SaunaFS FSAL, nfs-ganesha needs to be enabled and started:

systemctl enable nfs-ganesha
systemctl start nfs-ganesha

Connecting NFS clients to SaunaFS clusters

Before connecting NFS clients to SaunaFS clusters, make sure package nfs-common is already installed. This package contains programs like statd, showmount and mount.nfs that are needed for NFS clients to connect successfully.

For connecting NFS clients to one SaunaFS cluster, we can use the following command:

mount -vvvv ganesha_server_ip:/ganesha_export /local_mountpoint

The option vvvv is optional and enables verbose mode to see whether the mount command was successful and other useful debug information.
The second parameter is the IP address assigned to the Ganesha server, followed by the export (defined at ganesha.conf) to which we want to connect.
The third parameter is the local mount point defined to access (locally) to the export defined at the ganesha.conf file.

Below, there is an example to connect a NFS client (locally) to NFS-Ganesha server installed at the same workstation:

mount -vvvv localhost:/ /mnt/export1/

The folder /mnt/export1/ is the directory under which the NFS share will be mounted on the client machine. This directory can be changed to any directory name.

Once NFS client is connected to the cluster, we can perform the following operations:

stat
readdir
create folders and files
remove dir and files
cat
symbolic links
change permissions
copy files and folders
rename files and folders

NFS protocol version, client's authorization, and multiple exports

NFS-Ganesha supports NFS v3, 4.0, 4.1, and 4.2. When connecting NFS clients to the cluster, it’s possible to define a specific version of NFS to be used by the client. Below there are some examples to connect NFS clients with different NFS versions:

NFS v3: mount -o nfsvers=3 localhost:/ /mnt/nfs3
NFS v4.1: mount -o v4.1 localhost:/ /mnt/nfs41
NFS v4.2 (default in Ubuntu 22.04): mount localhost:/ /mnt/nfs42

Another important step during configuration of an export is the list of clients authorized to access the export. The following example shows different ways to allow clients to connect to a given export:

EXPORT
{
    …
    CLIENT
    {
        #Clients = 192.168.208.236;
        #Clients = *;
        #Clients = 192.168.208.0/24;
        #Clients = mfsmaster;
    }
     …
}

The list of clients is usually defined inside a CLIENT section at the ganesha.conf file. The most frequent ways to authorize NFS clients are:

Specific IP address for a single client: Clients = 192.168.208.236;
All clients: Clients = *;
Specific subnet: Clients = 192.168.208.0/24.
Hostname of clients: Clients = nfsclient01;

NFS-Ganesha also allows to define multiple exports for the same namespace. The following example shows the definition of multiple exports in the same ganesha.conf file.

EXPORT
{
     Attr_Expiration_Time = 0;
     Export_Id = 1;
     Path = /export1;
     Pseudo = /e1;
     Access_Type = RW;

     FSAL
     {
          Name = SaunaFS;
          hostname = localhost;
          port = ${saunafs_info_[matocl]};
     }

     Protocols = 3, 4;
}

EXPORT
{
     Attr_Expiration_Time = 0;
     Export_Id = 2;
     Path = /export2;
     Pseudo = /e2;
     Access_Type = RW;

     FSAL
     {
          Name = SaunaFS;
          hostname = localhost;
          port = ${saunafs_info_[matocl]};
     }

     Protocols = 3, 4;
}

EXPORT
{
     Attr_Expiration_Time = 0;
     Export_Id = 97;
     Path = /;
     Pseudo = /e97;
     Access_Type = MDONLY;

     FSAL
     {
          Name = SaunaFS;
          hostname = localhost;
          port = ${saunafs_info_[matocl]};
     }

     Protocols = 4;
}

EXPORT
{
     Attr_Expiration_Time = 0;
     Export_Id = 99;
     Path = /;
     Pseudo = /e99;
     Access_Type = RO;

     FSAL
     {
          Name = SaunaFS;
          hostname = localhost;
          port = ${saunafs_info_[matocl]};
     }

     Protocols = 4;
}

The definition of multiple exports allows us to define different levels of access (RW, MDONLY, RO), which guarantee a fine-grained level of permissions for different folders in the namespace.

The way to connect to multiple exports is the same as before, we only need to define a NFS directory for each export.

NFS client

Installing NFS-Ganesha​

Ubuntu LTS 22.04​

Ubuntu LTS 24.04​

Installing and setup SaunaFS FSAL​

Connecting NFS clients to SaunaFS clusters​

NFS protocol version, client's authorization, and multiple exports​

Installing NFS-Ganesha

Ubuntu LTS 22.04

Ubuntu LTS 24.04

Installing and setup SaunaFS FSAL

Connecting NFS clients to SaunaFS clusters

NFS protocol version, client's authorization, and multiple exports