1.\" $NetBSD: mount_nfs.8,v 1.39 2009/04/18 14:55:50 wiz Exp $ 2.\" 3.\" Copyright (c) 1992, 1993, 1994, 1995 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mount_nfs.8 8.3 (Berkeley) 3/29/95 31.\" 32.Dd April 18, 2009 33.Dt MOUNT_NFS 8 34.Os 35.Sh NAME 36.Nm mount_nfs 37.Nd mount NFS file systems 38.Sh SYNOPSIS 39.Nm 40.Bk -words 41.Op Fl 23bCcdilPpqsTUX 42.Ek 43.Bk -words 44.Op Fl a Ar maxreadahead 45.Ek 46.Bk -words 47.Op Fl D Ar deadthresh 48.Ek 49.Bk -words 50.Op Fl g Ar maxgroups 51.Ek 52.Bk -words 53.Op Fl I Ar readdirsize 54.Ek 55.Bk -words 56.Op Fl L Ar leaseterm 57.Ek 58.Bk -words 59.Op Fl o Ar options 60.Ek 61.Bk -words 62.Op Fl R Ar retrycnt 63.Ek 64.Bk -words 65.Op Fl r Ar readsize 66.Ek 67.Bk -words 68.Op Fl t Ar timeout 69.Ek 70.Bk -words 71.Op Fl w Ar writesize 72.Ek 73.Bk -words 74.Op Fl x Ar retrans 75.Ek 76.Ar rhost:path node 77.Sh DESCRIPTION 78The 79.Nm 80command calls the 81.Xr mount 2 82system call to prepare and graft a remote 83.Tn NFS 84file system (rhost:path) 85on to the file system tree at the mount point 86.Ar node . 87The directory specified by 88.Ar node 89is converted to an absolute path before use. 90This command is normally executed by 91.Xr mount 8 . 92It implements the mount protocol as described in RFC 1094, Appendix A and 93.%T "NFS: Network File System Version 3 Protocol Specification" , 94Appendix I. 95.Pp 96The options are: 97.Bl -tag -width indent 98.It Fl 2 99Use the 100.Tn NFS 101Version 2 protocol. 102.It Fl 3 103Use the 104.Tn NFS 105Version 3 protocol. 106The default is to try version 3 first, and 107fall back to version 2 if the mount fails. 108.It Fl a Ar maxreadahead 109Set the read-ahead count to the specified value. 110This may be in the range of 0 - 4, and determines how many blocks 111will be read ahead when a large file is being read sequentially. 112Trying a value greater than 1 for this is suggested for 113mounts with a large bandwidth * delay product. 114.It Fl b 115If an initial attempt to contact the server fails, fork off a child to keep 116trying the mount in the background. 117Useful for 118.Xr fstab 5 , 119where the filesystem mount is not critical to multiuser operation. 120.It Fl C 121For 122.Tn UDP 123mount points, do a 124.Xr connect 2 . 125Although this flag increases the efficiency of 126.Tn UDP 127mounts it cannot 128be used for servers that do not reply to requests from the 129standard 130.Tn NFS 131port number 2049, or for servers with multiple network interfaces. 132In these cases if the socket is connected and the server 133replies from a different port number or a different network interface 134the client will get ICMP port unreachable and the mount will hang. 135.It Fl c 136For 137.Tn UDP 138mount points, do not do a 139.Xr connect 2 . 140This flag is deprecated and connectionless 141.Tn UDP 142mounts are the default. 143.It Fl D Ar deadthresh 144Set the 145.Dq "dead server threshold" 146to the specified number of round trip timeout intervals. 147After a 148.Dq "dead server threshold" 149of retransmit timeouts, 150.Dq "not responding" 151message is printed to a tty. 152.It Fl d 153Turn off the dynamic retransmit timeout estimator. 154This may be useful for 155.Tn UDP 156mounts that exhibit high retry rates, 157since it is possible that the dynamically estimated timeout interval is too 158short. 159.It Fl g Ar maxgroups 160Set the maximum size of the group list for the credentials to the 161specified value. 162This should be used for mounts on old servers that cannot handle a 163group list size of 16, as specified in RFC 1057. 164Try 8, if users in a lot of groups cannot get response from the mount 165point. 166.It Fl I Ar readdirsize 167Set the readdir read size to the specified value. 168The value should normally 169be a multiple of 170.Dv DIRBLKSIZ 171that is \*[Le] the read size for the mount. 172.It Fl i 173Make the mount interruptible, which implies that file system calls that 174are delayed due to an unresponsive server will fail with 175.Er EINTR 176when a 177termination signal is posted for the process. 178.It Fl L Ar leaseterm 179Ignored. 180It used to be 181.Tn NQNFS 182lease term. 183.It Fl l 184Used with 185.Tn NFS 186Version 3 to specify that the 187.Fn ReaddirPlus 188.Tn RPC 189should be used. 190This option reduces 191.Tn RPC 192traffic for cases such as 193.Ic "ls -l" , 194but tends to flood the attribute and name caches with prefetched entries. 195Try this option and see whether performance improves or degrades. 196Probably most useful for client to server network 197interconnects with a large bandwidth times delay product. 198.It Fl o Ar options 199Options are specified with a 200.Fl o 201flag followed by a comma separated string of options. 202See the 203.Xr mount 8 204man page for possible options and their meanings. 205.Pp 206The following 207.Tn NFS 208specific options are also available: 209.Bl -tag -width indent 210.It Cm bg 211Same as 212.Fl b . 213.It Cm conn 214Same as 215.Fl C . 216.It Cm deadthresh Ns = Ns Aq Ar deadthresh 217Same as 218.Fl D Ar deadthresh . 219.It Cm dumbtimer 220Same as 221.Fl d . 222.It Cm intr 223Same as 224.Fl i . 225.It Cm leaseterm Ns = Ns Aq Ar leaseterm 226Same as 227.Fl L Ar leaseterm . 228.It Cm maxgrps Ns = Ns Aq Ar maxgroups 229Same as 230.Fl g Ar maxgroups . 231.It Cm mntudp 232Same as 233.Fl U . 234.It Cm nfsv2 235Same as 236.Fl 2 . 237.It Cm nfsv3 238Same as 239.Fl 3 . 240.It Cm noresport 241Same as 242.Fl p . 243.It Cm nqnfs 244Same as 245.Fl q . 246.It Cm port Ns = Ns Aq Ar portnumber 247Use the specified port number for 248.Tn NFS 249requests. 250The default is to query the portmapper for the 251.Tn NFS 252port. 253.It Cm rdirplus 254Same as 255.Fl l . 256.It Cm readahead Ns = Ns Aq Ar maxreadahead 257Same as 258.Fl a Ar maxreadahead . 259.It Cm rsize Ns = Ns Aq Ar readsize 260Same as 261.Fl -r Ar readsize . 262.It Cm soft 263Same as 264.Fl s . 265.It Cm tcp 266Same as 267.Fl T . 268.It Cm timeo Ns = Ns Aq Ar timeout 269Same as 270.Fl t Ar timeout . 271.It Cm wsize Ns = Ns Aq Ar writesize 272Same as 273.Fl w Ar writesize . 274.El 275.It Fl P 276Use a reserved socket port number. 277This is the default, and available 278for backwards compatibility purposes only. 279.It Fl p 280Do not use a reserved port number for RPCs. 281This option is provided only to be able to mimic the old 282default behavior of not using a reserved port, and should rarely be useful. 283.It Fl q 284A synonym of 285.Fl 3 . 286It used to specify 287.Tn NQNFS . 288.It Fl R Ar retrycnt 289Set the retry count for doing the mount to the specified value. 290The default is 10000. 291.It Fl r Ar readsize 292Set the read data size to the specified value in bytes. 293It should normally be a power of 2 greater than or equal to 1024. 294.Pp 295This should be used for 296.Tn UDP 297mounts when the 298.Dq "fragments dropped after timeout" 299value is getting large while actively using a mount point. 300Use 301.Xr netstat 1 302with the 303.Fl s 304option to see what the 305.Dq "fragments dropped after timeout" 306value is. 307See the 308.Nm 309.Fl w 310option also. 311.It Fl s 312A soft mount, which implies that file system calls will fail 313after 314.Ar retrans 315round trip timeout intervals. 316.It Fl T 317Use 318.Tn TCP 319transport instead of 320.Tn UDP . 321This is recommended for servers that are not on the same physical network as 322the client. 323Not all 324.Tn NFS 325servers, especially not old ones, support this. 326.It Fl t Ar timeout 327Set the initial retransmit timeout to the specified value in 0.1 seconds. 328May be useful for fine tuning 329.Tn UDP 330mounts over internetworks 331with high packet loss rates or an overloaded server. 332Try increasing the interval if 333.Xr nfsstat 1 334shows high retransmit rates while the file system is active or reducing the 335value if there is a low retransmit rate but long response delay observed. 336Normally, the -d option should be specified when using this option to manually 337tune the timeout 338interval. 339The default is 3 seconds. 340.It Fl U 341Force the mount protocol to use 342.Tn UDP 343transport, even for 344.Tn TCP 345.Tn NFS 346mounts. 347This is necessary for some old 348.Bx 349servers. 350.It Fl w Ar writesize 351Set the write data size to the specified value in bytes. 352.Pp 353The same logic applies for use of this option as with the 354.Nm 355.Fl r 356option, but using the 357.Dq "fragments dropped after timeout" 358value on the 359.Tn NFS 360server instead of the client. 361Note that both the 362.Fl r 363and 364.Fl w 365options should only be used as a last ditch effort at improving performance 366when mounting servers that do not support 367.Tn TCP 368mounts. 369.It Fl X 370Perform 32 \*[Lt]-\*[Gt] 64 bit directory cookie translation for version 3 mounts. 371This may be need in the case of a server using the upper 32 bits of 372version 3 directory cookies, and when you are running emulated binaries 373that access such a filesystem. 374Native 375.Nx 376binaries will never need this option. 377This option introduces some overhead. 378.It Fl x Ar retrans 379Set the retransmit timeout count for soft mounts to the specified value. 380The default is 10. 381.El 382.Sh EXAMPLES 383The simplest way to invoke 384.Nm 385is with a command like: 386.Pp 387.Dl "mount -t nfs remotehost:/filesystem /localmountpoint" 388.Pp 389It is also possible to automatically mount filesystems at boot from your 390.Pa /etc/fstab 391by using a line like: 392.Pp 393.Dl "remotehost:/home /home nfs rw 0 0" 394.Sh PERFORMANCE 395As can be derived from the comments accompanying the options, performance 396tuning of 397.Tn NFS 398can be a non-trivial task. 399Here are some common points 400to watch: 401.Bl -bullet -offset indent 402.It 403Increasing the read and write size with the 404.Fl r 405and 406.Fl w 407options respectively will increase throughput if the network 408interface can handle the larger packet sizes. 409.Pp 410The default size for 411.Tn NFS 412version 2 is 8K when 413using 414.Tn UDP , 41564K when using 416.Tn TCP . 417.Pp 418The default size for 419.Tn NFS 420version 3 is platform dependent: 421on 422.Nx Ns /i386 , 423the default is 32K, for other platforms it is 8K. 424Values over 32K are only supported for 425.Tn TCP , 426where 64K is the maximum. 427.Pp 428Any value over 32K is unlikely to get you more performance, unless 429you have a very fast network. 430.It 431If the network interface cannot handle larger packet sizes or a 432long train of back to back packets, you may see low performance 433figures or even temporary hangups during 434.Tn NFS 435activity. 436.Pp 437This can especially happen with older 438.Tn Ethernet 439network interfaces. 440What happens is that either the receive buffer on the network 441interface on the client side is overflowing, or that similar events 442occur on the server, leading to a lot of dropped packets. 443.Pp 444In this case, decreasing the read and write size, using 445.Tn TCP , 446or a combination of both will usually lead to better throughput. 447Should you need to decrease the read and write size for all your 448.Tn NFS 449mounts because of a slow 450.Tn Ethernet 451network interface 452.Pq e.g. a USB 1.1 to 10/100 Tn Ethernet network interface , 453you can use 454.Pp 455.Bl -ohang -compact 456.It Cd options NFS_RSIZE=value 457.It Cd options NFS_WSIZE=value 458.El 459.Pp 460in your kernel 461.Xr config 1 462file to avoid having do specify the sizes for all mounts. 463.It 464For connections that are not on the same 465.Tn LAN , 466and/or may experience packet loss, using 467.Tn TCP 468is strongly recommended. 469.El 470.Sh ERRORS 471Some common problems with 472.Nm 473can be difficult for first time users to understand. 474.Pp 475.Dl "mount_nfs: can't access /foo: Permission denied" 476.Pp 477This message means that the remote host, is either not exporting 478the filesystem you requested, or is not exporting it to your host. 479If you believe the remote host is indeed exporting a filesystem to you, 480make sure the 481.Xr exports 5 482file is exporting the proper directories. 483.Pp 484A common mistake is that 485.Xr mountd 8 486will not export a filesystem with the 487.Fl alldirs 488option, unless it 489is a mount point on the exporting host. 490It is not possible to remotely 491mount a subdirectory of an exported mount, unless it is exported with the 492.Fl alldirs 493option. 494.Pp 495The following error: 496.Pp 497.Dl "NFS Portmap: RPC: Program not registered" 498.Pp 499means that the remote host is not running 500.Xr mountd 8 . 501The program 502.Xr rpcinfo 8 503can be used to determine if the remote host is running nfsd, and mountd by issuing 504the command: 505.Pp 506.Dl rpcinfo -p remotehostname 507.Pp 508If the remote host is running nfsd, and mountd, it would display: 509.Pp 510.Dl "100005 3 udp 719 mountd" 511.Dl "100005 1 tcp 720 mountd" 512.Dl "100005 3 tcp 720 mountd" 513.Dl "100003 2 udp 2049 nfs" 514.Dl "100003 3 udp 2049 nfs" 515.Dl "100003 2 tcp 2049 nfs" 516.Dl "100003 3 tcp 2049 nfs" 517.Pp 518The error: 519.Pp 520.Dl "mount_nfs: can't get net id for host" 521.Pp 522indicates that 523.Nm 524cannot resolve the name of the remote host. 525.Sh SEE ALSO 526.Xr nfsstat 1 , 527.Xr mount 2 , 528.Xr unmount 2 , 529.Xr options 4 , 530.Xr exports 5 , 531.Xr fstab 5 , 532.Xr mount 8 , 533.Xr mountd 8 , 534.Xr rpcinfo 8 535.Rs 536.%R RFC 1094 537.%D March 1989 538.%T "NFS: Network File System Protocol specification" 539.Re 540.Rs 541.%R RFC 2623 542.%D June 1999 543.%T "NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use of RPCSEC_GCC and Kerberos V5" 544.Re 545.Rs 546.%R RFC 2624 547.%D June 1999 548.%T "NFS Version 4 Design Considerations" 549.Re 550.Rs 551.%R RFC 2695 552.%D September 1999 553.%T "Authentication Mechanisms for ONC RPC" 554.Re 555.Sh CAVEATS 556An NFS server shouldn't loopback-mount its own exported file systems because 557it's fundamentally prone to deadlock. 558