From nobody@FreeBSD.org  Tue Aug 13 15:42:28 2013
Return-Path: <nobody@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 2C4C6818
	for <freebsd-gnats-submit@FreeBSD.org>; 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 <freebsd-gnats-submit@FreeBSD.org>; 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 <freebsd-gnats-submit@FreeBSD.org>; 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 <kreed002@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Network Servers - NFS Content Rewrite/Update
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         181269
>Category:       docs
>Synopsis:       Network Servers - NFS Content Rewrite/Update
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Aug 13 15:50:00 UTC 2013
>Closed-Date:    Mon Sep 02 12:52:42 UTC 2013
>Last-Modified:  Mon Sep 02 12:52:42 UTC 2013
>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 @@
     <title>Network File System (NFS)</title>
 
     <indexterm><primary>NFS</primary></indexterm>
-    <para>Among the many different file systems that FreeBSD supports
-      is the Network File System, also known as <acronym role="Network
-      File System">NFS</acronym>.  <acronym role="Network File
-      System">NFS</acronym> allows a system to share directories and
-      files with others over a network.  By using <acronym
-      role="Network File System">NFS</acronym>, users and programs can
-      access files on remote systems almost as if they were local
-      files.</para>
+    <para>&os; supports the Network File System
+      (<acronym role="Network File System">NFS</acronym>).
+      <acronym role="Network File System">NFS</acronym>
+      allows a server to share directories and
+      files with clients over a network.  By using
+      <acronym role="Network File System">NFS</acronym>,
+      users and programs can access files on remote systems
+      as if they were stored locally.</para>
 
-    <para>Some of the most notable benefits that
-      <acronym>NFS</acronym> can provide are:</para>
+    <para>The most notable benefits that
+      <acronym>NFS</acronym> provides are:</para>
 
     <itemizedlist>
       <listitem>
-	<para>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.</para>
+	<para>Data that would otherwise be duplicated on each
+	  client can be kept in single location and accessed 
+	  by clients on the network.</para>
       </listitem>
 
       <listitem>
-	<para>There is no need for users to have separate home
-	  directories on every network machine.  Home directories
-	  could be set up on the <acronym>NFS</acronym> server and
-	  made available throughout the network.</para>
+	<para>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.</para>
       </listitem>
 
       <listitem>
-	<para>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.</para>
+	<para>Storage devices such as floppy disks or
+	  <acronym>CD/DVD-ROM</acronym> 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.</para>
       </listitem>
     </itemizedlist>
 
@@ -600,7 +603,7 @@
 	order for this to function properly a few processes have to be
 	configured and running.</para>
 
-      <para>The server has to be running the following daemons:</para>
+      <para>The server must be running the following daemons:</para>
       <indexterm>
 	<primary>NFS</primary>
 	<secondary>server</secondary>
@@ -661,8 +664,8 @@
 	<application>nfsiod</application>.  The
 	<application>nfsiod</application> daemon services the requests
 	from the <acronym>NFS</acronym> 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.</para>
     </sect2>
 
@@ -674,15 +677,12 @@
 	<secondary>configuration</secondary>
       </indexterm>
 
-      <para><acronym>NFS</acronym> configuration is a relatively
-	straightforward process.  The processes that need to be
-	running can all start at boot time with a few modifications
-	to <filename>/etc/rc.conf</filename>.</para>
+      <para>Enabling the <acronym>NFS</acronym> server
+	is straightforward.  The processes that need
+	to be running can setup to be started at boot
+	time by adding these options to
+	<filename>/etc/rc.conf</filename>:</para>
 
-      <para>On the <acronym>NFS</acronym> server, make sure that the
-	following options are configured in the
-	<filename>/etc/rc.conf</filename> file:</para>
-
       <programlisting>rpcbind_enable="YES"
 nfs_server_enable="YES"
 mountd_flags="-r"</programlisting>
@@ -690,24 +690,22 @@
       <para><application>mountd</application> runs automatically
 	whenever the <acronym>NFS</acronym> server is enabled.</para>
 
-      <para>On the client, make sure this option is present in
-	<filename>/etc/rc.conf</filename>:</para>
+      <para>Likewise, to enable the client, make sure this option
+	is defined in <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>nfs_client_enable="YES"</programlisting>
 
       <para>The <filename>/etc/exports</filename> file specifies which
-	file systems <acronym>NFS</acronym> should export (sometimes
-	referred to as <quote>share</quote>).  Each line in
-	<filename>/etc/exports</filename> 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.</para>
+	file systems the <acronym>NFS</acronym> server will
+	export (sometimes referred to as <quote>share</quote>).  Each
+	line in <filename>/etc/exports</filename> 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.</para>
 
-      <para>Here are a few example <filename>/etc/exports</filename>
-	entries:</para>
 
       <indexterm>
 	<primary>NFS</primary>
@@ -716,69 +714,76 @@
 
       <para>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 <filename>/cdrom</filename> 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 <filename>/etc/hosts</filename> file.  The
-	<option>-ro</option> 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.</para>
+	the environment and network configuration.</para>
 
+      <para>Typical <filename>/etc/exports</filename> entries
+	may include:</para>
+
+      <para>To export the <filename>/cdrom</filename> directory to
+	three clients that are either within the same domain as
+	the server or are defined in the server's
+	<filename>/etc/hosts</filename> file (allowing for
+	client reference by their short names):</para>
+
       <programlisting>/cdrom -ro host1 host2 host3</programlisting>
 
-      <para>The following line exports <filename>/home</filename> to
-	three hosts by IP address.  This is a useful setup on
-	a private network without a <acronym>DNS</acronym> server
+      <para>The <literal>-ro</literal> flag makes the exported file
+	system read-only, preventing the clients from making any
+	changes to the exported file system.</para>
+
+      <para>The next example exports <filename>/home</filename> to
+	three clients by IP address.  This is a useful setup for
+	networks that may not have a <acronym>DNS</acronym> server
 	configured.  Optionally the <filename>/etc/hosts</filename>
 	file could be configured for internal hostnames; please review
 	&man.hosts.5; for more information.  The
