X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fexportfs%2Fexports.man;h=fd6d4be4a74bfe53a44799eef5fcabc7399e2fa1;hp=2863feaeaa66960ebdeb0c7bf003cf5772459286;hb=1408e610ac2db753543a546c4312b2eb6799f044;hpb=8b7ad01b14df1e7529b9ba8a1ea17df0d6004ef9 diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man index 2863fea..fd6d4be 100644 --- a/utils/exportfs/exports.man +++ b/utils/exportfs/exports.man @@ -1,73 +1,94 @@ -.TH EXPORTS 5 "11 August 1997" -.UC 5 +.TH EXPORTS 5 "4 March 2005" "Linux" "Linux File Formats Manual" .SH NAME -exports \- NFS file systems being exported +exports \- NFS file systems being exported (for Kernel based NFS) .SH SYNOPSIS .B /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 it used by both the NFS mount daemon, +exported to NFS clients. It is used by +.IR exportfs (8) +to give information to .IR mountd (8) -and the NFS file server daemon +and to the kernel based NFS file server daemon .IR nfsd (8). .PP The file format is similar to the SunOS .I exports -file, except that several additional options are permitted. Each line -contains a mount point and a list of machine or netgroup names allowed -to mount the file system at that point. An optional parenthesized list -of mount 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. +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 +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 exportfs -ra or (on Debian) +/etc/init.d/nfs-kernel-server reload. .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 recognizued be the resolver, the fully qualified domain +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 all -netgroup members is extracted and added to the access list. Empty host +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. 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 as -.IR address/netmask . -.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. +.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 +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. .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. +.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 mountd " and " nfsd -understand the following export options: +.IR exportfs +understands the following export options: .TP .IR secure "\*d This option requires that requests originate on an internet port less @@ -75,29 +96,225 @@ than IPPORT_RESERVED (1024). This option is on by default. To turn it off, specify .IR insecure . .TP -.IR ro -Allow only read-only requests on this NFS volume. The default is to -allow write requests as well, which can also be made explicit by using +.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 rw " option. +.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 upto and including 1.0.0, this option was the +default. In this and future releases, +.I sync +is the default, and +.I async +must be explicit requested if needed. +To help make system adminstrators aware of this change, 'exportfs' +will issue a warning if neither +.I sync +nor +.I async +is specified. +.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 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 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 . + .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. +.IR insecure_locks .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. +.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 -.IR link_absolute -Leave all symbolic link as they are. This is the default operation. +.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 +.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 nominted 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. + +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. + +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). + +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. + .SS User ID Mapping .PP .I nfsd @@ -118,58 +335,61 @@ and can be turned off with .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 -of -2 (i.e. 65534) is used. These values can also be overridden by +'''.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 +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 -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 +'''.PP +'''In addition to this, +'''.I 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 +'''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 @@ -180,14 +400,14 @@ not apply to any other uids that might be equally sensitive, such as user .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 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 @@ -195,60 +415,60 @@ public FTP directories, news spool directories, etc. The opposite option 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-1500 -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 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. @@ -269,7 +489,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) -/pub/private (noaccess) +'''/pub/private (noaccess) .fi .PP The first line exports the entire filesystem to machines master and trusty. @@ -281,26 +501,33 @@ 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 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. +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. .SH FILES /etc/exports -.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 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.