1.\" Copyright (c) 1992, 1993, 1994, 1995 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)mount_nfs.8 8.3 (Berkeley) 3/29/95 29.\" 30.Dd June 14, 2023 31.Dt MOUNT_NFS 8 32.Os 33.Sh NAME 34.Nm mount_nfs 35.Nd mount NFS file systems 36.Sh SYNOPSIS 37.Nm 38.Op Fl 23bcdiLlNPsTU 39.Op Fl a Ar maxreadahead 40.Op Fl D Ar deadthresh 41.Op Fl g Ar maxgroups 42.Op Fl I Ar readdirsize 43.Op Fl o Ar options 44.Op Fl R Ar retrycnt 45.Op Fl r Ar readsize 46.Op Fl t Ar timeout 47.Op Fl w Ar writesize 48.Op Fl x Ar retrans 49.Ar rhost : Ns Ar path node 50.Sh DESCRIPTION 51The 52.Nm 53utility calls the 54.Xr nmount 2 55system call to prepare and graft a remote NFS file system 56.Pq Ar rhost : Ns Ar path 57on to the file system tree at the point 58.Ar node . 59This command is normally executed by 60.Xr mount 8 . 61For NFSv2 and NFSv3, 62it implements the mount protocol as described in RFC 1094, Appendix A and 63RFC 1813, Appendix I. 64For NFSv4, it uses the NFSv4 protocol as described in RFC 7530, RFC 5661 and 65RFC 7862. 66.Pp 67By default, 68.Nm 69keeps retrying until the mount succeeds. 70This behaviour is intended for file systems listed in 71.Xr fstab 5 72that are critical to the boot process. 73For non-critical file systems, the 74.Cm bg 75and 76.Cm retrycnt 77options provide mechanisms to prevent the boot process from hanging 78if the server is unavailable. 79.Pp 80If the server becomes unresponsive while an NFS file system is 81mounted, any new or outstanding file operations on that file system 82will hang uninterruptibly until the server comes back. 83To modify this default behaviour, see the 84.Cm intr 85and 86.Cm soft 87options. 88.Pp 89The options are: 90.Bl -tag -width indent 91.It Fl o 92Options are specified with a 93.Fl o 94flag followed by a comma separated string of options. 95See the 96.Xr mount 8 97man page for possible options and their meanings. 98The following NFS specific options are also available: 99.Bl -tag -width indent 100.It Cm acregmin Ns = Ns Aq Ar seconds 101.It Cm acregmax Ns = Ns Aq Ar seconds 102.It Cm acdirmin Ns = Ns Aq Ar seconds 103.It Cm acdirmax Ns = Ns Aq Ar seconds 104When attributes of files are cached, a timeout calculated to determine 105whether a given cache entry has expired. 106These four values determine the upper and lower bounds of the timeouts for 107.Dq directory 108attributes and 109.Dq regular 110(ie: everything else). 111The default values are 3 -> 60 seconds 112for regular files, and 30 -> 60 seconds for directories. 113The algorithm to calculate the timeout is based on the age of the file. 114The older the file, 115the longer the cache is considered valid, subject to the limits above. 116.It Cm actimeo Ns = Ns Aq Ar seconds 117Set four cache timeouts above to specified value. 118.It Cm allgssname 119This option can be used along with 120.Fl o Cm gssname 121to specify that all operations should use the host-based initiator 122credential. 123This may be used for clients that run system daemons that need to 124access files on the NFSv4 mounted volume. 125.It Cm bg 126If an initial attempt to contact the server fails, fork off a child to keep 127trying the mount in the background. 128Useful for 129.Xr fstab 5 , 130where the file system mount is not critical to multiuser operation. 131.It Cm bgnow 132Like 133.Cm bg , 134fork off a child to keep trying the mount in the background, 135but do not attempt to mount in the foreground first. 136This eliminates a 13760+ second timeout when the server is not responding. 138Useful for speeding up the boot process of a client when the server is 139likely to be unavailable. 140This is often the case for interdependent servers 141such as cross-mounted servers (each of two servers is an NFS client of 142the other) and for cluster nodes that must boot before the file servers. 143.It Cm deadthresh Ns = Ns Aq Ar value 144Set the 145.Dq "dead server threshold" 146to the specified number of round trip timeout intervals before a 147.Dq "server not responding" 148message is displayed. 149.It Cm dumbtimer 150Turn off the dynamic retransmit timeout estimator. 151This may be useful for UDP mounts that exhibit high retry rates, 152since it is possible that the dynamically estimated timeout interval is too 153short. 154.It Cm fg 155Same as not specifying 156.Cm bg . 157.It Cm gssname Ns = Ns Aq Ar service-principal-name 158This option can be used with the KerberosV security flavors for NFSv4 mounts 159to specify the 160.Dq "service-principal-name" 161of a host-based entry in the default 162keytab file that is used for system operations. 163It allows the mount to be performed by 164.Dq "root" 165and avoids problems with 166cached credentials for the system operations expiring. 167The 168.Dq "service-principal-name" 169should be specified without instance or domain and is typically 170.Dq "host" , 171.Dq "nfs" 172or 173.Dq "root" , 174although the form 175.Sm off 176.Aq Ar service 177@ 178.Aq Ar fqdn 179.Sm on 180can also be used if the local system's 181.Xr gethostname 3 182value does not match the host-based principal in the keytab. 183.It Cm hard 184Same as not specifying 185.Cm soft . 186.It Cm intr 187Make the mount interruptible, which implies that file system calls that 188are delayed due to an unresponsive server will fail with EINTR when a 189termination signal is posted for the process. 190To avoid leaving file locks in an indeterminate state on the NFS 191server, it is recommended that the 192.Cm nolockd 193option be used with this option. 194.It Cm maxgroups Ns = Ns Aq Ar value 195Set the maximum size of the group list for the credentials to the 196specified value. 197This should be used for mounts on old servers that cannot handle a 198group list size of 16, as specified in RFC 1057. 199Try 8, if users in a lot of groups cannot get response from the mount 200point. 201.It Cm mntudp 202Force the mount protocol to use UDP transport, even for TCP NFS mounts. 203(Necessary for some old 204.Bx 205servers.) 206.It Cm nametimeo Ns = Ns Aq Ar value 207Override the default of NFS_DEFAULT_NAMETIMEO for the timeout (in seconds) 208for positive name cache entries. 209If this is set to 0 it disables positive name caching for the mount point. 210.It Cm negnametimeo Ns = Ns Aq Ar value 211Override the default of NFS_DEFAULT_NEGNAMETIMEO for the timeout (in seconds) 212for negative name cache entries. 213If this is set to 0 it disables negative name caching for the mount point. 214.It Cm nconnect Ns = Ns Aq Ar value 215Specify the number of TCP connections (1-16) to be used 216for an NFS Version 4, minor version 1 or 2 mount. 217Multiple TCP connections can provide more client to server network 218bandwidth for certain network configurations such as: 219.Bd -literal 220- Multiple network interfaces that are aggregated together. 221- A fast network interface that uses multiple queues. 222.Ed 223.sp 224The first TCP connection will be used for all RPCs that consist 225entirely of small RPC messages. 226The RPCs that can have large RPC messages (Read/Readdir/Write) are 227distributed over the additional TCP connections in a round robin 228fashion. 229This option will result in more IP port#s being used. 230This option requires the 231.Cm nfsv4 232option. 233Note that for NFS servers such as AmazonEFS, where each new TCP 234connection can connect to a different cluster that maintains lock 235state separately, this option cannot be used. 236.It Cm nfsv2 237Use the NFS Version 2 protocol (the default is to try version 3 first 238then version 2). 239Note that NFS version 2 has a file size limit of 2 gigabytes. 240.It Cm nfsv3 241Use the NFS Version 3 protocol. 242.It Cm nfsv4 243Use the NFS Version 4 protocol. 244This option will force the mount to use 245TCP transport. 246By default, the highest minor version of NFS Version 4 that is 247supported by the NFS Version 4 server will be used. 248See the 249.Cm minorversion 250option. 251Make sure that all your NFS Version 4 clients have unique 252values in 253.Pa /etc/hostid . 254.It Cm minorversion Ns = Ns Aq Ar value 255Use the specified minor version for a NFS Version 4 mount, 256overriding the default. 257The minor versions supported are 0, 1, and 2. 258This option is only meaningful when used with the 259.Cm nfsv4 260option. 261.It Cm oneopenown 262Make a minor version 1 or 2 of the NFS Version 4 protocol mount use a single 263OpenOwner for all Opens. 264This may be useful for a server with a very low limit on OpenOwners, such as 265AmazonEFS. 266It may be required when an accumulation of NFS version 4 Opens occurs, 267as indicated by the 268.Dq Opens 269count displayed by 270.Xr nfsstat 1 271with the 272.Fl c 273and 274.Fl E 275command-line options. 276A common case for an accumulation of Opens is a shared library within 277the NFS mount that is used by several 278processes, where at least one of these processes is always running. 279This option cannot be used for an NFS Version 4, minor version 0 mount. 280It may not work correctly when Delegations are being issued by a server, 281but note that the AmazonEFS server does not issued delegations at this time. 282This option is only meaningful when used with the 283.Cm nfsv4 284option. 285.It Cm pnfs 286Enable support for parallel NFS (pNFS) for minor version 1 or 2 of the 287NFS Version 4 protocol. 288This option is only meaningful when used with the 289.Cm nfsv4 290option. 291.It Cm noac 292Disable attribute caching. 293.It Cm noconn 294For UDP mount points, do not do a 295.Xr connect 2 . 296This must be used if the server does not reply to requests from the standard 297NFS port number 2049 or replies to requests using a different IP address 298(which can occur if the server is multi-homed). 299Setting the 300.Va vfs.nfs.nfs_ip_paranoia 301sysctl to 0 will make this option the default. 302.It Cm nocto 303Normally, NFS clients maintain the close-to-open cache coherency. 304This works by flushing at close time and checking at open time. 305Checking at open time is implemented by getting attributes from 306the server and purging the data cache if they do not match 307attributes cached by the client. 308.Pp 309This option disables checking at open time. 310It may improve performance for read-only mounts, 311but should only be used if the data on the server changes rarely. 312Be sure to understand the consequences before enabling this option. 313.It Cm noinet4 , noinet6 314Disables 315.Dv AF_INET 316or 317.Dv AF_INET6 318connections. 319Useful for hosts that have 320both an A record and an AAAA record for the same name. 321.It Cm nolockd 322Do 323.Em not 324forward 325.Xr fcntl 2 326locks over the wire via the NLM protocol for NFSv3 mounts 327or via the NFSv4 protocol for NFSv4 mounts. 328All locks will be local and not seen by the server 329and likewise not seen by other NFS clients for NFSv3 or NFSv4 mounts. 330This removes the need to run the 331.Xr rpcbind 8 332service and the 333.Xr rpc.statd 8 334and 335.Xr rpc.lockd 8 336servers on the client for NFSv3 mounts. 337Note that this option will only be honored when performing the 338initial mount, it will be silently ignored if used while updating 339the mount options. 340Also, note that NFSv4 mounts do not use these daemons. 341The NFSv4 protocol handles locks, 342unless this option is specified. 343.It Cm noncontigwr 344This mount option allows the NFS client to 345combine non-contiguous byte ranges being written 346such that the dirty byte range becomes a superset of the bytes 347that are dirty. 348This reduces the number of writes significantly for software 349builds. 350The merging of byte ranges is not done if the file has been file 351locked, since most applications modifying a file from multiple 352clients will use file locking. 353As such, this option could result in a corrupted file for the 354rare case of an application modifying the file from multiple 355clients concurrently without using file locking. 356.It Cm principal 357For the RPCSEC_GSS security flavors, such as krb5, krb5i and krb5p, 358this option sets the name of the host based principal name expected 359by the server. 360This option overrides the default, which will be ``nfs@<server-fqdn>'' 361and should normally be sufficient. 362.It Cm noresvport 363Do 364.Em not 365use a reserved socket port number (see below). 366.It Cm port Ns = Ns Aq Ar port_number 367Use specified port number for NFS requests. 368The default is to query the portmapper for the NFS port. 369.It Cm proto Ns = Ns Aq Ar protocol 370Specify transport protocol version to use. 371Currently, they are: 372.Bd -literal 373udp - Use UDP over IPv4 374tcp - Use TCP over IPv4 375udp6 - Use UDP over IPv6 376tcp6 - Use TCP over IPv6 377.Ed 378.It Cm rdirplus 379Used with NFSV3 to specify that the \fBReaddirPlus\fR RPC should 380be used. 381For NFSV4, setting this option has a similar effect, in that it will make 382the Readdir Operation get more attributes. 383This option reduces RPC traffic for cases such as 384.Dq "ls -l" , 385but tends to flood the attribute and name caches with prefetched entries. 386Try this option and see whether performance improves or degrades. 387Probably 388most useful for client to server network interconnects with a large bandwidth 389times delay product. 390.It Cm readahead Ns = Ns Aq Ar value 391Set the read-ahead count to the specified value. 392This may be in the range of 0 - 4, and determines how many blocks 393will be read ahead when a large file is being read sequentially. 394Trying a value greater than 1 for this is suggested for 395mounts with a large bandwidth * delay product. 396.It Cm readdirsize Ns = Ns Aq Ar value 397Set the readdir read size to the specified value. 398The value should normally 399be a multiple of 400.Dv DIRBLKSIZ 401that is <= the read size for the mount. 402.It Cm resvport 403Use a reserved socket port number. 404This flag is obsolete, and only retained for compatibility reasons. 405Reserved port numbers are used by default now. 406(For the rare case where the client has a trusted root account 407but untrustworthy users and the network cables are in secure areas this does 408help, but for normal desktop clients this does not apply.) 409.It Cm retrans Ns = Ns Aq Ar value 410Set the retransmit timeout count for soft mounts to the specified value. 411.It Cm retrycnt Ns = Ns Aq Ar count 412Set the mount retry count to the specified value. 413The default is a retry count of zero, which means to keep retrying 414forever. 415There is a 60 second delay between each attempt. 416.It Cm rsize Ns = Ns Aq Ar value 417Set the read data size to the specified value. 418It should normally be a power of 2 greater than or equal to 1024. 419This should be used for UDP mounts when the 420.Dq "fragments dropped due to timeout" 421value is getting large while actively using a mount point. 422(Use 423.Xr netstat 1 424with the 425.Fl s 426option to see what the 427.Dq "fragments dropped due to timeout" 428value is.) 429.It Cm sec Ns = Ns Aq Ar flavor 430This option specifies what security flavor should be used for the mount. 431Currently, they are: 432.Bd -literal 433krb5 - Use KerberosV authentication 434krb5i - Use KerberosV authentication and 435 apply integrity checksums to RPCs 436krb5p - Use KerberosV authentication and 437 encrypt the RPC data 438sys - The default AUTH_SYS, which uses a 439 uid + gid list authenticator 440.Ed 441.It Cm soft 442A soft mount, which implies that file system calls will fail 443after 444.Ar retrycnt 445round trip timeout intervals. 446.It Cm syskrb5 447This option specifies that a KerberosV NFSv4 minor version 1 or 2 mount 448uses AUTH_SYS for system operations. 449Using this option avoids the need for a KerberosV mount to have a 450host-based principal entry in the default keytab file 451(no 452.Cm gssname 453option) or a requirement for the user doing the mount to have a 454valid KerberosV ticket granting ticket (TGT) when the mount is done. 455This option is intended to be used with the 456.Cm sec Ns = Ns krb5 457and 458.Cm tls 459options and can only be used for 460NFSv4 mounts with minor version 1 or 2. 461.It Cm tcp 462Use TCP transport. 463This is the default option, as it provides for increased reliability on both 464LAN and WAN configurations compared to UDP. 465Some old NFS servers do not support this method; UDP mounts may be required 466for interoperability. 467.It Cm timeout Ns = Ns Aq Ar value 468Set the initial retransmit timeout to the specified value, 469expressed in tenths of a second. 470May be useful for fine tuning UDP mounts over internetworks 471with high packet loss rates or an overloaded server. 472Try increasing the interval if 473.Xr nfsstat 1 474shows high retransmit rates while the file system is active or reducing the 475value if there is a low retransmit rate but long response delay observed. 476(Normally, the 477.Cm dumbtimer 478option should be specified when using this option to manually 479tune the timeout 480interval.) 481.It Cm timeo Ns = Ns Aq Ar value 482Alias for 483.Cm timeout . 484.It Cm tls 485This option specifies that the connection to the server must use TLS 486per RFC 9289. 487TLS is only supported for TCP connections and the 488.Xr rpc.tlsclntd 8 489daemon must be running for an NFS over TCP connection to use TLS. 490.It Cm tlscertname Ns = Ns Aq Ar name 491This option specifies the name of an alternate certificate to be 492presented to the NFS server during TLS handshake. 493The default certificate file names are 494.Dq cert.pem 495and 496.Dq certkey.pem . 497When this option is specified, 498.Ar name 499replaces 500.Dq cert 501in the above file names. 502For example, if the value of 503.Ar name 504is specified as 505.Dq other 506the certificate file names to be used will be 507.Dq other.pem 508and 509.Dq otherkey.pem . 510These files are stored in 511.Pa /etc/rpc.tlsclntd 512by default. 513This option is only meaningful when used with the 514.Cm tls 515option and the 516.Xr rpc.tlsclntd 8 517is running with the 518.Fl m 519command line flag set. 520.It Cm udp 521Use UDP transport. 522.It Cm vers Ns = Ns Aq Ar vers_number 523Use the specified version number for NFS requests. 524See the 525.Cm nfsv2 , 526.Cm nfsv3 , 527and 528.Cm nfsv4 529options for details. 530.It Cm wcommitsize Ns = Ns Aq Ar value 531Set the maximum pending write commit size to the specified value. 532This determines the maximum amount of pending write data that the NFS 533client is willing to cache for each file. 534.It Cm wsize Ns = Ns Aq Ar value 535Set the write data size to the specified value. 536Ditto the comments w.r.t.\& the 537.Cm rsize 538option, but using the 539.Dq "fragments dropped due to timeout" 540value on the server instead of the client. 541Note that both the 542.Cm rsize 543and 544.Cm wsize 545options should only be used as a last ditch effort at improving performance 546when mounting servers that do not support TCP mounts. 547.El 548.El 549.Sh IMPLEMENTATION NOTES 550When neither the 551.Cm rsize 552nor 553.Cm wsize 554options are specified, the I/O size will be set to the largest value 555supported by both the NFS client and server. 556The largest value supported by the NFS client is defined by 557the tunable 558.Cd vfs.maxbcachebuf 559which can be set to a power of two up to 560.Cd kern.maxphys . 561.Pp 562The 563.Xr nfsstat 1 564command with the 565.Ic -m 566command line option will show what 567.Nm 568option settings are actually in use for the mount. 569.Sh COMPATIBILITY 570The following command line flags are equivalent to 571.Fl o 572named options and are supported for compatibility with older 573installations. 574.Bl -tag -width indent 575.It Fl 2 576Same as 577.Fl o Cm nfsv2 578.It Fl 3 579Same as 580.Fl o Cm nfsv3 581.It Fl D 582Same as 583.Fl o Cm deadthresh 584.It Fl I 585Same as 586.Fl o Cm readdirsize Ns = Ns Aq Ar value 587.It Fl L 588Same as 589.Fl o Cm nolockd 590.It Fl N 591Same as 592.Fl o Cm noresvport 593.It Fl P 594Use a reserved socket port number. 595This flag is obsolete, and only retained for compatibility reasons. 596(For the rare case where the client has a trusted root account 597but untrustworthy users and the network cables are in secure areas this does 598help, but for normal desktop clients this does not apply.) 599.It Fl R 600Same as 601.Fl o Cm retrycnt Ns = Ns Aq Ar value 602.It Fl T 603Same as 604.Fl o Cm tcp 605.It Fl U 606Same as 607.Fl o Cm mntudp 608.It Fl a 609Same as 610.Fl o Cm readahead Ns = Ns Aq Ar value 611.It Fl b 612Same as 613.Fl o Cm bg 614.It Fl c 615Same as 616.Fl o Cm noconn 617.It Fl d 618Same as 619.Fl o Cm dumbtimer 620.It Fl g 621Same as 622.Fl o Cm maxgroups 623.It Fl i 624Same as 625.Fl o Cm intr 626.It Fl l 627Same as 628.Fl o Cm rdirplus 629.It Fl r 630Same as 631.Fl o Cm rsize Ns = Ns Aq Ar value 632.It Fl s 633Same as 634.Fl o Cm soft 635.It Fl t 636Same as 637.Fl o Cm retransmit Ns = Ns Aq Ar value 638.It Fl w 639Same as 640.Fl o Cm wsize Ns = Ns Aq Ar value 641.It Fl x 642Same as 643.Fl o Cm retrans Ns = Ns Aq Ar value 644.El 645.Pp 646The following 647.Fl o 648named options are equivalent to other 649.Fl o 650named options and are supported for compatibility with other 651operating systems (e.g., Linux, Solaris, and OSX) to ease usage of 652.Xr autofs 5 653support. 654.Bl -tag -width indent 655.It Fl o Cm vers Ns = Ns 2 656Same as 657.Fl o Cm nfsv2 658.It Fl o Cm vers Ns = Ns 3 659Same as 660.Fl o Cm nfsv3 661.It Fl o Cm vers Ns = Ns 4 662Same as 663.Fl o Cm nfsv4 664.El 665.Sh SEE ALSO 666.Xr nfsstat 1 , 667.Xr nmount 2 , 668.Xr unmount 2 , 669.Xr lagg 4 , 670.Xr nfsv4 4 , 671.Xr fstab 5 , 672.Xr gssd 8 , 673.Xr mount 8 , 674.Xr nfsd 8 , 675.Xr nfsiod 8 , 676.Xr rpc.tlsclntd 8 , 677.Xr showmount 8 678.Sh HISTORY 679A version of the 680.Nm 681utility appeared in 682.Bx 4.4 . 683.Sh BUGS 684Since NFSv4 performs open/lock operations that have their ordering strictly 685enforced by the server, the options 686.Cm intr 687and 688.Cm soft 689cannot be safely used. 690For NFSv4 minor version 1 or 2 mounts, the ordering is done 691via session slots and the NFSv4 client now handles broken session slots 692fairly well. 693As such, if the 694.Cm nolockd 695option is used along with 696.Cm intr 697and/or 698.Cm soft , 699an NFSv4 minor version 1 or 2 mount 700should work fairly well, although still not completely correctly. 701For NFSv4 minor version 0 mounts, 702.Cm hard 703mounts without the 704.Cm intr 705mount option is strongly recommended. 706