X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fexportfs%2Fexports.man;h=3aa8de8ab45b6af86d842c6f502929318556c39e;hp=4b31ccf9c03e1316f3483a8d7cf3810a29ee7f91;hb=e91ff0175602cc56f223f1d92de6511099fa40d1;hpb=8d53a2630763f8f639d2de2ddd26282bff1c7cad diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man index 4b31ccf..3aa8de8 100644 --- a/utils/exportfs/exports.man +++ b/utils/exportfs/exports.man @@ -1,5 +1,4 @@ -.TH EXPORTS 5 "28 October 1999" -.UC 5 +.TH EXPORTS 5 "4 March 2005" "Linux" "Linux File Formats Manual" .SH NAME exports \- NFS file systems being exported (for Kernel based NFS) .SH SYNOPSIS @@ -17,15 +16,23 @@ and to the kernel based NFS file server daemon .PP The file format is similar to the SunOS .I exports -file, except that several additional options are permitted. Each line -contains an export point and a list of machine or netgroup names allowed -to mount the file system at that point. An optional parenthesized list -of export parameters may follow each machine name. Blank lines are -ignored, and a # introduces a comment to the end of the line. Entries may -be continued across newlines using a backslash. If export name contains spaces -it should be quoted using double-quotes. You can also specify spaces -or any other unusual characters in the export path name using a -backslash followed by the character code as 3 octal digits. +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 .SS Machine Name Formats NFS clients may be specified in a number of ways: @@ -42,9 +49,10 @@ 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. However, -these wildcard characters do not match the dots in a domain name, so the -above pattern does not include hosts such as \fIa.b.cs.foo.edu\fR. +\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 @@ -53,8 +61,9 @@ as 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). -.TP +host). 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 @@ -74,12 +83,17 @@ host). '''.B \-\-public\-root '''option. Multiple specifications of a public root will be ignored. .PP +.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. +.PP .SS General Options .IR exportfs understands the following export options: .TP .IR secure "\*d -This option requires that requests originate on an internet port less +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 . @@ -90,18 +104,39 @@ 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 -This option requests that all file writes be committed to disc before -the write request completes. This is required for complete safety of -data in the face of a server crash, but incurs a performance hit. -The default is to allow the server to write the data out whenever it -is ready. This can be explicitly requested with the -.IR async " option. +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, this option was the +default. In all subsequence releases, +.I sync +is the default, and +.I async +must be explicitly requested if needed. +To help make system administrators aware of this change, 'exportfs' +will issue a warning if neither +.I sync +nor +.I async +is specified. .TP .IR no_wdelay -This option only has effect if -.I sync +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 @@ -145,9 +180,17 @@ copes with the situation effectively. The option can be explicitly disabled with .IR hide . .TP +.IR crossmnt +This option is similar to +.I nohide +but it makes it possible for clients to move from the filesystem marked +with crossmnt to exported filesystems mounted on it. Thus when a child +filesystem "B" is mounted on a parent "A", setting crossmnt on "A" has +the same effect as setting "nohide" on B. +.TP .IR no_subtree_check This option disables subtree checking, which has mild security -implications, but can improve reliability is some circumstances. +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 @@ -166,7 +209,7 @@ 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 the file itself allows more general access. +(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 @@ -179,6 +222,16 @@ 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, +.I exportfs +will warn you that the change is pending. + .TP .IR insecure_locks .TP @@ -199,6 +252,21 @@ be explicitly requested with either of the synonymous .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 @@ -218,6 +286,54 @@ or '''.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. + .SS User ID Mapping .PP .I nfsd @@ -244,7 +360,7 @@ By default, '''in the password file at startup time. If it isn't found, a uid and gid .I 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. @@ -298,8 +414,11 @@ 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. @@ -392,6 +511,7 @@ is supposedly that of user joe). /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) '''/pub/private (noaccess) .fi .PP @@ -405,6 +525,9 @@ 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 last line denies all NFS clients '''access to the private directory. '''.SH CAVEATS @@ -422,6 +545,12 @@ don't use a reserved port for NFS. '''entry. .SH FILES /etc/exports +.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