-.TH EXPORTS 5 "4 March 2005" "Linux" "Linux File Formats Manual"
+.\"@(#)exports.5"
+.\"
+.TH exports 5 "31 December 2009"
.SH NAME
-exports \- NFS file systems being exported (for Kernel based NFS)
-.SH SYNOPSIS
-.B /etc/exports
+exports \- NFS server export table
.SH DESCRIPTION
The file
.I /etc/exports
-serves as the access control list for file systems which may be
-exported to NFS clients. It is used by
-.IR exportfs (8)
+contains a table of local physical file systems on an NFS server
+that are accessible to NFS clients.
+The contents of the file are maintained by the server's system
+administrator.
+.PP
+Each file system in this table has a list of options and an
+access control list.
+The table is used by
+.BR exportfs (8)
to give information to
-.IR mountd (8)
-and to the kernel based NFS file server daemon
-.IR nfsd (8).
+.BR mountd (8).
.PP
The file format is similar to the SunOS
.I exports
list of export options for that client. No whitespace is permitted
between a client and its option list.
.PP
+Also, each line may have one or more specifications for default options
+after the path name, in the form of a dash ("\-") followed by an option
+list. The option list is used for all subsequent exports on that line
+only.
+.PP
Blank lines are ignored. A pound sign ("#") introduces a comment to the
end of the line. Entries may be continued across newlines using a
backslash. If an export name contains spaces it should be quoted using
the export name using a backslash followed by the character code as three
octal digits.
.PP
+To apply changes to this file, run
+.BR exportfs \-ra
+or restart the NFS server.
+.PP
.SS Machine Name Formats
NFS clients may be specified in a number of ways:
.IP "single host
-This is the most common format. You may specify a host either by an
+You may specify a host either by an
abbreviated name recognized be the resolver, the fully qualified domain
-name, or an IP address.
-.IP "netgroups
-NIS netgroups may be given as
-.IR @group .
-Only the host part of each
-netgroup members is consider in checking for membership. Empty host
-parts or those containing a single dash (\-) are ignored.
-.IP "wildcards
-Machine names may contain the wildcard characters \fI*\fR and \fI?\fR.
-This can be used to make the \fIexports\fR file more compact; for instance,
-\fI*.cs.foo.edu\fR matches all hosts in the domain
-\fIcs.foo.edu\fR. As these characters also match the dots in a domain
-name, the given pattern will also match all hosts within any subdomain
-of \fIcs.foo.edu\fR.
+name, an IPv4 address, or an IPv6 address. IPv6 addresses must not be
+inside square brackets in /etc/exports lest they be confused with
+character-class wildcard matches.
.IP "IP networks
You can also export directories to all hosts on an IP (sub-) network
simultaneously. This is done by specifying an IP address and netmask pair
as
.IR address/netmask
where the netmask can be specified in dotted-decimal format, or as a
-contiguous mask length (for example, either `/255.255.252.0' or `/22' appended
-to the network base address result in identical subnetworks with 10 bits of
-host). Wildcard characters generally do not work on IP addresses, though they
+contiguous mask length.
+For example, either `/255.255.252.0' or `/22' appended
+to the network base IPv4 address results in identical subnetworks with 10 bits
+of host. IPv6 addresses must use a contiguous mask length and must not be inside square brackets to avoid confusion with character-class wildcards. Wildcard characters generally do not work on IP addresses, though they
may work by accident when reverse DNS lookups fail.
-'''.TP
-'''.B =public
-'''This is a special ``hostname'' that identifies the given directory name
-'''as the public root directory (see the section on WebNFS in
-'''.BR nfsd (8)
-'''for a discussion of WebNFS and the public root handle). When using this
-'''convention,
-'''.B =public
-'''must be the only entry on this line, and must have no export options
-'''associated with it. Note that this does
-'''.I not
-'''actually export the named directory; you still have to set the exports
-'''options in a separate entry.
-'''.PP
-'''The public root path can also be specified by invoking
-'''.I nfsd
-'''with the
-'''.B \-\-public\-root
-'''option. Multiple specifications of a public root will be ignored.
+.IP "wildcards
+Machine names may contain the wildcard characters \fI*\fR and \fI?\fR, or may contain character class lists within [square brackets].
+This can be used to make the \fIexports\fR file more compact; for instance,
+\fI*.cs.foo.edu\fR matches all hosts in the domain
+\fIcs.foo.edu\fR. As these characters also match the dots in a domain
+name, the given pattern will also match all hosts within any subdomain
+of \fIcs.foo.edu\fR.
+.IP "netgroups
+NIS netgroups may be given as
+.IR @group .
+Only the host part of each
+netgroup members is consider in checking for membership. Empty host
+parts or those containing a single dash (\-) are ignored.
+.IP "anonymous
+This is specified by a single
+.I *
+character (not to be confused with the
+.I wildcard
+entry above) and will match all clients.
+.\".TP
+.\".B =public
+.\"This is a special ``hostname'' that identifies the given directory name
+.\"as the public root directory (see the section on WebNFS in
+.\".BR nfsd (8)
+.\"for a discussion of WebNFS and the public root handle). When using this
+.\"convention,
+.\".B =public
+.\"must be the only entry on this line, and must have no export options
+.\"associated with it. Note that this does
+.\".I not
+.\"actually export the named directory; you still have to set the exports
+.\"options in a separate entry.
+.\".PP
+.\"The public root path can also be specified by invoking
+.\".I nfsd
+.\"with the
+.\".B \-\-public\-root
+.\"option. Multiple specifications of a public root will be ignored.
.PP
+If a client matches more than one of the specifications above, then
+the first match from the above list order takes precedence - regardless of
+the order they appear on the export line. However, if a client matches
+more than one of the same type of specification (e.g. two netgroups),
+then the first match from the order they appear on the export line takes
+precedence.
.SS RPCSEC_GSS security
-To restrict access to an export using rpcsec_gss security, use the special
-string "gss/krb5" as the client. It is not possible to simultaneously require
-rpcsec_gss and to make requirements on the IP address of the client.
+You may use the special strings "gss/krb5", "gss/krb5i", or "gss/krb5p"
+to restrict access to clients using rpcsec_gss security. However, this
+syntax is deprecated; on linux kernels since 2.6.23, you should instead
+use the "sec=" export option:
+.TP
+.IR sec=
+The sec= option, followed by a colon-delimited list of security flavors,
+restricts the export to clients using those flavors. Available security
+flavors include sys (the default--no cryptographic security), krb5
+(authentication only), krb5i (integrity protection), and krb5p (privacy
+protection). For the purposes of security flavor negotiation, order
+counts: preferred flavors should be listed first. The order of the sec=
+option with respect to the other options does not matter, unless you
+want some options to be enforced differently depending on flavor.
+In that case you may include multiple sec= options, and following options
+will be enforced only for access using flavors listed in the immediately
+preceding sec= option. The only options that are permitted to vary in
+this way are ro, rw, no_root_squash, root_squash, and all_squash.
.PP
.SS General Options
-.IR exportfs
+.BR exportfs
understands the following export options:
.TP
-.IR secure "\*d
-This option requires that requests originate on an internet port less
+.IR secure
+This option requires that requests originate on an Internet port less
than IPPORT_RESERVED (1024). This option is on by default. To turn it
off, specify
.IR insecure .
an unclean server restart (i.e. a crash) can cause data to be lost or
corrupted.
-In releases of nfs-utils upto and including 1.0.0, this option was the
-default. In this and future releases,
+.TP
+.IR sync
+Reply to requests only after the changes have been committed to stable
+storage (see
+.IR async
+above).
+
+In releases of nfs-utils up to and including 1.0.0, the
+.I async
+option was the
+default. In all releases after 1.0.0,
.I sync
is the default, and
.I async
-must be explicit requested if needed.
-To help make system adminstrators aware of this change, 'exportfs'
+must be explicitly requested if needed.
+To help make system administrators aware of this change,
+.B exportfs
will issue a warning if neither
.I sync
nor
option is currently only effective on
.I "single host
exports. It does not work reliably with netgroup, subnet, or wildcard
-exports.
+exports.
This option can be very useful in some situations, but it should be
used with due care, and only after confirming that the client system
requested with
.IR subtree_check .
+From release 1.1.0 of nfs-utils onwards, the default will be
+.I no_subtree_check
+as subtree_checking tends to cause more problems than it is worth.
+If you genuinely require subtree checking, you should explicitly put
+that option in the
+.B exports
+file. If you put neither option,
+.B exportfs
+will warn you that the change is pending.
+
.TP
.IR insecure_locks
.TP
.IR auth_nlm ,
or
.IR secure_locks .
-.TP
-.IR no_acl
-On some specially patched kernels, and when exporting filesystems that
-support ACLs, this option tells nfsd not to reveal ACLs to clients, so
-they will see only a subset of actual permissions on the given file
-system. This option is safe for filesystems used by NFSv2 clients and
-old NFSv3 clients that perform access decisions locally. Current
-NFSv3 clients use the ACCESS RPC to perform all access decisions on
-the server. Note that the
-.I no_acl
-option only has effect on kernels specially patched to support it, and
-when exporting filesystems with ACL support. The default is to export
-with ACL support (i.e. by default,
-.I no_acl
-is off).
-
-'''.TP
-'''.I noaccess
-'''This makes everything below the directory inaccessible for the named
-'''client. This is useful when you want to export a directory hierarchy to
-'''a client, but exclude certain subdirectories. The client's view of a
-'''directory flagged with noaccess is very limited; it is allowed to read
-'''its attributes, and lookup `.' and `..'. These are also the only entries
-'''returned by a readdir.
-'''.TP
-'''.IR link_relative
-'''Convert absolute symbolic links (where the link contents start with a
-'''slash) into relative links by prepending the necessary number of ../'s
-'''to get from the directory containing the link to the root on the
-'''server. This has subtle, perhaps questionable, semantics when the file
-'''hierarchy is not mounted at its root.
-'''.TP
-'''.IR link_absolute
-'''Leave all symbolic link as they are. This is the default operation.
+.\".TP
+.\".I noaccess
+.\"This makes everything below the directory inaccessible for the named
+.\"client. This is useful when you want to export a directory hierarchy to
+.\"a client, but exclude certain subdirectories. The client's view of a
+.\"directory flagged with noaccess is very limited; it is allowed to read
+.\"its attributes, and lookup `.' and `..'. These are also the only entries
+.\"returned by a readdir.
+.\".TP
+.\".IR link_relative
+.\"Convert absolute symbolic links (where the link contents start with a
+.\"slash) into relative links by prepending the necessary number of ../'s
+.\"to get from the directory containing the link to the root on the
+.\"server. This has subtle, perhaps questionable, semantics when the file
+.\"hierarchy is not mounted at its root.
+.\".TP
+.\".IR link_absolute
+.\"Leave all symbolic link as they are. This is the default operation.
.TP
.IR mountpoint= path
If a path is given (e.g.
.IR mountpoint= "/path or " mp= /path)
-then the nominted path must be a mountpoint for the exportpoint to be
+then the nominated path must be a mountpoint for the exportpoint to be
exported.
.TP
-.IR fsid= num
-This option forces the filesystem identification portion of the file
-handle and file attributes used on the wire to be
-.I num
-instead of a number derived from the major and minor number of the
-block device on which the filesystem is mounted. Any 32 bit number
-can be used, but it must be unique amongst all the exported filesystems.
+.IR fsid= num|root|uuid
+NFS needs to be able to identify each filesystem that it exports.
+Normally it will use a UUID for the filesystem (if the filesystem has
+such a thing) or the device number of the device holding the
+filesystem (if the filesystem is stored on the device).
+
+As not all filesystems are stored on devices, and not all filesystems
+have UUIDs, it is sometimes necessary to explicitly tell NFS how to
+identify a filesystem. This is done with the
+.I fsid=
+option.
-This can be useful for NFS failover, to ensure that both servers of
-the failover pair use the same NFS file handles for the shared filesystem
-thus avoiding stale file handles after failover.
+For NFSv4, there is a distinguished filesystem which is the root of
+all exported filesystem. This is specified with
+.I fsid=root
+or
+.I fsid=0
+both of which mean exactly the same thing.
-Some Linux filesystems are not mounted on a block device; exporting
-these via NFS requires the use of the
-.I fsid
-option (although that may still not be enough).
+Other filesystems can be identified with a small integer, or a UUID
+which should contain 32 hex digits and arbitrary punctuation.
-The value 0 has a special meaning when use with NFSv4. NFSv4 has a
-concept of a root of the overall exported filesystem. The export point
-exported with fsid=0 will be used as this root.
+Linux kernels version 2.6.20 and earlier do not understand the UUID
+setting so a small integer must be used if an fsid option needs to be
+set for such kernels. Setting both a small number and a UUID is
+supported so the same configuration can be made to work on old and new
+kernels alike.
+
+.TP
+.IR refer= path@host[+host][:path@host[+host]]
+A client referencing the export point will be directed to choose from
+the given list an alternative location for the filesystem.
+(Note that the server must have a mountpoint here, though a different
+filesystem is not required; so, for example,
+.IR "mount --bind" " /path /path"
+is sufficient.)
+.TP
+.IR replicas= path@host[+host][:path@host[+host]]
+If the client asks for alternative locations for the export point, it
+will be given this list of alternatives. (Note that actual replication
+of the filesystem must be handled elsewhere.)
.SS User ID Mapping
.PP
-.I nfsd
+.B nfsd
bases its access control to files on the server machine on the uid and
gid provided in each NFS RPC request. The normal behavior a user would
expect is that she can access her files on the server just as she would
.IR no_root_squash .
.PP
By default,
-'''.I nfsd
-'''tries to obtain the anonymous uid and gid by looking up user
-'''.I nobody
-'''in the password file at startup time. If it isn't found, a uid and gid
-.I exportfs
+.\".B nfsd
+.\"tries to obtain the anonymous uid and gid by looking up user
+.\".I nobody
+.\"in the password file at startup time. If it isn't found, a uid and gid
+.B exportfs
chooses a uid and gid
-of -2 (i.e. 65534) for squashed access. These values can also be overridden by
+of 65534 for squashed access. These values can also be overridden by
the
.IR anonuid " and " anongid
options.
-'''.PP
-'''In addition to this,
-'''.I nfsd
-'''lets you specify arbitrary uids and gids that should be mapped to user
-'''nobody as well.
+.\".PP
+.\"In addition to this,
+.\".B nfsd
+.\"lets you specify arbitrary uids and gids that should be mapped to user
+.\"nobody as well.
Finally, you can map all user requests to the
anonymous uid by specifying the
.IR all_squash " option.
-'''.PP
-'''For the benefit of installations where uids differ between different
-'''machines,
-'''.I nfsd
-'''provides several mechanism to dynamically map server uids to client
-'''uids and vice versa: static mapping files, NIS-based mapping, and
-'''.IR ugidd -based
-'''mapping.
-'''.PP
-'''.IR ugidd -based
-'''mapping is enabled with the
-'''.I map_daemon
-'''option, and uses the UGID RPC protocol. For this to work, you have to run
-'''the
-'''.IR ugidd (8)
-'''mapping daemon on the client host. It is the least secure of the three methods,
-'''because by running
-'''.IR ugidd ,
-'''everybody can query the client host for a list of valid user names. You
-'''can protect yourself by restricting access to
-'''.I ugidd
-'''to valid hosts only. This can be done by entering the list of valid
-'''hosts into the
-'''.I hosts.allow
-'''or
-'''.I hosts.deny
-'''file. The service name is
-'''.IR ugidd .
-'''For a description of the file's syntax, please read
-'''.IR hosts_access (5).
-'''.PP
-'''Static mapping is enabled by using the
-'''.I map_static
-'''option, which takes a file name as an argument that describes the mapping.
-'''NIS-based mapping queries the client's NIS server to obtain a mapping from
-'''user and group names on the server host to user and group names on the
-'''client.
.PP
Here's the complete list of mapping options:
.TP
.IR root_squash
Map requests from uid/gid 0 to the anonymous uid/gid. Note that this does
-not apply to any other uids that might be equally sensitive, such as user
-.IR bin .
+not apply to any other uids or gids that might be equally sensitive, such as
+user
+.IR bin
+or group
+.IR staff .
.TP
.IR no_root_squash
Turn off root squashing. This option is mainly useful for diskless clients.
-'''.TP
-'''.IR squash_uids " and " squash_gids
-'''This option specifies a list of uids or gids that should be subject to
-'''anonymous mapping. A valid list of ids looks like this:
-'''.IP
-'''.IR squash_uids=0-15,20,25-50
-'''.IP
-'''Usually, your squash lists will look a lot simpler.
.TP
.IR all_squash
Map all uids and gids to the anonymous user. Useful for NFS-exported
public FTP directories, news spool directories, etc. The opposite option
-is
+is
.IR no_all_squash ,
which is the default setting.
-'''.TP
-'''.IR map_daemon
-'''This option turns on dynamic uid/gid mapping. Each uid in an NFS request
-'''will be translated to the equivalent server uid, and each uid in an
-'''NFS reply will be mapped the other way round. This option requires that
-'''.IR rpc.ugidd (8)
-'''runs on the client host. The default setting is
-'''.IR map_identity ,
-'''which leaves all uids untouched. The normal squash options apply regardless
-'''of whether dynamic mapping is requested or not.
-'''.TP
-'''.IR map_static
-'''This option enables static mapping. It specifies the name of the file
-'''that describes the uid/gid mapping, e.g.
-'''.IP
-'''.IR map_static=/etc/nfs/foobar.map
-'''.IP
-'''The file's format looks like this
-'''.IP
-'''.nf
-'''.ta +3i
-'''# Mapping for client foobar:
-'''# remote local
-'''uid 0-99 - # squash these
-'''uid 100-500 1000 # map 100-500 to 1000-1400
-'''gid 0-49 - # squash these
-'''gid 50-100 700 # map 50-100 to 700-750
-'''.fi
-'''.TP
-'''.IR map_nis
-'''This option enables NIS-based uid/gid mapping. For instance, when
-'''the server encounters the uid 123 on the server, it will obtain the
-'''login name associated with it, and contact the NFS client's NIS server
-'''to obtain the uid the client associates with the name.
-'''.IP
-'''In order to do this, the NFS server must know the client's NIS domain.
-'''This is specified as an argument to the
-'''.I map_nis
-'''options, e.g.
-'''.IP
-'''.I map_nis=foo.com
-'''.IP
-'''Note that it may not be sufficient to simply specify the NIS domain
-'''here; you may have to take additional actions before
-'''.I nfsd
-'''is actually able to contact the server. If your distribution uses
-'''the NYS library, you can specify one or more NIS servers for the
-'''client's domain in
-'''.IR /etc/yp.conf .
-'''If you are using a different NIS library, you may have to obtain a
-'''special
-'''.IR ypbind (8)
-'''daemon that can be configured via
-'''.IR yp.conf .
.TP
.IR anonuid " and " anongid
These options explicitly set the uid and gid of the anonymous account.
.B /home/joe
in the example section below, which maps all requests to uid 150 (which
is supposedly that of user joe).
+.SS Extra Export Tables
+After reading
+.I /etc/exports
+.B exportfs
+reads files under
+.I /etc/exports.d.
+directory as extra export tables.
+.B exportfs
+regards only a file which name is ended with
+.I .exports
+and
+not started with
+.I .
+as an extra export file. A file which name
+is not met this condition is just ignored.
+The format for extra export tables is the same as
+.I /etc/exports
+.
.IP
.SH EXAMPLE
.PP
/projects proj*.local.domain(rw)
/usr *.local.domain(ro) @trusted(rw)
/home/joe pc001(rw,all_squash,anonuid=150,anongid=100)
-/pub (ro,insecure,all_squash)
-'''/pub/private (noaccess)
+/pub *(ro,insecure,all_squash)
+/srv/www \-sync,rw server @trusted @external(ro)
+/foo 2001:db8:9:e54::/64(rw) 192.0.2.0/24(rw)
+/build buildhost[0-9].local.domain(rw)
+.\"/pub/private (noaccess)
.fi
.PP
The first line exports the entire filesystem to machines master and trusty.
entry for the PC/NFS client discussed above. Line 5 exports the
public FTP directory to every host in the world, executing all requests
under the nobody account. The
-.I insecure
+.I insecure
option in this entry also allows clients with NFS implementations that
don't use a reserved port for NFS.
-''' The last line denies all NFS clients
-'''access to the private directory.
-'''.SH CAVEATS
-'''Unlike other NFS server implementations, this
-'''.I nfsd
-'''allows you to export both a directory and a subdirectory thereof to
-'''the same host, for instance
-'''.IR /usr " and " /usr/X11R6 .
-'''In this case, the mount options of the most specific entry apply. For
-'''instance, when a user on the client host accesses a file in
-'''.IR /usr/X11R6 ,
-'''the mount options given in the
-'''.I /usr/X11R6
-'''entry apply. This is also true when the latter is a wildcard or netgroup
-'''entry.
+The sixth line exports a directory read-write to the machine 'server'
+as well as the `@trusted' netgroup, and read-only to netgroup `@external',
+all three mounts with the `sync' option enabled. The seventh line exports
+a directory to both an IPv6 and an IPv4 subnet. The eighth line demonstrates
+a character class wildcard match.
+.\" The last line denies all NFS clients
+.\"access to the private directory.
+.\".SH CAVEATS
+.\"Unlike other NFS server implementations, this
+.\".B nfsd
+.\"allows you to export both a directory and a subdirectory thereof to
+.\"the same host, for instance
+.\".IR /usr " and " /usr/X11R6 .
+.\"In this case, the mount options of the most specific entry apply. For
+.\"instance, when a user on the client host accesses a file in
+.\".IR /usr/X11R6 ,
+.\"the mount options given in the
+.\".I /usr/X11R6
+.\"entry apply. This is also true when the latter is a wildcard or netgroup
+.\"entry.
.SH FILES
/etc/exports
+/etc/exports.d
.SH SEE ALSO
.BR exportfs (8),
.BR netgroup (5),
.BR mountd (8),
.BR nfsd (8),
.BR showmount (8).
-'''.SH DIAGNOSTICS
-'''An error parsing the file is reported using syslogd(8) as level NOTICE from
-'''a DAEMON whenever nfsd(8) or mountd(8) is started up. Any unknown
-'''host is reported at that time, but often not all hosts are not yet known
-'''to named(8) at boot time, thus as hosts are found they are reported
-'''with the same syslogd(8) parameters.
+.\".SH DIAGNOSTICS
+.\"An error parsing the file is reported using syslogd(8) as level NOTICE from
+.\"a DAEMON whenever
+.\".BR nfsd (8)
+.\"or
+.\".BR mountd (8)
+.\"is started up. Any unknown
+.\"host is reported at that time, but often not all hosts are not yet known
+.\"to
+.\".BR named (8)
+.\"at boot time, thus as hosts are found they are reported
+.\"with the same
+.\".BR syslogd (8)
+.\"parameters.