From owner-svn-doc-head@FreeBSD.ORG Thu Aug 29 01:46:15 2013 Return-Path: Delivered-To: svn-doc-head@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 49F30EF0; Thu, 29 Aug 2013 01:46:15 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 3623427E8; Thu, 29 Aug 2013 01:46:15 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r7T1kFds043106; Thu, 29 Aug 2013 01:46:15 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r7T1kFFk043105; Thu, 29 Aug 2013 01:46:15 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201308290146.r7T1kFFk043105@svn.freebsd.org> From: Warren Block Date: Thu, 29 Aug 2013 01:46:15 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42602 - head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 29 Aug 2013 01:46:15 -0000 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 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-argumentsNetwork File System (NFS) NFS - Among the many different file systems that FreeBSD supports - is the Network File System, also known as NFS. NFS allows a system to share directories and - files with others over a network. By using NFS, users and programs can - access files on remote systems almost as if they were local - files. + &os; supports the Network File System + (NFS), which allows a server to share + directories and files with clients over a network. With + NFS, users and programs can access files + on remote systems as if they were stored locally. - Some of the most notable benefits that - NFS can provide are: + The most notable benefits that + NFS provides are: - Local workstations use less disk space because commonly - used data can be stored on a single machine and still remain - accessible to others over the network. + Data that would otherwise be duplicated on each client + can be kept in a single location and accessed by clients + on the network. - There is no need for users to have separate home - directories on every network machine. Home directories - could be set up on the NFS server and - made available throughout the network. + User home directories can be stored in one location + and accessed by their owners over the network. - 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. + Administration of NFS exports is + also simplified. For example, there is only one file + system where security or backup policies must be + set. + + + + Removable media storage devices, such as floppy disks + or CD-ROM 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. @@ -600,7 +603,7 @@ server-program-arguments - The server has to be running the following daemons: + These daemons must be running on the server: NFS server @@ -657,13 +660,8 @@ server-program-arguments - The client can also run a daemon, known as - nfsiod. The - nfsiod daemon services the requests - from the NFS server. This is optional, and - improves performance, but is not required for normal and - correct operation. See the &man.nfsiod.8; manual page for - more information. + Running &man.nfsiod.8; can improve performance on the + client, but is not required. @@ -674,14 +672,11 @@ server-program-argumentsconfiguration - NFS configuration is a relatively - straightforward process. The processes that need to be - running can all start at boot time with a few modifications - to /etc/rc.conf. - - On the NFS server, make sure that the - following options are configured in the - /etc/rc.conf file: + Enabling the NFS server + is straightforward. The required processes + can be set to start at boot time by adding + these options to + /etc/rc.conf: rpcbind_enable="YES" nfs_server_enable="YES" @@ -690,99 +685,101 @@ mountd_flags="-r" mountd runs automatically whenever the NFS server is enabled. - On the client, make sure this option is present in + To enable the client, set this option in /etc/rc.conf: nfs_client_enable="YES" - The /etc/exports file specifies which - file systems NFS should export (sometimes - referred to as share). Each line in + /etc/exports specifies which + file systems the NFS server will + export. Each line in /etc/exports specifies a file system to - be exported and which machines have access to that file - system. Along with what machines have access to that file - system, access options may also be specified. There are many - such options that can be used in this file but only a few will - be mentioned here. Other options are discussed in - the &man.exports.5; manual page. - - Here are a few example /etc/exports - entries: + 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. NFS export examples - The following examples give an idea of how to export file - systems, although the settings may be different depending on - the environment and network configuration. For instance, to - export the /cdrom directory to three - example machines that have the same domain name as the server - (hence the lack of a domain name for each) or have entries in - the /etc/hosts file. The - flag makes the exported file system - read-only. With this flag, the remote system will not be able - to write any changes to the exported file system. - - /cdrom -ro host1 host2 host3 - - The following line exports /home to - three hosts by IP address. This is a useful setup on - a private network without a DNS server - configured. Optionally the /etc/hosts - file could be configured for internal hostnames; please review - &man.hosts.5; for more information. The - flag allows the subdirectories to be - mount points. In other words, it will not mount the - subdirectories but permit the client to mount only the - directories that are required or needed. + These examples give an idea of how to export file systems. + Minor modifications may be required for the examples to work + on the reader's network. + + This example shows how to export the + /cdrom directory to + three clients called alpha, + bravo, and + charlie: + + /cdrom -ro alpha bravo charlie + + The -ro flag makes the file systems + read-only, preventing clients from making any changes to + those exported file systems. + + The next example exports + /home to three clients + by IP address. This can be useful for networks without + DNS. Optionally, + /etc/hosts could be configured for + internal hostnames; please review &man.hosts.5; for more + information. The -alldirs flag allows + subdirectories to be mount points. In other words, it will + not mount the subdirectories but permit the client to mount + only the directories that are required or needed. /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4 - The following line exports /a so that - two clients from different domains may access the file system. + This next line exports + /a so that two clients + from different domains may access the file system. The flag allows the root user on the remote system to write data on the exported file system as root. If the -maproot=root flag is not specified, - then even if a user has root access on - the remote system, he will not be able to modify files on - the exported file system. + the client's root user will be mapped + to the server's nobody account and will + be subject to the access limitations defined for user, + nobody. /a -maproot=root host.example.com box.example.org - In order for a client to access an exported file system, - the client must have permission to do so. Make sure the - client is listed in /etc/exports. - - In /etc/exports, each line represents - the export information for one file system to one host. A - remote host can only be specified once per file system, and - may only have one default entry. For example, assume that - /usr is a single file system. The - following /etc/exports would be - invalid: + For a client to have access to an exported file system, + the client must be listed in + /etc/exports. + + In /etc/exports, each line defines + the export information for one file system to one or more + clients. A remote host can only be specified once per file + system. For example, assume that + /usr is a single file + system. This entry, in /etc/exports, + would be invalid: # Invalid when /usr is one file system /usr/src client /usr/ports client - One file system, /usr, has two lines + The /usr file + system has two lines specifying exports to the same host, client. The correct format for this situation is: /usr/src /usr/ports client - The properties of one file system exported to a given host - must all occur on one line. Lines without a client specified - are treated as a single host. This limits how file systems - may be exported; however, for most environments, this is not - an issue. + The exported file system, its properties, and allowed + hosts must occur on a single line. If no clients are listed, + then any client on the network may mount the exported file + system. The following is an example of a valid export list, where - /usr and /exports - are local file systems: + /usr and + /exports are local + file systems: # Export src and ports to client01 and client02, but only # client01 has root privileges on it @@ -793,24 +790,20 @@ mountd_flags="-r" /exports -alldirs -maproot=root client01 client02 /exports/obj -ro - The mountd daemon must be - forced to recheck the /etc/exports file - whenever it has been modified, so the changes can take effect. - This can be accomplished either by sending a HUP signal to the - running daemon: - - &prompt.root; kill -HUP `cat /var/run/mountd.pid` - - or by invoking the mountd &man.rc.8; - script with the appropriate parameter: + The mountd daemon reads + /etc/exports when started. To make + NFS server changes take effect immediately, + force mountd to reread + /etc/exports: - &prompt.root; service mountd onereload + &prompt.root; service mountd reload Please refer to for more information about using rc scripts. - NFS services can now be started by running the following - command, on the NFS server, as + On a new server being configured with + NFS services, the server can be + started by running this command as root: &prompt.root; service nfsd start @@ -819,12 +812,13 @@ mountd_flags="-r" &prompt.root; service nfsclient restart - Now everything should be ready to actually mount a remote - file system. In these examples the server's name will be - server and the client's name will be + The client now has everything it needs to mount a remote + file system. In these examples, the server's name is + server and the client's name is client. For testing or to temporarily mount - a remote file system execute a command like this as - root on the client: + a remote file system, execute + mount as + root on client: NFS @@ -832,16 +826,20 @@ mountd_flags="-r" &prompt.root; mount server:/home /mnt - This will mount the /home directory - on the server at /mnt on the client. If - everything is set up correctly, the server's files should be - visible and available in the /mnt - directory. - - To permanently mount a remote file system each time the - computer boots, add the file system to the - /etc/fstab file. Here is an - example: + This mounts the + server: + /home + file system to the + client: + /mnt mount + point. The files and directories in the + server + /home file system will + now be available on client, in the + /mnt directory. + + To mount a remote file system each time the client + boots, add it to /etc/fstab: server:/home /mnt nfs rw 0 0 @@ -855,32 +853,35 @@ mountd_flags="-r" Some applications (e.g., mutt) require file locking to operate correctly. In the case of NFS, rpc.lockd - can be used for file locking. To enable it, add the following - to the /etc/rc.conf file on both client - and server (it is assumed that the NFS - client and server are configured already): + can be used for file locking. To enable it, add this line to + /etc/rc.conf on both client + and server: rpc_lockd_enable="YES" rpc_statd_enable="YES" - Start the application by using: + Please note that this assumes that both + NFS client and server are already + configured. + + Start the application, as + root, with: &prompt.root; service lockd start &prompt.root; service statd start - If real locking between the NFS clients - and NFS server is not required, it is - possible to let the NFS client do locking - locally by passing to &man.mount.nfs.8;. - Refer to the &man.mount.nfs.8; manual page for further - details. + If locking is not required on the server, the + NFS client can be configured to + lock locally by passing to + &man.mount.nfs.8;. Refer to the &man.mount.nfs.8; + manual page for further details. Practical Uses NFS has many practical uses. Some of - the more common ones are listed below: + the more common uses: NFS @@ -888,25 +889,26 @@ rpc_statd_enable="YES" - Set several machines to share a CDROM or other media - among them. This is cheaper and often a more convenient - method to install software on multiple machines. + Share a CD-ROM or other media + with any number of clients. It is often more + convenient to install software on multiple + machines from a single location. - On large networks, it might be more convenient to - configure a central NFS server in which - to store all the user home directories. These home - directories can then be exported to the network so that - users would always have the same home directory, - regardless of which workstation they log in to. + On large networks, it is often more convenient to + configure a central NFS server on which + all user home directories are stored. Users can log into + a client anywhere on the network and have access to their + home directories. - Several machines could have a common - /usr/ports/distfiles directory. This - allows for quick access to the source files without - downloading them on each machine. + Several clients may need access to the + /usr/ports/distfiles + directory. Sharing that directory allows for quick access + to the source files without having to download them to + each client. @@ -940,34 +942,37 @@ rpc_statd_enable="YES" mounts a remote file system whenever a file or directory within that file system is accessed. Filesystems that are inactive for a period of time will also be automatically - unmounted by amd. Using - amd provides a simple alternative - to permanent mounts, as permanent mounts are usually listed in - /etc/fstab. + unmounted by amd. + amd provides an alternative to + modifying /etc/fstab to list every + client. amd operates by attaching - itself as an NFS server to the /host and - /net directories. When a file is + itself as an NFS server to the + /host + and /net directories. When a file is accessed within one of these directories, amd looks up the corresponding remote mount and automatically mounts it. - /net is used to mount an exported file - system from an IP address, while /host is + /net is used to mount an exported file + system from an IP address, while + /host is used to mount an export from a remote hostname. - An access to a file within - /host/foobar/usr would tell - amd to attempt to mount the - /usr export on the host + For instance, an attempt to access a file within + /host/foobar/usr would tell + amd to mount the + /usr export on the host foobar. Mounting an Export with <application>amd</application> - The showmount command shows the - available mounts on a remote host. For example, to view the - mounts of a host named foobar: + showmount -e shows the + exported file systems that can be mounted from + the NFS server, + foobar: &prompt.user; showmount -e foobar Exports list on foobar: @@ -976,155 +981,39 @@ Exports list on foobar: &prompt.user; cd /host/foobar/usr - As seen in the example, the showmount - shows /usr as an export. When changing - directories to /host/foobar/usr, - amd attempts to resolve the - hostname foobar and automatically mount the - desired export. + The output from showmount + shows /usr as an + export. When changing directories to + /host/foobar/usr, + amd intercepts the request and + attempts to resolve the hostname foobar. + If successful, amd automatically + mounts the desired export. - amd can be started by the - startup scripts by placing the following lines in - /etc/rc.conf: + amd is enabled by placing + this line in /etc/rc.conf: amd_enable="YES" - Additionally, custom flags can be passed to + It can then be started using the &os; &man.rc.8; scripts + or by using the &man.service.8; command. + + Custom flags can be passed to amd from the - amd_flags option. By default, - amd_flags is set to: + amd_flags environment variable. By + default, amd_flags is set to: amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map" - The /etc/amd.map file defines the - default options that exports are mounted with. The - /etc/amd.conf file defines some of the + /etc/amd.map defines the + default options with which exports are mounted. + /etc/amd.conf defines some of the more advanced features of amd. Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more information. - - - - - - John - Lind - Contributed by - - - - Problems Integrating with Other Systems - - Certain Ethernet adapters for ISA PC systems have - limitations which can lead to serious network problems, - particularly with NFS. This difficulty is not specific to - FreeBSD, but FreeBSD systems are affected by it. - - 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. - - Though the correct solution is to get a - higher performance and capacity Ethernet adapter for the - FreeBSD system, there is a simple workaround that will allow - satisfactory operation. If the FreeBSD system is the - server, include the option - on the mount from the client. If the - FreeBSD system is the client, then mount - the NFS file system with the option . - These options may be specified using the fourth field of the - fstab entry on the client for automatic - mounts, or by using the parameter of the - &man.mount.8; command for manual mounts. - - 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 - certain that the routers are routing the - necessary UDP information. - - In the following examples, fastws is the - host (interface) name of a high-performance workstation, and - freebox is the host (interface) name of a - FreeBSD system with a lower-performance Ethernet adapter. - Also, /sharedfs will be the exported NFS - file system (see &man.exports.5;), and - /project will be the mount point on the - client for the exported file system. In all cases, note that - additional options, such as or - and may be desirable - in the application. - - Examples for the FreeBSD system (freebox) - as the client in /etc/fstab on - freebox: - - fastws:/sharedfs /project nfs rw,-r=1024 0 0 - - As a manual mount command on - freebox: - - &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project - - Examples for the FreeBSD system as the server in - /etc/fstab on - fastws: - - freebox:/sharedfs /project nfs rw,-w=1024 0 0 - - As a manual mount command on - fastws: - - &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project - - Nearly any 16-bit Ethernet adapter will allow operation - without the above restrictions on the read or write - size. - - For anyone who cares, here is what happens when the - failure occurs, which also explains why it is unrecoverable. - NFS typically works with a block size of - 8 K (though it may do fragments of smaller sizes). Since - the maximum Ethernet packet is around 1500 bytes, the NFS - block gets split into multiple Ethernet - packets, even though it is still a single unit to the - upper-level code, and must be received, assembled, and - acknowledged as a unit. The - high-performance workstations can pump out the packets which - comprise the NFS unit one right after the other, just as close - together as the standard allows. On the smaller, lower - capacity cards, the later packets overrun the earlier packets - of the same unit before they can be transferred to the host - and the unit as a whole cannot be reconstructed or - acknowledged. As a result, the workstation will time out and - try again, but it will try again with the entire 8 K - unit, and the process will be repeated, ad infinitum. - - 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. - - Overruns may still occur when a high-performance - workstations is slamming data out to a PC system, but with the - better cards, such overruns are not guaranteed on NFS - units. When an overrun occurs, the units - affected will be retransmitted, and there will be a fair - chance that they will be received, assembled, and - acknowledged. -