-	<option>-alldirs</option> flag allows the subdirectories to be
-	mount points.  In other words, it will not mount the
+	<literal>-alldirs</literal> 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.</para>
 
       <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
 
-      <para>The following line exports <filename>/a</filename> so that
+      <para>This next line exports <filename>/a</filename> so that
 	two clients from different domains may access the file system.
 	The <option>-maproot=root</option> flag allows the
 	<username>root</username> user on the remote system to write
 	data on the exported file system as <username>root</username>.
 	If the <literal>-maproot=root</literal> flag is not specified,
-	then even if a user has <username>root</username> access on
-	the remote system, he will not be able to modify files on
-	the exported file system.</para>
+	the client's <username>root</username> user will be mapped
+	to the server's <username>nobody</username> account and will
+	be subject to the access limitations set for the
+	<username>nobody</username> user.</para>
 
       <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
 
-      <para>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 <filename>/etc/exports</filename>.</para>
+      <para>For a client to have access to an exported file system,
+	make sure it is listed in
+	<filename>/etc/exports</filename>.</para>
 
-      <para>In <filename>/etc/exports</filename>, 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
-	<filename>/usr</filename> is a single file system.  The
-	following <filename>/etc/exports</filename> would be
-	invalid:</para>
+      <para>In <filename>/etc/exports</filename>, 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 <filename>/usr</filename> is a single file
+	system.  The following <filename>/etc/exports</filename>
+	would be invalid:</para>
 
       <programlisting># Invalid when /usr is one file system
 /usr/src   client
 /usr/ports client</programlisting>
 
-      <para>One file system, <filename>/usr</filename>, has two lines
+      <para>The <filename>/usr</filename> file system has two lines
 	specifying exports to the same host, <hostid>client</hostid>.
 	The correct format for this situation is:</para>
 
       <programlisting>/usr/src /usr/ports  client</programlisting>
 
-      <para>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.</para>
+      <para>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.</para>
 
       <para>The following is an example of a valid export list, where
 	<filename>/usr</filename> and <filename>/exports</filename>
@@ -793,11 +798,12 @@
 /exports -alldirs -maproot=root      client01 client02
 /exports/obj -ro</programlisting>
 
-      <para>The <application>mountd</application> daemon must be
-	forced to recheck the <filename>/etc/exports</filename> 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:</para>
+      <para>The <application>mountd</application> daemon only reads
+	<filename>/etc/exports</filename> at start up.  To make
+	<acronym>NFS</acronym> server changes immediately, it must be
+	forced to recheck the <filename>/etc/exports</filename> file.
+	The two recommended methods for executing immediate change
+	are:</para>
 
       <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 
@@ -809,8 +815,9 @@
       <para>Please refer to <xref linkend="configtuning-rcd"/> for
 	more information about using rc scripts.</para>
 
-      <para>NFS services can now be started by running the following
-	command, on the <acronym>NFS</acronym> server, as
+      <para>On a new server being configured with
+	<acronym>NFS</acronym> services, the server can be started by
+	running the following command as
 	<username>root</username>:</para>
 
       <screen>&prompt.root; <userinput>service nfsd start</userinput></screen>
@@ -819,11 +826,12 @@
 
       <screen>&prompt.root; <userinput>service nfsclient restart</userinput></screen>
 
-      <para>Now everything should be ready to actually mount a remote
-	file system.  In these examples the server's name will be
+      <para>The client now has everything it needs to mount a remote
+	file system.  In these examples, the server's name will be
 	<hostid>server</hostid> and the client's name will be
 	<hostid>client</hostid>.  For testing or to temporarily mount
-	a remote file system execute a command like this as
+	a remote file system execute the
+	<application>mount</application> command as
 	<username>root</username> on the client:</para>
 
       <indexterm>
@@ -832,16 +840,15 @@
       </indexterm>
       <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
 
-      <para>This will mount the <filename>/home</filename> directory
-	on the server at <filename>/mnt</filename> on the client.  If
+      <para>This will mount the server's <filename>/home</filename>
+	file system at <filename>/mnt</filename> on the client.  If
 	everything is set up correctly, the server's files should be
-	visible and available in the <filename>/mnt</filename>
-	directory.</para>
+	visible and available in the client's
+	<filename>/mnt</filename> directory.</para>
 
       <para>To permanently mount a remote file system each time the
-	computer boots, add the file system to the
-	<filename>/etc/fstab</filename> file.  Here is an
-	example:</para>
+	client boots, add the remote file system to the
+	<filename>/etc/fstab</filename> file:</para>
 
       <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
 
@@ -855,25 +862,26 @@
       <para>Some applications (e.g., <application>mutt</application>)
 	require file locking to operate correctly.  In the case of
 	<acronym>NFS</acronym>, <application>rpc.lockd</application>
-	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 <filename>/etc/rc.conf</filename> file on both client
-	and server (it is assumed that the <acronym>NFS</acronym>
-	client and server are configured already):</para>
+	and server:</para>
 
       <programlisting>rpc_lockd_enable="YES"
 rpc_statd_enable="YES"</programlisting>
 
-      <para>Start the application by using:</para>
+      <para>Please note that this assumes that both
+	<acronym>NFS</acronym> client and server are already
+	configured.</para>
 
+      <para>Start the application, as root, by using:</para>
+
       <screen>&prompt.root; <userinput>service lockd start</userinput>
 &prompt.root; <userinput>service statd start</userinput></screen>
 
