537 lines
14 KiB
Groff
537 lines
14 KiB
Groff
.\" $NetBSD: mount_nfs.8,v 1.27 2005/01/31 05:19:19 erh 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 22, 2005
|
|
.Dt MOUNT_NFS 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mount_nfs
|
|
.Nd mount NFS file systems
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl 23bcCdiKlpPqsTUX
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl D Ar deadthresh
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl I Ar readdirsize
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl L Ar leaseterm
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl R Ar retrycnt
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl a Ar maxreadahead
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl g Ar maxgroups
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl m Ar realm
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl o Ar options
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl r Ar readsize
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl t Ar timeout
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl w Ar writesize
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl x Ar retrans
|
|
.Ek
|
|
.Ar rhost:path node
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command calls the
|
|
.Xr mount 2
|
|
system call to prepare and graft a remote
|
|
.Tn 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
|
|
.Tn NFS
|
|
Version 2 protocol.
|
|
.It Fl 3
|
|
Use the
|
|
.Tn NFS
|
|
Version 3 protocol.
|
|
The default is to try version 3 first, and
|
|
fall back to version 2 if the mount fails.
|
|
.It Fl D
|
|
Used with
|
|
.Tn NQNFS
|
|
to set the
|
|
.Dq "dead server threshold"
|
|
to the specified number of round trip timeout intervals.
|
|
After a
|
|
.Dq "dead server threshold"
|
|
of retransmit timeouts,
|
|
cached data for the unresponsive server is assumed to still be valid.
|
|
Values may be set in the range of 1 - 9, with 9 referring to an
|
|
.Dq "infinite dead threshold"
|
|
(i.e. never assume cached data still valid).
|
|
This option is not generally recommended and is really an experimental
|
|
feature.
|
|
.It Fl I
|
|
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 K
|
|
Pass
|
|
.Tn Kerberos
|
|
authenticators to the server for client-to-server user-credential mapping.
|
|
This requires that the
|
|
.Nx
|
|
kernel be built with the
|
|
.Dv NFSKERB
|
|
.Xr option 4 .
|
|
Refer to RFC 2695,
|
|
.%T "Authentication Mechanisms for ONC RPC" ,
|
|
for more information.
|
|
.It Fl L
|
|
Used with
|
|
.Tn NQNFS
|
|
to set the lease term to the specified number of seconds.
|
|
Only use this argument for mounts with a large round trip delay.
|
|
Values are normally in the 10-30 second range.
|
|
.It Fl P
|
|
Use a reserved socket port number.
|
|
This is the default, and available
|
|
for backwards compatibility purposes only.
|
|
.It Fl R
|
|
Set the retry count for doing the mount to the specified value.
|
|
.It Fl T
|
|
Use
|
|
.Tn TCP
|
|
transport instead of
|
|
.Tn UDP .
|
|
This is recommended for servers that are not on the same physical network as
|
|
the client.
|
|
Not all
|
|
.Tn NFS
|
|
servers, especially not old ones, support this.
|
|
.It Fl U
|
|
Force the mount protocol to use
|
|
.Tn UDP
|
|
transport, even for
|
|
.Tn TCP
|
|
.Tn NFS
|
|
mounts.
|
|
This is necessary for some old
|
|
.Bx
|
|
servers.
|
|
.It Fl X
|
|
Perform 32 \*[Lt]-\*[Gt] 64 bit directory cookie translation for version 3 mounts.
|
|
This may be need 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 a
|
|
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
|
|
.Tn UDP
|
|
mount points, do not do a
|
|
.Xr connect 2 .
|
|
This flag is deprecated and connectionless
|
|
.Tn UDP
|
|
mounts are the default.
|
|
.It Fl C
|
|
For
|
|
.Tn UDP
|
|
mount points, do a
|
|
.Xr connect 2 .
|
|
Although this flag increases the efficiency of
|
|
.Tn UDP
|
|
mounts it cannot
|
|
be used for servers that do not reply to requests from the
|
|
standard
|
|
.Tn 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 d
|
|
Turn off the dynamic retransmit timeout estimator.
|
|
This may be useful for
|
|
.Tn UDP
|
|
mounts that exhibit high retry rates,
|
|
since it is possible that the dynamically estimated timeout interval is too
|
|
short.
|
|
.It Fl g
|
|
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
|
|
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
|
|
Used with
|
|
.Tn NQNFS
|
|
and
|
|
.Tn NFS
|
|
Version 3 to specify that the
|
|
.Fn ReaddirPlus
|
|
.Tn RPC
|
|
should be used.
|
|
This option reduces
|
|
.Tn 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 m
|
|
Set the
|
|
.Tn Kerberos
|
|
realm to the string argument.
|
|
Used with the
|
|
.Fl K
|
|
option for mounts to other realms.
|
|
.It Fl o
|
|
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.
|
|
.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
|
|
Use the leasing extensions to the
|
|
.Tn NFS
|
|
Version 3 protocol
|
|
to maintain cache consistency.
|
|
This protocol version 2 revision to Not Quite
|
|
.Tn NFS
|
|
.Pq Tn NQNFS
|
|
is only supported by this updated release of
|
|
.Tn NFS
|
|
code.
|
|
It is not backwards compatible with the version 1
|
|
.Tn NQNFS
|
|
protocol that was part of the first release of
|
|
.Bx 4.4 Lite .
|
|
To interoperate with a first release
|
|
.Bx 4.4 Lite
|
|
.Tn NFS
|
|
system you will have to avoid this option until you have had
|
|
an opportunity to upgrade the
|
|
.Tn NFS
|
|
code to release 2 of
|
|
.Bx 4.4 Lite
|
|
on all your systems.
|
|
.It Fl r
|
|
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
|
|
.Tn 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 retrycnt
|
|
round trip timeout intervals.
|
|
.It Fl t
|
|
Set the initial retransmit timeout to the specified value.
|
|
May be useful for fine tuning
|
|
.Tn 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.
|
|
.It Fl w
|
|
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
|
|
.Tn 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
|
|
.Tn TCP
|
|
mounts.
|
|
.It Fl x
|
|
Set the retransmit timeout count for soft mounts to the specified value.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The simplest way to invoke
|
|
.Nm
|
|
is with a command like:
|
|
.Pp
|
|
.Dl "mount remotehost:/filesystem /localmountpoint
|
|
or:
|
|
.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
|
|
.Tn 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
|
|
.Tn NFS
|
|
version 2 is 8K when
|
|
using
|
|
.Tn UDP ,
|
|
64K when using
|
|
.Tn TCP .
|
|
.Pp
|
|
The default size for
|
|
.Tn NFS
|
|
version 3 is platform dependent:
|
|
on
|
|
.Nx Ns /i386 ,
|
|
the default is 32K, for other platforms it is 8K.
|
|
Values over 32K are only supported for
|
|
.Tn 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
|
|
.Tn NFS
|
|
activity.
|
|
.Pp
|
|
This can especially happen with older
|
|
.Tn 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
|
|
.Tn 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
|
|
.Tn NFS
|
|
mounts because of a slow
|
|
.Tn Ethernet
|
|
network interface
|
|
.Pq e.g. a USB 1.1 to 10/100 Tn 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 8
|
|
file to avoid having do specify the sizes for all mounts.
|
|
.It
|
|
For connections that are not on the same
|
|
.Tn LAN ,
|
|
and/or may experience packet loss, using
|
|
.Tn 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 CAVEATS
|
|
An NFS server shouldn't loopback-mount its own exported file systems because
|
|
it's fundamentally prone to deadlock.
|