path: root/usr/src/man/man1m/mount_nfs.1m

.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2017 Nexenta Systems, Inc.
.\"
.Dd March 12, 2016
.Dt MOUNT_NFS 1M
.Os
.Sh NAME
.Nm mount_nfs
.Nd mount remote NFS resources
.Sh SYNOPSIS
.Nm mount
.Op Fl F Sy nfs
.Op Ar generic_options
.Op Fl o Ar specific_options
.Ar resource
.Nm mount
.Op Fl F Sy nfs
.Op Ar generic_options
.Op Fl o Ar specific_options
.Ar mount_point
.Nm mount
.Op Fl F Sy nfs
.Op Ar generic_options
.Op Fl o Ar specific_options
.Ar resource mount_point
.Sh DESCRIPTION
The
.Nm mount
utility attaches a named
.Ar resource
to the file system hierarchy at the pathname location
.Ar mount_point ,
which must already exist.
If
.Ar mount_point
has any contents prior to the
.Nm mount
operation, the contents remain hidden until the
.Ar resource
is once again unmounted.
.Pp
.Nm
starts the
.Xr lockd 1M
and
.Xr statd 1M
daemons if they are not already running.
.Pp
If the resource is listed in the
.Pa /etc/vfstab
file, the command line can specify either
.Ar resource
or
.Ar mount_point ,
and
.Nm mount
consults
.Pa /etc/vfstab
for more information.
If the
.Fl F
option is omitted,
.Nm mount
takes the file system type from
.Pa /etc/vfstab .
.Pp
If the resource is not listed in the
.Pa /etc/vfstab
file, then the command line must specify both the
.Ar resource
and the
.Ar mount_point .
.Pp
.Ar host
can be an IPv4 or IPv6 address string.
As IPv6 addresses already contain colons, enclose
.Ar host
in a pair of square brackets when specifying an IPv6 address string.
Otherwise the first occurrence of a colon can be interpreted as the separator
between the host name and path, for example,
.Li [1080::8:800:200C:417A]:tmp/file .
See
.Xr inet 7P
and
.Xr inet6 7P .
.Bl -tag -width Ds
.It Ar host Ns \&: Ns Ar pathname
Where
.Ar host
is the name of the NFS server host, and
.Ar pathname
is the path name of the directory on the server being mounted.
The path name is interpreted according to the server's path name parsing rules
and is not necessarily slash-separated, though on most servers, this is the
case.
.It No nfs:// Ns Ar host Ns Oo : Ns Ar port Oc Ns / Ns Ar pathname
This is an NFS URL and follows the standard convention for NFS URLs as described
in
.Rs
.%R NFS URL Scheme
.%T RFC 2224
.Re
See the discussion of URLs and the public option under
.Sx NFS FILE SYSTEMS
for a more detailed discussion.
.It Xo
.Ar host Ns \&: Ns Ar pathname
.No nfs:// Ns Ar host Ns Oo : Ns Ar port Oc Ns / Ns Ar pathname
.Xc
.Ar host Ns \&: Ns Ar pathname
is a comma-separated list of
.Ar host Ns \&: Ns Ar pathname .
See the discussion of replicated file systems and failover under
.Sx NFS FILE SYSTEMS
for a more detailed discussion.
.It Ar hostlist pathname
.Ar hostlist
is a comma-separated list of hosts.
See the discussion of replicated file systems and failover under
.Sx NFS FILE SYSTEMS
for a more detailed discussion.
.El
.Pp
The
.Nm mount
command maintains a table of mounted file systems in
.Pa /etc/mnttab ,
described in
.Xr mnttab 4 .
.Pp
.Nm mount_nfs
supports both NFSv3 and NFSv4 mounts.
The default NFS version is NFSv4.
.Ss Options
See
.Xr mount 1M
for the list of supported
.Ar generic_options .
See
.Xr share_nfs 1M
for a description of server options.
.Bl -tag -width Ds
.It Fl o Ar specific_options
Set file system specific options according to a comma-separated list with no
intervening spaces.
.El
.Pp
The following list describes
.Ar specific_options :
.Bl -tag -width Ds
.It Sy acdirmax Ns = Ns Ar n
Hold cached attributes for no more than
.Ar n
seconds after directory update.
The default value is 60.
.It Sy acdirmin Ns = Ns Ar n
Hold cached attributes for at least
.Ar n
seconds after directory update.
The default value is 30.
.It Sy acregmax Ns = Ns Ar n
Hold cached attributes for no more than
.Ar n
seconds after file modification.
The default value is 60.
.It Sy acregmin Ns = Ns Ar n
Hold cached attributes for at least
.Ar n
seconds after file modification.
The default value is 3.
.It Sy actimeo Ns = Ns n
Set
.Sy min
and
.Sy max
times for regular files and directories to
.Ar n
seconds.
See
.Sx File Attributes ,
below, for a description of the effect of setting this option to 0.
.Pp
See
.Sx Specifying Values for Attribute Cache Duration Options ,
below, for a description of how
.Sy acdirmax , acdirmin , acregmax , acregmin ,
and
.Sy actimeo
are parsed on a
.Nm mount
command line.
.It Sy bg Ns | Ns Sy fg
If the first attempt fails, retry in the background, or, in the foreground.
The default is
.Sy fg .
.It Sy forcedirectio Ns | Ns Sy noforcedirectio
If
.Sy forcedirectio
is specified, then for the duration of the mount, forced direct I/O is used.
If the filesystem is mounted using
.Sy forcedirectio ,
data is transferred directly between client and server, with no buffering on the
client.
If the filesystem is mounted using
.Sy noforcedirectio ,
data is buffered on the client.
.Sy forcedirectio
is a performance option that is of benefit only in large sequential data
transfers.
The default behavior is
.Sy noforcedirectio .
.It Sy grpid
By default, the GID associated with a newly created file obeys the System V
semantics; that is, the GID is set to the effective GID of the calling process.
This behavior can be overridden on a per-directory basis by setting the set-GID
bit of the parent directory; in this case, the GID of a newly created file is
set to the GID of the parent directory
.Po see
.Xr open 2
and
.Xr mkdir 2
.Pc .
Files created on file systems that are mounted with the
.Sy grpid
option obeys BSD semantics independent of whether the set-GID bit of the parent
directory is set; that is, the GID is unconditionally inherited from that of the
parent directory.
.It Sy hard Ns | Ns Sy soft
Continue to retry requests until the server responds
.Pq Sy hard
or give up and return an error
.Pq Sy soft .
The default value is
.Sy hard .
Note that NFSv4 clients do not support soft mounts.
.It Sy intr Ns | Ns Sy nointr
Allow
.Pq do not allow
keyboard interrupts to kill a process that is hung while waiting for a response
on a hard-mounted file system.
The default is
.Sy intr ,
which makes it possible for clients to interrupt applications that can be
waiting for a remote mount.
.It Sy noac
Suppress data and attribute caching.
The data caching that is suppressed is the write-behind.
The local page cache is still maintained, but data copied into it is immediately
written to the server.
.It Sy nocto
Do not perform the normal close-to-open consistency.
When a file is closed, all modified data associated with the file is flushed to
the server and not held on the client.
When a file is opened the client sends a request to the server to validate the
client's local caches.
This behavior ensures a file's consistency across multiple NFS clients.
When
.Sy nocto
is in effect, the client does not perform the flush on close and the request for
validation, allowing the possibility of differences among copies of the same
file as stored on multiple clients.
.Pp
This option can be used where it can be guaranteed that accesses to a specified
file system are made from only one client and only that client.
Under such a condition, the effect of
.Sy nocto
can be a slight performance gain.
.It Sy port Ns = Ns Ar n
The server IP port number.
The default is
.Dv NFS_PORT .
If the
.Sy port
option is specified, and if the resource includes one or more NFS URLs, and if
any of the URLs include a port number, then the port number in the option and in
the URL must be the same.
.It Sy posix
Request POSIX.1 semantics for the file system.
Requires a mount Version 2
.Xr mountd 1M
on the server.
See
.Xr standards 5
for information regarding POSIX.
.It Sy proto Ns = Ns Ar netid Ns | Ns Sy rdma
By default, the transport protocol that the NFS mount uses is the first
available RDMA transport supported both by the client and the server.
If no RDMA transport is found, then it attempts to use a TCP transport or,
failing that, a UDP transport, as ordered in the
.Pa /etc/netconfig
file.
If it does not find a connection oriented transport, it uses the first available
connectionless transport.
Use this option to override the default behavior.
.Pp
.Sy proto
is set to the value of
.Ar netid
or
.Sy rdma .
.Ar netid
is the value of the
.Sy network_id
field entry in the
.Pa /etc/netconfig
file.
.Pp
The UDP protocol is not supported for NFS Version 4.
If you specify a UDP protocol with the
.Sy proto
option, NFS version 4 is not used.
.It Sy public
The
.Sy public
option forces the use of the public file handle when connecting to the NFS
server.
The resource specified might not have an NFS URL.
See the discussion of URLs and the public option under
.Sx NFS FILE SYSTEMS
for a more detailed discussion.
.It Sy quota Ns | Ns Sy noquota
Enable or prevent
.Xr quota 1M
to check whether the user is over quota on this file system; if the file system
has quotas enabled on the server, quotas are still checked for operations on
this file system.
.It Sy remount
Remounts a read-only file system as read-write
.Po using the
.Sy rw
option
.Pc .
This option cannot be used with other
.Fl o
options, and this option works only on currently mounted read-only file systems.
.It Sy retrans Ns = Ns Ar n
Set the number of NFS retransmissions to
.Ar n .
The default value is 5.
For connection-oriented transports, this option has no effect because it is
assumed that the transport performs retransmissions on behalf of NFS.
.It Sy retry Ns = Ns Ar n
The number of times to retry the
.Nm mount
operation.
The default for the
.Nm mount
command is 10000.
.Pp
The default for the automounter is 0, in other words, do not retry.
You might find it useful to increase this value on heavily loaded servers, where
automounter traffic is dropped, causing unnecessary
.Qq server not responding
errors.
.It Sy rsize Ns = Ns Ar n
Set the read buffer size to a maximum of
.Ar n
bytes.
The default value is 1048576 when using connection-oriented transports with
Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less
transports.
The default can be negotiated down if the server prefers a smaller transfer
size.
.Qq Read
operations may not necessarily use the maximum buffer size.
When using Version 2, the default value is 32768 for all transports.
.It Sy sec Ns = Ns Ar mode
Set the security
.Ar mode
for NFS transactions.
If
.Sy sec Ns =
is not specified, then the default action is to use AUTH_SYS over NFS Version 2
mounts, use a user-configured default
.Sy auth
over NFS version 3 mounts, or to  negotiate a mode over Version 4 mounts.
.Pp
The preferred mode for NFS Version 3 mounts is the default mode specified in
.Pa /etc/nfssec.conf
.Po see
.Xr nfssec.conf 4
.Pc
on the client.
If there is no default configured in this file or if the server does not export
using the client's default mode, then the client picks the first mode that it
supports in the array of modes returned by the server.
These alternatives are limited to the security flavors listed in
.Pa /etc/nfssec.conf .
.Pp
NFS Version 4 mounts negotiate a security mode when the server returns an array
of security modes.
The client attempts the mount with each security mode, in order, until one is
successful.
.Pp
Only one mode can be specified with the
.Sy sec Ns =
option.
See
.Xr nfssec 5
for the available
.Ar mode
options.
.It Sy secure
This option has been deprecated in favor of the
.Sy sec Ns = Ns Sy dh
option.
.It Sy timeo Ns = Ns Ar n
Set the NFS timeout to
.Ar n
tenths of a second.
The default value is 11 tenths of a second for connectionless transports, and
600 tenths of a second for connection-oriented transports.
This value is ignored for connectionless transports.
Such transports might implement their own timeouts, which are outside the
control of NFS.
.It Sy vers Ns = Ns Ar "NFS version number"
By default, the version of NFS protocol used between the client and the server
is the highest one available on both systems.
If the NFS server does not support the client's default maximum, the next lowest
version attempted until a matching version is found.
See
.Xr nfs 4
for more information on setting default minimum and maximum client versions.
.It Sy wsize Ns = Ns Ar n
Set the write buffer size to a maximum of
.Ar n
bytes.
The default value is 1048576 when using connection-oriented transports with
Version 3 or Version 4 of the NFS protocol, and 32768 when using connection-less
transports.
The default can be negotiated down if the server prefers a smaller transfer
size.
.Qq Write
operations may not necessarily use the maximum buffer size.
When using Version 2, the default value is 32768 for all transports.
.It Sy xattr Ns | Ns Sy noxattr
Allow or disallow the creation and manipulation of extended attributes.
The default is
.Sy xattr .
See
.Xr fsattr 5
for a description of extended attributes.
.El
.Sh NFS FILE SYSTEMS
.Ss Background versus Foreground
File systems mounted with the
.Sy bg
option indicate that
.Nm mount
is to retry in the background if the server's mount daemon
.Pq Xr mountd 1M
does not respond.
.Nm mount
retries the request up to the count specified in the
.Sy retry Ns = Ns Ar n
option
.Po note that the default value for
.Sy retry
differs between
.Nm mount
and
.Nm automount ;
see the description of
.Sy retry ,
above
.Pc .
Once the file system is mounted, each NFS request made in the kernel waits
.Sy timeo Ns = Ns Ar n
tenths of a second for a response.
If no response arrives, the time-out is multiplied by 2 and the request is
retransmitted.
When the number of retransmissions has reached the number specified in the
.Sy retrans Ns = Ns Ar n
option, a file system mounted with the
.Sy soft
option returns an error on the request; one mounted with the
.Sy hard
option prints a warning message and continues to retry the request.
.Ss Hard versus Soft
File systems that are mounted read-write or that contain executable files should
always be mounted with the
.Sy hard
option.
Applications using
.Sy soft
mounted file systems can incur unexpected I/O errors, file corruption, and
unexpected program core dumps.
The
.Sy soft
option is not recommended.
.Ss Authenticated requests
The server can require authenticated NFS requests from the client.
.Sy sec Ns = Ns Sy dh
authentication might be required.
See
.Xr nfssec 5 .
.Ss URLs and the public option
If the
.Sy public
option is specified, or if the
.Ar resource
includes and NFS URL,
.Nm mount
attempts to connect to the server using the public file handle lookup protocol.
See
.Rs
.%R WebNFS Client Specification
.%T RFC 2054
.Re
If the server supports the public file handle, the attempt is successful;
.Nm mount
does not need to contact the server's
.Xr rpcbind 1M
and the
.Xr mountd 1M
daemons to get the port number of the
.Nm mount
server and the initial file handle of
.Ar pathname ,
respectively.
If the NFS client and server are separated by a firewall that allows all
outbound connections through specific ports, such as
.Dv NFS_PORT ,
then this enables NFS operations through the firewall.
The public option and the NFS URL can be specified independently or together.
They interact as specified in the following matrix:
.Bd -literal
                   Resource Style

                   host:pathname              NFS URL

