29.3. Network File System (NFS)

Reorganized and enhanced by Tom Rhodes.
Written by Bill Swingle.

FreeBSD supports the Network File System (NFS), which allows a server to share directories and files with clients over a network. With NFS, users and programs can access files on remote systems as if they were stored locally.

The most notable benefits that NFS provides are:

29.3.1. How NFS Works

NFS consists of at least two main parts: a server and one or more clients. The client remotely accesses the data that is stored on the server machine. In order for this to function properly a few processes have to be configured and running.

These daemons must be running on the server:

nfsdThe NFS daemon which services requests from the NFS clients.
mountdThe NFS mount daemon which carries out the requests that nfsd(8) passes on to it.
rpcbind This daemon allows NFS clients to discover which port the NFS server is using.

Running nfsiod(8) can improve performance on the client, but is not required.

29.3.2. Configuring NFS

Enabling the NFS server is straightforward. The required processes can be set to start at boot time by adding these options to /etc/rc.conf:

rpcbind_enable="YES" nfs_server_enable="YES" mountd_flags="-r"

mountd runs automatically whenever the NFS server is enabled.

To enable the client, set this option in /etc/rc.conf:


/etc/exports specifies which file systems the NFS server will export. Each line in /etc/exports specifies a file system to be exported and which clients have access to that file system, as well as any access options. There are many such options that can be used in this file, but only a few will be mentioned here. See exports(5) for the full list of options.

These examples give an idea of how to export file systems. Minor modifications may be required for the examples to work on the reader's network.

This example shows how to export the /cdrom directory to three clients called alpha, bravo, and charlie:

/cdrom -ro alpha bravo charlie

The -ro flag makes the file systems read-only, preventing clients from making any changes to those exported file systems.

The next example exports /home to three clients by IP address. This can be useful for networks without DNS. Optionally, /etc/hosts could be configured for internal hostnames; please review hosts(5) for more information. The -alldirs flag allows subdirectories to be mount points. In other words, it will not mount the subdirectories but permit the client to mount only the directories that are required or needed.

/home -alldirs

This next line exports /a so that two clients from different domains may access the file system. The -maproot=root flag allows the root user on the remote system to write data on the exported file system as root. If the -maproot=root flag is not specified, the client's root user will be mapped to the server's nobody account and will be subject to the access limitations defined for user, nobody.

/a -maproot=root host.example.com box.example.org

For a client to have access to an exported file system, the client must be listed in /etc/exports.

In /etc/exports, each line defines the export information for one file system to one or more clients. A remote host can only be specified once per file system. For example, assume that /usr is a single file system. This entry, in /etc/exports, would be invalid:

# Invalid when /usr is one file system /usr/src client /usr/ports client

The /usr file system has two lines specifying exports to the same host, client. The correct format for this situation is:

/usr/src /usr/ports client

The exported file system, its properties, and allowed hosts must occur on a single line. If no clients are listed, then any client on the network may mount the exported file system.

The following is an example of a valid export list, where /usr and /exports are local file systems:

# Export src and ports to client01 and client02, but only # client01 has root privileges on it /usr/src /usr/ports -maproot=root client01 /usr/src /usr/ports client02 # The client machines have root and can mount anywhere # on /exports. Anyone in the world can mount /exports/obj read-only /exports -alldirs -maproot=root client01 client02 /exports/obj -ro

The mountd daemon reads /etc/exports when started. To make NFS server changes take effect immediately, force mountd to reread /etc/exports:

# service mountd reload

Please refer to Section 12.7, “Using rc(8) Under FreeBSD” for more information about using rc scripts.

On a new server being configured with NFS services, the server can be started by running this command as root:

# service nfsd start

On the NFS client:

# service nfsclient restart

The client now has everything it needs to mount a remote file system. In these examples, the server's name is server and the client's name is client. For testing or to temporarily mount a remote file system, execute mount as root on client:

# mount server:/home /mnt

This mounts the server: /home file system to the client: /mnt mount point. The files and directories in the server /home file system will now be available on client, in the /mnt directory.

To mount a remote file system each time the client boots, add it to /etc/fstab:

server:/home /mnt nfs rw 0 0

The fstab(5) manual page lists all the available options.

29.3.3. Locking

Some applications (e.g., mutt) require file locking to operate correctly. In the case of NFS, rpc.lockd can be used for file locking. To enable it, add this line to /etc/rc.conf on both client and server:

rpc_lockd_enable="YES" rpc_statd_enable="YES"

Please note that this assumes that both NFS client and server are already configured.

Start the application, as root, with:

# service lockd start # service statd start

If locking is not required on the server, the NFS client can be configured to lock locally by passing -L to mount_nfs(8). Refer to the mount_nfs(8) manual page for further details.

29.3.4. Practical Uses

NFS has many practical uses. Some of the more common uses:

  • Share a CD-ROM or other media with any number of clients. It is often more convenient to install software on multiple machines from a single location.

  • On large networks, it is often more convenient to configure a central NFS server on which all user home directories are stored. Users can log into a client anywhere on the network and have access to their home directories.

  • Several clients may need access to the /usr/ports/distfiles directory. Sharing that directory allows for quick access to the source files without having to download them to each client.

29.3.5. Automatic Mounts with amd

Contributed by Wylie Stilwell.
Rewritten by Chern Lee.

amd(8) (the automatic mounter daemon) automatically mounts a remote file system whenever a file or directory within that file system is accessed. Filesystems that are inactive for a period of time will also be automatically unmounted by amd. amd provides an alternative to modifying /etc/fstab to list every client.

amd operates by attaching itself as an NFS server to the /host and /net directories. When a file is accessed within one of these directories, amd looks up the corresponding remote mount and automatically mounts it. /net is used to mount an exported file system from an IP address, while /host is used to mount an export from a remote hostname.

For instance, an attempt to access a file within /host/foobar/usr would tell amd to mount the /usr export on the host foobar.

Example 29.2. Mounting an Export with amd

showmount -e shows the exported file systems that can be mounted from the NFS server, foobar:

% showmount -e foobar Exports list on foobar: /usr /a % cd /host/foobar/usr

The output from showmount shows /usr as an export. When changing directories to /host/foobar/usr, amd intercepts the request and attempts to resolve the hostname foobar. If successful, amd automatically mounts the desired export.

amd is enabled by placing this line in /etc/rc.conf:


It can then be started using the FreeBSD rc(8) scripts or by using the service(8) command.

Custom flags can be passed to amd from the amd_flags environment variable. By default, amd_flags is set to:

amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"

/etc/amd.map defines the default options with which exports are mounted. /etc/amd.conf defines some of the more advanced features of amd.

Consult the amd(8) and amd.conf(5) manual pages for more information.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.