projects techreports press lab location staff
citi top.2 top.3
citi mid.3
bot.1 bot.2 bot.3

Projects: NFS Version 4 Open Source Reference Implementation

Linux 2.4 NFSv4 Installation and Configuration

This document serves as the installation and configuration guide for the first release of the Linux 2.4 NFSv4 implementation. This first release is a client-only release. Server support is expected in Release Two.

Reporting Bugs

Please see the Release Notes for instructions on how to report bugs. Questions, comments, and bug reports to


  • Red Hat Professional Series 7.3 already installed
  • /tmp must be a file system that supports loopback devices
  • The latest version of the modutils RPM already installed
  • MIT Kerberos 5 available or installed
  • Local configuration instructions for your Kerberos 5 realm
  • A running NFSv4 server

This installation process installs a new kernel on your system. If you require kernel customizations, download the NFSv4 kernel source RPM, add your customizations, then rebuild and install your modified kernel.

The mount RPM replaces the mount command on your system. If you have a custom version of mount, download the NFSv4 mount source RPM, add your customizations, then rebuild and install the modified mount command. The mount command RPM does not support relocation.

You may install on a Red Hat system with a custom-built kernel as long as the kernel has support for loopback devices enabled. During installation, /tmp must be a file system that supports loopback devices. Note that tmpfs file systems do not support loopback devices. After installation of the kernel RPM there is no longer any requirement for loopback support.

Kerberos 5 Configuration

Ensure that Kerberos 5 is installed and configured using your local Kerberos 5 configuration instructions. Here are some guidelines for carrying out this procedure.

Make sure that the Red Hat Kerberos 5 packages are installed on your system.

   % rpm -qa | grep krb5

Make sure the target system knows about the local Kerberos 5 realm by editing your /etc/krb5.conf file. Your local system administrator can fill you in on these details.

Note: The following step is not required if you want to mount only Network Appliance filers.

Create machine credentials for your client. For this release, this means creating a Kerberos V5 principal/instance name of the form nfs/hostname@domain, and either adding a key for this principal to an existing /etc/krb5.keytab on your client, or creating an /etc/krb5.keytab using a random password.

Note: Only the encryption type of des-cbc-crc is functional so far in the kernel, so add ONLY this type of key.

On the kdc:

   kadmin: addprinc -randkey nfs/hostname.domain
   kadmin: ktadd -e des-cbc-crc:normal -k /tmp/keytab nfs/hostname.domain   

Substitute your client's hostname and your realm's domain name where appropriate. Your local Kerberos 5 kdc administrator will need to help you with this step.

NFSv4 Client Installation

This is the simple and most general case where no other customization is required. Begin by installing the user-level RPMs. These require approximately 2MB of free space in /usr.

   % su
   # rpm -Uvh --replacepkgs mount-2.11n-12.nfsv4.i386.rpm
   # rpm -Uvh --replacepkgs nfsv4-daemons-0.9-1.i386.rpm
   # rpm -Uvh --replacepkgs initscripts-6.67-1.nfsv4.i386.rpm

The "--replacepkgs" option is required if rpm complains about previously installed package versions.

The kernel installation RPM requires the latest version of modutils. If you don't regularly run up2date, you must download and install the latest version of the modutils RPM for Red Hat 7.3. A copy of this RPM is available on our web site for your convenience. To install this RPM, use:

   % su
   # rpm -Uvh modutils-2.4.18-3.7x.i386.rpm

Now install the NFSv4 kernel. Use the kernel RPM that suits your system's hardware architecture. We have used i686 SMP in this example.

   % su
   # rpm -Uvh --replacepkgs kernel-2.4.18-18.nfsv4.i686-smp.rpm

Ensure that your LILO or GRUB configuration is correct, then run LILO if necessary.



If you want to uninstall some or all of the NFSv4 RPMs, follow these instructions.

Uninstall the nfsv4 daemons RPM. This unmounts all of your NFSv4 file systems automatically, and shuts down the gssd and idmapper, before proceding.

   % su
   # rpm -e nfsv4-daemons-0.9-1

Reinstall the original versions of the mount command and halt script. You can obtain these from or a Red Hat mirror.

   % su
   # rpm -Uvh --replacepkgs mount-2.11n-12.i386.rpm
   # rpm -Uvh --replacepkgs initscripts-6.67-1.i386.rpm
Adjust your LILO or GRUB configuration to remove the NFSv4 kernel.


You may also uninstall the NFSv4 kernel, but that usually isn't necessary.

NFSv4 Client Configuration

You can mount the root of an NFSv4 server's pseudo-fs, or you can explicitly mount named exported file system just like in NFSv2 or NFSv3.

This release of the Linux NFSv4 client does not support server reboot recovery. Therefore, you need to umount and remount a server on your NFSv4 clients after rebooting a server.

There is an "nfsnobody" user and group defined on Linux. The idmapper uses this user and group name and ID when it receives a user or group string from the server that it doesn't recognize. On Red Hat systems, the nfsnobody user and group IDs are set to 65534 by default, which is (u16) -2 .

You can change the values that idmapd uses for anonymous UIDs by editting /etc/idmapd.conf.

The NFSv4 client introduces a new file system type to Linux: nfs4 .

In the past, system administrators could mount an NFS file system with these commands:

   % su
   # mount -o vers=2 server:/export /mnt/server