public option      Force public file          Force public file
                   handle and fail            handle and fail
                   mount if not supported.    mount if not supported.

                   Use Native paths.          Use Canonical paths.

default            Use MOUNT protocol.        Try public file handle
                                              with Canonical paths.
                                              Fall back to MOUNT
                                              protocol if not
                                              supported.
.Ed
.Pp
A Native path is a path name that is interpreted according to conventions used
on the native operating system of the NFS server.
A Canonical path is a path name that is interpreted according to the URL rules.
See
.Rs
.%R Uniform Resource Locators (URL)
.%T RFC 1738
.Re
.Ss Replicated file systems and failover
.Ar resource
can list multiple read-only file systems to be used to provide data.
These file systems should contain equivalent directory structures and identical
files.
It is also recommended that they be created by a utility such as
.Xr rdist 1 .
The file systems can be specified either with a comma-separated list of
.Pa host:/pathname
entries and/or NFS URL entries, or with a comma-separated list of hosts, if all
file system names are the same.
If multiple file systems are named and the first server in the list is down,
failover uses the next alternate server to access files.
If the read-only option is not chosen, replication is disabled.
File access, for NFS Versions 2 and 3, is blocked on the original if NFS locks
are active for that file.
.Ss File Attributes
To improve NFS read performance, files and file attributes are cached.
File modification times get updated whenever a write occurs.
However, file access times can be temporarily out-of-date until the cache gets
refreshed.
.Pp
The attribute cache retains file attributes on the client.
Attributes for a file are assigned a time to be flushed.
If the file is modified before the flush time, then the flush time is extended
by the time since the last modification
.Po under the assumption that files that changed recently are likely to change
soon
.Pc .
There is a minimum and maximum flush time extension for regular files and for
directories.
Setting
.Sy actimeo Ns = Ns Ar n
sets flush time to
.Ar n
seconds for both regular files and directories.
.Pp
Setting
.Sy actimeo Ns = Ns Sy 0
disables attribute caching on the client.
This means that every reference to attributes is satisfied directly from the
server though file data is still cached.
While this guarantees that the client always has the latest file attributes from
the server, it has an adverse effect on performance through additional latency,
network load, and server load.
.Pp
Setting the
.Sy noac
option also disables attribute caching, but has the further effect of disabling
client write caching.
While this guarantees that data written by an application is written directly to
a server, where it can be viewed immediately by other clients, it has a
significant adverse effect on client write performance.
Data written into memory-mapped file pages
.Pq Xr mmap 2
are not written directly to this server.
.Ss Specifying Values for Attribute Cache Duration Options
The attribute cache duration options are
.Sy acdirmax , acdirmin , acregmax , acregmin ,
and
.Sy actimeo ,
as described under
.Sx Options.
A value specified for
.Sy actimeo
sets the values of all attribute cache duration options except for any of these
options specified following
.Sy actimeo
on a
.Nm mount
command line.
For example, consider the following command:
.Bd -literal -offset indent
example# mount -o acdirmax=10,actimeo=1000 server:/path /localpath
.Ed
.Pp
Because
.Sy actimeo
is the last duration option in the command line, its value
.Pq 1000
becomes the setting for all of the duration options, including
.Sy acdirmax .
Now consider:
.Bd -literal -offset indent
example# mount -o actimeo=1000,acdirmax=10 server:/path /localpath
.Ed
.Pp
Because the
.Sy acdirmax
option follows
.Sy actimeo
on the command line, it is assigned the value specified
.Pq 10 .
The remaining duration options are set to the value of
.Sy actimeo
.Pq 1000 .
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/mnttab
table of mounted file systems
.It Pa /etc/dfs/fstypes
default distributed file system type
.It Pa /etc/vfstab
table of automatically mounted resources
.El
.Sh EXAMPLES
.Bl -tag -width Ds
.It Sy Example 1 No Mounting an NFS File System
To mount an NFS file system:
.Bd -literal
example# mount serv:/usr/src /usr/src
.Ed
.It Xo
.Sy Example 2
Mounting An NFS File System Read-Only With No suid Privileges
.Xc
To mount an NFS file system read-only with no suid privileges:
.Bd -literal
example# mount -r -o nosuid serv:/usr/src /usr/src
.Ed
.It Xo
.Sy Example 3
Mounting An NFS File System Over Version 2, with the UDP Transport
.Xc
To mount an NFS file system over Version 2, with the UDP transport:
.Bd -literal
example# mount -o vers=2,proto=udp serv:/usr/src /usr/src
.Ed
.It Xo
.Sy Example 4
Mounting an NFS File System Using An NFS URL
.Xc
To mount an NFS file system using an NFS URL
.Pq a canonical path :
.Bd -literal
example# mount nfs://serv/usr/man /usr/man
.Ed
.It Xo
.Sy Example 5
Mounting An NFS File System Forcing Use Of The Public File Handle
.Xc
To mount an NFS file system and force the use of the public file handle
and an NFS URL
.Pq a canonical path
that has a non 7-bit ASCII escape sequence:
.Bd -literal
example# mount -o public nfs://serv/usr/%A0abc /mnt/test
.Ed
.It Xo
.Sy Example 6
Mounting an NFS File System Using a Native Path
.Xc
To mount an NFS file system using a native path
.Po where the server uses colons
.Pq Qq Sy \:
as the component separator
.Pc
and the public file handle:
.Bd -literal
example# mount -o public serv:C:doc:new /usr/doc
.Ed
.It Xo
.Sy Example 7
Mounting a Replicated Set of NFS File Systems with the Same Pathnames
.Xc
To mount a replicated set of NFS file systems with the same pathnames:
.Bd -literal
example# mount serv-a,serv-b,serv-c:/usr/man /usr/man
.Ed
.It Xo
.Sy Example 8
Mounting a Replicated Set of NFS File Systems with Different Pathnames
.Xc
To mount a replicated set of NFS file systems with different pathnames:
.Bd -literal
example# mount serv-x:/usr/man,serv-y:/var/man,nfs://serv-z/man /usr/man
.Ed
.El
.Sh SEE ALSO
.Xr rdist 1 ,
.Xr lockd 1M ,
.Xr mountall 1M ,
.Xr mountd 1M ,
.Xr nfsd 1M ,
.Xr quota 1M ,
.Xr statd 1M ,
.Xr mkdir 2 ,
.Xr mmap 2 ,
.Xr mount 2 ,
.Xr open 2 ,
.Xr umount 2 ,
.Xr mnttab 4 ,
.Xr nfs 4 ,
.Xr nfssec.conf 4 ,
.Xr attributes 5 ,
.Xr fsattr 5 ,
.Xr nfssec 5 ,
.Xr standards 5 ,
.Xr lofs 7FS ,
.Xr inet 7P ,
.Xr inet6 7P
.Rs
.%A Callaghan
.%A Brent
.%R WebNFS Client Specification
.%T RFC 2054
.%D October 1996
.Re
.Rs
.%A Callaghan
.%A Brent
.%R NFS URL Scheme
.%T RFC 2224
.%D October 1997
.Re
.Rs
.%A Berners-Lee
.%A Masinter
.%A McCahill
.%R Uniform Resource Locators (URL)
.%T RFC 1738
.%D December 1994
.Re
.Sh NOTES
An NFS server should not attempt to mount its own file systems.
See
.Xr lofs 7FS .
.Pp
If the directory on which a file system is to be mounted is a symbolic link,
the file system is mounted on the directory to which the symbolic link refers,
rather than being mounted on top of the symbolic link itself.
.Pp
SunOS 4.x used the
.Sy biod
maintenance procedure to perform parallel read-ahead and write-behind on NFS
clients.
SunOS 5.x made
.Sy biod
obsolete with multi-threaded processing, which transparently performs parallel
read-ahead and write-behind.
.Pp
Since the root
.Pq Pa /
file system is mounted read-only by the kernel during the boot process, only the
.Sy remount
option
.Po and options that can be used in conjunction with
.Sy remount
.Pc
affect the root
.Pq Pa /
entry in the
.Pa /etc/vfstab
file.
.Pp
The NFS client service is managed by the service management facility,
.Xr smf 5 ,
under the service identifier:
.Bd -literal -offset indent
svc:/network/nfs/client:default
.Ed
.Pp
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using
.Xr svcadm 1M .
The service's status can be queried using the
.Xr svcs 1
command.