X-Git-Url: https://git.decadent.org.uk/gitweb/?p=nfs-utils.git;a=blobdiff_plain;f=utils%2Fexportfs%2Fexports.man;h=ea28ca883ba9ef28c5f5a2e4eeaec59e20d802fd;hp=7ab7640da1350b8f8b6733c007135fb13d639abe;hb=e4719f90f77de2ea2c083cbc304b5cc7a7b516bd;hpb=617f2d4dad0525eb63ddb44b2f33d041f45578cb diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man index 7ab7640..ea28ca8 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 @@ -23,6 +22,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 @@ -30,6 +34,8 @@ 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 restart the NFS server. +.PP .SS Machine Name Formats NFS clients may be specified in a number of ways: .IP "single host @@ -79,12 +85,32 @@ may work by accident when reverse DNS lookups fail. '''.B \-\-public\-root '''option. Multiple specifications of a public root will be ignored. .PP +.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. +.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 . @@ -105,13 +131,20 @@ 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. -In releases of nfs-utils upto and including 1.0.0, this option was the -default. In this and future releases, +.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, this 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 adminstrators aware of this change, 'exportfs' +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 @@ -164,9 +197,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 @@ -185,7 +226,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 @@ -198,6 +239,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 @@ -218,6 +269,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 @@ -237,6 +303,82 @@ 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. + +.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 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 @@ -263,7 +405,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. @@ -275,61 +417,19 @@ options. 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 @@ -337,60 +437,6 @@ 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-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. @@ -410,7 +456,8 @@ 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 *(ro,insecure,all_squash) +/srv/www \-sync,rw server @trusted @external(ro) '''/pub/private (noaccess) .fi .PP @@ -424,6 +471,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 @@ -441,6 +491,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