docs/handbook/handbook-network-nfs.mdwn

   1 \r
   2 \r
   3 ## 19.6 NFS \r
   4 \r
   5 ***Reorganized and enhanced by Tom Rhodes. Written by Bill Swingle. ***\r
   6 \r
   7 Among the many different file systems that DragonFly 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.\r
   8 \r
   9 Some of the most notable benefits that NFS can provide are:\r
  10 \r
  11
  12 * 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.\r
  13
  14 * 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.\r
  15
  16 * Storage devices such as floppy disks, CDROM drives, and ZIP drives can be used by other machines on the network. This may reduce the number of removable media drives throughout the network.\r
  17 \r
  18 ### 19.6.1 How NFS Works \r
  19 \r
  20 NFS consists of at least two main parts: a server and one or more clients. The client remotely accesses the data that is stored on the server machine. In order for this to function properly a few processes have to be configured and running:\r
  21 \r
  22 The server has to be running the following daemons:\r
  23 \r
  24 [[!table  data="""
  25 | Daemon | Description
  26  nfsd | The NFS daemon which services requests from the NFS clients.
  27  mountd | The NFS mount daemon which carries out the requests that [nfsd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#nfsd&section8) passes on to it.
  28  portmap | The portmapper daemon allows NFS clients to discover which port the NFS server is using. |\r
  29 """]]\r
  30 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 [nfsiod(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#nfsiod&section8) manual page for more information.\r
  31 \r
  32 ### 19.6.2 Configuring NFS \r
  33 \r
  34 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 your `/etc/rc.conf` file.\r
  35 \r
  36 On the NFS server, make sure that the following options are configured in the `/etc/rc.conf` file:\r
  37 \r
  38     \r
  39     portmap_enable="YES"\r
  40     nfs_server_enable="YES"\r
  41     mountd_flags="-r"\r
  42 \r
  43 \r
  44 `mountd` runs automatically whenever the NFS server is enabled.\r
  45 \r
  46 On the client, make sure this option is present in `/etc/rc.conf`:\r
  47 \r
  48     \r
  49     nfs_client_enable="YES"\r
  50 \r
  51 \r
  52 The `/etc/exports` file specifies which file systems NFS should export (sometimes referred to as ***share***). Each line in `/etc/exports` specifies a file system to be exported and which machines have access to that file system. Along with what machines have access to that file system, access options may also be specified. There are many such options that can be used in this file but only a few will be mentioned here. You can easily discover other options by reading over the [exports(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#exports&section5) manual page.\r
  53 \r
  54 Here are a few example `/etc/exports` entries:\r
  55 \r
  56 The following examples give an idea of how to export filesystems, although the settings may be different depending on your 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 your `/etc/hosts` file. The `-ro` flag makes the exported filesystem read-only. With this flag, the remote system will not be able to write any changes to the exported filesystem.\r
  57 \r
  58     \r
  59     /cdrom -ro host1 host2 host3\r
  60 \r
  61 \r
  62 The following line exports `/home` to three hosts by IP address. This is a useful setup if you have a private network without a DNS server configured. Optionally the `/etc/hosts` file could be configured for internal hostnames; please review [hosts(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#hosts&section5) for more information. The `-alldirs` flag allows the subdirectories to be mount points. In other words, it will not mount the subdirectories but permit the client to mount only the directories that are required or needed.\r
  63 \r
  64     \r
  65     /home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4\r
  66 \r
  67 \r
  68 The following line exports `/a` so that two clients from different domains may access the filesystem. The `-maproot#root` flag allows the `root` user on the remote system to write data on the exported filesystem as `root`. If the `-maprootroot` flag is not specified, then even if a user has `root` access on the remote system, they will not be able to modify files on the exported filesystem.\r
  69 \r
  70     \r
  71     /a  -maproot=root  host.example.com box.example.org\r
  72 \r
  73 \r
  74 In order for a client to access an exported filesystem, the client must have permission to do so. Make sure the client is listed in your `/etc/exports` file.\r
  75 \r
  76 In `/etc/exports`, each line represents the export information for one filesystem to one host. A remote host can only be specified once per filesystem, and may only have one default entry. For example, assume that `/usr` is a single filesystem. The following `/etc/exports` would be invalid:\r
  77 \r
  78     \r
  79     /usr/src   client\r
  80     /usr/ports client\r
  81 \r
  82 \r
  83 One filesystem, `/usr`, has two lines specifying exports to the same host, `client`. The correct format for this situation is:\r
  84 \r
  85     \r
  86     /usr/src /usr/ports  client\r
  87 \r
  88 \r
  89 The properties of one filesystem 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 you can export filesystems, but for most people this is not an issue.\r
  90 \r
  91 The following is an example of a valid export list, where `/usr` and `/exports` are local filesystems:\r
  92 \r
  93     \r
  94     # Export src and ports to client01 and client02, but only\r
  95     # client01 has root privileges on it\r
  96     /usr/src /usr/ports -maproot=root    client01\r
  97     /usr/src /usr/ports               client02\r
  98     # The client machines have root and can mount anywhere\r
  99     # on /exports. Anyone in the world can mount /exports/obj read-only\r
 100     /exports -alldirs -maproot=root      client01 client02\r
 101     /exports/obj -ro\r
 102 \r
 103 \r
 104 You must restart `mountd` whenever you modify `/etc/exports` so the changes can take effect. This can be accomplished by sending the HUP signal to the `mountd` process:\r
 105 \r
 106     \r
 107     # kill -HUP `cat /var/run/mountd.pid`\r
 108 \r
 109 \r
 110 Alternatively, a reboot will make DragonFly set everything up properly. A reboot is not necessary though. Executing the following commands as `root` should start everything up.\r
 111 \r
 112 On the NFS server:\r
 113 \r
 114     \r
 115     # portmap\r
 116     # nfsd -u -t -n 4\r
 117     # mountd -r\r
 118 \r
 119 \r
 120 On the NFS client:\r
 121 \r
 122     \r
 123     # nfsiod -n 4\r
 124 \r
 125 \r
 126 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 `client`. If you only want to temporarily mount a remote filesystem or would rather test the configuration, just execute a command like this as `root` on the client:\r
 127 \r
 128     \r
 129     # mount server:/home /mnt\r
 130 \r
 131 \r
 132 This will mount the `/home` directory on the server at `/mnt` on the client. If everything is set up correctly you should be able to enter `/mnt` on the client and see all the files that are on the server.\r
 133 \r
 134 If you want to automatically mount a remote filesystem each time the computer boots, add the filesystem to the `/etc/fstab` file. Here is an example:\r
 135 \r
 136     \r
 137     server:/home        /mnt    nfs     rw      0       0\r
 138 \r
 139 \r
 140 The [fstab(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#fstab&section5) manual page lists all the available options.\r
 141 \r
 142 ### 19.6.3 Practical Uses \r
 143 \r
 144 NFS has many practical uses. Some of the more common ones are listed below:\r
 145 \r
 146
 147 * 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.\r
 148
 149 * 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.\r
 150
 151 * Several machines could have a common `/usr/ports/distfiles` directory. That way, when you need to install a port on several machines, you can quickly access the source without downloading it on each machine.\r
 152 \r
 153 ### 19.6.4 Automatic Mounts with amd \r
 154 \r
 155 ***Contributed by Wylie Stilwell. Rewritten by Chern Lee.***\r
 156 \r
 157 [amd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#amd&section8) (the automatic mounter daemon) automatically mounts a remote filesystem whenever a file or directory within that filesystem 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`.\r
 158 \r
 159  **amd**  operates by attaching itself as an NFS server to the `/host` and `/net` directories. When a file is accessed within one of these directories,  **amd**  looks up the corresponding remote mount and automatically mounts it. `/net` is used to mount an exported filesystem from an IP address, while `/host` is used to mount an export from a remote hostname.\r
 160 \r
 161 An access to a file within `/host/foobar/usr` would tell  **amd**  to attempt to mount the `/usr` export on the host `foobar`.\r
 162 \r
 163  **Example 19-1. Mounting an Export with amd** \r
 164 \r
 165 You can view the available mounts of a remote host with the `showmount` command. For example, to view the mounts of a host named `foobar`, you can use:\r
 166 \r
 167     \r
 168     % showmount -e foobar\r
 169     Exports list on foobar:\r
 170     /usr                               10.10.10.0\r
 171     /a                                 10.10.10.0\r
 172     % cd /host/foobar/usr\r
 173 \r
 174 \r
 175 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.\r
 176 \r
 177  **amd**  can be started by the startup scripts by placing the following lines in `/etc/rc.conf`:\r
 178 \r
 179     \r
 180     amd_enable="YES"\r
 181 \r
 182 \r
 183 Additionally, custom flags can be passed to  **amd**  from the `amd_flags` option. By default, `amd_flags` is set to:\r
 184 \r
 185     \r
 186     amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"\r
 187 \r
 188 \r
 189 The `/etc/amd.map` file defines the default options that exports are mounted with. The `/etc/amd.conf` file defines some of the more advanced features of  **amd** .\r
 190 \r
 191 Consult the [amd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#amd&section8) and [amd.conf(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=amd.conf&section=5) manual pages for more information.\r
 192 \r
 193 ### 19.6.5 Problems Integrating with Other Systems \r
 194 \r
 195 ***Contributed by John Lind.***\r
 196 \r
 197 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 DragonFly, but DragonFly systems are affected by it.\r
 198 \r
 199 The problem nearly always occurs when (DragonFly) 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 DragonFly 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.\r
 200 \r
 201 Though the ***correct*** solution is to get a higher performance and capacity Ethernet adapter for the DragonFly system, there is a simple workaround that will allow satisfactory operation. If the DragonFly system is the ***server***, include the option `-w#1024` on the mount from the client. If the DragonFly system is the ***client***, then mount the NFS filesystem with the option `-r1024`. These options may be specified using the fourth field of the `fstab` entry on the client for automatic mounts, or by using the `-o` parameter of the [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=mount&section=8) command for manual mounts.\r
 202 \r
 203 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 your routers are routing the necessary UDP information, or you will not get anywhere, no matter what else you are doing.\r
 204 \r
 205 In the following examples, `fastws` is the host (interface) name of a high-performance workstation, and `freebox` is the host (interface) name of a DragonFly system with a lower-performance Ethernet adapter. Also, `/sharedfs` will be the exported NFS filesystem (see [exports(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#exports&section5)), and `/project` will be the mount point on the client for the exported filesystem. In all cases, note that additional options, such as `hard` or `soft` and `bg` may be desirable in your application.\r
 206 \r
 207 Examples for the DragonFly system (`freebox`) as the client in `/etc/fstab` on `freebox`:\r
 208 \r
 209     \r
 210     fastws:/sharedfs /project nfs rw,-r=1024 0 0\r
 211 \r
 212 \r
 213 As a manual mount command on `freebox`:\r
 214 \r
 215     \r
 216     # mount -t nfs -o -r=1024 fastws:/sharedfs /project\r
 217 \r
 218 \r
 219 Examples for the DragonFly system as the server in `/etc/fstab` on `fastws`:\r
 220 \r
 221     \r
 222     freebox:/sharedfs /project nfs rw,-w=1024 0 0\r
 223 \r
 224 \r
 225 As a manual mount command on `fastws`:\r
 226 \r
 227     \r
 228     # mount -t nfs -o -w=1024 freebox:/sharedfs /project\r
 229 \r
 230 \r
 231 Nearly any 16-bit Ethernet adapter will allow operation without the above restrictions on the read or write size.\r
 232 \r
 233 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.\r
 234 \r
 235 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.\r
 236 \r
 237 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.\r