X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fexportfs%2Fexports.man;h=54adfeb555f837f5ba1fd81cf0e2244579674724;hp=ec33442db64911c6c84054adb391aac54ccbe5c2;hb=014e00dfaea0efc92150e2aedc5ca43aa337545e;hpb=6bd461c4f1708b38f59f9f4a1bec881f027fd8aa diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man index ec33442..54adfeb 100644 --- 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 -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 @@ -22,6 +26,11 @@ 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 @@ -29,65 +38,99 @@ 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 -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 +.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 @@ -116,13 +159,16 @@ 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, +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 administrators 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 @@ -166,7 +212,7 @@ The 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 @@ -224,7 +270,7 @@ If you genuinely require subtree checking, you should explicitly put 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 @@ -250,7 +296,9 @@ or .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 @@ -263,24 +311,24 @@ 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 @@ -301,30 +349,51 @@ 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. + +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. -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. +Other filesystems can be identified with a small integer, or a UUID +which should contain 32 hex digits and arbitrary punctuation. -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). +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. -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. +.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 @@ -342,140 +411,44 @@ 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 -.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 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. @@ -485,6 +458,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). +.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 @@ -495,8 +486,11 @@ 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) -/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. @@ -506,35 +500,49 @@ 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 +.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.