From Funtoo
Jump to navigation Jump to search


This wiki will explain how to install and use NFS (a Network File System) on Funtoo/Linux. Before we start a little hint for those who already searched for information :

Recent linux has NO need to do any tuning like suggested in the old days, like there was often mentioned playing with rsize and wsize parameters and such. If you don't run outdated kernel/userland, which is unlikely since Funtoo/Linux was not there that time, all necessary parameters are dynamically controlled by the kernel and will exceed the old values by far, hence you may not wonder if "mount" returns values which are 100 times greater than you expected.

These Days we differ usually between NFS V3 and NFS V4 which has nothing in common but the name. Older variants are weak,error prone, insecure etc. and are not mentioned any longer.

If you plan to setup a new NFS Server, i would strongly recommend V4 because it has several advantages over V3.


In general, you need a kernel with NFS enabled modules or built in, those settings can be found in "File systems" -> "Network file systems" using make menuconfig.

For generic client functionality you need

root # emerge net-fs/libnfs
root # emerge net-fs/nfs-utils

This will give you the necessary tools and environment to mount some NFS from a server or start a server on the machine itself.

NFS V3 can take care about disappearing and re-appearing machines on the network and deal accordingly with locked files and timeouts, to achieve that, you want to

root # rc-update add rpc.statd default
root # rc

the first time you installed it, will be automatic on reboot. This is not neccessary on pure V4 environments but since it can't be auto-detected the rc-script will force it. If you won't use V 3 at all, you may remove it from the scripts dependencies by editing /etc/init.d/nfs and /etc/init.d/nfsmount and remove "rpc.statd" from need.

NFS V3 syntax

If you consider to use only V3, you need to add some exported directories in /etc/exports, this can be something like this :

   /etc/exports - NFS V3 export syntax
...          /absolute/path/to/desired/dir   (rw,async)
some.domain.tld     /another/full/path/to/dir2  (ro,async)

and several alternative globbing with additional options where "man exports" gives you a good overview. One of the biggest differences to V4 ( see below ) in dirs export is the fact you write absolute paths ( from / downwards to the dir ) and V3 cares not about about username but uid.


NFS V3 is mapping uids on the exported files and dirs, this can become cumbersome on networks with different uids on the clients

NFS V4 syntax

If you consider to use V4, you need to add exported directories in a different way, there is only one NFSROOT and all other dirs have to appear below that :

   /etc/exports - NFS V4 export syntax
...         /srv   (fsid=0,rw,async,no_root_squash,no_all_squash)
some.domain.tld    /srv/dir2  (ro,async)

In this situation, we define the root of your nfs to be /srv ( latest V4 will take the first entry, early V4 used the above fsid=0 to mark it. This is considered deprecated but doesn't harm ). Also, we define another dir below NFSROOT, here /srv/dir2 which is meant to be mounted relative. ( See below ). You may mount a dir that exists somewhere else but in that case you need to bind-mount it for V4. e.g. if you want to export /mnt/another, you get this done by

root # mkdir /srv/dir2
root # mount -o bind /mnt/another /srv/dir2

If you do so, remember to add the mount also in fstab for next reboot :

root ##y##/srv/dir2      /mnt/another      bind       defaults     0  0

Activate changes on servers

Whenever you add or change settings in /etc/exports, there is no need to restart the server(s), else just

root #exportfs -rv

ID mapping

Like mentioned above, V4 does not care any longer for uids but will use username@machine instead. This is a big improvement since we must not longer care about the order of given users when adding accounts. However, if for some reason the protocol version 4 becomes inappropriate ( old client, bad parameters etc.) it will automatically fall back to use V3 where we need a way to get the different behavior somehow mapped, this is also the case in mixed environments and such where we have a solution for this. If you plan to use V4, you want to :

root # emerge net-libs/libnfsidmap
root # rc-update add rpc.idmapd default
root # rc

which will care about such situations.

Mounting V3 export from clients

Using V3, you have to specify the server and it's absolute path to the exported dir, this can be by IP like this :

root #mount -t nfs /somewhere

Or you may use a hostname or FQDN but only if you have a proper setup to resolve that reproducible from the client ( e.g. entry in /etc/hosts or local DNS servers etc. ) :

root # mount -t nfs nfsserver:/my/absolute/path/to/mounting/location /somewhere

Mounted via fstab, this would look like :

root ##y##/somewhere      nfs       defaults     0  0
root ##y##/somewhere      nfsserver:/my/absolute/path/to/mounting/location      nfs       defaults     0  0

the usage of IPs is recommented for machines mounting their own root on NFS to avoid early resolving issues.

Mounting V4 export from clients

Using V4, you DONT specify the absolute path, else it will fall back to V3 :

root # mount -t nfs4 /somewhere

( Above example exported by /srv/dir2 aka $NFSROOT/dir2 ) You may also use a hostname or FQDN

and in fstab :

root ##y##/somewhere      nfs4       defaults     0  0
root ##y##/somewhere      nfsserver:/dir2      nfs4       defaults     0  0


The use of -t nfs resp -t nfs4 is most likely redundant, recent userland has a good auto-detection. If not specially mentioned, nfs will map your users to nobody:nogroup, if you want to differ them on exported dirs, use the above mentioned "no_all_squash" option, The local user root is not necessarily the same superuser like on the server, if you want him to be the same, use "no_root_squash" else he is nobody ;)


As was noted above, with the latest versions of NFS problems should be rare. But when they crop up, they can be a bear. So collected here are some of those things that can bite you and make you pull out your hair.

Problem: NFS seems to work for the most part, but from time to time will hang with threads stuck in a 'D' state.

Solution: Check to see if there is an IP collision on your network. If there is, then resolve the collision and NFS should not hang anymore.