The Funtoo Linux project has transitioned to "Hobby Mode" and this wiki is now read-only.
Nfs
NFS
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.
Installation
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...
10.0.0.0/8 /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...
10.0.0.0/8 /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 10.0.8.254:/my/absolute/path/to/mounting/location /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 10.0.8.254:/my/absolute/path/to/mounting/location 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 10.0.8.254:/dir2 /somewhere
( Above example exported by /srv/dir2 aka $NFSROOT/dir2 ) You may also use a hostname or FQDN
and in fstab :
root ##y##/somewhere 10.0.8.254:/dir2 nfs4 defaults 0 0 root ##y##/somewhere nfsserver:/dir2 nfs4 defaults 0 0
Hints
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 ;)
Troubleshooting
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.