Attachment 136156 Details for Bug 181269 – file.diff

[patch] file.diff

file.diff (text/plain), 31.47 KB, created by Ken Reed on 2013-08-13 16:50:00 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Ken Reed

Created: 2013-08-13 16:50:00 UTC

Size: 31.47 KB

patch

obsolete

>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>

Actions: View | Diff

Attachments on bug 181269: 136156