492 lines
14 KiB
Groff
492 lines
14 KiB
Groff
.\" $NetBSD: mount_nfs.8,v 1.52 2021/03/14 02:56:51 rin Exp $
|
|
.\"
|
|
.\" Copyright (c) 1992, 1993, 1994, 1995
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)mount_nfs.8 8.3 (Berkeley) 3/29/95
|
|
.\"
|
|
.Dd January 24, 2021
|
|
.Dt MOUNT_NFS 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mount_nfs
|
|
.Nd mount NFS file systems
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl 23AbCcdilPpqsTUuX
|
|
.Op Fl a Ar maxreadahead
|
|
.Op Fl D Ar deadthresh
|
|
.Op Fl g Ar maxgroups
|
|
.Op Fl I Ar readdirsize
|
|
.Op Fl L Ar leaseterm
|
|
.Op Fl o Ar options
|
|
.Op Fl R Ar retrycnt
|
|
.Op Fl r Ar readsize
|
|
.Op Fl t Ar timeout
|
|
.Op Fl w Ar writesize
|
|
.Op Fl x Ar retrans
|
|
.Ar rhost:path node
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command calls the
|
|
.Xr mount 2
|
|
system call to prepare and graft a remote NFS file system (rhost:path)
|
|
on to the file system tree at the mount point
|
|
.Ar node .
|
|
The directory specified by
|
|
.Ar node
|
|
is converted to an absolute path before use.
|
|
This command is normally executed by
|
|
.Xr mount 8 .
|
|
It implements the mount protocol as described in RFC 1094, Appendix A and
|
|
.%T "NFS: Network File System Version 3 Protocol Specification" ,
|
|
Appendix I.
|
|
.Pp
|
|
The options are:
|
|
.Bl -tag -width indent
|
|
.It Fl 2
|
|
Use the NFS Version 2 protocol.
|
|
.It Fl 3
|
|
Use the NFS Version 3 protocol.
|
|
The default is to try version 3 first, and
|
|
fall back to version 2 if the mount fails.
|
|
.It Fl A
|
|
Disable the attribute cache in the client, making it consult the server
|
|
for the current version of a given file's attributes every time the file
|
|
is accessed.
|
|
.Pp
|
|
By default the attribute cache is enabled, making the client only consult
|
|
the server every handful of seconds.
|
|
This improves performance, however at the cost of the risk of a
|
|
mid-air collision when changes are made simultaneously by different
|
|
NFS clients and/or locally on the NFS server that affect the same file.
|
|
In that case changes made elsewhere may be missed, leading to
|
|
consistency issues.
|
|
.It Fl a Ar maxreadahead
|
|
Set the read-ahead count to the specified value.
|
|
This may be in the range of 0 - 4, and determines how many blocks
|
|
will be read ahead when a large file is being read sequentially.
|
|
Trying a value greater than 1 for this is suggested for
|
|
mounts with a large bandwidth * delay product.
|
|
.It Fl b
|
|
If an initial attempt to contact the server fails, fork off a child to keep
|
|
trying the mount in the background.
|
|
Useful for
|
|
.Xr fstab 5 ,
|
|
where the filesystem mount is not critical to multiuser operation.
|
|
.It Fl C
|
|
For UDP mount points, do a
|
|
.Xr connect 2 .
|
|
Although this flag increases the efficiency of UDP mounts it cannot
|
|
be used for servers that do not reply to requests from the
|
|
standard NFS port number 2049, or for servers with multiple network interfaces.
|
|
In these cases if the socket is connected and the server
|
|
replies from a different port number or a different network interface
|
|
the client will get ICMP port unreachable and the mount will hang.
|
|
.It Fl c
|
|
For UDP mount points, do not do a
|
|
.Xr connect 2 .
|
|
This flag is deprecated and connectionless UDP mounts are the default.
|
|
.It Fl D Ar deadthresh
|
|
Set the
|
|
.Dq "dead server threshold"
|
|
to the specified number of round trip timeout intervals.
|
|
After a
|
|
.Dq "dead server threshold"
|
|
of retransmit timeouts,
|
|
.Dq "not responding"
|
|
message is printed to a tty.
|
|
.It Fl d
|
|
Turn off the dynamic retransmit timeout estimator.
|
|
This may be useful for UDP mounts that exhibit high retry rates,
|
|
since it is possible that the dynamically estimated timeout interval is too
|
|
short.
|
|
.It Fl g Ar maxgroups
|
|
Set the maximum size of the group list for the credentials to the
|
|
specified value.
|
|
This should be used for mounts on old servers that cannot handle a
|
|
group list size of 16, as specified in RFC 1057.
|
|
Try 8, if users in a lot of groups cannot get response from the mount
|
|
point.
|
|
.It Fl I Ar readdirsize
|
|
Set the readdir read size to the specified value.
|
|
The value should normally
|
|
be a multiple of
|
|
.Dv DIRBLKSIZ
|
|
that is \*[Le] the read size for the mount.
|
|
.It Fl i
|
|
Make the mount interruptible, which implies that file system calls that
|
|
are delayed due to an unresponsive server will fail with
|
|
.Er EINTR
|
|
when a
|
|
termination signal is posted for the process.
|
|
.It Fl L Ar leaseterm
|
|
Ignored.
|
|
It used to be NQNFS lease term.
|
|
.It Fl l
|
|
Used with NFS Version 3 to specify that the
|
|
.Fn ReaddirPlus
|
|
RPC should be used.
|
|
This option reduces RPC traffic for cases such as
|
|
.Ic "ls -l" ,
|
|
but tends to flood the attribute and name caches with prefetched entries.
|
|
Try this option and see whether performance improves or degrades.
|
|
Probably most useful for client to server network
|
|
interconnects with a large bandwidth times delay product.
|
|
.It Fl o Ar options
|
|
Options are specified with a
|
|
.Fl o
|
|
flag followed by a comma separated string of options.
|
|
See the
|
|
.Xr mount 8
|
|
man page for possible options and their meanings.
|
|
.Pp
|
|
The following NFS specific options are also available:
|
|
.Bl -tag -width indent
|
|
.It Cm bg
|
|
Same as
|
|
.Fl b .
|
|
.It Cm conn
|
|
Same as
|
|
.Fl C .
|
|
.It Cm deadthresh Ns = Ns Aq Ar deadthresh
|
|
Same as
|
|
.Fl D Ar deadthresh .
|
|
.It Cm dumbtimer
|
|
Same as
|
|
.Fl d .
|
|
.It Cm intr
|
|
Same as
|
|
.Fl i .
|
|
.It Cm leaseterm Ns = Ns Aq Ar leaseterm
|
|
Same as
|
|
.Fl L Ar leaseterm .
|
|
.It Cm maxgrps Ns = Ns Aq Ar maxgroups
|
|
Same as
|
|
.Fl g Ar maxgroups .
|
|
.It Cm mntudp
|
|
Same as
|
|
.Fl U .
|
|
.It Cm nfsv2
|
|
Same as
|
|
.Fl 2 .
|
|
.It Cm nfsv3
|
|
Same as
|
|
.Fl 3 .
|
|
.It Cm noac
|
|
Same as
|
|
.Fl A .
|
|
.It Cm noresport
|
|
Same as
|
|
.Fl p .
|
|
.It Cm nqnfs
|
|
Same as
|
|
.Fl q .
|
|
.It Cm port Ns = Ns Aq Ar portnumber
|
|
Use the specified port number for NFS requests.
|
|
The default is to query the portmapper for the NFS port.
|
|
.It Cm rdirplus
|
|
Same as
|
|
.Fl l .
|
|
.It Cm readahead Ns = Ns Aq Ar maxreadahead
|
|
Same as
|
|
.Fl a Ar maxreadahead .
|
|
.It Cm rsize Ns = Ns Aq Ar readsize
|
|
Same as
|
|
.Fl r Ar readsize .
|
|
.It Cm soft
|
|
Same as
|
|
.Fl s .
|
|
.It Cm tcp
|
|
Same as
|
|
.Fl T .
|
|
.It Cm udp
|
|
Same as
|
|
.Fl u .
|
|
.It Cm timeo Ns = Ns Aq Ar timeout
|
|
Same as
|
|
.Fl t Ar timeout .
|
|
.It Cm wsize Ns = Ns Aq Ar writesize
|
|
Same as
|
|
.Fl w Ar writesize .
|
|
.El
|
|
.It Fl P
|
|
Use a reserved socket port number.
|
|
This is the default, and available
|
|
for backwards compatibility purposes only.
|
|
.It Fl p
|
|
Do not use a reserved port number for RPCs.
|
|
This option is provided only to be able to mimic the old
|
|
default behavior of not using a reserved port, and should rarely be useful.
|
|
.It Fl q
|
|
A synonym of
|
|
.Fl 3 .
|
|
It used to specify NQNFS.
|
|
.It Fl R Ar retrycnt
|
|
Set the retry count for doing the mount to the specified value.
|
|
The default is 10000.
|
|
.It Fl r Ar readsize
|
|
Set the read data size to the specified value in bytes.
|
|
It should normally be a power of 2 greater than or equal to 1024.
|
|
.Pp
|
|
This should be used for UDP mounts when the
|
|
.Dq "fragments dropped after timeout"
|
|
value is getting large while actively using a mount point.
|
|
Use
|
|
.Xr netstat 1
|
|
with the
|
|
.Fl s
|
|
option to see what the
|
|
.Dq "fragments dropped after timeout"
|
|
value is.
|
|
See the
|
|
.Nm
|
|
.Fl w
|
|
option also.
|
|
.It Fl s
|
|
A soft mount, which implies that file system calls will fail
|
|
after
|
|
.Ar retrans
|
|
round trip timeout intervals.
|
|
.It Fl T
|
|
Use TCP transport instead of UDP.
|
|
This is the default;
|
|
the flag is maintained for backwards compatibility.
|
|
.It Fl t Ar timeout
|
|
Set the initial retransmit timeout to the specified value in 0.1 seconds.
|
|
May be useful for fine tuning UDP mounts over internetworks
|
|
with high packet loss rates or an overloaded server.
|
|
Try increasing the interval if
|
|
.Xr nfsstat 1
|
|
shows high retransmit rates while the file system is active or reducing the
|
|
value if there is a low retransmit rate but long response delay observed.
|
|
Normally, the -d option should be specified when using this option to manually
|
|
tune the timeout
|
|
interval.
|
|
The default is 3 seconds.
|
|
.It Fl U
|
|
Force the mount protocol to use UDP transport, even for TCP NFS mounts.
|
|
This is necessary for some old
|
|
.Bx
|
|
servers.
|
|
.It Fl u
|
|
Use UDP transport instead of TCP.
|
|
This may be necessary for some very old servers.
|
|
.It Fl w Ar writesize
|
|
Set the write data size to the specified value in bytes.
|
|
.Pp
|
|
The same logic applies for use of this option as with the
|
|
.Nm
|
|
.Fl r
|
|
option, but using the
|
|
.Dq "fragments dropped after timeout"
|
|
value on the NFS server instead of the client.
|
|
Note that both the
|
|
.Fl r
|
|
and
|
|
.Fl w
|
|
options should only be used as a last ditch effort at improving performance
|
|
when mounting servers that do not support TCP mounts.
|
|
.It Fl X
|
|
Perform 32 <-> 64 bit directory cookie translation for version 3 mounts.
|
|
This may be needed in the case of a server using the upper 32 bits of
|
|
version 3 directory cookies, and when you are running emulated binaries
|
|
that access such a filesystem.
|
|
Native
|
|
.Nx
|
|
binaries will never need this option.
|
|
This option introduces some overhead.
|
|
.It Fl x Ar retrans
|
|
Set the retransmit timeout count for soft mounts to the specified value.
|
|
The default is 10.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The simplest way to invoke
|
|
.Nm
|
|
is with a command like:
|
|
.Pp
|
|
.Dl "mount -t nfs remotehost:/filesystem /localmountpoint"
|
|
.Pp
|
|
It is also possible to automatically mount filesystems at boot from your
|
|
.Pa /etc/fstab
|
|
by using a line like:
|
|
.Pp
|
|
.Dl "remotehost:/home /home nfs rw 0 0"
|
|
.Sh PERFORMANCE
|
|
As can be derived from the comments accompanying the options, performance
|
|
tuning of NFS can be a non-trivial task.
|
|
Here are some common points
|
|
to watch:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
Increasing the read and write size with the
|
|
.Fl r
|
|
and
|
|
.Fl w
|
|
options respectively will increase throughput if the network
|
|
interface can handle the larger packet sizes.
|
|
.Pp
|
|
The default size for NFS version 2 is 8K when using UDP,
|
|
64K when using TCP.
|
|
.Pp
|
|
The default size for NFS version 3 is platform dependent:
|
|
on
|
|
.Nx Ns /aarch64 ,
|
|
.Nx Ns /amd64 ,
|
|
and
|
|
.Nx Ns /i386 ,
|
|
the default is 32K, for other platforms it is 8K.
|
|
Values over 32K are only supported for TCP,
|
|
where 64K is the maximum.
|
|
.Pp
|
|
Any value over 32K is unlikely to get you more performance, unless
|
|
you have a very fast network.
|
|
.It
|
|
If the network interface cannot handle larger packet sizes or a
|
|
long train of back to back packets, you may see low performance
|
|
figures or even temporary hangups during NFS activity.
|
|
.Pp
|
|
This can especially happen with older Ethernet network interfaces.
|
|
What happens is that either the receive buffer on the network
|
|
interface on the client side is overflowing, or that similar events
|
|
occur on the server, leading to a lot of dropped packets.
|
|
.Pp
|
|
In this case, decreasing the read and write size, using TCP,
|
|
or a combination of both will usually lead to better throughput.
|
|
Should you need to decrease the read and write size for all your NFS
|
|
mounts because of a slow Ethernet network interface
|
|
.Pq e.g. a USB 1.1 to 10/100 Ethernet network interface ,
|
|
you can use
|
|
.Pp
|
|
.Bl -ohang -compact
|
|
.It Cd options NFS_RSIZE=value
|
|
.It Cd options NFS_WSIZE=value
|
|
.El
|
|
.Pp
|
|
in your kernel
|
|
.Xr config 1
|
|
file to avoid having do specify the sizes for all mounts.
|
|
.It
|
|
For connections that are not on the same LAN,
|
|
and/or may experience packet loss, using TCP is strongly recommended.
|
|
.El
|
|
.Sh ERRORS
|
|
Some common problems with
|
|
.Nm
|
|
can be difficult for first time users to understand.
|
|
.Pp
|
|
.Dl "mount_nfs: can't access /foo: Permission denied"
|
|
.Pp
|
|
This message means that the remote host is either not exporting
|
|
the filesystem you requested, or is not exporting it to your host.
|
|
If you believe the remote host is indeed exporting a filesystem to you,
|
|
make sure the
|
|
.Xr exports 5
|
|
file is exporting the proper directories.
|
|
.Pp
|
|
A common mistake is that
|
|
.Xr mountd 8
|
|
will not export a filesystem with the
|
|
.Fl alldirs
|
|
option, unless it
|
|
is a mount point on the exporting host.
|
|
It is not possible to remotely
|
|
mount a subdirectory of an exported mount, unless it is exported with the
|
|
.Fl alldirs
|
|
option.
|
|
.Pp
|
|
The following error:
|
|
.Pp
|
|
.Dl "NFS Portmap: RPC: Program not registered"
|
|
.Pp
|
|
means that the remote host is not running
|
|
.Xr mountd 8 .
|
|
The program
|
|
.Xr rpcinfo 8
|
|
can be used to determine if the remote host is running nfsd, and mountd by issuing
|
|
the command:
|
|
.Pp
|
|
.Dl rpcinfo -p remotehostname
|
|
.Pp
|
|
If the remote host is running nfsd, and mountd, it would display:
|
|
.Pp
|
|
.Dl "100005 3 udp 719 mountd"
|
|
.Dl "100005 1 tcp 720 mountd"
|
|
.Dl "100005 3 tcp 720 mountd"
|
|
.Dl "100003 2 udp 2049 nfs"
|
|
.Dl "100003 3 udp 2049 nfs"
|
|
.Dl "100003 2 tcp 2049 nfs"
|
|
.Dl "100003 3 tcp 2049 nfs"
|
|
.Pp
|
|
The error:
|
|
.Pp
|
|
.Dl "mount_nfs: can't get net id for host"
|
|
.Pp
|
|
indicates that
|
|
.Nm
|
|
cannot resolve the name of the remote host.
|
|
.Sh SEE ALSO
|
|
.Xr nfsstat 1 ,
|
|
.Xr mount 2 ,
|
|
.Xr unmount 2 ,
|
|
.Xr options 4 ,
|
|
.Xr exports 5 ,
|
|
.Xr fstab 5 ,
|
|
.Xr mount 8 ,
|
|
.Xr mountd 8 ,
|
|
.Xr rpcinfo 8
|
|
.Rs
|
|
.%R RFC 1094
|
|
.%D March 1989
|
|
.%T "NFS: Network File System Protocol specification"
|
|
.Re
|
|
.Rs
|
|
.%R RFC 2623
|
|
.%D June 1999
|
|
.%T "NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use of RPCSEC_GCC and Kerberos V5"
|
|
.Re
|
|
.Rs
|
|
.%R RFC 2624
|
|
.%D June 1999
|
|
.%T "NFS Version 4 Design Considerations"
|
|
.Re
|
|
.Rs
|
|
.%R RFC 2695
|
|
.%D September 1999
|
|
.%T "Authentication Mechanisms for ONC RPC"
|
|
.Re
|
|
.Sh HISTORY
|
|
A version of the
|
|
.Nm
|
|
utility appeared in
|
|
.Bx 4.4 .
|
|
.Sh CAVEATS
|
|
An NFS server should not mount its own exported file systems
|
|
.Pq loopback fashion
|
|
because doing so is fundamentally prone to deadlock.
|