-      <para>If real locking between the <acronym>NFS</acronym> clients
-	and <acronym>NFS</acronym> server is not required, it is
-	possible to let the <acronym>NFS</acronym> client do locking
-	locally by passing <option>-L</option> to &man.mount.nfs.8;.
-	Refer to the &man.mount.nfs.8; manual page for further
-	details.</para>
+      <para>If locking is not required, the <acronym>NFS</acronym>
+	client can be configured to lock locally by passing
+	<option>-L</option> to &man.mount.nfs.8;.  Refer to the
+	&man.mount.nfs.8; manual page for further details.</para>
     </sect2>
 
     <sect2>
@@ -880,7 +888,7 @@
       <title>Practical Uses</title>
 
       <para><acronym>NFS</acronym> has many practical uses.  Some of
-	the more common ones are listed below:</para>
+	the more common uses:</para>
 
       <indexterm>
 	<primary>NFS</primary>
@@ -888,25 +896,26 @@
       </indexterm>
       <itemizedlist>
 	<listitem>
-	  <para>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.</para>
+	  <para>Share a <acronym>CD/DVD-ROM</acronym> or other media
+	    to any number of clients.  This is cheaper and often a
+	    more convenient method to install software on multiple
+	    machines.</para>
 	</listitem>
 
 	<listitem>
-	  <para>On large networks, it might be more convenient to
-	    configure a central <acronym>NFS</acronym> 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.</para>
+	  <para>On large networks, it is more convenient to
+	    configure a central <acronym>NFS</acronym> 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.</para>
 	</listitem>
 
 	<listitem>
-	  <para>Several machines could have a common
+	  <para>Several clients could have a need for the
 	    <filename>/usr/ports/distfiles</filename> directory.  This
 	    allows for quick access to the source files without
-	    downloading them on each machine.</para>
+	    having to download them to each client.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
@@ -937,27 +946,28 @@
       </indexterm>
 
       <para>&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 <application>amd</application>.  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,
+	<application>amd</application> unmounts a remote file
+	system if it has been inactive for a period of time.  Using
 	<application>amd</application> provides a simple alternative
-	to permanent mounts, as permanent mounts are usually listed in
+	to permanent mounts which are permanently listed in
 	<filename>/etc/fstab</filename>.</para>
 
-      <para><application>amd</application> operates by attaching
-	itself as an NFS server to the <filename>/host</filename> and
-	<filename>/net</filename> directories.  When a file is
-	accessed within one of these directories,
-	<application>amd</application> looks up the corresponding
-	remote mount and automatically mounts it.
+      <para>By default, <application>amd</application> operates
+	by attaching itself as an NFS server to the
+	<filename>/host</filename> and <filename>/net</filename>
+	directories.  When a file is accessed within one of these
+	directories, <application>amd</application> looks up the
+	corresponding remote mount and automatically mounts it.
 	<filename>/net</filename> is used to mount an exported file
 	system from an IP address, while <filename>/host</filename> is
 	used to mount an export from a remote hostname.</para>
 
-      <para>An access to a file within
+      <para>For instance, an attempt to access a file within
 	<filename>/host/foobar/usr</filename> would tell
-	<application>amd</application> to attempt to mount the
+	<application>amd</application> to mount the
 	<filename>/usr</filename> export on the host
 	<hostid>foobar</hostid>.</para>
 
@@ -965,9 +975,10 @@
 	<title>Mounting an Export with
 	  <application>amd</application></title>
 
-	<para>The <command>showmount</command> command shows the
-	  available mounts on a remote host.  For example, to view the
-	  mounts of a host named <hostid>foobar</hostid>:</para>
+	<para>The <command>showmount</command>, with the
+	  <literal>-e</literal> flag, shows the exported file systems
+	  available for mount from the remote <acronym>NFS</acronym>
+	  server:</para>
 
 	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
 Exports list on foobar:
@@ -976,23 +987,26 @@
 &prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>
       </example>
 
-      <para>As seen in the example, the <command>showmount</command>
+      <para>The output from <command>showmount</command>
 	shows <filename>/usr</filename> as an export.  When changing
 	directories to <filename>/host/foobar/usr</filename>,
-	<application>amd</application> attempts to resolve the
-	hostname <hostid>foobar</hostid> and automatically mount the
-	desired export.</para>
+	<application>amd</application> intercepts the request and
+	attempts to resolve the hostname <hostid>foobar</hostid>.
+	If successful, <application>amd</application> automatically
+	mounts the desired export.</para>
 
-      <para><application>amd</application> can be started by the
-	startup scripts by placing the following lines in
-	<filename>/etc/rc.conf</filename>:</para>
+      <para><application>amd</application> is enabled by placing
+	the following lines <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>amd_enable="YES"</programlisting>
 
-      <para>Additionally, custom flags can be passed to
+      <para>It can then be started using the &os; &man.rc.8; scripts
+	or by using the &man.service.8; command.</para>
+
+      <para>Custom flags can be passed to
 	<application>amd</application> from the
-	<varname>amd_flags</varname> option.  By default,
-	<varname>amd_flags</varname> is set to:</para>
+	<varname>amd_flags</varname> environment variable.  By
+	default, <varname>amd_flags</varname> is set to:</para>
 
       <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
 
@@ -1018,73 +1032,76 @@
       </sect2info>
       <title>Problems Integrating with Other Systems</title>
 
-      <para>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.</para>
+      <para>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.</para>
 
-      <para>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.</para>
+      <para>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.</para>
 
       <para>Though the <quote>correct</quote> 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
