Debian Codegraph @

upstream/debian-unstable/man5/nfs.5

raw
1 .\"@(#)nfs.5"
2 .TH NFS 5 "9 October 2012"
3 .SH NAME
4 nfs \- fstab format and options for the
5 .B nfs
6 file systems
7 .SH SYNOPSIS
8 .I /etc/fstab
9 .SH DESCRIPTION
10 NFS is an Internet Standard protocol
11 created by Sun Microsystems in 1984. NFS was developed
12 to allow file sharing between systems residing
13 on a local area network.
14 Depending on kernel configuration, the Linux NFS client may
15 support NFS versions 3, 4.0, 4.1, or 4.2.
16 .P
17 The
18 .BR mount (8)
19 command attaches a file system to the system's
20 name space hierarchy at a given mount point.
21 The
22 .I /etc/fstab
23 file describes how
24 .BR mount (8)
25 should assemble a system's file name hierarchy
26 from various independent file systems
27 (including file systems exported by NFS servers).
28 Each line in the
29 .I /etc/fstab
30 file describes a single file system, its mount point,
31 and a set of default mount options for that mount point.
32 .P
33 For NFS file system mounts, a line in the
34 .I /etc/fstab
35 file specifies the server name,
36 the path name of the exported server directory to mount,
37 the local directory that is the mount point,
38 the type of file system that is being mounted,
39 and a list of mount options that control
40 the way the filesystem is mounted and
41 how the NFS client behaves when accessing
42 files on this mount point.
43 The fifth and sixth fields on each line are not used
44 by NFS, thus conventionally each contain the digit zero. For example:
45 .P
46 .nf
47 .ta 8n +14n +14n +9n +20n
48 server:path /mountpoint fstype option,option,... 0 0
49 .fi
50 .P
51 The server's hostname and export pathname
52 are separated by a colon, while
53 the mount options are separated by commas. The remaining fields
54 are separated by blanks or tabs.
55 .P
56 The server's hostname can be an unqualified hostname,
57 a fully qualified domain name,
58 a dotted quad IPv4 address, or
59 an IPv6 address enclosed in square brackets.
60 Link-local and site-local IPv6 addresses must be accompanied by an
61 interface identifier.
62 See
63 .BR ipv6 (7)
64 for details on specifying raw IPv6 addresses.
65 .P
66 The
67 .I fstype
68 field contains "nfs". Use of the "nfs4" fstype in
69 .I /etc/fstab
70 is deprecated.
71 .SH "MOUNT OPTIONS"
72 Refer to
73 .BR mount (8)
74 for a description of generic mount options
75 available for all file systems. If you do not need to
76 specify any mount options, use the generic option
77 .B defaults
78 in
79 .IR /etc/fstab .
80 .DT
81 .SS "Options supported by all versions"
82 These options are valid to use with any NFS version.
83 .TP 1.5i
84 .BI nfsvers= n
85 The NFS protocol version number used to contact the server's NFS service.
86 If the server does not support the requested version, the mount request
87 fails.
88 If this option is not specified, the client tries version 4.2 first,
89 then negotiates down until it finds a version supported by the server.
90 .TP 1.5i
91 .BI vers= n
92 This option is an alternative to the
93 .B nfsvers
94 option.
95 It is included for compatibility with other operating systems
96 .TP 1.5i
97 .BR soft " / " softerr " / " hard
98 Determines the recovery behavior of the NFS client
99 after an NFS request times out.
100 If no option is specified (or if the
101 .B hard
102 option is specified), NFS requests are retried indefinitely.
103 If either the
104 .BR soft " or " softerr
105 option is specified, then the NFS client fails an NFS request
106 after
107 .B retrans
108 retransmissions have been sent,
109 causing the NFS client to return either the error
110 .B EIO
111 (for the
112 .B soft
113 option) or
114 .B ETIMEDOUT
115 (for the
116 .B softerr
117 option) to the calling application.
118 .IP
119 .I NB:
120 A so-called "soft" timeout can cause
121 silent data corruption in certain cases. As such, use the
122 .BR soft " or " softerr
123 option only when client responsiveness
124 is more important than data integrity.
125 Using NFS over TCP or increasing the value of the
126 .B retrans
127 option may mitigate some of the risks of using the
128 .BR soft " or " softerr
129 option.
130 .TP 1.5i
131 .BR softreval " / " nosoftreval
132 In cases where the NFS server is down, it may be useful to
133 allow the NFS client to continue to serve up paths and
134 attributes from cache after
135 .B retrans
136 attempts to revalidate that cache have timed out.
137 This may, for instance, be helpful when trying to unmount a
138 filesystem tree from a server that is permanently down.
139 .IP
140 It is possible to combine
141 .BR softreval
142 with the
143 .B soft
144 mount option, in which case operations that cannot be served up
145 from cache will time out and return an error after
146 .B retrans
147 attempts. The combination with the default
148 .B hard
149 mount option implies those uncached operations will continue to
150 retry until a response is received from the server.
151 .IP
152 Note: the default mount option is
153 .BR nosoftreval
154 which disallows fallback to cache when revalidation fails, and
155 instead follows the behavior dictated by the
156 .B hard
157 or
158 .B soft
159 mount option.
160 .TP 1.5i
161 .BR intr " / " nointr
162 This option is provided for backward compatibility.
163 It is ignored after kernel 2.6.25.
164 .TP 1.5i
165 .BI timeo= n
166 The time in deciseconds (tenths of a second) the NFS client waits for a
167 response before it retries an NFS request.
168 .IP
169 For NFS over TCP the default
170 .B timeo
171 value is 600 (60 seconds).
172 The NFS client performs linear backoff: After each retransmission the
173 timeout is increased by
174 .BR timeo
175 up to the maximum of 600 seconds.
176 .IP
177 However, for NFS over UDP, the client uses an adaptive
178 algorithm to estimate an appropriate timeout value for frequently used
179 request types (such as READ and WRITE requests), but uses the
180 .B timeo
181 setting for infrequently used request types (such as FSINFO requests).
182 If the
183 .B timeo
184 option is not specified,
185 infrequently used request types are retried after 1.1 seconds.
186 After each retransmission, the NFS client doubles the timeout for
187 that request,
188 up to a maximum timeout length of 60 seconds.
189 .IP
190 Any timeo value greater than default value will be set to the default value.
191 For TCP and RDMA, default value is 600 (60 seconds).
192 For UDP, default value is 60 (6 seconds).
193 .TP 1.5i
194 .BI retrans= n
195 The number of times the NFS client retries a request before
196 it attempts further recovery action. If the
197 .B retrans
198 option is not specified, the NFS client tries each UDP request
199 three times and each TCP request twice.
200 .IP
201 The NFS client generates a "server not responding" message
202 after
203 .B retrans
204 retries, then attempts further recovery (depending on whether the
205 .B hard
206 mount option is in effect).
207 .TP 1.5i
208 .BI rsize= n
209 The maximum number of bytes in each network READ request
210 that the NFS client can receive when reading data from a file
211 on an NFS server.
212 The actual data payload size of each NFS READ request is equal to
213 or smaller than the
214 .B rsize
215 setting. The largest read payload supported by the Linux NFS client
216 is 1,048,576 bytes (one megabyte).
217 .IP
218 The allowed
219 .B rsize
220 value is a positive integral multiple of
221 system's page size
222 or a power of two if it is less than
223 system's page size.
224 Specified
225 .B rsize
226 values lower than 1024 are replaced with 4096; values larger than
227 1048576 are replaced with 1048576. If a specified value is within the supported
228 range but not such an allowed value, it is rounded down to the nearest
229 allowed value.
230 .IP
231 If an
232 .B rsize
233 value is not specified, or if the specified
234 .B rsize
235 value is larger than the maximum that either client or server can support,
236 the client and server negotiate the largest
237 .B rsize
238 value that they can both support.
239 .IP
240 The
241 .B rsize
242 mount option as specified on the
243 .BR mount (8)
244 command line appears in the
245 .I /etc/mtab
246 file. However, the effective
247 .B rsize
248 value negotiated by the client and server is reported in the
249 .I /proc/mounts
250 file.
251 .TP 1.5i
252 .BI wsize= n
253 The maximum number of bytes per network WRITE request
254 that the NFS client can send when writing data to a file
255 on an NFS server. The actual data payload size of each
256 NFS WRITE request is equal to
257 or smaller than the
258 .B wsize
259 setting. The largest write payload supported by the Linux NFS client
260 is 1,048,576 bytes (one megabyte).
261 .IP
262 Similar to
263 .BR rsize ,
264 the allowed
265 .B wsize
266 value is a positive integral multiple of
267 system's page size
268 or a power of two if it is less than
269 system's page size.
270 Specified
271 .B wsize
272 values lower than 1024 are replaced with 4096; values larger than
273 1048576 are replaced with 1048576. If a specified value is within the supported
274 range but not such an allowed value, it is rounded down to the nearest
275 allowed value.
276 .IP
277 If a
278 .B wsize
279 value is not specified, or if the specified
280 .B wsize
281 value is larger than the maximum that either client or server can support,
282 the client and server negotiate the largest
283 .B wsize
284 value that they can both support.
285 .IP
286 The
287 .B wsize
288 mount option as specified on the
289 .BR mount (8)
290 command line appears in the
291 .I /etc/mtab
292 file. However, the effective
293 .B wsize
294 value negotiated by the client and server is reported in the
295 .I /proc/mounts
296 file.
297 .TP 1.5i
298 .BR ac " / " noac
299 Selects whether the client may cache file attributes. If neither
300 option is specified (or if
301 .B ac
302 is specified), the client caches file
303 attributes.
304 .IP
305 To improve performance, NFS clients cache file
306 attributes. Every few seconds, an NFS client checks the server's version of each
307 file's attributes for updates. Changes that occur on the server in
308 those small intervals remain undetected until the client checks the
309 server again. The
310 .B noac
311 option prevents clients from caching file
312 attributes so that applications can more quickly detect file changes
313 on the server.
314 .IP
315 In addition to preventing the client from caching file attributes,
316 the
317 .B noac
318 option forces application writes to become synchronous so
319 that local changes to a file become visible on the server
320 immediately. That way, other clients can quickly detect recent
321 writes when they check the file's attributes.
322 .IP
323 Using the
324 .B noac
325 option provides greater cache coherence among NFS clients
326 accessing the same files,
327 but it extracts a significant performance penalty.
328 As such, judicious use of file locking is encouraged instead.
329 The DATA AND METADATA COHERENCE section contains a detailed discussion
330 of these trade-offs.
331 .TP 1.5i
332 .BI acregmin= n
333 The minimum time (in seconds) that the NFS client caches
334 attributes of a regular file before it requests
335 fresh attribute information from a server.
336 If this option is not specified, the NFS client uses
337 a 3-second minimum.
338 See the DATA AND METADATA COHERENCE section
339 for a full discussion of attribute caching.
340 .TP 1.5i
341 .BI acregmax= n
342 The maximum time (in seconds) that the NFS client caches
343 attributes of a regular file before it requests
344 fresh attribute information from a server.
345 If this option is not specified, the NFS client uses
346 a 60-second maximum.
347 See the DATA AND METADATA COHERENCE section
348 for a full discussion of attribute caching.
349 .TP 1.5i
350 .BI acdirmin= n
351 The minimum time (in seconds) that the NFS client caches
352 attributes of a directory before it requests
353 fresh attribute information from a server.
354 If this option is not specified, the NFS client uses
355 a 30-second minimum.
356 See the DATA AND METADATA COHERENCE section
357 for a full discussion of attribute caching.
358 .TP 1.5i
359 .BI acdirmax= n
360 The maximum time (in seconds) that the NFS client caches
361 attributes of a directory before it requests
362 fresh attribute information from a server.
363 If this option is not specified, the NFS client uses
364 a 60-second maximum.
365 See the DATA AND METADATA COHERENCE section
366 for a full discussion of attribute caching.
367 .TP 1.5i
368 .BI actimeo= n
369 Using
370 .B actimeo
371 sets all of
372 .BR acregmin ,
373 .BR acregmax ,
374 .BR acdirmin ,
375 and
376 .B acdirmax
377 to the same value.
378 If this option is not specified, the NFS client uses
379 the defaults for each of these options listed above.
380 .TP 1.5i
381 .BR bg " / " fg
382 Determines how the
383 .BR mount (8)
384 command behaves if an attempt to mount an export fails.
385 The
386 .B fg
387 option causes
388 .BR mount (8)
389 to exit with an error status if any part of the mount request
390 times out or fails outright.
391 This is called a "foreground" mount,
392 and is the default behavior if neither the
393 .B fg
394 nor
395 .B bg
396 mount option is specified.
397 .IP
398 If the
399 .B bg
400 option is specified, a timeout or failure causes the
401 .BR mount (8)
402 command to fork a child which continues to attempt
403 to mount the export.
404 The parent immediately returns with a zero exit code.
405 This is known as a "background" mount.
406 .IP
407 If the local mount point directory is missing, the
408 .BR mount (8)
409 command acts as if the mount request timed out.
410 This permits nested NFS mounts specified in
411 .I /etc/fstab
412 to proceed in any order during system initialization,
413 even if some NFS servers are not yet available.
414 Alternatively these issues can be addressed
415 using an automounter (refer to
416 .BR automount (8)
417 for details).
418 .TP 1.5i
419 .BR nconnect= n
420 When using a connection oriented protocol such as TCP, it may
421 sometimes be advantageous to set up multiple connections between
422 the client and server. For instance, if your clients and/or servers
423 are equipped with multiple network interface cards (NICs), using multiple
424 connections to spread the load may improve overall performance.
425 In such cases, the
426 .BR nconnect
427 option allows the user to specify the number of connections
428 that should be established between the client and server up to
429 a limit of 16.
430 .IP
431 Note that the
432 .BR nconnect
433 option may also be used by some pNFS drivers to decide how many
434 connections to set up to the data servers.
435 .TP 1.5i
436 .BR rdirplus " / " nordirplus
437 Selects whether to use NFS v3 or v4 READDIRPLUS requests. If this option is
438 not specified, the NFS client uses a heuristic to optimize performance by
439 choosing READDIR vs READDIRPLUS based on how often the calling process uses
440 the additional attributes returned from READDIRPLUS. Some applications
441 perform better if the client uses only READDIR requests for all directories.
442 .TP 1.5i
443 .BR rdirplus={none|force}
444 If set to "force", the NFS client always attempts to use READDIRPLUS
445 requests. If set to "none", the behavior is the same as
446 .B nordirplus.
447 .TP 1.5i
448 .BI retry= n
449 The number of minutes that the
450 .BR mount (8)
451 command retries an NFS mount operation
452 in the foreground or background before giving up.
453 If this option is not specified, the default value for foreground mounts
454 is 2 minutes, and the default value for background mounts is 10000 minutes
455 (80 minutes shy of one week).
456 If a value of zero is specified, the
457 .BR mount (8)
458 command exits immediately after the first failure.
459 .IP
460 Note that this only affects how many retries are made and doesn't
461 affect the delay caused by each retry. For UDP each retry takes the
462 time determined by the
463 .BR timeo
464 and
465 .BR retrans
466 options, which by default will be about 7 seconds. For TCP the
467 default is 3 minutes, but system TCP connection timeouts will
468 sometimes limit the timeout of each retransmission to around 2 minutes.
469 .TP 1.5i
470 .BI sec= flavors
471 A colon-separated list of one or more security flavors to use for accessing
472 files on the mounted export. If the server does not support any of these
473 flavors, the mount operation fails.
474 If
475 .B sec=
476 is not specified, the client attempts to find
477 a security flavor that both the client and the server supports.
478 Valid
479 .I flavors
480 are
481 .BR none ,
482 .BR sys ,
483 .BR krb5 ,
484 .BR krb5i ,
485 and
486 .BR krb5p .
487 Refer to the SECURITY CONSIDERATIONS section for details.
488 .TP 1.5i
489 .BR sharecache " / " nosharecache
490 Determines how the client's data cache and attribute cache are shared
491 when mounting the same export more than once concurrently. Using the
492 same cache reduces memory requirements on the client and presents
493 identical file contents to applications when the same remote file is
494 accessed via different mount points.
495 .IP
496 If neither option is specified, or if the
497 .B sharecache
498 option is
499 specified, then a single cache is used for all mount points that
500 access the same export. If the
501 .B nosharecache
502 option is specified,
503 then that mount point gets a unique cache. Note that when data and
504 attribute caches are shared, the mount options from the first mount
505 point take effect for subsequent concurrent mounts of the same export.
506 .IP
507 As of kernel 2.6.18, the behavior specified by
508 .B nosharecache
509 is legacy caching behavior. This
510 is considered a data risk since multiple cached copies
511 of the same file on the same client can become out of sync
512 following a local update of one of the copies.
513 .TP 1.5i
514 .BR resvport " / " noresvport
515 Specifies whether the NFS client should use a privileged source port
516 when communicating with an NFS server for this mount point.
517 If this option is not specified, or the
518 .B resvport
519 option is specified, the NFS client uses a privileged source port.
520 If the
521 .B noresvport
522 option is specified, the NFS client uses a non-privileged source port.
523 This option is supported in kernels 2.6.28 and later.
524 .IP
525 Using non-privileged source ports helps increase the maximum number of
526 NFS mount points allowed on a client, but NFS servers must be configured
527 to allow clients to connect via non-privileged source ports.
528 .IP
529 Refer to the SECURITY CONSIDERATIONS section for important details.
530 .TP 1.5i
531 .BI lookupcache= mode
532 Specifies how the kernel manages its cache of directory entries
533 for a given mount point.
534 .I mode
535 can be one of
536 .BR all ,
537 .BR none ,
538 .BR pos ,
539 or
540 .BR positive .
541 This option is supported in kernels 2.6.28 and later.
542 .IP
543 The Linux NFS client caches the result of all NFS LOOKUP requests.
544 If the requested directory entry exists on the server,
545 the result is referred to as
546 .IR positive .
547 If the requested directory entry does not exist on the server,
548 the result is referred to as
549 .IR negative .
550 .IP
551 If this option is not specified, or if
552 .B all
553 is specified, the client assumes both types of directory cache entries
554 are valid until their parent directory's cached attributes expire.
555 .IP
556 If
557 .BR pos " or " positive
558 is specified, the client assumes positive entries are valid
559 until their parent directory's cached attributes expire, but
560 always revalidates negative entries before an application
561 can use them.
562 .IP
563 If
564 .B none
565 is specified,
566 the client revalidates both types of directory cache entries
567 before an application can use them.
568 This permits quick detection of files that were created or removed
569 by other clients, but can impact application and server performance.
570 .IP
571 The DATA AND METADATA COHERENCE section contains a
572 detailed discussion of these trade-offs.
573 .TP 1.5i
574 .BR fsc " / " nofsc
575 Enable/Disables the cache of (read-only) data pages to the local disk
576 using the FS-Cache facility. See cachefilesd(8)
577 and <kernel_source>/Documentation/filesystems/caching
578 for detail on how to configure the FS-Cache facility.
579 Default value is nofsc.
580 .TP 1.5i
581 .B sloppy
582 The
583 .B sloppy
584 option is an alternative to specifying
585 .BR mount.nfs " -s " option.
586 .TP 1.5i
587 .BI xprtsec= policy
588 Specifies the use of transport layer security to protect NFS network
589 traffic on behalf of this mount point.
590 .I policy
591 can be one of
592 .BR none ,
593 .BR tls ,
594 or
595 .BR mtls .
596 .IP
597 If
598 .B none
599 is specified,
600 transport layer security is forced off, even if the NFS server supports
601 transport layer security.
602 .IP
603 If
604 .B tls
605 is specified, the client uses RPC-with-TLS to provide in-transit
606 confidentiality.
607 .IP
608 If
609 .B mtls
610 is specified, the client uses RPC-with-TLS to authenticate itself and
611 to provide in-transit confidentiality.
612 .IP
613 If either
614 .B tls
615 or
616 .B mtls
617 is specified and the server does not support RPC-with-TLS or peer
618 authentication fails, the mount attempt fails.
619 .IP
620 If the
621 .B xprtsec=
622 option is not specified,
623 the default behavior depends on the kernel version,
624 but is usually equivalent to
625 .BR "xprtsec=none" .
626 .TP 1.5i
627 .BI noalignwrite
628 This option disables the default behavior of extending buffered write operations
629 to full page boundaries.
630 .IP
631 Normally, the NFS client rounds non-aligned buffered writes up to the system
632 page size, which can lead to "lost writes" when multiple clients write
633 concurrently to distinct non-overlapping regions. Use this option when your
634 applications perform non-aligned buffered writes and you can guarantee that file
635 regions do not overlap, thus avoiding the need for file locking.
636 .IP
637 .SS "Options for NFS versions 2 and 3 only"
638 Use these options, along with the options in the above subsection,
639 for NFS versions 2 and 3 only.
640 .TP 1.5i
641 .BI proto= netid
642 The
643 .I netid
644 determines the transport that is used to communicate with the NFS
645 server. Available options are
646 .BR udp ", " udp6 ", "tcp ", " tcp6 ", " rdma ", and " rdma6 .
647 Those which end in
648 .B 6
649 use IPv6 addresses and are only available if support for TI-RPC is
650 built in. Others use IPv4 addresses.
651 .IP
652 Each transport protocol uses different default
653 .B retrans
654 and
655 .B timeo
656 settings.
657 Refer to the description of these two mount options for details.
658 .IP
659 In addition to controlling how the NFS client transmits requests to
660 the server, this mount option also controls how the
661 .BR mount (8)
662 command communicates with the server's rpcbind and mountd services.
663 Specifying a netid that uses TCP forces all traffic from the
664 .BR mount (8)
665 command and the NFS client to use TCP.
666 Specifying a netid that uses UDP forces all traffic types to use UDP.
667 .IP
668 .B Before using NFS over UDP, refer to the TRANSPORT METHODS section.
669 .IP
670 If the
671 .B proto
672 mount option is not specified, the
673 .BR mount (8)
674 command discovers which protocols the server supports
675 and chooses an appropriate transport for each service.
676 Refer to the TRANSPORT METHODS section for more details.
677 .TP 1.5i
678 .B udp
679 The
680 .B udp
681 option is an alternative to specifying
682 .BR proto=udp.
683 It is included for compatibility with other operating systems.
684 .IP
685 .B Before using NFS over UDP, refer to the TRANSPORT METHODS section.
686 .TP 1.5i
687 .B tcp
688 The
689 .B tcp
690 option is an alternative to specifying
691 .BR proto=tcp.
692 It is included for compatibility with other operating systems.
693 .TP 1.5i
694 .B rdma
695 The
696 .B rdma
697 option is an alternative to specifying
698 .BR proto=rdma.
699 .TP 1.5i
700 .BI port= n
701 The numeric value of the server's NFS service port.
702 If the server's NFS service is not available on the specified port,
703 the mount request fails.
704 .IP
705 If this option is not specified, or if the specified port value is 0,
706 then the NFS client uses the NFS service port number
707 advertised by the server's rpcbind service.
708 The mount request fails if the server's rpcbind service is not available,
709 the server's NFS service is not registered with its rpcbind service,
710 or the server's NFS service is not available on the advertised port.
711 .TP 1.5i
712 .BI mountport= n
713 The numeric value of the server's mountd port.
714 If the server's mountd service is not available on the specified port,
715 the mount request fails.
716 .IP
717 If this option is not specified,
718 or if the specified port value is 0, then the
719 .BR mount (8)
720 command uses the mountd service port number
721 advertised by the server's rpcbind service.
722 The mount request fails if the server's rpcbind service is not available,
723 the server's mountd service is not registered with its rpcbind service,
724 or the server's mountd service is not available on the advertised port.
725 .IP
726 This option can be used when mounting an NFS server
727 through a firewall that blocks the rpcbind protocol.
728 .TP 1.5i
729 .BI mountproto= netid
730 The transport the NFS client uses
731 to transmit requests to the NFS server's mountd service when performing
732 this mount request, and when later unmounting this mount point.
733 .IP
734 .I netid
735 may be one of
736 .BR udp ", and " tcp
737 which use IPv4 address or, if TI-RPC is built into the
738 .B mount.nfs
739 command,
740 .BR udp6 ", and " tcp6
741 which use IPv6 addresses.
742 .IP
743 This option can be used when mounting an NFS server
744 through a firewall that blocks a particular transport.
745 When used in combination with the
746 .B proto
747 option, different transports for mountd requests and NFS requests
748 can be specified.
749 If the server's mountd service is not available via the specified
750 transport, the mount request fails.
751 .IP
752 Refer to the TRANSPORT METHODS section for more on how the
753 .B mountproto
754 mount option interacts with the
755 .B proto
756 mount option.
757 .TP 1.5i
758 .BI mounthost= name
759 The hostname of the host running mountd.
760 If this option is not specified, the
761 .BR mount (8)
762 command assumes that the mountd service runs
763 on the same host as the NFS service.
764 .TP 1.5i
765 .BI mountvers= n
766 The RPC version number used to contact the server's mountd.
767 If this option is not specified, the client uses a version number
768 appropriate to the requested NFS version.
769 This option is useful when multiple NFS services
770 are running on the same remote server host.
771 .TP 1.5i
772 .BI namlen= n
773 The maximum length of a pathname component on this mount.
774 If this option is not specified, the maximum length is negotiated
775 with the server. In most cases, this maximum length is 255 characters.
776 .IP
777 Some early versions of NFS did not support this negotiation.
778 Using this option ensures that
779 .BR pathconf (3)
780 reports the proper maximum component length to applications
781 in such cases.
782 .TP 1.5i
783 .BR lock " / " nolock
784 Selects whether to use the NLM sideband protocol to lock files on the server.
785 If neither option is specified (or if
786 .B lock
787 is specified), NLM locking is used for this mount point.
788 When using the
789 .B nolock
790 option, applications can lock files,
791 but such locks provide exclusion only against other applications
792 running on the same client.
793 Remote applications are not affected by these locks.
794 .IP
795 NLM locking must be disabled with the
796 .B nolock
797 option when using NFS to mount
798 .I /var
799 because
800 .I /var
801 contains files used by the NLM implementation on Linux.
802 Using the
803 .B nolock
804 option is also required when mounting exports on NFS servers
805 that do not support the NLM protocol.
806 .TP 1.5i
807 .BR cto " / " nocto
808 Selects whether to use close-to-open cache coherence semantics.
809 If neither option is specified (or if
810 .B cto
811 is specified), the client uses close-to-open
812 cache coherence semantics. If the
813 .B nocto
814 option is specified, the client uses a non-standard heuristic to determine when
815 files on the server have changed.
816 .IP
817 Using the
818 .B nocto
819 option may improve performance for read-only mounts,
820 but should be used only if the data on the server changes only occasionally.
821 The DATA AND METADATA COHERENCE section discusses the behavior
822 of this option in more detail.
823 .TP 1.5i
824 .BR acl " / " noacl
825 Selects whether to use the NFSACL sideband protocol on this mount point.
826 The NFSACL sideband protocol is a proprietary protocol
827 implemented in Solaris that manages Access Control Lists. NFSACL was never
828 made a standard part of the NFS protocol specification.
829 .IP
830 If neither
831 .B acl
832 nor
833 .B noacl
834 option is specified,
835 the NFS client negotiates with the server
836 to see if the NFSACL protocol is supported,
837 and uses it if the server supports it.
838 Disabling the NFSACL sideband protocol may be necessary
839 if the negotiation causes problems on the client or server.
840 Refer to the SECURITY CONSIDERATIONS section for more details.
841 .TP 1.5i
842 .BR local_lock= mechanism
843 Specifies whether to use local locking for any or both of the flock and the
844 POSIX locking mechanisms.
845 .I mechanism
846 can be one of
847 .BR all ,
848 .BR flock ,
849 .BR posix ,
850 or
851 .BR none .
852 This option is supported in kernels 2.6.37 and later.
853 .IP
854 The Linux NFS client provides a way to make locks local. This means, the
855 applications can lock files, but such locks provide exclusion only against
856 other applications running on the same client. Remote applications are not
857 affected by these locks.
858 .IP
859 If this option is not specified, or if
860 .B none
861 is specified, the client assumes that the locks are not local.
862 .IP
863 If
864 .BR all
865 is specified, the client assumes that both flock and POSIX locks are local.
866 .IP
867 If
868 .BR flock
869 is specified, the client assumes that only flock locks are local and uses
870 NLM sideband protocol to lock files when POSIX locks are used.
871 .IP
872 If
873 .BR posix
874 is specified, the client assumes that POSIX locks are local and uses NLM
875 sideband protocol to lock files when flock locks are used.
876 .IP
877 To support legacy flock behavior similar to that of NFS clients < 2.6.12,
878 use 'local_lock=flock'. This option is required when exporting NFS mounts via
879 Samba as Samba maps Windows share mode locks as flock. Since NFS clients >
880 2.6.12 implement flock by emulating POSIX locks, this will result in
881 conflicting locks.
882 .IP
883 NOTE: When used together, the 'local_lock' mount option will be overridden
884 by 'nolock'/'lock' mount option.
885 .SS "Options for NFS version 4 only"
886 Use these options, along with the options in the first subsection above,
887 for NFS version 4.0 and newer.
888 .TP 1.5i
889 .BI proto= netid
890 The
891 .I netid
892 determines the transport that is used to communicate with the NFS
893 server. Supported options are
894 .BR tcp ", " tcp6 ", " rdma ", and " rdma6 .
895 .B tcp6
896 use IPv6 addresses and is only available if support for TI-RPC is
897 built in. Both others use IPv4 addresses.
898 .IP
899 All NFS version 4 servers are required to support TCP,
900 so if this mount option is not specified, the NFS version 4 client
901 uses the TCP protocol.
902 Refer to the TRANSPORT METHODS section for more details.
903 .TP 1.5i
904 .BI minorversion= n
905 Specifies the protocol minor version number.
906 NFSv4 introduces "minor versioning," where NFS protocol enhancements can
907 be introduced without bumping the NFS protocol version number.
908 Before kernel 2.6.38, the minor version is always zero, and this
909 option is not recognized.
910 After this kernel, specifying "minorversion=1" enables a number of
911 advanced features, such as NFSv4 sessions.
912 .IP
913 Recent kernels allow the minor version to be specified using the
914 .B vers=
915 option.
916 For example, specifying
917 .B vers=4.1
918 is the same as specifying
919 .BR vers=4,minorversion=1 .
920 .TP 1.5i
921 .BI port= n
922 The numeric value of the server's NFS service port.
923 If the server's NFS service is not available on the specified port,
924 the mount request fails.
925 .IP
926 If this mount option is not specified,
927 the NFS client uses the standard NFS port number of 2049
928 without first checking the server's rpcbind service.
929 This allows an NFS version 4 client to contact an NFS version 4
930 server through a firewall that may block rpcbind requests.
931 .IP
932 If the specified port value is 0,
933 then the NFS client uses the NFS service port number
934 advertised by the server's rpcbind service.
935 The mount request fails if the server's rpcbind service is not available,
936 the server's NFS service is not registered with its rpcbind service,
937 or the server's NFS service is not available on the advertised port.
938 .TP 1.5i
939 .BR cto " / " nocto
940 Selects whether to use close-to-open cache coherence semantics
941 for NFS directories on this mount point.
942 If neither
943 .B cto
944 nor
945 .B nocto
946 is specified,
947 the default is to use close-to-open cache coherence
948 semantics for directories.
949 .IP
950 File data caching behavior is not affected by this option.
951 The DATA AND METADATA COHERENCE section discusses
952 the behavior of this option in more detail.
953 .TP 1.5i
954 .BI clientaddr= n.n.n.n
955 .TP 1.5i
956 .BI clientaddr= n:n: ... :n
957 Specifies a single IPv4 address (in dotted-quad form),
958 or a non-link-local IPv6 address,
959 that the NFS client advertises to allow servers
960 to perform NFS version 4.0 callback requests against
961 files on this mount point. If the server is unable to
962 establish callback connections to clients, performance
963 may degrade, or accesses to files may temporarily hang.
964 Can specify a value of IPv4_ANY (0.0.0.0) or equivalent
965 IPv6 any address which will signal to the NFS server that
966 this NFS client does not want delegations.
967 .IP
968 If this option is not specified, the
969 .BR mount (8)
970 command attempts to discover an appropriate callback address automatically.
971 The automatic discovery process is not perfect, however.
972 In the presence of multiple client network interfaces,
973 special routing policies,
974 or atypical network topologies,
975 the exact address to use for callbacks may be nontrivial to determine.
976 .IP
977 NFS protocol versions 4.1 and 4.2 use the client-established
978 TCP connection for callback requests, so do not require the server to
979 connect to the client. This option is therefore only affect NFS version
980 4.0 mounts.
981 .TP 1.5i
982 .BR migration " / " nomigration
983 Selects whether the client uses an identification string that is compatible
984 with NFSv4 Transparent State Migration (TSM).
985 If the mounted server supports NFSv4 migration with TSM, specify the
986 .B migration
987 option.
988 .IP
989 Some server features misbehave in the face of a migration-compatible
990 identification string.
991 The
992 .B nomigration
993 option retains the use of a traditional client identification string
994 which is compatible with legacy NFS servers.
995 This is also the behavior if neither option is specified.
996 A client's open and lock state cannot be migrated transparently
997 when it identifies itself via a traditional identification string.
998 .IP
999 This mount option has no effect with NFSv4 minor versions newer than zero,
1000 which always use TSM-compatible client identification strings.
1001 .TP 1.5i
1002 .BR max_connect= n
1003 While
1004 .BR nconnect
1005 option sets a limit on the number of connections that can be established
1006 to a given server IP,
1007 .BR max_connect
1008 option allows the user to specify maximum number of connections to different
1009 server IPs that belong to the same NFSv4.1+ server (session trunkable
1010 connections) up to a limit of 16. When client discovers that it established
1011 a client ID to an already existing server, instead of dropping the newly
1012 created network transport, the client will add this new connection to the
1013 list of available transports for that RPC client.
1014 .TP 1.5i
1015 .BR trunkdiscovery " / " notrunkdiscovery
1016 When the client discovers a new filesystem on a NFSv4.1+ server, the
1017 .BR trunkdiscovery
1018 mount option will cause it to send a GETATTR for the fs_locations attribute.
1019 If is receives a non-zero length reply, it will iterate through the response,
1020 and for each server location it will establish a connection, send an
1021 EXCHANGE_ID, and test for session trunking. If the trunking test succeeds,
1022 the connection will be added to the existing set of transports for the server,
1023 subject to the limit specified by the
1024 .BR max_connect
1025 option. The default is
1026 .BR notrunkdiscovery .
1027 .SH nfs4 FILE SYSTEM TYPE
1028 The
1029 .BR nfs4
1030 file system type is an old syntax for specifying NFSv4 usage. It can still
1031 be used with all NFSv4-specific and common options, excepted the
1032 .B nfsvers
1033 mount option.
1034 .SH MOUNT CONFIGURATION FILE
1035 If the mount command is configured to do so, all of the mount options
1036 described in the previous section can also be configured in the
1037 .I /etc/nfsmount.conf
1038 file. See
1039 .BR nfsmount.conf(5)
1040 for details.
1041 .SH EXAMPLES
1042 To mount using NFS version 3,
1043 use the
1044 .B nfs
1045 file system type and specify the
1046 .B nfsvers=3
1047 mount option.
1048 To mount using NFS version 4,
1049 use either the
1050 .B nfs
1051 file system type, with the
1052 .B nfsvers=4
1053 mount option, or the
1054 .B nfs4
1055 file system type.
1056 .P
1057 The following example from an
1058 .I /etc/fstab
1059 file causes the mount command to negotiate
1060 reasonable defaults for NFS behavior.
1061 .P
1062 .nf
1063 .ta 8n +16n +6n +6n +30n
1064 server:/export /mnt nfs defaults 0 0
1065 .fi
1066 .P
1067 This example shows how to mount using NFS version 4 over TCP
1068 with Kerberos 5 mutual authentication.
1069 .P
1070 .nf
1071 .ta 8n +16n +6n +6n +30n
1072 server:/export /mnt nfs4 sec=krb5 0 0
1073 .fi
1074 .P
1075 This example shows how to mount using NFS version 4 over TCP
1076 with Kerberos 5 privacy or data integrity mode.
1077 .P
1078 .nf
1079 .ta 8n +16n +6n +6n +30n
1080 server:/export /mnt nfs4 sec=krb5p:krb5i 0 0
1081 .fi
1082 .P
1083 This example can be used to mount /usr over NFS.
1084 .P
1085 .nf
1086 .ta 8n +16n +6n +6n +30n
1087 server:/export /usr nfs ro,nolock,nocto,actimeo=3600 0 0
1088 .fi
1089 .P
1090 This example shows how to mount an NFS server
1091 using a raw IPv6 link-local address.
1092 .P
1093 .nf
1094 .ta 8n +40n +5n +4n +9n
1095 [fe80::215:c5ff:fb3e:e2b1%eth0]:/export /mnt nfs defaults 0 0
1096 .fi
1097 .SH "TRANSPORT METHODS"
1098 NFS clients send requests to NFS servers via
1099 Remote Procedure Calls, or
1100 .IR RPCs .
1101 The RPC client discovers remote service endpoints automatically,
1102 handles per-request authentication,
1103 adjusts request parameters for different byte endianness on client and server,
1104 and retransmits requests that may have been lost by the network or server.
1105 RPC requests and replies flow over a network transport.
1106 .P
1107 In most cases, the
1108 .BR mount (8)
1109 command, NFS client, and NFS server
1110 can automatically negotiate proper transport
1111 and data transfer size settings for a mount point.
1112 In some cases, however, it pays to specify
1113 these settings explicitly using mount options.
1114 .P
1115 Traditionally, NFS clients used the UDP transport exclusively for
1116 transmitting requests to servers. Though its implementation is
1117 simple, NFS over UDP has many limitations that prevent smooth
1118 operation and good performance in some common deployment
1119 environments. Even an insignificant packet loss rate results in the
1120 loss of whole NFS requests; as such, retransmit timeouts are usually
1121 in the subsecond range to allow clients to recover quickly from
1122 dropped requests, but this can result in extraneous network traffic
1123 and server load.
1124 .P
1125 However, UDP can be quite effective in specialized settings where
1126 the networks MTU is large relative to NFSs data transfer size (such
1127 as network environments that enable jumbo Ethernet frames). In such
1128 environments, trimming the
1129 .B rsize
1130 and
1131 .B wsize
1132 settings so that each
1133 NFS read or write request fits in just a few network frames (or even
1134 in a single frame) is advised. This reduces the probability that
1135 the loss of a single MTU-sized network frame results in the loss of
1136 an entire large read or write request.
1137 .P
1138 TCP is the default transport protocol used for all modern NFS
1139 implementations. It performs well in almost every conceivable
1140 network environment and provides excellent guarantees against data
1141 corruption caused by network unreliability. TCP is often a
1142 requirement for mounting a server through a network firewall.
1143 .P
1144 Under normal circumstances, networks drop packets much more
1145 frequently than NFS servers drop requests. As such, an aggressive
1146 retransmit timeout setting for NFS over TCP is unnecessary. Typical
1147 timeout settings for NFS over TCP are between one and ten minutes.
1148 After the client exhausts its retransmits (the value of the
1149 .B retrans
1150 mount option), it assumes a network partition has occurred,
1151 and attempts to reconnect to the server on a fresh socket. Since
1152 TCP itself makes network data transfer reliable,
1153 .B rsize
1154 and
1155 .B wsize
1156 can safely be allowed to default to the largest values supported by
1157 both client and server, independent of the network's MTU size.
1158 .SS "Using the mountproto mount option"
1159 This section applies only to NFS version 3 mounts
1160 since NFS version 4 does not use a separate protocol for mount
1161 requests.
1162 .P
1163 The Linux NFS client can use a different transport for
1164 contacting an NFS server's rpcbind service, its mountd service,
1165 its Network Lock Manager (NLM) service, and its NFS service.
1166 The exact transports employed by the Linux NFS client for
1167 each mount point depends on the settings of the transport
1168 mount options, which include
1169 .BR proto ,
1170 .BR mountproto ,
1171 .BR udp ", and " tcp .
1172 .P
1173 The client sends Network Status Manager (NSM) notifications
1174 via UDP no matter what transport options are specified, but
1175 listens for server NSM notifications on both UDP and TCP.
1176 The NFS Access Control List (NFSACL) protocol shares the same
1177 transport as the main NFS service.
1178 .P
1179 If no transport options are specified, the Linux NFS client
1180 uses UDP to contact the server's mountd service, and TCP to
1181 contact its NLM and NFS services by default.
1182 .P
1183 If the server does not support these transports for these services, the
1184 .BR mount (8)
1185 command attempts to discover what the server supports, and then retries
1186 the mount request once using the discovered transports.
1187 If the server does not advertise any transport supported by the client
1188 or is misconfigured, the mount request fails.
1189 If the
1190 .B bg
1191 option is in effect, the mount command backgrounds itself and continues
1192 to attempt the specified mount request.
1193 .P
1194 When the
1195 .B proto
1196 option, the
1197 .B udp
1198 option, or the
1199 .B tcp
1200 option is specified but the
1201 .B mountproto
1202 option is not, the specified transport is used to contact
1203 both the server's mountd service and for the NLM and NFS services.
1204 .P
1205 If the
1206 .B mountproto
1207 option is specified but none of the
1208 .BR proto ", " udp " or " tcp
1209 options are specified, then the specified transport is used for the
1210 initial mountd request, but the mount command attempts to discover
1211 what the server supports for the NFS protocol, preferring TCP if
1212 both transports are supported.
1213 .P
1214 If both the
1215 .BR mountproto " and " proto
1216 (or
1217 .BR udp " or " tcp )
1218 options are specified, then the transport specified by the
1219 .B mountproto
1220 option is used for the initial mountd request, and the transport
1221 specified by the
1222 .B proto
1223 option (or the
1224 .BR udp " or " tcp " options)"
1225 is used for NFS, no matter what order these options appear.
1226 No automatic service discovery is performed if these options are
1227 specified.
1228 .P
1229 If any of the
1230 .BR proto ", " udp ", " tcp ", "
1231 or
1232 .B mountproto
1233 options are specified more than once on the same mount command line,
1234 then the value of the rightmost instance of each of these options
1235 takes effect.
1236 .SS "Using NFS over UDP on high-speed links"
1237 Using NFS over UDP on high-speed links such as Gigabit
1238 .BR "can cause silent data corruption" .
1239 .P
1240 The problem can be triggered at high loads, and is caused by problems in
1241 IP fragment reassembly. NFS read and writes typically transmit UDP packets
1242 of 4 Kilobytes or more, which have to be broken up into several fragments
1243 in order to be sent over the Ethernet link, which limits packets to 1500
1244 bytes by default. This process happens at the IP network layer and is
1245 called fragmentation.
1246 .P
1247 In order to identify fragments that belong together, IP assigns a 16bit
1248 .I IP ID
1249 value to each packet; fragments generated from the same UDP packet
1250 will have the same IP ID. The receiving system will collect these
1251 fragments and combine them to form the original UDP packet. This process
1252 is called reassembly. The default timeout for packet reassembly is
1253 30 seconds; if the network stack does not receive all fragments of
1254 a given packet within this interval, it assumes the missing fragment(s)
1255 got lost and discards those it already received.
1256 .P
1257 The problem this creates over high-speed links is that it is possible
1258 to send more than 65536 packets within 30 seconds. In fact, with
1259 heavy NFS traffic one can observe that the IP IDs repeat after about
1260 5 seconds.
1261 .P
1262 This has serious effects on reassembly: if one fragment gets lost,
1263 another fragment
1264 .I from a different packet
1265 but with the
1266 .I same IP ID
1267 will arrive within the 30 second timeout, and the network stack will
1268 combine these fragments to form a new packet. Most of the time, network
1269 layers above IP will detect this mismatched reassembly - in the case
1270 of UDP, the UDP checksum, which is a 16 bit checksum over the entire
1271 packet payload, will usually not match, and UDP will discard the
1272 bad packet.
1273 .P
1274 However, the UDP checksum is 16 bit only, so there is a chance of 1 in
1275 65536 that it will match even if the packet payload is completely
1276 random (which very often isn't the case). If that is the case,
1277 silent data corruption will occur.
1278 .P
1279 This potential should be taken seriously, at least on Gigabit
1280 Ethernet.
1281 Network speeds of 100Mbit/s should be considered less
1282 problematic, because with most traffic patterns IP ID wrap around
1283 will take much longer than 30 seconds.
1284 .P
1285 It is therefore strongly recommended to use
1286 .BR "NFS over TCP where possible" ,
1287 since TCP does not perform fragmentation.
1288 .P
1289 If you absolutely have to use NFS over UDP over Gigabit Ethernet,
1290 some steps can be taken to mitigate the problem and reduce the
1291 probability of corruption:
1292 .TP +1.5i
1293 .I Jumbo frames:
1294 Many Gigabit network cards are capable of transmitting
1295 frames bigger than the 1500 byte limit of traditional Ethernet, typically
1296 9000 bytes. Using jumbo frames of 9000 bytes will allow you to run NFS over
1297 UDP at a page size of 8K without fragmentation. Of course, this is
1298 only feasible if all involved stations support jumbo frames.
1299 .IP
1300 To enable a machine to send jumbo frames on cards that support it,
1301 it is sufficient to configure the interface for a MTU value of 9000.
1302 .TP +1.5i
1303 .I Lower reassembly timeout:
1304 By lowering this timeout below the time it takes the IP ID counter
1305 to wrap around, incorrect reassembly of fragments can be prevented
1306 as well. To do so, simply write the new timeout value (in seconds)
1307 to the file
1308 .BR /proc/sys/net/ipv4/ipfrag_time .
1309 .IP
1310 A value of 2 seconds will greatly reduce the probability of IPID clashes on
1311 a single Gigabit link, while still allowing for a reasonable timeout
1312 when receiving fragmented traffic from distant peers.
1313 .SH "DATA AND METADATA COHERENCE"
1314 Some modern cluster file systems provide
1315 perfect cache coherence among their clients.
1316 Perfect cache coherence among disparate NFS clients
1317 is expensive to achieve, especially on wide area networks.
1318 As such, NFS settles for weaker cache coherence that
1319 satisfies the requirements of most file sharing types.
1320 .SS "Close-to-open cache consistency"
1321 Typically file sharing is completely sequential.
1322 First client A opens a file, writes something to it, then closes it.
1323 Then client B opens the same file, and reads the changes.
1324 .P
1325 When an application opens a file stored on an NFS version 3 server,
1326 the NFS client checks that the file exists on the server
1327 and is permitted to the opener by sending a GETATTR or ACCESS request.
1328 The NFS client sends these requests
1329 regardless of the freshness of the file's cached attributes.
1330 .P
1331 When the application closes the file,
1332 the NFS client writes back any pending changes
1333 to the file so that the next opener can view the changes.
1334 This also gives the NFS client an opportunity to report
1335 write errors to the application via the return code from
1336 .BR close (2).
1337 .P
1338 The behavior of checking at open time and flushing at close time
1339 is referred to as
1340 .IR "close-to-open cache consistency" ,
1341 or
1342 .IR CTO .
1343 It can be disabled for an entire mount point using the
1344 .B nocto
1345 mount option.
1346 .SS "Weak cache consistency"
1347 There are still opportunities for a client's data cache
1348 to contain stale data.
1349 The NFS version 3 protocol introduced "weak cache consistency"
1350 (also known as WCC) which provides a way of efficiently checking
1351 a file's attributes before and after a single request.
1352 This allows a client to help identify changes
1353 that could have been made by other clients.
1354 .P
1355 When a client is using many concurrent operations
1356 that update the same file at the same time
1357 (for example, during asynchronous write behind),
1358 it is still difficult to tell whether it was
1359 that client's updates or some other client's updates
1360 that altered the file.
1361 .SS "Attribute caching"
1362 Use the
1363 .B noac
1364 mount option to achieve attribute cache coherence
1365 among multiple clients.
1366 Almost every file system operation checks
1367 file attribute information.
1368 The client keeps this information cached
1369 for a period of time to reduce network and server load.
1370 When
1371 .B noac
1372 is in effect, a client's file attribute cache is disabled,
1373 so each operation that needs to check a file's attributes
1374 is forced to go back to the server.
1375 This permits a client to see changes to a file very quickly,
1376 at the cost of many extra network operations.
1377 .P
1378 Be careful not to confuse the
1379 .B noac
1380 option with "no data caching."
1381 The
1382 .B noac
1383 mount option prevents the client from caching file metadata,
1384 but there are still races that may result in data cache incoherence
1385 between client and server.
1386 .P
1387 The NFS protocol is not designed to support
1388 true cluster file system cache coherence
1389 without some type of application serialization.
1390 If absolute cache coherence among clients is required,
1391 applications should use file locking. Alternatively, applications
1392 can also open their files with the O_DIRECT flag
1393 to disable data caching entirely.
1394 .SS "File timestamp maintenance"
1395 NFS servers are responsible for managing file and directory timestamps
1396 .RB ( atime ,
1397 .BR ctime ", and"
1398 .BR mtime ).
1399 When a file is accessed or updated on an NFS server,
1400 the file's timestamps are updated just like they would be on a filesystem
1401 local to an application.
1402 .P
1403 NFS clients cache file attributes, including timestamps.
1404 A file's timestamps are updated on NFS clients when its attributes
1405 are retrieved from the NFS server.
1406 Thus there may be some delay before timestamp updates
1407 on an NFS server appear to applications on NFS clients.
1408 .P
1409 To comply with the POSIX filesystem standard, the Linux NFS client
1410 relies on NFS servers to keep a file's
1411 .B mtime
1412 and
1413 .B ctime
1414 timestamps properly up to date.
1415 It does this by flushing local data changes to the server
1416 before reporting
1417 .B mtime
1418 to applications via system calls such as
1419 .BR stat (2).
1420 .P
1421 The Linux client handles
1422 .B atime
1423 updates more loosely, however.
1424 NFS clients maintain good performance by caching data,
1425 but that means that application reads, which normally update
1426 .BR atime ,
1427 are not reflected to the server where a file's
1428 .B atime
1429 is actually maintained.
1430 .P
1431 Because of this caching behavior,
1432 the Linux NFS client does not support generic atime-related mount options.
1433 See
1434 .BR mount (8)
1435 for details on these options.
1436 .P
1437 In particular, the
1438 .BR atime / noatime ,
1439 .BR diratime / nodiratime ,
1440 .BR relatime / norelatime ,
1441 and
1442 .BR strictatime / nostrictatime
1443 mount options have no effect on NFS mounts.
1444 .P
1445 .I /proc/mounts
1446 may report that the
1447 .B relatime
1448 mount option is set on NFS mounts, but in fact the
1449 .B atime
1450 semantics are always as described here, and are not like
1451 .B relatime
1452 semantics.
1453 .SS "Directory entry caching"
1454 The Linux NFS client caches the result of all NFS LOOKUP requests.
1455 If the requested directory entry exists on the server,
1456 the result is referred to as a
1457 .IR positive " lookup result.
1458 If the requested directory entry does not exist on the server
1459 (that is, the server returned ENOENT),
1460 the result is referred to as
1461 .IR negative " lookup result.
1462 .P
1463 To detect when directory entries have been added or removed
1464 on the server,
1465 the Linux NFS client watches a directory's mtime.
1466 If the client detects a change in a directory's mtime,
1467 the client drops all cached LOOKUP results for that directory.
1468 Since the directory's mtime is a cached attribute, it may
1469 take some time before a client notices it has changed.
1470 See the descriptions of the
1471 .BR acdirmin ", " acdirmax ", and " noac
1472 mount options for more information about
1473 how long a directory's mtime is cached.
1474 .P
1475 Caching directory entries improves the performance of applications that
1476 do not share files with applications on other clients.
1477 Using cached information about directories can interfere
1478 with applications that run concurrently on multiple clients and
1479 need to detect the creation or removal of files quickly, however.
1480 The
1481 .B lookupcache
1482 mount option allows some tuning of directory entry caching behavior.
1483 .P
1484 Before kernel release 2.6.28,
1485 the Linux NFS client tracked only positive lookup results.
1486 This permitted applications to detect new directory entries
1487 created by other clients quickly while still providing some of the
1488 performance benefits of caching.
1489 If an application depends on the previous lookup caching behavior
1490 of the Linux NFS client, you can use
1491 .BR lookupcache=positive .
1492 .P
1493 If the client ignores its cache and validates every application
1494 lookup request with the server,
1495 that client can immediately detect when a new directory
1496 entry has been either created or removed by another client.
1497 You can specify this behavior using
1498 .BR lookupcache=none .
1499 The extra NFS requests needed if the client does not
1500 cache directory entries can exact a performance penalty.
1501 Disabling lookup caching
1502 should result in less of a performance penalty than using
1503 .BR noac ,
1504 and has no effect on how the NFS client caches the attributes of files.
1505 .P
1506 .SS "The sync mount option"
1507 The NFS client treats the
1508 .B sync
1509 mount option differently than some other file systems
1510 (refer to
1511 .BR mount (8)
1512 for a description of the generic
1513 .B sync
1514 and
1515 .B async
1516 mount options).
1517 If neither
1518 .B sync
1519 nor
1520 .B async
1521 is specified (or if the
1522 .B async
1523 option is specified),
1524 the NFS client delays sending application
1525 writes to the server
1526 until any of these events occur:
1527 .IP
1528 Memory pressure forces reclamation of system memory resources.
1529 .IP
1530 An application flushes file data explicitly with
1531 .BR sync (2),
1532 .BR msync (2),
1533 or
1534 .BR fsync (3).
1535 .IP
1536 An application closes a file with
1537 .BR close (2).
1538 .IP
1539 The file is locked/unlocked via
1540 .BR fcntl (2).
1541 .P
1542 In other words, under normal circumstances,
1543 data written by an application may not immediately appear
1544 on the server that hosts the file.
1545 .P
1546 If the
1547 .B sync
1548 option is specified on a mount point,
1549 any system call that writes data to files on that mount point
1550 causes that data to be flushed to the server
1551 before the system call returns control to user space.
1552 This provides greater data cache coherence among clients,
1553 but at a significant performance cost.
1554 .P
1555 Applications can use the O_SYNC open flag to force application
1556 writes to individual files to go to the server immediately without
1557 the use of the
1558 .B sync
1559 mount option.
1560 .SS "Using file locks with NFS"
1561 The Network Lock Manager protocol is a separate sideband protocol
1562 used to manage file locks in NFS version 3.
1563 To support lock recovery after a client or server reboot,
1564 a second sideband protocol --
1565 known as the Network Status Manager protocol --
1566 is also required.
1567 In NFS version 4,
1568 file locking is supported directly in the main NFS protocol,
1569 and the NLM and NSM sideband protocols are not used.
1570 .P
1571 In most cases, NLM and NSM services are started automatically,
1572 and no extra configuration is required.
1573 Configure all NFS clients with fully-qualified domain names
1574 to ensure that NFS servers can find clients to notify them of server reboots.
1575 .P
1576 NLM supports advisory file locks only.
1577 To lock NFS files, use
1578 .BR fcntl (2)
1579 with the F_GETLK and F_SETLK commands.
1580 The NFS client converts file locks obtained via
1581 .BR flock (2)
1582 to advisory locks.
1583 .P
1584 When mounting servers that do not support the NLM protocol,
1585 or when mounting an NFS server through a firewall
1586 that blocks the NLM service port,
1587 specify the
1588 .B nolock
1589 mount option. NLM locking must be disabled with the
1590 .B nolock
1591 option when using NFS to mount
1592 .I /var
1593 because
1594 .I /var
1595 contains files used by the NLM implementation on Linux.
1596 .P
1597 Specifying the
1598 .B nolock
1599 option may also be advised to improve the performance
1600 of a proprietary application which runs on a single client
1601 and uses file locks extensively.
1602 .SS "NFS version 4 caching features"
1603 The data and metadata caching behavior of NFS version 4
1604 clients is similar to that of earlier versions.
1605 However, NFS version 4 adds two features that improve
1606 cache behavior:
1607 .I change attributes
1608 and
1609 .IR "file delegation" .
1610 .P
1611 The
1612 .I change attribute
1613 is a new part of NFS file and directory metadata
1614 which tracks data changes.
1615 It replaces the use of a file's modification
1616 and change time stamps
1617 as a way for clients to validate the content
1618 of their caches.
1619 Change attributes are independent of the time stamp
1620 resolution on either the server or client, however.
1621 .P
1622 A
1623 .I file delegation
1624 is a contract between an NFS version 4 client
1625 and server that allows the client to treat a file temporarily
1626 as if no other client is accessing it.
1627 The server promises to notify the client (via a callback request) if another client
1628 attempts to access that file.
1629 Once a file has been delegated to a client, the client can
1630 cache that file's data and metadata aggressively without
1631 contacting the server.
1632 .P
1633 File delegations come in two flavors:
1634 .I read
1635 and
1636 .IR write .
1637 A
1638 .I read
1639 delegation means that the server notifies the client
1640 about any other clients that want to write to the file.
1641 A
1642 .I write
1643 delegation means that the client gets notified about
1644 either read or write accessors.
1645 .P
1646 Servers grant file delegations when a file is opened,
1647 and can recall delegations at any time when another
1648 client wants access to the file that conflicts with
1649 any delegations already granted.
1650 Delegations on directories are not supported.
1651 .P
1652 In order to support delegation callback, the server
1653 checks the network return path to the client during
1654 the client's initial contact with the server.
1655 If contact with the client cannot be established,
1656 the server simply does not grant any delegations to
1657 that client.
1658 .SH "SECURITY CONSIDERATIONS"
1659 NFS servers control access to file data,
1660 but they depend on their RPC implementation
1661 to provide authentication of NFS requests.
1662 Traditional NFS access control mimics
1663 the standard mode bit access control provided in local file systems.
1664 Traditional RPC authentication uses a number
1665 to represent each user
1666 (usually the user's own uid),
1667 a number to represent the user's group (the user's gid),
1668 and a set of up to 16 auxiliary group numbers
1669 to represent other groups of which the user may be a member.
1670 .P
1671 Typically, file data and user ID values appear unencrypted
1672 (i.e. "in the clear") on the network.
1673 Moreover, NFS versions 2 and 3 use
1674 separate sideband protocols for mounting,
1675 locking and unlocking files,
1676 and reporting system status of clients and servers.
1677 These auxiliary protocols use no authentication.
1678 .P
1679 In addition to combining these sideband protocols with the main NFS protocol,
1680 NFS version 4 introduces more advanced forms of access control,
1681 authentication, and in-transit data protection.
1682 The NFS version 4 specification mandates support for
1683 strong authentication and security flavors
1684 that provide per-RPC integrity checking and encryption.
1685 Because NFS version 4 combines the
1686 function of the sideband protocols into the main NFS protocol,
1687 the new security features apply to all NFS version 4 operations
1688 including mounting, file locking, and so on.
1689 RPCGSS authentication can also be used with NFS versions 2 and 3,
1690 but it does not protect their sideband protocols.
1691 .P
1692 The
1693 .B sec
1694 mount option specifies the security flavor used for operations
1695 on behalf of users on that NFS mount point.
1696 Specifying
1697 .B sec=krb5
1698 provides cryptographic proof of a user's identity in each RPC request.
1699 This provides strong verification of the identity of users
1700 accessing data on the server.
1701 Note that additional configuration besides adding this mount option
1702 is required in order to enable Kerberos security.
1703 Refer to the
1704 .BR rpc.gssd (8)
1705 man page for details.
1706 .P
1707 Two additional flavors of Kerberos security are supported:
1708 .B krb5i
1709 and
1710 .BR krb5p .
1711 The
1712 .B krb5i
1713 security flavor provides a cryptographically strong guarantee
1714 that the data in each RPC request has not been tampered with.
1715 The
1716 .B krb5p
1717 security flavor encrypts every RPC request
1718 to prevent data exposure during network transit; however,
1719 expect some performance impact
1720 when using integrity checking or encryption.
1721 Similar support for other forms of cryptographic security
1722 is also available.
1723 .SS "NFS version 4 filesystem crossing"
1724 The NFS version 4 protocol allows
1725 a client to renegotiate the security flavor
1726 when the client crosses into a new filesystem on the server.
1727 The newly negotiated flavor effects only accesses of the new filesystem.
1728 .P
1729 Such negotiation typically occurs when a client crosses
1730 from a server's pseudo-fs
1731 into one of the server's exported physical filesystems,
1732 which often have more restrictive security settings than the pseudo-fs.
1733 .SS "NFS version 4 Leases"
1734 In NFS version 4, a lease is a period during which a server
1735 irrevocably grants a client file locks.
1736 Once the lease expires, the server may revoke those locks.
1737 Clients periodically renew their leases to prevent lock revocation.
1738 .P
1739 After an NFS version 4 server reboots, each client tells the
1740 server about existing file open and lock state under its lease
1741 before operation can continue.
1742 If a client reboots, the server frees all open and lock state
1743 associated with that client's lease.
1744 .P
1745 When establishing a lease, therefore,
1746 a client must identify itself to a server.
1747 Each client presents an arbitrary string
1748 to distinguish itself from other clients.
1749 The client administrator can
1750 supplement the default identity string using the
1751 .I nfs4.nfs4_unique_id
1752 module parameter to avoid collisions
1753 with other client identity strings.
1754 .P
1755 A client also uses a unique security flavor and principal
1756 when it establishes its lease.
1757 If two clients present the same identity string,
1758 a server can use client principals to distinguish between them,
1759 thus securely preventing one client from interfering with the other's lease.
1760 .P
1761 The Linux NFS client establishes one lease on each NFS version 4 server.
1762 Lease management operations, such as lease renewal, are not
1763 done on behalf of a particular file, lock, user, or mount
1764 point, but on behalf of the client that owns that lease.
1765 A client uses a consistent identity string, security flavor,
1766 and principal across client reboots to ensure that the server
1767 can promptly reap expired lease state.
1768 .P
1769 When Kerberos is configured on a Linux NFS client
1770 (i.e., there is a
1771 .I /etc/krb5.keytab
1772 on that client), the client attempts to use a Kerberos
1773 security flavor for its lease management operations.
1774 Kerberos provides secure authentication of each client.
1775 By default, the client uses the
1776 .I host/
1777 or
1778 .I nfs/
1779 service principal in its
1780 .I /etc/krb5.keytab
1781 for this purpose, as described in
1782 .BR rpc.gssd (8).
1783 .P
1784 If the client has Kerberos configured, but the server
1785 does not, or if the client does not have a keytab or
1786 the requisite service principals, the client uses
1787 .I AUTH_SYS
1788 and UID 0 for lease management.
1789 .SS "Using non-privileged source ports"
1790 NFS clients usually communicate with NFS servers via network sockets.
1791 Each end of a socket is assigned a port value, which is simply a number
1792 between 1 and 65535 that distinguishes socket endpoints at the same
1793 IP address.
1794 A socket is uniquely defined by a tuple that includes the transport
1795 protocol (TCP or UDP) and the port values and IP addresses of both
1796 endpoints.
1797 .P
1798 The NFS client can choose any source port value for its sockets,
1799 but usually chooses a
1800 .I privileged
1801 port.
1802 A privileged port is a port value less than 1024.
1803 Only a process with root privileges may create a socket
1804 with a privileged source port.
1805 .P
1806 The exact range of privileged source ports that can be chosen is
1807 set by a pair of sysctls to avoid choosing a well-known port, such as
1808 the port used by ssh.
1809 This means the number of source ports available for the NFS client,
1810 and therefore the number of socket connections that can be used
1811 at the same time,
1812 is practically limited to only a few hundred.
1813 .P
1814 As described above, the traditional default NFS authentication scheme,
1815 known as AUTH_SYS, relies on sending local UID and GID numbers to identify
1816 users making NFS requests.
1817 An NFS server assumes that if a connection comes from a privileged port,
1818 the UID and GID numbers in the NFS requests on this connection have been
1819 verified by the client's kernel or some other local authority.
1820 This is an easy system to spoof, but on a trusted physical network between
1821 trusted hosts, it is entirely adequate.
1822 .P
1823 Roughly speaking, one socket is used for each NFS mount point.
1824 If a client could use non-privileged source ports as well,
1825 the number of sockets allowed,
1826 and thus the maximum number of concurrent mount points,
1827 would be much larger.
1828 .P
1829 Using non-privileged source ports may compromise server security somewhat,
1830 since any user on AUTH_SYS mount points can now pretend to be any other
1831 when making NFS requests.
1832 Thus NFS servers do not support this by default.
1833 They explicitly allow it usually via an export option.
1834 .P
1835 To retain good security while allowing as many mount points as possible,
1836 it is best to allow non-privileged client connections only if the server
1837 and client both require strong authentication, such as Kerberos.
1838 .SS "Mounting through a firewall"
1839 A firewall may reside between an NFS client and server,
1840 or the client or server may block some of its own ports via IP
1841 filter rules.
1842 It is still possible to mount an NFS server through a firewall,
1843 though some of the
1844 .BR mount (8)
1845 command's automatic service endpoint discovery mechanisms may not work; this
1846 requires you to provide specific endpoint details via NFS mount options.
1847 .P
1848 NFS servers normally run a portmapper or rpcbind daemon to advertise
1849 their service endpoints to clients. Clients use the rpcbind daemon to determine:
1850 .IP
1851 What network port each RPC-based service is using
1852 .IP
1853 What transport protocols each RPC-based service supports
1854 .P
1855 The rpcbind daemon uses a well-known port number (111) to help clients find a service endpoint.
1856 Although NFS often uses a standard port number (2049),
1857 auxiliary services such as the NLM service can choose
1858 any unused port number at random.
1859 .P
1860 Common firewall configurations block the well-known rpcbind port.
1861 In the absence of an rpcbind service,
1862 the server administrator fixes the port number
1863 of NFS-related services so that the firewall
1864 can allow access to specific NFS service ports.
1865 Client administrators then specify the port number
1866 for the mountd service via the
1867 .BR mount (8)
1868 command's
1869 .B mountport
1870 option.
1871 It may also be necessary to enforce the use of TCP or UDP
1872 if the firewall blocks one of those transports.
1873 .SS "NFS Access Control Lists"
1874 Solaris allows NFS version 3 clients direct access
1875 to POSIX Access Control Lists stored in its local file systems.
1876 This proprietary sideband protocol, known as NFSACL,
1877 provides richer access control than mode bits.
1878 Linux implements this protocol
1879 for compatibility with the Solaris NFS implementation.
1880 The NFSACL protocol never became a standard part
1881 of the NFS version 3 specification, however.
1882 .P
1883 The NFS version 4 specification mandates a new version
1884 of Access Control Lists that are semantically richer than POSIX ACLs.
1885 NFS version 4 ACLs are not fully compatible with POSIX ACLs; as such,
1886 some translation between the two is required
1887 in an environment that mixes POSIX ACLs and NFS version 4.
1888 .SH "THE REMOUNT OPTION"
1889 Generic mount options such as
1890 .BR rw " and " sync
1891 can be modified on NFS mount points using the
1892 .BR remount
1893 option.
1894 See
1895 .BR mount (8)
1896 for more information on generic mount options.
1897 .P
1898 With few exceptions, NFS-specific options
1899 are not able to be modified during a remount.
1900 The underlying transport or NFS version
1901 cannot be changed by a remount, for example.
1902 .P
1903 Performing a remount on an NFS file system mounted with the
1904 .B noac
1905 option may have unintended consequences.
1906 The
1907 .B noac
1908 option is a combination of the generic option
1909 .BR sync ,
1910 and the NFS-specific option
1911 .BR actimeo=0 .
1912 .SS "Unmounting after a remount"
1913 For mount points that use NFS versions 2 or 3, the NFS umount subcommand
1914 depends on knowing the original set of mount options used to perform the
1915 MNT operation.
1916 These options are stored on disk by the NFS mount subcommand,
1917 and can be erased by a remount.
1918 .P
1919 To ensure that the saved mount options are not erased during a remount,
1920 specify either the local mount directory, or the server hostname and
1921 export pathname, but not both, during a remount. For example,
1922 .P
1923 .nf
1924 .ta 8n
1925 mount -o remount,ro /mnt
1926 .fi
1927 .P
1928 merges the mount option
1929 .B ro
1930 with the mount options already saved on disk for the NFS server mounted at /mnt.
1931 .SH FILES
1932 .TP 1.5i
1933 .I /etc/fstab
1934 file system table
1935 .TP 1.5i
1936 .I /etc/nfsmount.conf
1937 Configuration file for NFS mounts
1938 .SH NOTES
1939 Before 2.4.7, the Linux NFS client did not support NFS over TCP.
1940 .P
1941 Before 2.4.20, the Linux NFS client used a heuristic
1942 to determine whether cached file data was still valid
1943 rather than using the standard close-to-open cache coherency method
1944 described above.
1945 .P
1946 Starting with 2.4.22, the Linux NFS client employs
1947 a Van Jacobsen-based RTT estimator to determine retransmit
1948 timeout values when using NFS over UDP.
1949 .P
1950 Before 2.6.0, the Linux NFS client did not support NFS version 4.
1951 .P
1952 Before 2.6.8, the Linux NFS client used only synchronous reads and writes
1953 when the
1954 .BR rsize " and " wsize
1955 settings were smaller than the system's page size.
1956 .P
1957 The Linux client's support for protocol versions depend on whether the
1958 kernel was built with options CONFIG_NFS_V2, CONFIG_NFS_V3,
1959 CONFIG_NFS_V4, CONFIG_NFS_V4_1, and CONFIG_NFS_V4_2.
1960 .SH "SEE ALSO"
1961 .BR fstab (5),
1962 .BR mount (8),
1963 .BR umount (8),
1964 .BR mount.nfs (5),
1965 .BR umount.nfs (5),
1966 .BR exports (5),
1967 .BR nfsmount.conf (5),
1968 .BR netconfig (5),
1969 .BR ipv6 (7),
1970 .BR nfsd (8),
1971 .BR sm-notify (8),
1972 .BR rpc.statd (8),
1973 .BR rpc.idmapd (8),
1974 .BR rpc.gssd (8),
1975 .BR rpc.svcgssd (8),
1976 .BR kerberos (1)
1977 .sp
1978 RFC 768 for the UDP specification.
1979 .br
1980 RFC 793 for the TCP specification.
1981 .br
1982 RFC 1813 for the NFS version 3 specification.
1983 .br
1984 RFC 1832 for the XDR specification.
1985 .br
1986 RFC 1833 for the RPC bind specification.
1987 .br
1988 RFC 2203 for the RPCSEC GSS API protocol specification.
1989 .br
1990 RFC 7530 for the NFS version 4.0 specification.
1991 .br
1992 RFC 5661 for the NFS version 4.1 specification.
1993 .br
1994 RFC 7862 for the NFS version 4.2 specification.