exports: Clearly Defining Exports Priorities

[nfs-utils.git] / utils / exportfs / exports.man

diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
index 73817d7bf596007f5f18980cf72419e8db8d258e..241b3afadd2964b09b93a38d0d05407e830ddc15 100644 (file)
--- a/utils/exportfs/exports.man
+++ b/utils/exportfs/exports.man
@@ -1,18 +1,22 @@
-.TH EXPORTS 5 "4 March 2005" "Linux" "Linux File Formats Manual"
+.\"@(#)exports.5"
+.\"
+.TH exports 5 "31 December 2009"

 .SH NAME
 .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
 .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
 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
 .PP
 The file format is similar to the SunOS
 .I exports


@@ -34,35 +38,46 @@ double quotes. You can also specify spaces or other unusual character in
 the export name using a backslash followed by the character code as three
 octal digits.
 .PP
 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
 abbreviated name recognized be the resolver, the fully qualified domain
 name, or an IP address.
 .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
 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.

 .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
 .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. Wildcard characters generally do not work on IP addresses, though they

 may work by accident when reverse DNS lookups fail.
 may work by accident when reverse DNS lookups fail.

+.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.
+.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
 '''.TP
 '''.B =public
 '''This is a special ``hostname'' that identifies the given directory name


@@ -83,6 +98,12 @@ may work by accident when reverse DNS lookups fail.
 '''.B \-\-public\-root
 '''option. Multiple specifications of a public root will be ignored.
 .PP
 '''.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
 You may use the special strings "gss/krb5", "gss/krb5i", or "gss/krb5p"
 to restrict access to clients using rpcsec_gss security.  However, this
 .SS RPCSEC_GSS security
 You may use the special strings "gss/krb5", "gss/krb5i", or "gss/krb5p"
 to restrict access to clients using rpcsec_gss security.  However, this


@@ -104,7 +125,7 @@ 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
 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
 understands the following export options:
 .TP
 .IR secure "\*d


@@ -136,13 +157,16 @@ storage (see
 .IR async
 above).
 
 .IR async
 above).
 

-In releases of nfs-utils up to and including 1.0.0, this option was the
-default.  In all subsequence releases,
+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 explicitly requested if needed.
 .I sync
 is the default, and
 .I async
 must be explicitly requested if needed.

-To help make system administrators aware of this change, 'exportfs'
+To help make system administrators aware of this change,
+.B exportfs

 will issue a warning if neither
 .I sync
 nor
 will issue a warning if neither
 .I sync
 nor


@@ -186,7 +210,7 @@ The
 option is currently only effective on
 .I "single host
 exports.  It does not work reliably with netgroup, subnet, or wildcard
 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
 
 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


@@ -244,7 +268,7 @@ If you genuinely require subtree checking, you should explicitly put
 that option in the
 .B exports
 file.  If you put neither option,
 that option in the
 .B exports
 file.  If you put neither option,

-.I exportfs
+.B exportfs

 will warn you that the change is pending.
 
 .TP
 will warn you that the change is pending.
 
 .TP


@@ -270,7 +294,9 @@ or
 .TP
 .IR no_acl
 On some specially patched kernels, and when exporting filesystems that
 .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
+support ACLs, this option tells
+.B 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
 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


@@ -363,23 +389,9 @@ 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.)
 
 will be given this list of alternatives. (Note that actual replication
 of the filesystem must be handled elsewhere.)
 

-.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
 .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
 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


@@ -397,19 +409,19 @@ and can be turned off with
 .IR no_root_squash .
 .PP
 By default,
 .IR no_root_squash .
 .PP
 By default,

-'''.I nfsd
+'''.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
 '''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 exportfs

 chooses a uid and gid
 of 65534 for squashed access. These values can also be overridden by
 the
 .IR anonuid " and " anongid
 options.
 '''.PP
 chooses a uid and gid
 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
+'''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
 '''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


@@ -422,7 +434,7 @@ Here's the complete list of mapping options:
 Map requests from uid/gid 0 to the anonymous uid/gid. Note that this does
 not apply to any other uids or gids that might be equally sensitive, such as
 user
 Map requests from uid/gid 0 to the anonymous uid/gid. Note that this does
 not apply to any other uids or gids that might be equally sensitive, such as
 user

-.IR bin 
+.IR bin

 or group
 .IR staff .
 .TP
 or group
 .IR staff .
 .TP


@@ -432,7 +444,7 @@ Turn off root squashing. This option is mainly useful for diskless clients.
 .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
 .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 no_all_squash ,
 which is the default setting.
 .TP


@@ -444,6 +456,24 @@ export entry for
 .B /home/joe
 in the example section below, which maps all requests to uid 150 (which
 is supposedly that of user joe).
 .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
 .IP
 .SH EXAMPLE
 .PP


@@ -454,7 +484,7 @@ is supposedly that of user joe).
 /projects       proj*.local.domain(rw)
 /usr            *.local.domain(ro) @trusted(rw)
 /home/joe       pc001(rw,all_squash,anonuid=150,anongid=100)
 /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            *(ro,insecure,all_squash)

 /srv/www        \-sync,rw server @trusted @external(ro)
 '''/pub/private    (noaccess)
 .fi
 /srv/www        \-sync,rw server @trusted @external(ro)
 '''/pub/private    (noaccess)
 .fi


@@ -466,7 +496,7 @@ and netgroups (this is the entry `@trusted'). The fourth line shows the
 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
 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 sixth line exports a directory read-write to the machine 'server'
 option in this entry also allows clients with NFS implementations that
 don't use a reserved port for NFS.
 The sixth line exports a directory read-write to the machine 'server'


@@ -476,19 +506,20 @@ all three mounts with the `sync' option enabled.
 '''access to the private directory.
 '''.SH CAVEATS
 '''Unlike other NFS server implementations, this
 '''access to the private directory.
 '''.SH CAVEATS
 '''Unlike other NFS server implementations, this

-'''.I nfsd
+'''.B nfsd

 '''allows you to export both a directory and a subdirectory thereof to
 '''allows you to export both a directory and a subdirectory thereof to

-'''the same host, for instance 
+'''the same host, for instance

 '''.IR /usr " and " /usr/X11R6 .
 '''In this case, the mount options of the most specific entry apply. For
 '''.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 
+'''instance, when a user on the client host accesses a file in

 '''.IR /usr/X11R6 ,
 '''.IR /usr/X11R6 ,

-'''the mount options given in the 
-'''.I /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
 '''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),
 .SH SEE ALSO
 .BR exportfs (8),
 .BR netgroup (5),


@@ -497,7 +528,15 @@ all three mounts with the `sync' option enabled.
 .BR showmount (8).
 '''.SH DIAGNOSTICS
 '''An error parsing the file is reported using syslogd(8) as level NOTICE from
 .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
+'''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
 '''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.
+'''to
+'''.BR named (8)
+'''at boot time, thus as hosts are found they are reported
+'''with the same
+'''.BR syslogd (8)
+'''parameters.