-	<emphasis>server</emphasis>, include the option
-	<option>-w=1024</option> on the mount from the client.  If the
-	FreeBSD system is the <emphasis>client</emphasis>, then mount
-	the NFS file system with the option <option>-r=1024</option>.
-	These options may be specified using the fourth field of the
-	<filename>fstab</filename> entry on the client for automatic
-	mounts, or by using the <option>-o</option> parameter of the
-	&man.mount.8; command for manual mounts.</para>
+	&os; system, there is a simple workaround.  If the
+	&os; system is the <emphasis>server</emphasis>, include
+	the option <literal>-w=1024</literal> in the client's
+	<command>mount</command> command.  If the &os; system is
+	the <emphasis>client</emphasis>, then mount the NFS file
+	system with the option <option>-r=1024</option>.  These
+	options may be specified using the fourth field of the
+	<filename>/etc/fstab</filename> entry on the client for
+	automatic mounts, or by using the <option>-o</option>
+	parameter of the &man.mount.8; command for manual
+	mounts.</para>
 
-      <para>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
+      <para>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
 	<emphasis>certain</emphasis> that the routers are routing the
-	necessary <acronym>UDP</acronym> information.</para>
+	necessary <acronym>UDP</acronym> information.  In other
+	words, a <quote>helper</quote> may need to be enabled for
+	the subnets and/or VLANs in question and may require
+	consultation with Network Administrators for proper
+	configuration.</para>
 
-      <para>In the following examples, <hostid>fastws</hostid> is the
+      <para>In these examples, <hostid>fastws</hostid> is the
 	host (interface) name of a high-performance workstation, and
 	<hostid>freebox</hostid> is the host (interface) name of a
-	FreeBSD system with a lower-performance Ethernet adapter.
-	Also, <filename>/sharedfs</filename> will be the exported NFS
-	file system (see &man.exports.5;), and
-	<filename>/project</filename> will be the mount point on the
-	client for the exported file system.  In all cases, note that
-	additional options, such as <option>hard</option> or
-	<option>soft</option> and <option>bg</option> may be desirable
-	in the application.</para>
+	&os; system with a lower-performance Ethernet adapter.
+	The export is the <filename>/sharedfs</filename> file system
+	(see &man.exports.5;), and <filename>/project</filename>
+	will be the mount point on the client system.  In all cases,
+	note that additional options, such as <literal>hard</literal>
+	or <literal>soft</literal> and <literal>bg</literal> may be
+	desirable in the application.</para>
 
-      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>)
-	as the client in <filename>/etc/fstab</filename> on
-	<hostid>freebox</hostid>:</para>
-
+      <para>Example of the &os; client, <hostid>freebox</hostid>
+	configured with a permanent mount in
+	<filename>/etc/fstab</filename>:</para>
       <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
 
-      <para>As a manual mount command on
+      <para>Now, requesting a manual mount command on &os; client,
 	<hostid>freebox</hostid>:</para>
 
       <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
 
-      <para>Examples for the FreeBSD system as the server in
+      <para>Examples for the &os; system, <hostid>freebox</hostid>
+	acting as the <acronym>NFS</acronym> server, with the client
 	<filename>/etc/fstab</filename> on
 	<hostid>fastws</hostid>:</para>
 
       <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
 
-      <para>As a manual mount command on
+      <para>As a manual mount command on client,
 	<hostid>fastws</hostid>:</para>
 
       <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
@@ -1093,37 +1110,35 @@
 	without the above restrictions on the read or write
 	size.</para>
 
-      <para>For anyone who cares, here is what happens when the
-	failure occurs, which also explains why it is unrecoverable.
-	NFS typically works with a <quote>block</quote> size of
-	8&nbsp;K (though it may do fragments of smaller sizes).  Since
-	the maximum Ethernet packet is around 1500&nbsp;bytes, the NFS
-	<quote>block</quote> 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
-	<emphasis>acknowledged</emphasis> 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&nbsp;K
-	unit, and the process will be repeated, ad infinitum.</para>
+      <para>The symptoms of this failure, and why it is unrecoverable,
+	are explained in the way <acronym>NFS</acronym> works.
+	<acronym>NFS</acronym> works with a default
+	<quote>block</quote> size of 8&nbsp;K (though it may do
+	fragments of smaller sizes).  Since the typical ethernet
+	packet is around 1500&nbsp;bytes, the NFS
+	<quote>block</quote> gets split into multiple ethernet
+	packets.  These packets then must be re-assembled and
+	<emphasis>acknowledged</emphasis> 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&nbsp;K
+	block, and the process is repeated.</para>
 
-      <para>By keeping the unit size below the Ethernet packet size
+      <para>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.</para>
+	received can be acknowledged individually, avoiding this
+	buffer overflow situation.</para>
 
