Gentoo Wiki




NFS stands for Network File System. It is a filesystem that can be mounted over the network to share files and directories.

Getting NFSv4 support on Gentoo was not exactly straightforward. I'll attempt to give a step-by-step of how I got it working. I am by no means an expert on NFS and/or NFSv4 in particular, but after looking around the web for information and finally resorting to mailing the NFS maintainers for guidance, I figured I'd pass on what little pearls of knowledge I gained from the experience.


Portage Tree

Kernel Support

NFSv4 support is only in the 2.6 kernel. The gentoo-sources kernel source package should suffice. The current version (as of June 9, 2005) is 2.6.11-r9, which should have most of the NFSv4 features. For the most up to date, I would recommend unmasking the "unstable" versions of gentoo-sources - though its not necessary.

# echo "sys-kernel/gentoo-sources ~x86" >>/etc/portage/package.keywords
# emerge gentoo-sources

When this package has installed, you will want to build a new kernel with NFSv4 support with the following settings (see Kernel). The NFSv3 support isn't needed in the client case to support NFSv4, but it gives you additional flexibility.

Linux Kernel Configuration: NFSv4
File systems  --->
  Network File Systems  --->
    <M> NFS file system support
    [*]   Provide NFSv3 client support
    [*]   Provide NFSv4 client support (EXPERIMENTAL)
    [*]   Allow direct I/O on NFS files (EXPERIMENTAL)
    <M> NFS server support
    [*]   Provide NFSv3 server support
    [*]     Provide NFSv4 server support (EXPERIMENTAL)
    ---   Provide NFS server over TCP support
    --- Secure RPC: Kerberos V mechanism (EXPERIMENTAL)
    < > Secure RPC: SPKM3 mechanism (EXPERIMENTAL)

You can reboot onto this new kernel or wait till after rebuilding the user space components. (If you're really following these instructions, I recommend waiting till after your exports file is updated - for a clean bring-up of the whole stack including nfsd.)

User Space Support


The user space components of NFS are contained within net-fs/nfs-utils. You could explicitly turn off NFSv4 support with the nonfsv4 USE flag. We can then install nfs-utils.

# emerge nfs-utils


Now that the daemons have been updated, we can go about modifying our /etc/exports. For a description of the Syntax of the export entriesm see NFS/Share Directories.

File: /etc/exports

My previous export entry looked like this...

/export     *(rw,sync,no_root_squash)

Now translated for NFSv4...

/export    *(rw,fsid=0,insecure,no_subtree_check,sync)

This is a good example of a *BASE* configuration. Upon further examination I was able to understand the NFSv4 philosophy. Basically, you choose one dir that you want ALL your exports to be inside. Don't choose more than one as I cannot find a way for NFSv4 to understand different base dirs. (You can use bind mounts to get everything inside one directory.)

Lets say that you also have a folder under the /export dir that you want to have different features. Perhaps different kerberos authentication information, or maybe you'd rather use sync to async. Since we have already set /export as the *ROOT* NFSv4 folder we have to tell NFSv4 which other folders can be seen. If you don't, any folder under /export will appear empty because you didn't say it could be seen. (at least this is in my experience).

We also need to "unhide" the sub-folders of the shared /export folder with the following addition to the /etc/exports file:

/export/FOLDER *(rw,nohide,insecure,no_subtree_check,async)

Notice that I didn't specify fsid. That's because this isn't a virtual root filesystem. I *DID* specify nohide so that way you can see under it and its contents. Potentially you could use nohide in the first export and let everything below be seen, but that's really up to you. I hope this helps you understand the NFSv4 a bit further as I took me some googling to figure this out.

If there is some other filesystem mounted under /export/FOLDER then it will also have to be exported, but if it has the 'nohide' option, then it will be visible when it's parent FOLDER is mounted. The important thing is that nohide does not automatically make all mounted filesystems visible, each filesystem still has to be separately exported, but they can all be seen through one mount.

Starting the Server

If you haven't already, now would be a good time to reboot onto the new NFSv4-enabled kernel we just built.

Now we need to start the server applications. They are all bundled together in one init.d script called "nfs" (this will automaticly start portmap, rpc.stat and rpc.mount, which are needed). If you haven't added theis to your default runlevel, you need to start it manually:

File: /etc/conf.d/nfs
# use optional "--no-udp" for tcp only
# set NFSv4 only with 8 daemons
OPTS_RPC_NFSD="--no-nfs-version 2,3 8"
# /etc/init.d/rpc.idmapd start
# /etc/init.d/nfs start

Mounting Partitions as NFSv4

Previously, you could just mount an nfs filesystem with the host:path syntax and the mount wrapper would just figure out that it was supposed to use nfs. With NFSv4, the syntax is slightly different, though I'm not positive if its because I built the client/server with both NFSv3 and NFSv4 client support, but it doesn't really matter too much. (Maybe something to play around with at a later date.)
First, we should find the exported filesystems with showmount...

Code: showmount
 # showmount -e myhost
Export list for myhost:
/export *

With NFSv3/v2, you would normally mount this filesystem with...

# mount myhost:/export /mnt

With NFSv4, the mount syntax is slightly different. First, we need to specify that we're using NFSv4. Second, since we exported the filesystem with fsid=0, the remote path will be /, not /export...

# mount -t nfs4 myhost:/ /mnt

Subdirectories of the export root can also be mounted individually:

# mount -t nfs4 myhost:/FOLDER /mnt/FOLDER

Mounting An Export Within A Previous Instance

I wasted hours figuring this out - But it's fairly obvious if I first think about it. When I mount the same export from a same client inside a previous instance, the second "inside" mount received incorrect content and strange permissions. This may be a bug in my head or in the kernel (as of version 2.16.21), it shows up on the client but no impact on the server: (here we use nfs v3 client + nfs3+4 server setup)

# mount myhost:/export/FOLDER1 /mnt/TEST1

The above is works fine, but when followed by below:

# mount myhost:/export/FOLDER1/FOLDER2/FOLDER3 /mnt/TEST1/TEST2

The second mount does not give expected result for /mnt/TEST1/TEST2, e.g. contents of myhost:/export/FOLDER1/FOLDER2/FOLDER3, but instead maintain the content of myhost:/export/FOLDER1 with MAXINT values for user/group IDs.

I needed to mount this way for making a PXE diskless client filesystem, where the root of the client is booted/mounted at myhost:/export/home/diskless/machine1 but then when I wanted to mount myhost:/export/home on client's /home it didn't work as wanted.

See also

Retrieved from ""

Last modified: Mon, 22 Sep 2008 03:34:00 +0000 Hits: 17,865