From owner-freebsd-doc@FreeBSD.ORG Tue Aug 13 15:50:00 2013 Return-Path: Delivered-To: freebsd-doc@smarthost.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 8E0F89AE for ; Tue, 13 Aug 2013 15:50:00 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 6C9D12088 for ; Tue, 13 Aug 2013 15:50:00 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.7/8.14.7) with ESMTP id r7DFo0tW045043 for ; Tue, 13 Aug 2013 15:50:00 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.7/8.14.7/Submit) id r7DFo0pd045042; Tue, 13 Aug 2013 15:50:00 GMT (envelope-from gnats) Resent-Date: Tue, 13 Aug 2013 15:50:00 GMT Resent-Message-Id: <201308131550.r7DFo0pd045042@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Ken Reed Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 2C4C6818 for ; Tue, 13 Aug 2013 15:42:28 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from oldred.freebsd.org (oldred.freebsd.org [8.8.178.121]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 1738B202C for ; Tue, 13 Aug 2013 15:42:28 +0000 (UTC) Received: from oldred.freebsd.org ([127.0.1.6]) by oldred.freebsd.org (8.14.5/8.14.7) with ESMTP id r7DFgRwb082984 for ; Tue, 13 Aug 2013 15:42:27 GMT (envelope-from nobody@oldred.freebsd.org) Received: (from nobody@localhost) by oldred.freebsd.org (8.14.5/8.14.5/Submit) id r7DFgRMD082983; Tue, 13 Aug 2013 15:42:27 GMT (envelope-from nobody) Message-Id: <201308131542.r7DFgRMD082983@oldred.freebsd.org> Date: Tue, 13 Aug 2013 15:42:27 GMT From: Ken Reed To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Subject: docs/181269: Network Servers - NFS Content Rewrite/Update X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 13 Aug 2013 15:50:00 -0000 >Number: 181269 >Category: docs >Synopsis: Network Servers - NFS Content Rewrite/Update >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Tue Aug 13 15:50:00 UTC 2013 >Closed-Date: >Last-Modified: >Originator: Ken Reed >Release: 9.1-RELEASE-p5 >Organization: >Environment: FreeBSD wolverine 9.1-RELEASE-p5 FreeBSD 9.1-RELEASE-p5 #0: Sat Jul 27 01:14:23 UTC 2013 root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC amd64 >Description: Rewrote, corrected, and updated the NFS section of the Network Servers section (chapter 29). >How-To-Repeat: >Fix: Patch attached with submission follows: Index: en_US.ISO8859-1/books/handbook/network-servers/chapter.xml =================================================================== --- en_US.ISO8859-1/books/handbook/network-servers/chapter.xml (revision 42527) +++ en_US.ISO8859-1/books/handbook/network-servers/chapter.xml (working copy) @@ -557,37 +557,40 @@ Network File System (NFS) NFS - Among the many different file systems that FreeBSD supports - is the Network File System, also known as NFS. NFS allows a system to share directories and - files with others over a network. By using NFS, users and programs can - access files on remote systems almost as if they were local - files. + &os; supports the Network File System + (NFS). + NFS + allows a server to share directories and + files with clients over a network. By using + NFS, + users and programs can access files on remote systems + as if they were stored locally. - Some of the most notable benefits that - NFS can provide are: + The most notable benefits that + NFS provides are: - Local workstations use less disk space because commonly - used data can be stored on a single machine and still remain - accessible to others over the network. + Data that would otherwise be duplicated on each + client can be kept in single location and accessed + by clients on the network. - There is no need for users to have separate home - directories on every network machine. Home directories - could be set up on the NFS server and - made available throughout the network. + Users home directories can be stored in one location + and accessed by their owners over the network. This also + has the benefit of simplified administration. For example, + backing up one location instead of several, security + policies on one file system, etc. - Storage devices such as floppy disks, CDROM drives, and - &iomegazip; drives can be used by other machines on the - network. This may reduce the number of removable media - drives throughout the network. + Storage devices such as floppy disks or + CD/DVD-ROM drives can be used + by other machines on the network. This would reduce + the number of removable media drives throughout + the network and provide a centralized location to + manage the usage and security of such devices. @@ -600,7 +603,7 @@ order for this to function properly a few processes have to be configured and running. - The server has to be running the following daemons: + The server must be running the following daemons: NFS server @@ -661,8 +664,8 @@ nfsiod. The nfsiod daemon services the requests from the NFS server. This is optional, and - improves performance, but is not required for normal and - correct operation. See the &man.nfsiod.8; manual page for + improves performance but is not required for normal + operation. See the &man.nfsiod.8; manual page for more information. @@ -674,15 +677,12 @@ configuration - NFS configuration is a relatively - straightforward process. The processes that need to be - running can all start at boot time with a few modifications - to /etc/rc.conf. + Enabling the NFS server + is straightforward. The processes that need + to be running can setup to be started at boot + time by adding these options to + /etc/rc.conf: - On the NFS server, make sure that the - following options are configured in the - /etc/rc.conf file: - rpcbind_enable="YES" nfs_server_enable="YES" mountd_flags="-r" @@ -690,24 +690,22 @@ mountd runs automatically whenever the NFS server is enabled. - On the client, make sure this option is present in - /etc/rc.conf: + Likewise, to enable the client, make sure this option + is defined in /etc/rc.conf: nfs_client_enable="YES" The /etc/exports file specifies which - file systems NFS should export (sometimes - referred to as share). Each line in - /etc/exports specifies a file system to - be exported and which machines have access to that file - system. Along with what machines have access to that file - system, access options may also be specified. There are many - such options that can be used in this file but only a few will - be mentioned here. Other options are discussed in - the &man.exports.5; manual page. + file systems the NFS server will + export (sometimes referred to as share). 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 that may + be specified. There are many such options that can be + used in this file but only a few will be mentioned here. + Other options are discussed in the &man.exports.5; + manual page. - Here are a few example /etc/exports - entries: NFS @@ -716,69 +714,76 @@ The following examples give an idea of how to export file systems, although the settings may be different depending on - the environment and network configuration. For instance, to - export the /cdrom directory to three - example machines that have the same domain name as the server - (hence the lack of a domain name for each) or have entries in - the /etc/hosts file. The - flag makes the exported file system - read-only. With this flag, the remote system will not be able - to write any changes to the exported file system. + the environment and network configuration. + Typical /etc/exports entries + may include: + + To export the /cdrom directory to + three clients that are either within the same domain as + the server or are defined in the server's + /etc/hosts file (allowing for + client reference by their short names): + /cdrom -ro host1 host2 host3 - The following line exports /home to - three hosts by IP address. This is a useful setup on - a private network without a DNS server + The -ro flag makes the exported file + system read-only, preventing the clients from making any + changes to the exported file system. + + The next example exports /home to + three clients by IP address. This is a useful setup for + networks that may not have a DNS server configured. Optionally the /etc/hosts file could be configured for internal hostnames; please review &man.hosts.5; for more information. The - flag allows the subdirectories to be - mount points. In other words, it will not mount the + -alldirs flag allows the 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 10.0.0.2 10.0.0.3 10.0.0.4 - The following line exports /a so that + This next line exports /a so that two clients from different domains may access the file system. The 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, - then even if a user has root access on - the remote system, he will not be able to modify files on - the exported file system. + the client's root user will be mapped + to the server's nobody account and will + be subject to the access limitations set for the + nobody user. /a -maproot=root host.example.com box.example.org - In order for a client to access an exported file system, - the client must have permission to do so. Make sure the - client is listed in /etc/exports. + For a client to have access to an exported file system, + make sure it is listed in + /etc/exports. - In /etc/exports, each line represents - the export information for one file system to one host. A - remote host can only be specified once per file system, and - may only have one default entry. For example, assume that - /usr is a single file system. The - following /etc/exports would be - invalid: + 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, and may only have one default entry. For example, + assume that /usr is a single file + system. The following /etc/exports + would be invalid: # Invalid when /usr is one file system /usr/src client /usr/ports client - One file system, /usr, has two lines + 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 properties of one file system exported to a given host - must all occur on one line. Lines without a client specified - are treated as a single host. This limits how file systems - may be exported; however, for most environments, this is not - an issue. + The properties of one file system, exported to a given + host, must within a single line. Lines without a client + specified are treated as a single host. This limits how + file systems may be exported; however, for most environments, + this is not an issue. The following is an example of a valid export list, where /usr and /exports @@ -793,11 +798,12 @@ /exports -alldirs -maproot=root client01 client02 /exports/obj -ro - The mountd daemon must be - forced to recheck the /etc/exports file - whenever it has been modified, so the changes can take effect. - This can be accomplished either by sending a HUP signal to the - running daemon: + The mountd daemon only reads + /etc/exports at start up. To make + NFS server changes immediately, it must be + forced to recheck the /etc/exports file. + The two recommended methods for executing immediate change + are: &prompt.root; kill -HUP `cat /var/run/mountd.pid` @@ -809,8 +815,9 @@ Please refer to for more information about using rc scripts. - NFS services can now be started by running the following - command, on the NFS server, as + On a new server being configured with + NFS services, the server can be started by + running the following command as root: &prompt.root; service nfsd start @@ -819,11 +826,12 @@ &prompt.root; service nfsclient restart - Now everything should be ready to actually mount a remote - file system. In these examples the server's name will be + The client now has everything it needs to mount a remote + file system. In these examples, the server's name will be server and the client's name will be client. For testing or to temporarily mount - a remote file system execute a command like this as + a remote file system execute the + mount command as root on the client: @@ -832,16 +840,15 @@ &prompt.root; mount server:/home /mnt - This will mount the /home directory - on the server at /mnt on the client. If + This will mount the server's /home + file system at /mnt on the client. If everything is set up correctly, the server's files should be - visible and available in the /mnt - directory. + visible and available in the client's + /mnt directory. To permanently mount a remote file system each time the - computer boots, add the file system to the - /etc/fstab file. Here is an - example: + client boots, add the remote file system to the + /etc/fstab file: server:/home /mnt nfs rw 0 0 @@ -855,25 +862,26 @@ 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 the following + can be used for file locking. To enable it, add this line to the /etc/rc.conf file on both client - and server (it is assumed that the NFS - client and server are configured already): + and server: rpc_lockd_enable="YES" rpc_statd_enable="YES" - Start the application by using: + Please note that this assumes that both + NFS client and server are already + configured. + Start the application, as root, by using: + &prompt.root; service lockd start &prompt.root; service statd start - If real locking between the NFS clients - and NFS server is not required, it is - possible to let the NFS client do locking - locally by passing to &man.mount.nfs.8;. - Refer to the &man.mount.nfs.8; manual page for further - details. + If locking is not required, the NFS + client can be configured to lock locally by passing + to &man.mount.nfs.8;. Refer to the + &man.mount.nfs.8; manual page for further details. @@ -880,7 +888,7 @@ Practical Uses NFS has many practical uses. Some of - the more common ones are listed below: + the more common uses: NFS @@ -888,25 +896,26 @@ - Set several machines to share a CDROM or other media - among them. This is cheaper and often a more convenient - method to install software on multiple machines. + Share a CD/DVD-ROM or other media + to any number of clients. This is cheaper and often a + more convenient method to install software on multiple + machines. - On large networks, it might be more convenient to - configure a central NFS server in which - to store all the user home directories. These home - directories can then be exported to the network so that - users would always have the same home directory, - regardless of which workstation they log in to. + On large networks, it is more convenient to + configure a central NFS server on which + all user home directories are stored. The exported + home directories can then be accessed by authorized + clients, allowing authenticated users access to + their data. - Several machines could have a common + Several clients could have a need for the /usr/ports/distfiles directory. This allows for quick access to the source files without - downloading them on each machine. + having to download them to each client. @@ -937,27 +946,28 @@ &man.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. Using + mounts or unmounts a remote file system. It performs a + mount whenever a file or directory within a managed, remote + file system is accessed. Likewise, + amd unmounts a remote file + system if it has been inactive for a period of time. Using amd provides a simple alternative - to permanent mounts, as permanent mounts are usually listed in + to permanent mounts which are permanently listed in /etc/fstab. - 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. + By default, 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. - An access to a file within + For instance, an attempt to access a file within /host/foobar/usr would tell - amd to attempt to mount the + amd to mount the /usr export on the host foobar. @@ -965,9 +975,10 @@ Mounting an Export with <application>amd</application> - The showmount command shows the - available mounts on a remote host. For example, to view the - mounts of a host named foobar: + The showmount, with the + -e flag, shows the exported file systems + available for mount from the remote NFS + server: &prompt.user; showmount -e foobar Exports list on foobar: @@ -976,23 +987,26 @@ &prompt.user; cd /host/foobar/usr - As seen in the example, the showmount + The output from showmount shows /usr as an export. When changing directories to /host/foobar/usr, - amd attempts to resolve the - hostname foobar and automatically mount the - desired export. + amd intercepts the request and + attempts to resolve the hostname foobar. + If successful, amd automatically + mounts the desired export. - amd can be started by the - startup scripts by placing the following lines in - /etc/rc.conf: + amd is enabled by placing + the following lines /etc/rc.conf: amd_enable="YES" - Additionally, custom flags can be passed to + It can then be started using the &os; &man.rc.8; scripts + or by using the &man.service.8; command. + + Custom flags can be passed to amd from the - amd_flags option. By default, - amd_flags is set to: + 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" @@ -1018,73 +1032,76 @@ Problems Integrating with Other Systems - Certain Ethernet adapters for ISA PC systems have - limitations which can lead to serious network problems, - particularly with NFS. This difficulty is not specific to - FreeBSD, but FreeBSD systems are affected by it. + Certain Ethernet adapters, for ISA bus-type PC + systems, have limitations which can lead to serious network + problems, particularly with NFS. While this is not + specific to &os;, &os; systems built on this type + of hardware are affected. - The problem nearly always occurs when (FreeBSD) PC systems - are networked with high-performance workstations, such as - those made by Silicon Graphics, Inc., and Sun Microsystems, - Inc. The NFS mount will work fine, and some operations may - succeed, but suddenly the server will seem to become - unresponsive to the client, even though requests to and from - other systems continue to be processed. This happens to the - client system, whether the client is the FreeBSD system or the - workstation. On many systems, there is no way to shut down - the client gracefully once this problem has manifested itself. - The only solution is often to reset the client, because the - NFS situation cannot be resolved. + The problem occurs when these systems are networked + with high-performance workstations, such as those made by + Silicon Graphics, Inc., and Sun Microsystems, Inc. The + NFS mount will work fine, and initial operations may + succeed. Eventually the server will become unresponsive + to the client, even though requests to and from + other systems continue unaffected. Once this has occurred, + there is no way to shut the client down gracefully. The + only solution is to reboot the client. Though the correct solution is to get a higher performance and capacity Ethernet adapter for the - FreeBSD system, there is a simple workaround that will allow - satisfactory operation. If the FreeBSD system is the - server, include the option - on the mount from the client. If the - FreeBSD system is the client, then mount - the NFS file system with the option . - These options may be specified using the fourth field of the - fstab entry on the client for automatic - mounts, or by using the parameter of the - &man.mount.8; command for manual mounts. + &os; system, there is a simple workaround. If the + &os; system is the server, include + the option -w=1024 in the client's + mount command. If the &os; system is + the client, then mount the NFS file + system with the option . These + options may be specified using the fourth field of the + /etc/fstab entry on the client for + automatic mounts, or by using the + parameter of the &man.mount.8; command for manual + mounts. - It should be noted that there is a different problem, - sometimes mistaken for this one, when the NFS servers and - clients are on different networks. If that is the case, make + It should be noted that there is a similar problem + requiring a different workaround. It often manifests + itself when the NFS servers and clients are on different + networks. If that is the case, make certain that the routers are routing the - necessary UDP information. + necessary UDP information. In other + words, a helper may need to be enabled for + the subnets and/or VLANs in question and may require + consultation with Network Administrators for proper + configuration. - In the following examples, fastws is the + In these examples, fastws is the host (interface) name of a high-performance workstation, and freebox is the host (interface) name of a - FreeBSD system with a lower-performance Ethernet adapter. - Also, /sharedfs will be the exported NFS - file system (see &man.exports.5;), and - /project will be the mount point on the - client for the exported file system. In all cases, note that - additional options, such as or - and may be desirable - in the application. + &os; system with a lower-performance Ethernet adapter. + The export is the /sharedfs file system + (see &man.exports.5;), and /project + will be the mount point on the client system. In all cases, + note that additional options, such as hard + or soft and bg may be + desirable in the application. - Examples for the FreeBSD system (freebox) - as the client in /etc/fstab on - freebox: - + Example of the &os; client, freebox + configured with a permanent mount in + /etc/fstab: fastws:/sharedfs /project nfs rw,-r=1024 0 0 - As a manual mount command on + Now, requesting a manual mount command on &os; client, freebox: &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project - Examples for the FreeBSD system as the server in + Examples for the &os; system, freebox + acting as the NFS server, with the client /etc/fstab on fastws: freebox:/sharedfs /project nfs rw,-w=1024 0 0 - As a manual mount command on + As a manual mount command on client, fastws: &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project @@ -1093,37 +1110,35 @@ without the above restrictions on the read or write size. - For anyone who cares, here is what happens when the - failure occurs, which also explains why it is unrecoverable. - NFS typically works with a block size of - 8 K (though it may do fragments of smaller sizes). Since - the maximum Ethernet packet is around 1500 bytes, the NFS - block gets split into multiple Ethernet - packets, even though it is still a single unit to the - upper-level code, and must be received, assembled, and - acknowledged as a unit. The - high-performance workstations can pump out the packets which - comprise the NFS unit one right after the other, just as close - together as the standard allows. On the smaller, lower - capacity cards, the later packets overrun the earlier packets - of the same unit before they can be transferred to the host - and the unit as a whole cannot be reconstructed or - acknowledged. As a result, the workstation will time out and - try again, but it will try again with the entire 8 K - unit, and the process will be repeated, ad infinitum. + The symptoms of this failure, and why it is unrecoverable, + are explained in the way NFS works. + NFS works with a default + block size of 8 K (though it may do + fragments of smaller sizes). Since the typical ethernet + packet is around 1500 bytes, the NFS + block gets split into multiple ethernet + packets. These packets then must be re-assembled and + acknowledged wholey, as they are + received by the recipient. High-performance workstations + can transmit these packets faster than the lower capacity + cards can receive them, resulting in a buffer overflow + condition. Packets being sent to the client cannot recover, + cannot be reconstructed, and therefore cannot be acknowledged. + Ultimately, the workstation will time out and try again. + Repeating the request, the server sends the entire 8 K + block, and the process is repeated. - By keeping the unit size below the Ethernet packet size + By keeping the block size below the Ethernet packet size limitation, we ensure that any complete Ethernet packet - received can be acknowledged individually, avoiding the - deadlock situation. + received can be acknowledged individually, avoiding this + buffer overflow situation. - Overruns may still occur when a high-performance - workstations is slamming data out to a PC system, but with the - better cards, such overruns are not guaranteed on NFS - units. When an overrun occurs, the units - affected will be retransmitted, and there will be a fair - chance that they will be received, assembled, and - acknowledged. + Buffer overflows (aka overruns) may still occur + when a high-performance workstation is transmitting data + to a client, but with better cards, such overruns are less + likely. When an overrun does occur, the blocks affected + will be retransmitted, and the client is more likely to + recover on its own. >Release-Note: >Audit-Trail: >Unformatted: