Adding upstream version 1:2.6.4.upstream/1%2.6.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 678 insertions, 0 deletions

diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
new file mode 100644
index 0000000..b758277
--- /dev/null
+++ b/utils/exportfs/exports.man
@@ -0,0 +1,678 @@
+.\"@(#)exports.5"
+.\"
+.TH exports 5 "31 December 2009"
+.SH NAME
+exports \- NFS server export table
+.SH DESCRIPTION
+The file
+.I /etc/exports
+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
+.BR mountd (8).
+.PP
+The file format is similar to the SunOS
+.I exports
+file. Each line contains an export point and a whitespace-separated list
+of clients allowed to mount the file system at that point. Each listed
+client may be immediately followed by a parenthesized, comma-separated
+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
+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
+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
+You may specify a host either by an
+abbreviated name recognized be the resolver, the fully qualified domain
+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 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.
+.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
+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.
+.SS Transport layer security
+The Linux NFS server allows the use of RPC-with-TLS (RFC 9289) to
+protect RPC traffic between itself and its clients.
+Alternately, administrators can secure NFS traffic using a VPN,
+or an ssh tunnel or similar mechanism, in a way that is transparent
+to the server.
+.PP
+To enable the use of RPC-with-TLS, the server's administrator must
+install and configure
+.BR tlshd
+to handle transport layer security handshake requests from the local
+kernel.
+Clients can then choose to use RPC-with-TLS or they may continue
+operating without it.
+.PP
+Administrators may require the use of RPC-with-TLS to protect access
+to individual exports.
+This is particularly useful when using non-cryptographic security
+flavors such as
+.IR sec=sys .
+The
+.I xprtsec=
+option, followed by an unordered colon-delimited list of security policies,
+can restrict access to the export to only clients that have negotiated
+transport-layer security.
+Currently supported transport layer security policies include:
+.TP
+.IR none
+The server permits clients to access the export
+without the use of transport layer security.
+.TP
+.IR tls
+The server permits clients that have negotiated an RPC-with-TLS session
+without peer authentication (confidentiality only) to access the export.
+Clients are not required to offer an x.509 certificate
+when establishing a transport layer security session.
+.TP
+.IR mtls
+The server permits clients that have negotiated an RPC-with-TLS session
+with peer authentication to access the export.
+The server requires clients to offer an x.509 certificate
+when establishing a transport layer security session.
+.PP
+If RPC-with-TLS is configured and enabled and the
+.I xprtsec=
+option is not specified, the default setting for an export is
+.IR xprtsec=none:tls:mtls .
+With this setting, the server permits clients to use any transport
+layer security mechanism or none at all to access the export.
+.SS General Options
+.BR exportfs
+understands the following export options:
+.TP
+.IR secure
+This option requires that requests not using gss originate on an
+Internet port less than IPPORT_RESERVED (1024). This option is on by default.
+To turn it off, specify
+.IR insecure .
+(NOTE: older kernels (before upstream kernel version 4.17) enforced this
+requirement on gss requests as well.)
+.TP
+.IR rw
+Allow both read and write requests on this NFS volume. The
+default is to disallow any request which changes the filesystem.
+This can also be made explicit by using
+the
+.IR ro " option.
+.TP
+.IR async
+This option allows the NFS server to violate the NFS protocol and
+reply to requests before any changes made by that request have been
+committed to stable storage (e.g. disc drive).
+
+Using this option usually improves performance, but at the cost that
+an unclean server restart (i.e. a crash) can cause data to be lost or
+corrupted.
+
+.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 explicitly requested if needed.
+.TP
+.IR no_wdelay
+This option has no effect if
+.I async
+is also set.  The NFS server will normally delay committing a write request
+to disc slightly if it suspects that another related write request may be in
+progress or may arrive soon.  This allows multiple write requests to
+be committed to disc with the one operation which can improve
+performance.  If an NFS server received mainly small unrelated
+requests, this behaviour could actually reduce performance, so
+.IR no_wdelay
+is available to turn it off.
+The default can be explicitly requested with the
+.IR wdelay " option.
+.TP
+.IR nohide
+This option is based on the option of the same name provided in IRIX
+NFS.  Normally, if a server exports two filesystems one of which is
+mounted on the other, then the client will have to mount both
+filesystems explicitly to get access to them.  If it just mounts the
+parent, it will see an empty directory at the place where the other
+filesystem is mounted.  That filesystem is "hidden".
+
+Setting the
+.I nohide
+option on a filesystem causes it not to be hidden, and an
+appropriately authorised client will be able to move from the parent to
+that filesystem without noticing the change.
+
+However, some NFS clients do not cope well with this situation as, for
+instance, it is then possible for two files in the one apparent
+filesystem to have the same inode number.
+
+The
+.I nohide
+option is currently only effective on
+.I "single host
+exports.  It does not work reliably with netgroup, subnet, or wildcard
+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
+copes with the situation effectively.
+
+The option can be explicitly disabled for NFSv2 and NFSv3 with
+.IR hide .
+
+This option is not relevant when NFSv4 is use.  NFSv4 never hides
+subordinate filesystems.  Any filesystem that is exported will be
+visible where expected when using NFSv4.
+.TP
+.I crossmnt
+This option is similar to
+.I nohide
+but it makes it possible for clients to access all filesystems mounted
+on a filesystem marked with
+.IR crossmnt .
+Thus when a child filesystem "B" is mounted on a parent "A", setting
+crossmnt on "A" has a similar effect to setting "nohide" on B.
+
+With
+.I nohide
+the child filesystem needs to be explicitly exported.  With
+.I crossmnt
+it need not.  If a child of a
+.I crossmnt
+file is not explicitly exported, then it will be implicitly exported
+with the same export options as the parent, except for
+.IR fsid= .
+This makes it impossible to
+.B not
+export a child of a
+.I crossmnt
+filesystem.  If some but not all subordinate filesystems of a parent
+are to be exported, then they must be explicitly exported and the
+parent should not have
+.I crossmnt
+set.
+
+The
+.I nocrossmnt
+option can explictly disable
+.I crossmnt
+if it was previously set.  This is rarely useful.
+.TP
+.IR no_subtree_check
+This option disables subtree checking, which has mild security
+implications, but can improve reliability in some circumstances.
+
+If a subdirectory of a filesystem is exported, but the whole
+filesystem isn't then whenever a NFS request arrives, the server must
+check not only that the accessed file is in the appropriate filesystem
+(which is easy) but also that it is in the exported tree (which is
+harder). This check is called the
+.IR subtree_check .
+
+In order to perform this check, the server must include some
+information about the location of the file in the "filehandle" that is
+given to the client.  This can cause problems with accessing files that
+are renamed while a client has them open (though in many simple cases
+it will still work).
+
+subtree checking is also used to make sure that files inside
+directories to which only root has access can only be accessed if the
+filesystem is exported with
+.I no_root_squash
+(see below), even if the file itself allows more general access.
+
+As a general guide, a home directory filesystem, which is normally
+exported at the root and may see lots of file renames, should be
+exported with subtree checking disabled.  A filesystem which is mostly
+readonly, and at least doesn't see many file renames (e.g. /usr or
+/var) and for which subdirectories may be exported, should probably be
+exported with subtree checks enabled.
+
+The default of having subtree checks enabled, can be explicitly
+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 no_auth_nlm
+This option (the two names are synonymous) tells the NFS server not to require authentication of
+locking requests (i.e. requests which use the NLM protocol).  Normally
+the NFS server will require a lock request to hold a credential for a
+user who has read access to the file.  With this flag no access checks
+will be performed.
+
+Early NFS client implementations did not send credentials with lock
+requests, and many current NFS clients still exist which are based on
+the old implementations.  Use this flag if you find that you can only
+lock files which are world readable.
+
+The default behaviour of requiring authentication for NLM requests can
+be explicitly requested with either of the synonymous
+.IR auth_nlm ,
+or
+.IR secure_locks .
+.\".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
+.TP
+.I mp
+This option makes it possible to only export a directory if it has
+successfully been mounted.
+If no path is given (e.g.
+.IR mountpoint " or " mp )
+then the export point must also be a mount point.  If it isn't then
+the export point is not exported.  This allows you to be sure that the
+directory underneath a mountpoint will never be exported by accident
+if, for example, the filesystem failed to mount due to a disc error.
+
+If a path is given (e.g.
+.IR mountpoint= "/path or " mp= /path)
+then the nominated path must be a mountpoint for the exportpoint to be
+exported.
+
+.TP
+.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.
+
+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.
+
+Other filesystems can be identified with a small integer, or a UUID
+which should contain 32 hex digits and arbitrary punctuation.
+
+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 nordirplus
+This option will disable READDIRPLUS request handling.  When set,
+READDIRPLUS requests from NFS clients return NFS3ERR_NOTSUPP, and
+clients fall back on READDIR.  This option affects only NFSv3 clients.
+.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.)
+
+.TP
+.IR pnfs
+This option enables the use of the pNFS extension if the protocol level
+is NFSv4.1 or higher, and the filesystem supports pNFS exports.  With
+pNFS clients can bypass the server and perform I/O directly to storage
+devices. The default can be explicitly requested with the
+.I no_pnfs
+option.
+
+.TP
+.IR security_label
+With this option set, clients using NFSv4.2 or higher will be able to
+set and retrieve security labels (such as those used by SELinux).  This
+will only work if all clients use a consistent security policy.  Note
+that early kernels did not support this export option, and instead
+enabled security labels by default.
+
+.TP
+.IR reexport= auto-fsidnum|predefined-fsidnum
+This option helps when a NFS share is re-exported. Since the NFS server
+needs a unique identifier for each exported filesystem and a NFS share
+cannot provide such, usually a manual fsid is needed.
+As soon
+.IR crossmnt
+is used manually assigning fsid won't work anymore. This is where this
+option becomes handy. It will automatically assign a numerical fsid
+to exported NFS shares. The fsid and path relations are stored in a SQLite
+database. If
+.IR auto-fsidnum
+is selected, the fsid is also autmatically allocated.
+.IR predefined-fsidnum
+assumes pre-allocated fsid numbers and will just look them up.
+This option depends also on the kernel, you will need at least kernel version
+5.19.
+Since
+.IR reexport=
+can automatically allocate and assign numerical fsids, it is no longer possible
+to have numerical fsids in other exports as soon this option is used in at least
+one export entry.
+
+The association between fsid numbers and paths is stored in a SQLite database.
+Don't edit or remove the database unless you know exactly what you're doing.
+.IR predefined-fsidnum
+is useful when you have used
+.IR auto-fsidnum
+before and don't want further entries stored.
+
+
+.SS User ID Mapping
+.PP
+.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
+on a normal file system. This requires that the same uids and gids are
+used on the client and the server machine. This is not always true, nor
+is it always desirable.
+.PP
+Very often, it is not desirable that the root user on a client machine
+is also treated as root when accessing files on the NFS server. To this
+end, uid 0 is normally mapped to a different id: the so-called
+anonymous or
+.I nobody
+uid. This mode of operation (called `root squashing') is the default,
+and can be turned off with
+.IR no_root_squash .
+.PP
+By default,
+.\".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 65534 for squashed access. These values can also be overridden by
+the
+.IR anonuid " and " anongid
+options.
+.\".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
+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 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 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
+.IR no_all_squash ,
+which is the default setting.
+.TP
+.IR anonuid " and " anongid
+These options explicitly set the uid and gid of the anonymous account.
+This option is primarily useful for PC/NFS clients, where you might want
+all requests appear to be from one user. As an example, consider the
+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).
+
+.SS Subdirectory Exports
+
+Normally you should only export only the root of a filesystem.  The NFS
+server will also allow you to export a subdirectory of a filesystem,
+however, this has drawbacks:
+
+First, it may be possible for a malicious user to access files on the
+filesystem outside of the exported subdirectory, by guessing filehandles
+for those other files.  The only way to prevent this is by using the
+.IR no_subtree_check
+option, which can cause other problems.
+
+Second, export options may not be enforced in the way that you would
+expect.  For example, the
+.IR security_label
+option will not work on subdirectory exports, and if nested subdirectory
+exports change the
+.IR security_label
+or
+.IR sec=
+options, NFSv4 clients will normally see only the options on the parent
+export.  Also, where security options differ, a malicious client may use
+filehandle-guessing attacks to access the files from one subdirectory
+using the options from another.
+
+
+.SS Extra Export Tables
+After reading 
+.I /etc/exports 
+.B exportfs
+reads files in the
+.I /etc/exports.d
+directory as extra export tables.  Only files ending in
+.I .exports
+are considered.  Files beginning with a dot are ignored.
+The format for extra export tables is the same as 
+.I /etc/exports
+.
+.IP
+.SH EXAMPLE
+.PP
+.nf
+.ta +3i
+# sample /etc/exports file
+/               master(rw) trusty(rw,no_root_squash)
+/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)
+/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.
+In addition to write access, all uid squashing is turned off for host
+trusty. The second and third entry show examples for wildcard hostnames
+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
+.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'
+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),
+.BR tlshd (8).
+.\".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.