Table of Contents
exports – directories and files exported to NFS clients
/etc/exports
The
/etc/exports file contains a list of export entries for all file system paths that Data ONTAP exports automatically when NFS starts up. The
/etc/exports file can contain up to 10, 240 export entries. Each export entry can contain up to 4, 096 characters, including the end-of-line character. To specify that an export entry continues onto the next line, you must use the line continuation character "\”.
An export entry has the following syntax:
Each export entry is a line in the following format:
pathname -option[, option ] …
The following list describes the fields in an export entry:
- pathname
- path name of a file or directory to be exported.
- option
- the export option specifying how a file or directory is exported.
You can specify an option in one of the following formats:
- actual=path
- Specifies the actual path to use when a NFS client attempts to mount the original path. This option is useful for moving mount points without reconfiguring the clients right away. Note that while the exported pathname need not exist, the pathname given as a parameter to actual must exist.
anon=uid|name If a request comes from user ID of 0 (root user ID on the client), use
uid as the effective user ID unless the client host is included in the
root option. The default value of
uid is 65534. To disable root access, set
uid to 65535. To grant root access to all clients, set
uid to 0. The user ID can also be specified by a name string corresponding to an entry in
/etc/passwd.
- nosuid
- If a request tries to set either with either setuid or setgid or if a special file, i.e., block or character type via mknod, then nosuid disallows that request. The default mode is to allow such requests.
ro | ro=hostname[:
hostname]…
A
pathname can be either exported
ro to all hosts or to a set of specified hosts.
rw | rw=hostname[:hostname]…
A pathname can be either exported rw to all hosts or to a set of specified hosts. If no access modifiers are provided, then the default is rw.
root=hostname[:hostname]…
Give root access only to the specified hosts. Note that there is no -root option, i.e., this option always takes at least one hostname as a parameter.
sec=secflavor[:secflavor]…
Allow access to the mounted directory only using the listed security flavors. If no sec directive is provided, then the default of sys is applied to the export. The sec directive may appear multiple times in a rule, which each appearance setting the context of the following directives: anon, nosuid, ro, root, and rw. The contexts apply in order. If only one security context is provided in an export, then it applies regardless of where it appears in the export. Note that any given secflavor can only appear once in an export rule.
The supported security flavors are:
- sys
- for Unix(tm) style security based on uids and gids
- krb5
- for Kerberos(tm) Version 5 authentication.
- krb5i
- for Kerberos(tm) Version 5 integrity service
- krb5p
- for Kerberos(tm) Version 5 privacy service
The Kerberos(tm) authentication service verifies the identity of the users accessing the filer on all accesses, and also verifies to the client that the responses are from the filer. The integrity service provides a strong assurance that the messages have not been tampered with. The privacy service ensures that messages intercepted on the wire cannot be read by any other party. The integrity and privacy services both include authentication. The default security flavor is
sys.
The security flavor of none can also be applied to an export. If the client uses this flavor, then all requests get the effective UID of the anonymous user. Also, if a request arrives with a security context which is not present in the export, and none is allowed, then that request is treated as if it arrived with the flavor of none.
A host is allowed to mount an export if it has either
ro or
rw access permissions.
A hostname is described as:
[-][machine name|netgroup|machine IP|subnet|DNS domain]
Where, `-’ indicates that the host is to be denied access.
A machine name is an alphanumeric string.
A netgroup is also an alphanumeric string and describes a group of machine names. If NIS is not enabled, then each netgroup must be defined in the /etc/netgroup file. If NIS is enabled, then each netgroup may either be in a NIS mapping or defined in the /etc/netgroup file.
If a netgroup occurs in both NIS and /etc/netgroup, then the ordering given in /etc/nsswitch.conf determines which definition is used.
A netgroup can be differentiated from a hostname by prepending an `@’ to the name. When an entry begins with an `@’, ONTAP treats it as netgroup and not a hostname. When an entry does not begin with `@’, the handling depends on the setting of the option nfs.netgroup.strict.
If nfs.netgroup.strict is set, then the `@’ determines whether an entry is either a netgroup or a hostname. In this case, when an entry appears without a prepended `@’, it is assumed to be a hostname, i.e., it cannot be a netgroup.
If nfs.netgroup.strict is not set, then an entry with `@’ will still only denote a netgroup, but the absence of the `@’ does not determine that an entry is a host.
The use of the nfs.netgroup.strict option eliminates spurious netgroup lookups (which can be helpful to performance). If it is not used, backwards compatibility with export specifications in which netgroups are not specified with an `@’ is retained.
A machine IP is in dotted decimal format: AAA.BBB.CCC.DDD
A subnet is in the forms:
dotted_IP/num_bits
The dotted_IP field is a subnet number. The num_bits field specifies the size of the subnet by the number of leading bits of the netmask.
"[network] subnet [netmask] netmask” The subnet field is the subnet number. The netmask field is the netmask. Note that the keywords network and netmask are optional.
A DNS domain starts with a `.’ and is alphanumeric.
If there is a machine name and a netgroup with the same name, then the hostname is assumed to be the name of a machine.
In UNIX, it is illegal to export a directory that has an exported ancestor in the same file system. Data ONTAP does not have this restriction. For example, you can export both the /vol/vol0 directory and the /vol/vol0/home directory. In determining permissions, the filer uses the longest matching prefix.
Neither the same path nor the same file handle can be advertised for exports. We restrict the path names to make mounts unique and the file handle restriction makes per NFS request checking also be unique.
As the /etc/exports file is parsed and the same path is determined to be used for exporting, then the last instance of the export rule is stored in memory. Note that different path names may evaluate to the same advertised path:
/home
/vol/vol0/home
/vol/vol0/home/ontap/..
The addition of actual complicates the rules for determining what gets exported. If an export uses -actual, then neither the advertised path nor the actual storage path may be duplicated in memory.
There is no set ordering of options, but as the
ro and
rw options interact, there is a strict interpretation of these options:
1) -rw is the default if -ro, -ro=, -rw, and -rw= are all not present.
2) If only -rw= is present, ro is not the default for all other hosts. This rule is a departure from pre-6.5 semantics.
3) -ro, ro= and -rw, rw= are errors.
4) -ro=A, rw=A is an error
5) -ro=A, rw=-A is an error
6) -ro=-A, rw=A is an error
7) The position of -rw, -rw= -ro, and -ro= in the options does not have any significance
8) -ro trumps -rw
9) -ro= trumps -rw
10) -rw= trumps -ro
11) A specific host name in either -ro= or -rw= overrides a grouping in the other access specifier.
12) -ro= trumps -rw=
13) Left to right precedence, which determines `-’ and the order we go across the wire.
Note, "A trumps B" means that option A overrules option B.
Given the following netgroups:
farm pets (alligator, , ) livestock workers
pets (dog, , ) (cat, , ) (skunk, , ) (pig, , ) (crow, , )
livestock
(cow, , ) (pig, , ) (chicken, , ) (ostrich, , )
workers
(dog, , ) (horse, , ) (ox, , ) (mule, , )
predators
(coyote, , ) (puma, , ) (fox, , ) (crow, , )
We can illustrate the access rules thusly:
/vol/vol0 -anon=0
All hosts have rw access, and root at that.
/vol/vol0 -root=horse, rw
All hosts have rw access, but only horse has root access.
/vol/vol0 -anon=0, rw=horse
Only horse has access and it is rw. Note the departure from the prior rule format, in which all other hosts would by default have ro access.
/vol/vol0 -anon=0, ro, rw=horse
All hosts have ro access, except horse, which has rw access.
/vol/vol1 -ro=@workers, rw=@farm:canary /vol/vol1 -rw=@farm:canary, ro=@workers
All hosts in the netgroup farm have rw access, except dog, horse, ox, and mule. All of which have ro access. In addition, canary has rw access to the export. Note that both lines are identical with respect to determining access rights.
/vol/vol2 -ro=@pets, rw
All hosts have rw access, except for dog, cat, skunk, pig, and crow, all of which have ro access.
/vol/vol2 -ro=-@pets, rw
All hosts have rw access, except for dog, cat, skunk, pig, and crow, all of which have no access at all.
By rule #9, all members of the netgroup pets are denied rw access. By negation, all members of the netgroup pets are denied ro access.
/vol/vol2 -ro, rw=@pets:canary
All hosts have ro access, except for canary, dog, cat, skunk, pig, and crow, all of which have rw access.
/vol/vol2 -ro, rw=-@pets:canary
All hosts have ro access, except for canary which has rw access.
/vol/vol2 -ro, rw=@pets:@farm:canary
All hosts have ro access, except for canary and all hosts in the netgroups pets and farm, which all have rw access.
/vol/vol2 -ro, rw=-@pets:@farm:canary
All hosts have ro access, except for all hosts in the netgroup farm, excluding all hosts in the netgroup pets, which have rw access. The host canary also has rw access.
If the host cat wants to write to /vol/vol2, by rule #10, we first check the -rw= access list. By rule #13, we check for access in order of -@pets, @farm, and finally canary. We match cat in the netgroup pets and therefore cat is denied rw access. It will however be granted ro access.
/vol/vol2 -ro, rw=@farm:-@pets:canary
Effectively, all hosts have ro access, except for canary and all hosts in the netgroup farm, which all have rw access.
If the host cat wants to write to /vol/vol2, by rule #10, we first check the -rw= access list. By rule #13, we check for access in order of @farm, -@pets, and finally canary. We match cat in the netgroup farm, by expansion, and therefore cat is granted rw access.
/vol/vol2a -rw=@pets:-@workers, ro=@livestock
By rule #12, cow, pig, chicken, and ostrich all have ro access.
By rule #13, dog, cat, and skunk all have rw access.
By negation, horse, ox, and mule have no rw access and by rule #2, they have no access at all.
/vol/vol2a -rw=-@workers:pets, ro=@livestock
By rule #12, cow, pig, chicken, and ostrich all have ro access.
By rule #13, negation, and rule #2, dog, horse, ox, and mule have no access.
cat and skunk have rw access.
/vol/vol3 -ro=@pets, rw=@farm:lion
All hosts in the netgroup farm have rw access, except for all hosts in the netgroup pets, which all have ro access. In addition, the host lion has rw access.
If the host cat wants to write to /vol/vol3, by rule #12, we first check the -ro= access list. We match cat in the netgroup pets and therefore we deny rw access.
/vol/vol4 -ro=10.56.17/24, rw=10.56/16
All hosts in the subnet 10.56/16 have rw access, except those in the subnet 10.56.17/24, which have ro access.
/vol/vol17
-ro=10.56.17/24, rw=10.56.17.5:10.56.17.6:farm
All hosts in the subnet 10.56.17/24 have ro access, except, by rule #11, for 10.56.17.5 and 10.56.17.6, which have rw access. If the hosts in the netgroup farm are on the 10.56.17/24 subnet, they have ro access, else they have rw access. Rule #11 allows for specific hosts to be excluded from a range provided by a group. Since it makes no sense to compare netgroups to subnets, we do not allow exceptions by groups.
/vol/vol19
-ro=10.56.17.9:.frogs.fauna.mycompany.com, \\ rw=.fauna.mycompany.com
All hosts in the subdomain .fauna.mycompany.com get rw access, except those in the subdomain Note that we determine this result from rule #12 and not rule #11; we do not evaluate if one grouping construct is a subset of another. If 10.56.17.9 is in the subdomain .fauna.mycompany.com, then by rule #11, it gets ro access.
/vol/vol21 -ro=10.56.17.9, rw=-pets:farm:skunk
Rule #11 interacts with rules #5 and #6 in an interesting way, if a host is mentioned in an export by either name or IP, then it appears that it will always be granted the access given by whether it is in -ro= or -rw=. However, rule #13 still applies. Thus, 10.56.17.9 always gets ro access, but in this case by rule #13, skunk is denied access to the mount. Since skunk is a member of the netgroup pets, and pets is denied rw access by negation, skunk is denied access.
/vol/vol5
-ro=.farm.mycompany.com, sec=krb5, rw, anon=0
If the secflavor is sys, then all hosts in the DNS subdomain of .farm.mycompany.com are granted ro access. If the secflavor is krb5, then all hosts are granted rw access.
/vol/vol6 -sec=sys:none, rw, sec=krb5:krb5i:k4b5p, rw, anon=0
If the secflavor is sys or none, then all hosts are granted rw access, but effectively all root access is blocked. If the secfla_vor is from one of the secure krb5, krb5i, or krb5p, then rw and effectively root access are both granted.
Exports defined prior to ONTAP 6.5 contain a different option,
-access, which defined which hosts were permitted to mount an export. With the newer finer grained options, and by allowing more flexibility such as netgroups in the options,
-access has been removed as an option.
Another significant change is that -ro is no longer the default if -rw= is present as an option.
During the upgrade process, the /etc/exports file is converted to the newer format.
The rules for upgrading to the new format are:
1) -root= options stay the same
2) No access list => -rw
3) -access=X => -rw=X
4) -ro => -ro
5) -access=X, ro => -ro=X
6) -rw=X => -rw=X
This is more secure than the change -rw=X, ro.
Remember from Access Rule #2, -ro is never a default.
If the less restrictive form is desired, then the option needs to be manually changed. Note that if an export file has a mix of old and new style options, the more secure new style option of -rw=X can not be differentiated from the less secure option of -rw=X(, ro) with the implicit ro modifier. To solve this problem, we always interpret -rw=X in the most secure format.
7) -access=Y, rw=X => -rw=X, ro=(Y-X)
There is a potential to remove write access here, but we keep the most secure translation.
In all cases, we preserve ordering inside an option.
/vol/vol0 -anon=0 By rule #2, this becomes:
/vol/vol0 -rw, anon=0
/vol/vol3 -ro By rule #4, this becomes:
/vol/vol3 -ro
/vol/vol0/home -rw=dog:cat:skunk:pig:mule By rule #6, this becomes:
/vol/vol0/home -rw=dog:cat:skunk:pig:mule
Note that by the access rules given above, all other hosts are denied ro access.
Since the upgrade code does not know about netgroups and netgroups used to not be allowed inside the -rw host list, this could be rewritten as:
/vol/vol0/home -rw=@pets
Also, if the security style is desired to be the older style, this could be further rewritten as:
/vol/vol0/home -ro, rw=@pets
- /vol/vol1
- -access=pets:workers:alligator:mule, \\ rw=dog:cat:skunk:pig:horse:ox:mule
By rule #7, this becomes:
- /vol/vol1
- -ro=pets:workers:alligator, \\ rw=dog:cat:skunk:pig:horse:ox:mule
This can be rewritten as:
- /vol/vol1
- -ro=pets:workers:alligator, \\ rw=pets:workers
And should be:
/vol/vol1 -ro=alligator, rw=@pets:@workers
The
/etc/exports file is changed by ONTAP for any of the following conditions:
vol create
A default entry is added for the new volume. If an admin host had been defined during the setup process, access is restricted to that host, otherwise all hosts have access to the new volume.
vol rename
All entries which have either a pathname or an -actual pathname which matches the old volume name are changed to be that of the new volume name.
vol destroy
All entries which have either a pathname or an -actual pathname which matches the old volume name are removed from the file.
upgrade
During every invocation of exportfs -a, the exports file is checked for old style formatting. If this style is found, the exports file is upgraded to follow the current formatting.
Please note that when we upgrade exports which contain subnets, we always rewrite the subnets in the compact format of dotted_IP/num_bits.
If the option nfs.export.auto-update is disabled, then the automatic updates for the vol commands will not take place. Instead the need for manual updates is syslogged.
A new feature in ONTAP 6.5 is the access cache, which allows netgroups to appear in
-ro=,
-rw=, and
-root= options. Each time a request arrives from a host, it refers to an exported path. To avoid lengthy delays, we first check for that host and path in the cache to determine if we will accept or reject the request. If there is cache miss, we reject the request and do name resolution in another thread. On the next request, we should get a cache hit (i.e., the hit or miss depends on network traffic).
The time that a entry lives in the cache is determined by the two options:
nfs.export.neg.timeout
dictates how long an entry which has been denied access lives
nfs.export.pos.timeout
dictates how long an entry which has been granted access lives
There are several ways that the cache can be flushed:
exportfs -f
Flushes the entire access cache.
exportfs -f pathname
Flushes the cache for the longest leading prefix match for the path.
Also, any command which alters an export entry will result in the access cache for that export being flushed. E.g., exportfs -au, exportfs -a, exportfs -io -rw /vol/vol1, etc.
As the access cache is designed to eliminate name service lookups, entries inside it can become stale when the name services are modified. For example, if a netgroup is changed or a DNS server is found to have corrupt maps. If the access cache is found to have stale data, then either parts of it or all of it must be flushed. If the stale data applies to only a few exports, then each may be flushed with the exportfs -f pathname command. The entire cache may be cleared with the exportfs -f command.
Note that the same effect may be had by using commands to reload the exports table. In prior versions of ONTAP, either the exportfs -au; exportfs -a command sequence or a simple exportfs -a command was commonly used to clear away exports issues. While these can be used to clear the access cache, they can also result in extra work and lead to very small windows when an export is unavailable.
All mount requests, and NFS requests, come across the wire with an IP address and not the hostname. In order for an address to be converted to a name, a reverse lookup must be performed. Depending on the contents and ordering in
/etc/nsswitch.conf, DNS, NIS, and/or
/etc/hosts may be examined to determine the mapping.
A common problem with reverse DNS lookups is the existence of a mapping from name to IP, but not IP to name.
The option nfs.mountd.trace can be turned on to help debug access requests. Note that as this option can be very verbose and it writes to the syslog, care should be taken to only enable it while trying to resolve an access problem.
Another useful tool is to use exportfs -c to check for access permissions.
All exported pathnames which do not begin with a leading "/vol/" or "/etc/" pathname are being deprecated.
Exporting the root volume as / can be misleading to some automounters.
/etc/hosts host name database
/etc/nsswitch.conf determines name resolution search order
exportfs
, reboot
, hosts
, netgroup
, nsswitch.conf
, options
, passwd
Table of Contents
Read more... (3474 words, estimated 13:54 mins reading time)
Manual Pages exports, man, manual, NetApp, ONTAP
