1.\" $NetBSD: mount_nfs.8,v 1.19 2002/10/01 13:40:41 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)mount_nfs.8 8.3 (Berkeley) 3/29/95 35.\" 36.Dd January 12, 1999 37.Dt MOUNT_NFS 8 38.Os 39.Sh NAME 40.Nm mount_nfs 41.Nd mount nfs file systems 42.Sh SYNOPSIS 43.Nm "" 44.Bk -words 45.Op Fl 23bcCdiKlpPqsTUX 46.Ek 47.Bk -words 48.Op Fl D Ar deadthresh 49.Ek 50.Bk -words 51.Op Fl I Ar readdirsize 52.Ek 53.Bk -words 54.Op Fl L Ar leaseterm 55.Ek 56.Bk -words 57.Op Fl R Ar retrycnt 58.Ek 59.Bk -words 60.Op Fl a Ar maxreadahead 61.Ek 62.Bk -words 63.Op Fl g Ar maxgroups 64.Ek 65.Bk -words 66.Op Fl m Ar realm 67.Ek 68.Bk -words 69.Op Fl o Ar options 70.Ek 71.Bk -words 72.Op Fl r Ar readsize 73.Ek 74.Bk -words 75.Op Fl t Ar timeout 76.Ek 77.Bk -words 78.Op Fl w Ar writesize 79.Ek 80.Bk -words 81.Op Fl x Ar retrans 82.Ek 83.Ar rhost:path node 84.Sh DESCRIPTION 85The 86.Nm 87command 88calls the 89.Xr mount 2 90system call to prepare and graft a remote nfs file system (rhost:path) 91on to the file system tree at the point 92.Ar node . 93This command is normally executed by 94.Xr mount 8 . 95It implements the mount protocol as described in RFC 1094, Appendix A and 96.%T "NFS: Network File System Version 3 Protocol Specification" , 97Appendix I. 98.Pp 99The options are: 100.Bl -tag -width indent 101.It Fl 2 102Use the NFS Version 2 protocol. 103.It Fl 3 104Use the NFS Version 3 protocol. 105The default is to try version 3 first, and 106fall back to version 2 if the mount fails. 107.It Fl D 108Used with NQNFS to set the 109.Dq "dead server threshold" 110to the specified number of round trip timeout intervals. 111After a 112.Dq "dead server threshold" 113of retransmit timeouts, 114cached data for the unresponsive server is assumed to still be valid. 115Values may be set in the range of 1 - 9, with 9 referring to an 116.Dq "infinite dead threshold" 117(i.e. never assume cached data still valid). 118This option is not generally recommended and is really an experimental 119feature. 120.It Fl I 121Set the readdir read size to the specified value. 122The value should normally 123be a multiple of DIRBLKSIZ that is \*[Le] the read size for the mount. 124.It Fl K 125Pass Kerberos authenticators to the server for client-to-server 126user-credential mapping. 127This requires that the kernel be built with the NFSKERB option. 128(Refer to the INTERNET-DRAFT titled 129.%T "Authentication Mechanisms for ONC RPC" , 130for more information.) 131.It Fl L 132Used with NQNFS to set the lease term to the specified number of seconds. 133Only use this argument for mounts with a large round trip delay. 134Values are normally in the 10-30 second range. 135.It Fl P 136Use a reserved socket port number. 137This is the default, and available 138for backwards compatibility purposes only. 139.It Fl R 140Set the retry count for doing the mount to the specified value. 141.It Fl T 142Use TCP transport instead of UDP. 143This is recommended for servers that are not on the same physical network as 144the client. 145Not all NFS servers, especially not old ones, support this. 146.It Fl U 147Force the mount protocol to use UDP transport, even for TCP NFS mounts. 148(Necessary for some old 149.Bx 150servers.) 151.It Fl X 152Perform 32 \*[Lt]-\*[Gt] 64 bit directory cookie translation for version 3 mounts. 153This may be need in the case of a server using the upper 32 bits of 154v3 directory cookies, and when you are running emulated binaries 155that access such a filesystem. 156Native 157.Nx 158binaries will never need this option. 159This option introduces some overhead. 160.It Fl a 161Set the read-ahead count to the specified value. 162This may be in the range of 0 - 4, and determines how many blocks 163will be read ahead when a large file is being read sequentially. 164Trying a value greater than 1 for this is suggested for 165mounts with a large bandwidth * delay product. 166.It Fl b 167If an initial attempt to contact the server fails, fork off a child to keep 168trying the mount in the background. 169Useful for 170.Xr fstab 5 , 171where the filesystem mount is not critical to multiuser operation. 172.It Fl c 173For UDP mount points, do not do a 174.Xr connect 2 . 175This flag is deprecated and connectionless UDP mounts are the default. 176.It Fl C 177For UDP mount points, do a 178.Xr connect 2 . 179Although this flag increases the efficiency of UDP mounts it cannot 180be used for servers that do not reply to requests from the 181standard NFS port number 2049, or for servers with multiple network 182interfaces. 183In these cases if the socket is connected and the server 184replies from a different port number or a different network interface 185the client will get ICMP port unreachable and the mount will hang. 186.It Fl d 187Turn off the dynamic retransmit timeout estimator. 188This may be useful for UDP mounts that exhibit high retry rates, 189since it is possible that the dynamically estimated timeout interval is too 190short. 191.It Fl g 192Set the maximum size of the group list for the credentials to the 193specified value. 194This should be used for mounts on old servers that cannot handle a 195group list size of 16, as specified in RFC 1057. 196Try 8, if users in a lot of groups cannot get response from the mount 197point. 198.It Fl i 199Make the mount interruptible, which implies that file system calls that 200are delayed due to an unresponsive server will fail with EINTR when a 201termination signal is posted for the process. 202.It Fl l 203Used with NQNFS and NFSV3 to specify that the ReaddirPlus RPC should 204be used. 205This option reduces RPC traffic for cases such as 206.Dq "ls -l" , 207but tends to flood the attribute and name caches with prefetched entries. 208Try this option and see whether performance improves or degrades. 209Probably most useful for client to server network 210interconnects with a large bandwidth times delay product. 211.It Fl m 212Set the Kerberos realm to the string argument. 213Used with the 214.Fl K 215option for mounts to other realms. 216.It Fl o 217Options are specified with a 218.Fl o 219flag followed by a comma separated string of options. 220See the 221.Xr mount 8 222man page for possible options and their meanings. 223.It Fl p 224Do not use a reserved port number for RPCs. 225This option is provided only to be able to mimic the old 226default behavior of not using a reserved port, and should rarely be useful. 227.It Fl q 228Use the leasing extensions to the NFS Version 3 protocol 229to maintain cache consistency. 230This protocol version 2 revision to Not Quite Nfs (NQNFS) 231is only supported by this updated release of NFS code. 232It is not backwards compatible with the version 1 NQNFS protocol 233that was part of the first release of 234.Bx 4.4 Lite . 235To interoperate with a first release 236.Bx 4.4 Lite 237NFS system you will have to avoid this option until you have had 238an opportunity to upgrade the NFS code to release 2 of 239.Bx 4.4 Lite 240on all your systems. 241.It Fl r 242Set the read data size to the specified value. 243It should normally be a power of 2 greater than or equal to 1024. 244This should be used for UDP mounts when the 245.Dq "fragments dropped after timeout" 246value is getting large while actively using a mount point. 247(Use 248.Xr netstat 1 249with the 250.Fl s 251option to see what the 252.Dq "fragments dropped after timeout" 253value is.) 254See the 255.Fl w 256option as well. 257.It Fl s 258A soft mount, which implies that file system calls will fail 259after 260.Ar retrycnt 261round trip timeout intervals. 262.It Fl t 263Set the initial retransmit timeout to the specified value. 264May be useful for fine tuning UDP mounts over internetworks 265with high packet loss rates or an overloaded server. 266Try increasing the interval if 267.Xr nfsstat 1 268shows high retransmit rates while the file system is active or reducing the 269value if there is a low retransmit rate but long response delay observed. 270(Normally, the -d option should be specified when using this option to manually 271tune the timeout 272interval.) 273.It Fl w 274Set the write data size to the specified value. 275Ditto the comments with respect to the 276.Fl r 277option, but using the 278.Dq "fragments dropped after timeout" 279value on the server instead of the client. 280Note that both the 281.Fl r 282and 283.Fl w 284options should only be used as a last ditch effort at improving performance 285when mounting servers that do not support TCP mounts. 286.It Fl x 287Set the retransmit timeout count for soft mounts to the specified value. 288.El 289.Sh EXAMPLES 290The simplest way to invoke 291.Nm 292is with a command like: 293.Pp 294.Dl "mount remotehost:/filesystem /localmountpoint 295or: 296.Dl "mount -t nfs remotehost:/filesystem /localmountpoint 297.Pp 298It is also possible to automaticly mount filesystems at boot from your 299.Pa /etc/fstab 300by using a line like: 301.Pp 302.Dl "remotehost:/home /home nfs rw 0 0 303.Sh PERFORMANCE 304As can be derived from the comments accompanying the options, performance 305tuning of NFS can be a non-trivial task. 306Here are some common points 307to watch: 308.Bl -bullet -offset indent 309.It 310Increasing the read and write size with the 311.Fl r 312and 313.Fl w 314options respectively will increase throughput if the hardware can handle 315the larger packet sizes. 316The default size for version 2 is 8k when 317using UDP, 64k when using TCP. 318The default size for v3 is platform dependent: 319on i386, the default is 32k, for other platforms it is 8k. 320Values over 32132k are only supported for TCP, where 64k is the maximum. 322Any value 323over 32k is unlikely to get you more performance, unless you have 324a very fast network. 325.It 326If the hardware can not handle larger packet sizes, you may see low 327performance figures or even temporary hangups during NFS activity. 328This can especially happen with older ethernet cards. 329What happens 330is that either the buffer on the card on the client side is overflowing, 331or that similar events occur on the server, leading to a lot 332of dropped packets. 333In this case, decreasing the read and write size, 334using TCP, or a combination of both will usually lead to better throughput. 335Should you need to decrease the read and write size for all your NFS mounts 336because of a slow ethernet card, you can use 337.Bl -ohang -compact 338.It Cd options NFS_RSIZE=value 339.It Cd options NFS_WSIZE=value 340.El 341in your kernel config file to avoid having do specify the 342sizes for all mounts. 343.It 344For connections that are not on the same LAN, and/or may experience 345packet loss, using TCP is strongly recommended. 346.El 347.Sh ERRORS 348Some common problems with 349.Nm 350can be difficult for first time users to understand. 351.Pp 352.Dl "mount_nfs: can't access /foo: Permission denied 353.Pp 354This message means that the remote host, is either not exporting 355the filesystem you requested, or is not exporting it to your host. 356If you believe the remote host is indeed exporting a filesystem to you, 357make sure the 358.Xr exports 5 359file is exporting the proper directories. 360A common mistake is that 361mountd will not export a filesystem with the 362.Fl alldirs 363option, unless it 364is a mount point on the exporting host. 365It is not possible to remotely 366mount a subdirectory of an exported mount, unless it is exported with the 367.Fl alldirs 368option. 369.Pp 370The following error: 371.Pp 372.Dl "NFS Portmap: RPC: Program not registered 373.Pp 374means that the remote host is not running 375.Xr mountd 8 . 376The program 377.Xr rpcinfo 8 378can be used to determine if the remote host is running nfsd, and mountd by issuing 379the command: 380.Pp 381.Dl rpcinfo -p remotehostname 382.Pp 383If the remote host is running nfsd, and mountd, it would display: 384.Pp 385.Dl "100005 3 udp 719 mountd 386.Dl "100005 1 tcp 720 mountd 387.Dl "100005 3 tcp 720 mountd 388.Dl "100003 2 udp 2049 nfs 389.Dl "100003 3 udp 2049 nfs 390.Dl "100003 2 tcp 2049 nfs 391.Dl "100003 3 tcp 2049 nfs 392.Pp 393The error: 394.Pp 395.Dl "mount_nfs: can't get net id for host 396.Pp 397indicates that mount_nfs cannot resolve the name of the remote host. 398.Sh SEE ALSO 399.Xr mount 2 , 400.Xr unmount 2 , 401.Xr exports 5 , 402.Xr fstab 5 , 403.Xr mount 8 , 404.Xr mountd 8 , 405.Xr rpcinfo 8 406