-      <para>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
-	<quote>units</quote>.  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.</para>
+      <para>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.</para>
     </sect2>
   </sect1>
 


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Tue Aug 13 16:00:30 UTC 2013 
Responsible-Changed-Why:  
Take. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=181269 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/181269: commit references a PR
Date: Thu, 29 Aug 2013 01:46:23 +0000 (UTC)

 Author: wblock
 Date: Thu Aug 29 01:46:14 2013
 New Revision: 42602
 URL: http://svnweb.freebsd.org/changeset/doc/42602
 
 Log:
   Patch from Ken Reed to update and improve the NFS section.  Modified
   version of the patch included with PR.
   
   PR:		docs/181269
   Submitted by:	Ken Reed <kreed002@gmail.com>
 
 Modified:
   head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
 
 Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
 ==============================================================================
 --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml	Thu Aug 29 00:52:20 2013	(r42601)
 +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml	Thu Aug 29 01:46:14 2013	(r42602)
 @@ -557,37 +557,40 @@ server-program-arguments</programlisting
      <title>Network File System (NFS)</title>
  
      <indexterm><primary>NFS</primary></indexterm>
 -    <para>Among the many different file systems that FreeBSD supports
 -      is the Network File System, also known as <acronym role="Network
 -      File System">NFS</acronym>.  <acronym role="Network File
 -      System">NFS</acronym> allows a system to share directories and
 -      files with others over a network.  By using <acronym
 -      role="Network File System">NFS</acronym>, users and programs can
 -      access files on remote systems almost as if they were local
 -      files.</para>
 +    <para>&os; supports the Network File System
 +      (<acronym>NFS</acronym>), which allows a server to share
 +      directories and files with clients over a network.  With
 +      <acronym>NFS</acronym>, users and programs can access files
 +      on remote systems as if they were stored locally.</para>
  
 -    <para>Some of the most notable benefits that
 -      <acronym>NFS</acronym> can provide are:</para>
 +    <para>The most notable benefits that
 +      <acronym>NFS</acronym> provides are:</para>
  
      <itemizedlist>
        <listitem>
 -	<para>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.</para>
 +	<para>Data that would otherwise be duplicated on each client
 +	  can be kept in a single location and accessed by clients
 +	  on the network.</para>
        </listitem>
  
        <listitem>
 -	<para>There is no need for users to have separate home
 -	  directories on every network machine.  Home directories
 -	  could be set up on the <acronym>NFS</acronym> server and
 -	  made available throughout the network.</para>
 +	<para>User home directories can be stored in one location
 +	  and accessed by their owners over the network.</para>
        </listitem>
  
        <listitem>
 -	<para>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.</para>
 +	<para>Administration of <acronym>NFS</acronym> exports is
 +	  also simplified.  For example, there is only one file
 +	  system where security or backup policies must be
 +	  set.</para>
 +      </listitem>
 +
 +      <listitem>
 +	<para>Removable media storage devices, such as floppy disks
 +	  or <acronym>CD-ROM</acronym> drives, can be used by other
 +	  machines on the network.  This reduces the number of devices
 +	  throughout the network and provides a centralized location
 +	  to manage their security.</para>
        </listitem>
      </itemizedlist>
  
 @@ -600,7 +603,7 @@ server-program-arguments</programlisting
  	order for this to function properly a few processes have to be
  	configured and running.</para>
  
 -      <para>The server has to be running the following daemons:</para>
 +      <para>These daemons must be running on the server:</para>
        <indexterm>
  	<primary>NFS</primary>
  	<secondary>server</secondary>
 @@ -657,13 +660,8 @@ server-program-arguments</programlisting
  	</tgroup>
        </informaltable>
  
 -      <para>The client can also run a daemon, known as
 -	<application>nfsiod</application>.  The
 -	<application>nfsiod</application> daemon services the requests
 -	from the <acronym>NFS</acronym> server.  This is optional, and
 -	improves performance, but is not required for normal and
 -	correct operation.  See the &man.nfsiod.8; manual page for
 -	more information.</para>
 +      <para>Running &man.nfsiod.8; can improve performance on the
 +	client, but is not required.</para>
      </sect2>
  
      <sect2 id="network-configuring-nfs">
 @@ -674,14 +672,11 @@ server-program-arguments</programlisting
  	<secondary>configuration</secondary>
        </indexterm>
  
 -      <para><acronym>NFS</acronym> configuration is a relatively
 -	straightforward process.  The processes that need to be
 -	running can all start at boot time with a few modifications
 -	to <filename>/etc/rc.conf</filename>.</para>
 -
 -      <para>On the <acronym>NFS</acronym> server, make sure that the
 -	following options are configured in the
 -	<filename>/etc/rc.conf</filename> file:</para>
 +      <para>Enabling the <acronym>NFS</acronym> server
 +	is straightforward.  The required processes
 +	can be set to start at boot time by adding
 +	these options to
 +	<filename>/etc/rc.conf</filename>:</para>
  
        <programlisting>rpcbind_enable="YES"
  nfs_server_enable="YES"
 @@ -690,99 +685,101 @@ mountd_flags="-r"</programlisting>
        <para><application>mountd</application> runs automatically
  	whenever the <acronym>NFS</acronym> server is enabled.</para>
  
 -      <para>On the client, make sure this option is present in
 +      <para>To enable the client, set this option in
  	<filename>/etc/rc.conf</filename>:</para>
  
        <programlisting>nfs_client_enable="YES"</programlisting>
  
 -      <para>The <filename>/etc/exports</filename> file specifies which
 -	file systems <acronym>NFS</acronym> should export (sometimes
 -	referred to as <quote>share</quote>).  Each line in
 +      <para><filename>/etc/exports</filename> specifies which
 +	file systems the <acronym>NFS</acronym> server will
 +	export.  Each line in
  	<filename>/etc/exports</filename> 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.</para>
 -
 -      <para>Here are a few example <filename>/etc/exports</filename>
 -	entries:</para>
 +	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 &man.exports.5; for the full list of
 +	options.</para>
  
        <indexterm>
  	<primary>NFS</primary>
  	<secondary>export examples</secondary>
        </indexterm>
  
 -      <para>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 <filename>/cdrom</filename> 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 <filename>/etc/hosts</filename> file.  The
 -	<option>-ro</option> 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.</para>
 -
 -      <programlisting>/cdrom -ro host1 host2 host3</programlisting>
 -
 -      <para>The following line exports <filename>/home</filename> to
 -	three hosts by IP address.  This is a useful setup on
 -	a private network without a <acronym>DNS</acronym> server
 -	configured.  Optionally the <filename>/etc/hosts</filename>
 -	file could be configured for internal hostnames; please review
 -	&man.hosts.5; for more information.  The
 -	<option>-alldirs</option> 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.</para>
 +      <para>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.</para>
 +
 +      <para>This example shows how to export the
 +	<filename class="directory">/cdrom</filename> directory to
 +	three clients called <replaceable>alpha</replaceable>,
 +	<replaceable>bravo</replaceable>, and
 +	<replaceable>charlie</replaceable>:</para>
 +
 +      <programlisting>/cdrom -ro <replaceable>alpha</replaceable> <replaceable>bravo</replaceable> <replaceable>charlie</replaceable></programlisting>
 +
 +      <para>The <literal>-ro</literal> flag makes the file systems
 +	read-only, preventing clients from making any changes to
 +	those exported file systems.</para>
 +
 +      <para>The next example exports
 +	<filename class="directory">/home</filename> to three clients
 +	by IP address.  This can be useful for networks without
 +	<acronym>DNS</acronym>.  Optionally,
 +	<filename>/etc/hosts</filename> could be configured for
 +	internal hostnames; please review &man.hosts.5; for more
 +	information.  The <literal>-alldirs</literal> 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.</para>
  
        <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
  
 -      <para>The following line exports <filename>/a</filename> so that
 -	two clients from different domains may access the file system.
 +      <para>This next line exports
 +	<filename class="directory">/a</filename> so that two clients
 +	from different domains may access the file system.
  	The <option>-maproot=root</option> flag allows the
  	<username>root</username> user on the remote system to write
  	data on the exported file system as <username>root</username>.
  	If the <literal>-maproot=root</literal> flag is not specified,
 -	then even if a user has <username>root</username> access on
 -	the remote system, he will not be able to modify files on
 -	the exported file system.</para>
 +	the client's <username>root</username> user will be mapped
 +	to the server's <username>nobody</username> account and will
 +	be subject to the access limitations defined for user,
 +	<username>nobody</username>.</para>
  
        <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
  
 -      <para>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 <filename>/etc/exports</filename>.</para>
 -
 -      <para>In <filename>/etc/exports</filename>, 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
 -	<filename>/usr</filename> is a single file system.  The
 -	following <filename>/etc/exports</filename> would be
 -	invalid:</para>
 +      <para>For a client to have access to an exported file system,
 +	the client must be listed in
 +	<filename>/etc/exports</filename>.</para>
 +
 +      <para>In <filename>/etc/exports</filename>, 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
 +	<filename class="directory">/usr</filename> is a single file
 +	system.  This entry, in <filename>/etc/exports</filename>,
 +	would be invalid:</para>
  
        <programlisting># Invalid when /usr is one file system
  /usr/src   client
  /usr/ports client</programlisting>
  
 -      <para>One file system, <filename>/usr</filename>, has two lines
 +      <para>The <filename class="directory">/usr</filename> file
 +	system has two lines
  	specifying exports to the same host, <hostid>client</hostid>.
  	The correct format for this situation is:</para>
  
        <programlisting>/usr/src /usr/ports  client</programlisting>
  
 -      <para>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.</para>
 +      <para>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.</para>
  
        <para>The following is an example of a valid export list, where
 -	<filename>/usr</filename> and <filename>/exports</filename>
 -	are local file systems:</para>
 +	<filename class="directory">/usr</filename> and
 +	<filename class="directory">/exports</filename> are local
 +	file systems:</para>
  
        <programlisting># Export src and ports to client01 and client02, but only
  # client01 has root privileges on it
 @@ -793,24 +790,20 @@ mountd_flags="-r"</programlisting>
  /exports -alldirs -maproot=root      client01 client02
  /exports/obj -ro</programlisting>
  
 -      <para>The <application>mountd</application> daemon must be
 -	forced to recheck the <filename>/etc/exports</filename> 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:</para>
 -
 -      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 -
 -      <para>or by invoking the <command>mountd</command> &man.rc.8;
 -	script with the appropriate parameter:</para>
 +      <para>The <application>mountd</application> daemon reads
 +	<filename>/etc/exports</filename> when started.  To make
 +	<acronym>NFS</acronym> server changes take effect immediately,
 +	force <application>mountd</application> to reread
 +	<filename>/etc/exports</filename>:</para>
  
 -      <screen>&prompt.root; <userinput>service mountd onereload</userinput></screen>
 +      <screen>&prompt.root; <userinput>service mountd reload</userinput></screen>
  
        <para>Please refer to <xref linkend="configtuning-rcd"/> for
  	more information about using rc scripts.</para>
  
 -      <para>NFS services can now be started by running the following
 -	command, on the <acronym>NFS</acronym> server, as
 +      <para>On a new server being configured with
 +	<acronym>NFS</acronym> services, the server can be
 +	started by running this command as
  	<username>root</username>:</para>
  
        <screen>&prompt.root; <userinput>service nfsd start</userinput></screen>
 @@ -819,12 +812,13 @@ mountd_flags="-r"</programlisting>
  
        <screen>&prompt.root; <userinput>service nfsclient restart</userinput></screen>
  
 -      <para>Now everything should be ready to actually mount a remote
 -	file system.  In these examples the server's name will be
 -	<hostid>server</hostid> and the client's name will be
 +      <para>The client now has everything it needs to mount a remote
 +	file system.  In these examples, the server's name is
 +	<hostid>server</hostid> and the client's name is
  	<hostid>client</hostid>.  For testing or to temporarily mount
 -	a remote file system execute a command like this as
 -	<username>root</username> on the client:</para>
 +	a remote file system, execute
 +	<application>mount</application> as
 +	<username>root</username> on <hostid>client</hostid>:</para>
  
        <indexterm>
  	<primary>NFS</primary>
 @@ -832,16 +826,20 @@ mountd_flags="-r"</programlisting>
        </indexterm>
        <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
  
 -      <para>This will mount the <filename>/home</filename> directory
 -	on the server at <filename>/mnt</filename> on the client.  If
 -	everything is set up correctly, the server's files should be
 -	visible and available in the <filename>/mnt</filename>
 -	directory.</para>
 -
 -      <para>To permanently mount a remote file system each time the
 -	computer boots, add the file system to the
 -	<filename>/etc/fstab</filename> file.  Here is an
 -	example:</para>
 +      <para>This mounts the
 +	<hostid>server</hostid>:
 +	<filename class="directory">/home</filename>
 +	file system to the
 +	<hostid>client</hostid>:
 +	<filename class="directory">/mnt</filename> mount
 +	point.  The files and directories in the
 +	<hostid>server</hostid>
 +	<filename class="directory">/home</filename> file system will
 +	now be available on <hostid>client</hostid>, in the
 +	<filename class="directory">/mnt</filename> directory.</para>
 +
 +      <para>To mount a remote file system each time the client
 +	boots, add it to <filename>/etc/fstab</filename>:</para>
  
        <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
  
 @@ -855,32 +853,35 @@ mountd_flags="-r"</programlisting>
        <para>Some applications (e.g., <application>mutt</application>)
  	require file locking to operate correctly.  In the case of
  	<acronym>NFS</acronym>, <application>rpc.lockd</application>
 -	can be used for file locking.  To enable it, add the following
 -	to the <filename>/etc/rc.conf</filename> file on both client
 -	and server (it is assumed that the <acronym>NFS</acronym>
 -	client and server are configured already):</para>
 +	can be used for file locking.  To enable it, add this line to
 +	<filename>/etc/rc.conf</filename> on both client
 +	and server:</para>
  
        <programlisting>rpc_lockd_enable="YES"
  rpc_statd_enable="YES"</programlisting>
  
 -      <para>Start the application by using:</para>
 +      <para>Please note that this assumes that both
 +	<acronym>NFS</acronym> client and server are already
 +	configured.</para>
 +
 +      <para>Start the application, as
 +	<username>root</username>, with:</para>
  
        <screen>&prompt.root; <userinput>service lockd start</userinput>
  &prompt.root; <userinput>service statd start</userinput></screen>
  
 -      <para>If real locking between the <acronym>NFS</acronym> clients
 -	and <acronym>NFS</acronym> server is not required, it is
 -	possible to let the <acronym>NFS</acronym> client do locking
 -	locally by passing <option>-L</option> to &man.mount.nfs.8;.
 -	Refer to the &man.mount.nfs.8; manual page for further
 -	details.</para>
 +      <para>If locking is not required on the server, the
 +	<acronym>NFS</acronym> client can be configured to
 +	lock locally by passing <option>-L</option> to
 +	&man.mount.nfs.8;.  Refer to the &man.mount.nfs.8;
 +	manual page for further details.</para>
      </sect2>
  
      <sect2>
        <title>Practical Uses</title>
  
        <para><acronym>NFS</acronym> has many practical uses.  Some of
 -	the more common ones are listed below:</para>
 +	the more common uses:</para>
  
        <indexterm>
  	<primary>NFS</primary>
 @@ -888,25 +889,26 @@ rpc_statd_enable="YES"</programlisting>
        </indexterm>
        <itemizedlist>
  	<listitem>
 -	  <para>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.</para>
 +	  <para>Share a <acronym>CD-ROM</acronym> or other media
 +	    with any number of clients.  It is often more
 +	    convenient to install software on multiple
 +	    machines from a single location.</para>
  	</listitem>
  
  	<listitem>
 -	  <para>On large networks, it might be more convenient to
 -	    configure a central <acronym>NFS</acronym> 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.</para>
 +	  <para>On large networks, it is often more convenient to
 +	    configure a central <acronym>NFS</acronym> 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.</para>
  	</listitem>
  
  	<listitem>
 -	  <para>Several machines could have a common
 -	    <filename>/usr/ports/distfiles</filename> directory.  This
 -	    allows for quick access to the source files without
 -	    downloading them on each machine.</para>
 +	  <para>Several clients may need access to the
 +	    <filename class="directory">/usr/ports/distfiles</filename>
 +	    directory.  Sharing that directory allows for quick access
 +	    to the source files without having to download them to
 +	    each client.</para>
  	</listitem>
        </itemizedlist>
      </sect2>
 @@ -940,34 +942,37 @@ rpc_statd_enable="YES"</programlisting>
  	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 <application>amd</application>.  Using
 -	<application>amd</application> provides a simple alternative
 -	to permanent mounts, as permanent mounts are usually listed in
 -	<filename>/etc/fstab</filename>.</para>
 +	unmounted by <application>amd</application>.
 +	<application>amd</application> provides an alternative to
 +	modifying <filename>/etc/fstab</filename> to list every
 +	client.</para>
  
        <para><application>amd</application> operates by attaching
 -	itself as an NFS server to the <filename>/host</filename> and
 -	<filename>/net</filename> directories.  When a file is
 +	itself as an NFS server to the
 +	<filename class="directory">/host</filename>
 +	and <filename class="directory">/net</filename> directories.  When a file is
  	accessed within one of these directories,
  	<application>amd</application> looks up the corresponding
  	remote mount and automatically mounts it.
 -	<filename>/net</filename> is used to mount an exported file
 -	system from an IP address, while <filename>/host</filename> is
 +	<filename class="directory">/net</filename> is used to mount an exported file
 +	system from an IP address, while
 +	<filename class="directory">/host</filename> is
  	used to mount an export from a remote hostname.</para>
  
 -      <para>An access to a file within
 -	<filename>/host/foobar/usr</filename> would tell
 -	<application>amd</application> to attempt to mount the
 -	<filename>/usr</filename> export on the host
 +      <para>For instance, an attempt to access a file within
 +	<filename class="directory">/host/foobar/usr</filename> would tell
 +	<application>amd</application> to mount the
 +	<filename class="directory">/usr</filename> export on the host
  	<hostid>foobar</hostid>.</para>
  
        <example>
  	<title>Mounting an Export with
  	  <application>amd</application></title>
  
 -	<para>The <command>showmount</command> command shows the
 -	  available mounts on a remote host.  For example, to view the
 -	  mounts of a host named <hostid>foobar</hostid>:</para>
 +	<para><command>showmount -e</command> shows the
 +	  exported file systems that can be mounted from
 +	  the <acronym>NFS</acronym> server,
 +	  <hostid>foobar</hostid>:</para>
  
  	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
  Exports list on foobar:
 @@ -976,155 +981,39 @@ Exports list on foobar:
  &prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>
        </example>
  
 -      <para>As seen in the example, the <command>showmount</command>
 -	shows <filename>/usr</filename> as an export.  When changing
 -	directories to <filename>/host/foobar/usr</filename>,
 -	<application>amd</application> attempts to resolve the
 -	hostname <hostid>foobar</hostid> and automatically mount the
 -	desired export.</para>
 +      <para>The output from <command>showmount</command>
 +	shows <filename class="directory">/usr</filename> as an
 +	export.  When changing directories to
 +	<filename class="directory">/host/foobar/usr</filename>,
 +	<application>amd</application> intercepts the request and
 +	attempts to resolve the hostname <hostid>foobar</hostid>.
 +	If successful, <application>amd</application> automatically
 +	mounts the desired export.</para>
  
 -      <para><application>amd</application> can be started by the
 -	startup scripts by placing the following lines in
 -	<filename>/etc/rc.conf</filename>:</para>
 +      <para><application>amd</application> is enabled by placing
 +	this line in <filename>/etc/rc.conf</filename>:</para>
  
        <programlisting>amd_enable="YES"</programlisting>
  
 -      <para>Additionally, custom flags can be passed to
 +      <para>It can then be started using the &os; &man.rc.8; scripts
 +	or by using the &man.service.8; command.</para>
 +
 +      <para>Custom flags can be passed to
  	<application>amd</application> from the
 -	<varname>amd_flags</varname> option.  By default,
 -	<varname>amd_flags</varname> is set to:</para>
 +	<varname>amd_flags</varname> environment variable.  By
 +	default, <varname>amd_flags</varname> is set to:</para>
  
        <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
  
 -      <para>The <filename>/etc/amd.map</filename> file defines the
 -	default options that exports are mounted with.  The
 -	<filename>/etc/amd.conf</filename> file defines some of the
 +      <para><filename>/etc/amd.map</filename> defines the
 +	default options with which exports are mounted.
 +	<filename>/etc/amd.conf</filename> defines some of the
  	more advanced features of
  	<application>amd</application>.</para>
  
        <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages
  	for more information.</para>
      </sect2>
 -
 -    <sect2 id="network-nfs-integration">
 -      <sect2info>
 -	<authorgroup>
 -	  <author>
 -	    <firstname>John</firstname>
 -	    <surname>Lind</surname>
 -	    <contrib>Contributed by </contrib>
 -	  </author>
 -	</authorgroup>
 -      </sect2info>
 -      <title>Problems Integrating with Other Systems</title>
 -
 -      <para>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.</para>
 -
 -      <para>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.</para>
 -
 -      <para>Though the <quote>correct</quote> 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
 -	<emphasis>server</emphasis>, include the option
 -	<option>-w=1024</option> on the mount from the client.  If the
 -	FreeBSD system is the <emphasis>client</emphasis>, then mount
 -	the NFS file system with the option <option>-r=1024</option>.
 -	These options may be specified using the fourth field of the
 -	<filename>fstab</filename> entry on the client for automatic
 -	mounts, or by using the <option>-o</option> parameter of the
 -	&man.mount.8; command for manual mounts.</para>
 -
 -      <para>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
 -	<emphasis>certain</emphasis> that the routers are routing the
 -	necessary <acronym>UDP</acronym> information.</para>
 -
 -      <para>In the following examples, <hostid>fastws</hostid> is the
 -	host (interface) name of a high-performance workstation, and
 -	<hostid>freebox</hostid> is the host (interface) name of a
 -	FreeBSD system with a lower-performance Ethernet adapter.
 -	Also, <filename>/sharedfs</filename> will be the exported NFS
 -	file system (see &man.exports.5;), and
 -	<filename>/project</filename> will be the mount point on the
 -	client for the exported file system.  In all cases, note that
 -	additional options, such as <option>hard</option> or
 -	<option>soft</option> and <option>bg</option> may be desirable
 -	in the application.</para>
 -
 -      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>)
 -	as the client in <filename>/etc/fstab</filename> on
 -	<hostid>freebox</hostid>:</para>
 -
 -      <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
 -
 -      <para>As a manual mount command on
 -	<hostid>freebox</hostid>:</para>
 -
 -      <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
 -
 -      <para>Examples for the FreeBSD system as the server in
 -	<filename>/etc/fstab</filename> on
 -	<hostid>fastws</hostid>:</para>
 -
 -      <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
 -
 -      <para>As a manual mount command on
 -	<hostid>fastws</hostid>:</para>
 -
 -      <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
 -
 -      <para>Nearly any 16-bit Ethernet adapter will allow operation
 -	without the above restrictions on the read or write
 -	size.</para>
 -
 -      <para>For anyone who cares, here is what happens when the
 -	failure occurs, which also explains why it is unrecoverable.
 -	NFS typically works with a <quote>block</quote> size of
 -	8&nbsp;K (though it may do fragments of smaller sizes).  Since
 -	the maximum Ethernet packet is around 1500&nbsp;bytes, the NFS
 -	<quote>block</quote> 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
 -	<emphasis>acknowledged</emphasis> 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&nbsp;K
 -	unit, and the process will be repeated, ad infinitum.</para>
 -
 -      <para>By keeping the unit size below the Ethernet packet size
 -	limitation, we ensure that any complete Ethernet packet
 -	received can be acknowledged individually, avoiding the
 -	deadlock situation.</para>
 -
 -      <para>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
 -	<quote>units</quote>.  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.</para>
 -    </sect2>
    </sect1>
  
    <sect1 id="network-nis">
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Mon Sep 2 12:52:16 UTC 2013 
State-Changed-Why:  
Modified version of patch committed.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=181269 
>Unformatted:
