xref: /freebsd/sbin/mount_nfs/mount_nfs.8 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
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.\" $FreeBSD$
30.\"
31.Dd December 21, 2020
32.Dt MOUNT_NFS 8
33.Os
34.Sh NAME
35.Nm mount_nfs
36.Nd mount NFS file systems
37.Sh SYNOPSIS
38.Nm
39.Op Fl 23bcdiLlNPsTU
40.Op Fl a Ar maxreadahead
41.Op Fl D Ar deadthresh
42.Op Fl g Ar maxgroups
43.Op Fl I Ar readdirsize
44.Op Fl o Ar options
45.Op Fl R Ar retrycnt
46.Op Fl r Ar readsize
47.Op Fl t Ar timeout
48.Op Fl w Ar writesize
49.Op Fl x Ar retrans
50.Ar rhost : Ns Ar path node
51.Sh DESCRIPTION
52The
53.Nm
54utility calls the
55.Xr nmount 2
56system call to prepare and graft a remote NFS file system
57.Pq Ar rhost : Ns Ar path
58on to the file system tree at the point
59.Ar node .
60This command is normally executed by
61.Xr mount 8 .
62For NFSv2 and NFSv3,
63it implements the mount protocol as described in RFC 1094, Appendix A and
64RFC 1813, Appendix I.
65For NFSv4, it uses the NFSv4 protocol as described in RFC 7530, RFC 5661 and
66RFC 7862.
67.Pp
68By default,
69.Nm
70keeps retrying until the mount succeeds.
71This behaviour is intended for file systems listed in
72.Xr fstab 5
73that are critical to the boot process.
74For non-critical file systems, the
75.Cm bg
76and
77.Cm retrycnt
78options provide mechanisms to prevent the boot process from hanging
79if the server is unavailable.
80.Pp
81If the server becomes unresponsive while an NFS file system is
82mounted, any new or outstanding file operations on that file system
83will hang uninterruptibly until the server comes back.
84To modify this default behaviour, see the
85.Cm intr
86and
87.Cm soft
88options.
89.Pp
90The options are:
91.Bl -tag -width indent
92.It Fl o
93Options are specified with a
94.Fl o
95flag followed by a comma separated string of options.
96See the
97.Xr mount 8
98man page for possible options and their meanings.
99The following NFS specific options are also available:
100.Bl -tag -width indent
101.It Cm acregmin Ns = Ns Aq Ar seconds
102.It Cm acregmax Ns = Ns Aq Ar seconds
103.It Cm acdirmin Ns = Ns Aq Ar seconds
104.It Cm acdirmax Ns = Ns Aq Ar seconds
105When attributes of files are cached, a timeout calculated to determine
106whether a given cache entry has expired.
107These four values determine the upper and lower bounds of the timeouts for
108.Dq directory
109attributes and
110.Dq regular
111(ie: everything else).
112The default values are 3 -> 60 seconds
113for regular files, and 30 -> 60 seconds for directories.
114The algorithm to calculate the timeout is based on the age of the file.
115The older the file,
116the longer the cache is considered valid, subject to the limits above.
117.It Cm actimeo Ns = Ns Aq Ar seconds
118Set four cache timeouts above to specified value.
119.It Cm allgssname
120This option can be used along with
121.Fl o Cm gssname
122to specify that all operations should use the host-based initiator
123credential.
124This may be used for clients that run system daemons that need to
125access files on the NFSv4 mounted volume.
126.It Cm bg
127If an initial attempt to contact the server fails, fork off a child to keep
128trying the mount in the background.
129Useful for
130.Xr fstab 5 ,
131where the file system mount is not critical to multiuser operation.
132.It Cm deadthresh Ns = Ns Aq Ar value
133Set the
134.Dq "dead server threshold"
135to the specified number of round trip timeout intervals before a
136.Dq "server not responding"
137message is displayed.
138.It Cm dumbtimer
139Turn off the dynamic retransmit timeout estimator.
140This may be useful for UDP mounts that exhibit high retry rates,
141since it is possible that the dynamically estimated timeout interval is too
142short.
143.It Cm fg
144Same as not specifying
145.Cm bg .
146.It Cm gssname Ns = Ns Aq Ar service-principal-name
147This option can be used with the KerberosV security flavors for NFSv4 mounts
148to specify the
149.Dq "service-principal-name"
150of a host-based entry in the default
151keytab file that is used for system operations.
152It allows the mount to be performed by
153.Dq "root"
154and avoids problems with
155cached credentials for the system operations expiring.
156The
157.Dq "service-prinicpal-name"
158should be specified without instance or domain and is typically
159.Dq "host" ,
160.Dq "nfs"
161or
162.Dq "root" ,
163although the form
164.Sm off
165.Aq Ar service
166@
167.Aq Ar fqdn
168.Sm on
169can also be used if the local system's
170.Xr gethostname 3
171value does not match the host-based principal in the keytab.
172.It Cm hard
173Same as not specifying
174.Cm soft .
175.It Cm intr
176Make the mount interruptible, which implies that file system calls that
177are delayed due to an unresponsive server will fail with EINTR when a
178termination signal is posted for the process.
179.It Cm maxgroups Ns = Ns Aq Ar value
180Set the maximum size of the group list for the credentials to the
181specified value.
182This should be used for mounts on old servers that cannot handle a
183group list size of 16, as specified in RFC 1057.
184Try 8, if users in a lot of groups cannot get response from the mount
185point.
186.It Cm mntudp
187Force the mount protocol to use UDP transport, even for TCP NFS mounts.
188(Necessary for some old
189.Bx
190servers.)
191.It Cm nametimeo Ns = Ns Aq Ar value
192Override the default of NFS_DEFAULT_NAMETIMEO for the timeout (in seconds)
193for positive name cache entries.
194If this is set to 0 it disables positive name caching for the mount point.
195.It Cm negnametimeo Ns = Ns Aq Ar value
196Override the default of NFS_DEFAULT_NEGNAMETIMEO for the timeout (in seconds)
197for negative name cache entries.
198If this is set to 0 it disables negative name caching for the mount point.
199.It Cm nfsv2
200Use the NFS Version 2 protocol (the default is to try version 3 first
201then version 2).
202Note that NFS version 2 has a file size limit of 2 gigabytes.
203.It Cm nfsv3
204Use the NFS Version 3 protocol.
205.It Cm nfsv4
206Use the NFS Version 4 protocol.
207This option will force the mount to use
208TCP transport.
209.It Cm minorversion Ns = Ns Aq Ar value
210Override the default of 0 for the minor version of the NFS Version 4 protocol.
211The minor versions other than 0 currently supported are 1 and 2.
212This option is only meaningful when used with the
213.Cm nfsv4
214option.
215.It Cm oneopenown
216Make a minor version 1 or 2 of the NFS Version 4 protocol mount use a single
217OpenOwner for all Opens.
218This may be useful for a server with a very low limit on OpenOwners, such as
219AmazonEFS.
220This option cannot be used for an NFS Version 4, minor version 0 mount.
221As such, this option requires the
222.Cm minorversion
223option be specified with a value of 1 for AmazonEFS, because AmazonEFS does
224not support minor version 2 at this time.
225It may not work correctly when Delegations are being issued by a server,
226but note that the AmazonEFS server does not issued delegations at this time.
227This option is only meaningful when used with the
228.Cm nfsv4
229and
230.Cm minorversion
231options.
232.It Cm pnfs
233Enable support for parallel NFS (pNFS) for minor version 1 or 2 of the
234NFS Version 4 protocol.
235This option is only meaningful when used with the
236.Cm minorversion
237option.
238.It Cm noac
239Disable attribute caching.
240.It Cm noconn
241For UDP mount points, do not do a
242.Xr connect 2 .
243This must be used if the server does not reply to requests from the standard
244NFS port number 2049 or replies to requests using a different IP address
245(which can occur if the server is multi-homed).
246Setting the
247.Va vfs.nfs.nfs_ip_paranoia
248sysctl to 0 will make this option the default.
249.It Cm nocto
250Normally, NFS clients maintain the close-to-open cache coherency.
251This works by flushing at close time and checking at open time.
252Checking at open time is implemented by getting attributes from
253the server and purging the data cache if they do not match
254attributes cached by the client.
255.Pp
256This option disables checking at open time.
257It may improve performance for read-only mounts,
258but should only be used if the data on the server changes rarely.
259Be sure to understand the consequences before enabling this option.
260.It Cm noinet4 , noinet6
261Disables
262.Dv AF_INET
263or
264.Dv AF_INET6
265connections.
266Useful for hosts that have
267both an A record and an AAAA record for the same name.
268.It Cm nolockd
269Do
270.Em not
271forward
272.Xr fcntl 2
273locks over the wire via the NLM protocol for NFSv3 mounts.
274All locks will be local and not seen by the server
275and likewise not seen by other NFS clients for NFSv3 mounts.
276This removes the need to run the
277.Xr rpcbind 8
278service and the
279.Xr rpc.statd 8
280and
281.Xr rpc.lockd 8
282servers on the client.
283Note that this option will only be honored when performing the
284initial mount, it will be silently ignored if used while updating
285the mount options.
286Also, note that NFSv4 mounts do not use these daemons and handle locks over the
287wire in the NFSv4 protocol.
288As such, this option is meaningless for NFSv4 mounts.
289.It Cm noncontigwr
290This mount option allows the NFS client to
291combine non-contiguous byte ranges being written
292such that the dirty byte range becomes a superset of the bytes
293that are dirty.
294This reduces the number of writes significantly for software
295builds.
296The merging of byte ranges is not done if the file has been file
297locked, since most applications modifying a file from multiple
298clients will use file locking.
299As such, this option could result in a corrupted file for the
300rare case of an application modifying the file from multiple
301clients concurrently without using file locking.
302.It Cm principal
303For the RPCSEC_GSS security flavors, such as krb5, krb5i and krb5p,
304this option sets the name of the host based principal name expected
305by the server.
306This option overrides the default, which will be ``nfs@<server-fqdn>''
307and should normally be sufficient.
308.It Cm noresvport
309Do
310.Em not
311use a reserved socket port number (see below).
312.It Cm port Ns = Ns Aq Ar port_number
313Use specified port number for NFS requests.
314The default is to query the portmapper for the NFS port.
315.It Cm proto Ns = Ns Aq Ar protocol
316Specify transport protocol version to use.
317Currently, they are:
318.Bd -literal
319udp -   Use UDP over IPv4
320tcp -   Use TCP over IPv4
321udp6 -  Use UDP over IPv6
322tcp6 -  Use TCP over IPv6
323.Ed
324.It Cm rdirplus
325Used with NFSV3 to specify that the \fBReaddirPlus\fR RPC should
326be used.
327For NFSV4, setting this option has a similar effect, in that it will make
328the Readdir Operation get more attributes.
329This option reduces RPC traffic for cases such as
330.Dq "ls -l" ,
331but tends to flood the attribute and name caches with prefetched entries.
332Try this option and see whether performance improves or degrades.
333Probably
334most useful for client to server network interconnects with a large bandwidth
335times delay product.
336.It Cm readahead Ns = Ns Aq Ar value
337Set the read-ahead count to the specified value.
338This may be in the range of 0 - 4, and determines how many blocks
339will be read ahead when a large file is being read sequentially.
340Trying a value greater than 1 for this is suggested for
341mounts with a large bandwidth * delay product.
342.It Cm readdirsize Ns = Ns Aq Ar value
343Set the readdir read size to the specified value.
344The value should normally
345be a multiple of
346.Dv DIRBLKSIZ
347that is <= the read size for the mount.
348.It Cm resvport
349Use a reserved socket port number.
350This flag is obsolete, and only retained for compatibility reasons.
351Reserved port numbers are used by default now.
352(For the rare case where the client has a trusted root account
353but untrustworthy users and the network cables are in secure areas this does
354help, but for normal desktop clients this does not apply.)
355.It Cm retrans Ns = Ns Aq Ar value
356Set the retransmit timeout count for soft mounts to the specified value.
357.It Cm retrycnt Ns = Ns Aq Ar count
358Set the mount retry count to the specified value.
359The default is a retry count of zero, which means to keep retrying
360forever.
361There is a 60 second delay between each attempt.
362.It Cm rsize Ns = Ns Aq Ar value
363Set the read data size to the specified value.
364It should normally be a power of 2 greater than or equal to 1024.
365This should be used for UDP mounts when the
366.Dq "fragments dropped due to timeout"
367value is getting large while actively using a mount point.
368(Use
369.Xr netstat 1
370with the
371.Fl s
372option to see what the
373.Dq "fragments dropped due to timeout"
374value is.)
375.It Cm sec Ns = Ns Aq Ar flavor
376This option specifies what security flavor should be used for the mount.
377Currently, they are:
378.Bd -literal
379krb5 -  Use KerberosV authentication
380krb5i - Use KerberosV authentication and
381        apply integrity checksums to RPCs
382krb5p - Use KerberosV authentication and
383        encrypt the RPC data
384sys -   The default AUTH_SYS, which uses a
385        uid + gid list authenticator
386.Ed
387.It Cm soft
388A soft mount, which implies that file system calls will fail
389after
390.Ar retrycnt
391round trip timeout intervals.
392.It Cm tcp
393Use TCP transport.
394This is the default option, as it provides for increased reliability on both
395LAN and WAN configurations compared to UDP.
396Some old NFS servers do not support this method; UDP mounts may be required
397for interoperability.
398.It Cm timeout Ns = Ns Aq Ar value
399Set the initial retransmit timeout to the specified value,
400expressed in tenths of a second.
401May be useful for fine tuning UDP mounts over internetworks
402with high packet loss rates or an overloaded server.
403Try increasing the interval if
404.Xr nfsstat 1
405shows high retransmit rates while the file system is active or reducing the
406value if there is a low retransmit rate but long response delay observed.
407(Normally, the
408.Cm dumbtimer
409option should be specified when using this option to manually
410tune the timeout
411interval.)
412.It Cm timeo Ns = Ns Aq Ar value
413Alias for
414.Cm timeout .
415.It Cm tls
416This option specifies that the connection to the server must use TLS
417per RFC NNNN.
418TLS is only supported for TCP connections and the
419.Xr rpc.tlsclntd 8
420daemon must be running for an NFS over TCP connection to use TLS.
421.It Cm tlscertname Ns = Ns Aq Ar name
422This option specifies the name of an alternate certificate to be
423presented to the NFS server during TLS handshake.
424The default certificate file names are
425.Dq cert.pem
426and
427.Dq certkey.pem .
428When this option is specified,
429.Ar name
430replaces
431.Dq cert
432in the above file names.
433For example, if the value of
434.Ar name
435is specified as
436.Dq other
437the certificate file names to be used will be
438.Dq other.pem
439and
440.Dq otherkey.pem .
441These files are stored in
442.Pa /etc/rpc.tlsclntd
443by default.
444This option is only meaningful when used with the
445.Cm tls
446option and the
447.Xr rpc.tlsclntd 8
448is running with the
449.Fl m
450command line flag set.
451.It Cm udp
452Use UDP transport.
453.It Cm vers Ns = Ns Aq Ar vers_number
454Use the specified version number for NFS requests.
455See the
456.Cm nfsv2 ,
457.Cm nfsv3 ,
458and
459.Cm nfsv4
460options for details.
461.It Cm wcommitsize Ns = Ns Aq Ar value
462Set the maximum pending write commit size to the specified value.
463This determines the maximum amount of pending write data that the NFS
464client is willing to cache for each file.
465.It Cm wsize Ns = Ns Aq Ar value
466Set the write data size to the specified value.
467Ditto the comments w.r.t.\& the
468.Cm rsize
469option, but using the
470.Dq "fragments dropped due to timeout"
471value on the server instead of the client.
472Note that both the
473.Cm rsize
474and
475.Cm wsize
476options should only be used as a last ditch effort at improving performance
477when mounting servers that do not support TCP mounts.
478.El
479.El
480.Sh COMPATIBILITY
481The following command line flags are equivalent to
482.Fl o
483named options and are supported for compatibility with older
484installations.
485.Bl -tag -width indent
486.It Fl 2
487Same as
488.Fl o Cm nfsv2
489.It Fl 3
490Same as
491.Fl o Cm nfsv3
492.It Fl D
493Same as
494.Fl o Cm deadthresh
495.It Fl I
496Same as
497.Fl o Cm readdirsize Ns = Ns Aq Ar value
498.It Fl L
499Same as
500.Fl o Cm nolockd
501.It Fl N
502Same as
503.Fl o Cm noresvport
504.It Fl P
505Use a reserved socket port number.
506This flag is obsolete, and only retained for compatibility reasons.
507(For the rare case where the client has a trusted root account
508but untrustworthy users and the network cables are in secure areas this does
509help, but for normal desktop clients this does not apply.)
510.It Fl R
511Same as
512.Fl o Cm retrycnt Ns = Ns Aq Ar value
513.It Fl T
514Same as
515.Fl o Cm tcp
516.It Fl U
517Same as
518.Fl o Cm mntudp
519.It Fl a
520Same as
521.Fl o Cm readahead Ns = Ns Aq Ar value
522.It Fl b
523Same as
524.Fl o Cm bg
525.It Fl c
526Same as
527.Fl o Cm noconn
528.It Fl d
529Same as
530.Fl o Cm dumbtimer
531.It Fl g
532Same as
533.Fl o Cm maxgroups
534.It Fl i
535Same as
536.Fl o Cm intr
537.It Fl l
538Same as
539.Fl o Cm rdirplus
540.It Fl r
541Same as
542.Fl o Cm rsize Ns = Ns Aq Ar value
543.It Fl s
544Same as
545.Fl o Cm soft
546.It Fl t
547Same as
548.Fl o Cm retransmit Ns = Ns Aq Ar value
549.It Fl w
550Same as
551.Fl o Cm wsize Ns = Ns Aq Ar value
552.It Fl x
553Same as
554.Fl o Cm retrans Ns = Ns Aq Ar value
555.El
556.Pp
557The following
558.Fl o
559named options are equivalent to other
560.Fl o
561named options and are supported for compatibility with other
562operating systems (e.g., Linux, Solaris, and OSX) to ease usage of
563.Xr autofs 5
564support.
565.Bl -tag -width indent
566.It Fl o Cm vers Ns = Ns 2
567Same as
568.Fl o Cm nfsv2
569.It Fl o Cm vers Ns = Ns 3
570Same as
571.Fl o Cm nfsv3
572.It Fl o Cm vers Ns = Ns 4
573Same as
574.Fl o Cm nfsv4
575.El
576.Sh SEE ALSO
577.Xr nmount 2 ,
578.Xr unmount 2 ,
579.Xr nfsv4 4 ,
580.Xr fstab 5 ,
581.Xr gssd 8 ,
582.Xr mount 8 ,
583.Xr nfsd 8 ,
584.Xr nfsiod 8 ,
585.Xr rpc.tlsclntd 8 ,
586.Xr showmount 8
587.Sh HISTORY
588A version of the
589.Nm
590utility appeared in
591.Bx 4.4 .
592.Sh BUGS
593Since nfsv4 performs open/lock operations that have their ordering strictly
594enforced by the server, the options
595.Cm intr
596and
597.Cm soft
598cannot be safely used.
599.Cm hard
600nfsv4 mounts are strongly recommended.
601