for NFS version 2, and

   % su
   # mount -o vers=3 server:/export /mnt/server

for NFS version 3. In this release of the Linux NFS client, issuing a mount command with no options gives an NFSv3 over TCP connection by default.

To mount an NFSv4 file system, use:

   % su
   # mount -t nfs4 server:/export /mnt/server

Using "-t nfs -o vers=4" will not work.

The nfs4 file system type no longer supports the "udp" and "tcp" mount options. To specify the underlying network protocol, use "proto=" instead. For UDP, use "proto=udp" and for TCP, use "proto=tcp".

Be aware that some servers do not support NFSv4 over UDP. If you specify the "proto=udp" option when mounting a server that does not support NFSv4 over UDP, your mount command will fail, but it may not be clear why it did. Always use the default (which should be TCP), or explicitly specify proto=tcp.

The "lock" and "nolock" options are not supported for the nfs4 file system type. In its final implementation, the NFSv4 client will always enable locking. This release of the client, however, does not support file locking.

Security Mechanisms

By default, AUTH_UNIX security is used for NFSv4 mount points. What follows is a brief introduction to NFSv4 mount options that allow you to set up advanced security mechanisms, such as Kerberos 5.

To specify an advanced security mechanism for a mount point, use the new "sec=" mount option. In this release, only Kerberos 5 mutual authentication is supported. To enable Kerberos 5 mutual authentication, specify:

   % su
   # mount -t nfs4 -o sec=krb5 server:/export /mnt/server

Note: You must remove the "-m" option from the gssd command line (by editing /etc/rc.d/init.d/rpcgssd) in order to mount a Network Appliance filer. Before mounting, you must run kinit to get a ticket for the root user.

The server must be configured to export the requested parttition with Kerberos 5 security in order for the mount to succeed. Follow your server's instructions for properly configuring Kerberos 5 on the server and for setting up UID to principal mapping (see "man gsscred" on Solaris, and refer to the OnTAP System Administrator's Guide for Network Appliance filers).

You cannot mount a partition with AUTH_UNIX security if the server has exported it with only Kerberos 5 security, nor can you mount a partition using Kerberos 5 security if it was exported with only AUTH_UNIX security.

If you specify an unsupported security mechanism with the "sec=" option, the mount command will fail with this helpful message:

   mount: wrong fs type, bad option, bad superblock on bay:/export,
          or too many mounted file systems

The kernel log may contain this message:

   RPC: Couldn't create auth handle (flavor #######)

When using Kerberos security, each user must authenticate in order for the NFSv4 server to recognize their requests. This means every user who wants access to a Kerberos-secured export must have a Kerberos principal and password in the same realm as the client and server. This release of the client does not support specifying multiple security mechanisms per mount on the client (using Kerberos and falling back to AUTH_UNIX if a user's principal is not recognized).

First, ensure that /usr/kerberos/bin is in your path.

A user can authenticate via Kerberos by running the "kinit" command at any time during their login session.

   % kinit
   Password for user@REALM:

The credentials are stored in a file in /tmp permitted only to the user who authenticated. To view the credentials in the file, use klist. When I do a klist, I see this:

   % klist
   Ticket cache: FILE:/tmp/krb5cc_20057
   Default principal: cel@CITI.UMICH.EDU

   Valid starting     Expires            Service principal
   02/13/03 15:16:17  02/14/03 01:16:17  krbtgt/CITI.UMICH.EDU@CITI.UMICH.EDU

   Kerberos 4 ticket cache: /tmp/tkt20057
   klist: You have no tickets cached

To destroy her own Kerberos credentials, a user can use the kdestroy command.

   % kdestroy

Kerberos credentials are not automatically destroyed when a user logs out. A user can log out and log back in without destroying her credentials. However, credentials do expire after a set time (usually less than a day). You can ensure your ticket file is deleted by adding a kdestroy command to your .logout file.

Automatic authentication during normal login is possible using Pluggable Authentication Modules (PAM, for short). This allows a user to login using their Kerberos 5 password, and automatically acquire Kerberos credentials without running kinit.

As root, go into the /etc/pam.d directory. You will see a number of files named after various system utilities that require authentication: su, ftp, sshd, and so on. Select the files that correspond to the applications you wish to Kerberos-enable. Add this line at the end of the "auth" section in each file:

    auth      optional      /lib/security/

"Optional" means that any local user IDs on the system can log in whether they have Kerberos principals or not. For remote logins via ftp or sshd, you may want to change this to "required" to deny access via these ports of entry to users who don't have Kerberos principals.

The Kerberos PAM library creates a per-session ticket file in /tmp. This file must be moved to a per-UID location so that gssd can find it (this will be fixed in a future release). As part of your login scripts, you must move your per-session ticket file to the standard location. For example:

    # move kerberos cred file to a place where gssd can find it
    TMPNAME=`/bin/basename ${KRB5CCNAME:-unset}`
    if [ -f /tmp/${TMPNAME} ]; then
      mv /tmp/${TMPNAME} /tmp/krb5cc_${UID}

Last Modified: Thu Mar 13 15:43:44 EST 2003 projects | techreports | press | lab | location | staff Email address
or call +1 734 763 2929
Copyright © 1996-2013
The Regents of the University of Michigan