| 1 |
.\"@(#)exports.5" |
| 2 |
.\" |
| 3 |
.TH exports 5 "31 December 2009" |
| 4 |
.SH NAME |
| 5 |
exports \- NFS server export table |
| 6 |
.SH DESCRIPTION |
| 7 |
The file |
| 8 |
.I /etc/exports |
| 9 |
contains a table of local physical file systems on an NFS server |
| 10 |
that are accessible to NFS clients. |
| 11 |
The contents of the file are maintained by the server's system |
| 12 |
administrator. |
| 13 |
.PP |
| 14 |
Each file system in this table has a list of options and an |
| 15 |
access control list. |
| 16 |
The table is used by |
| 17 |
.BR exportfs (8) |
| 18 |
to give information to |
| 19 |
.BR mountd (8). |
| 20 |
.PP |
| 21 |
The file format is similar to the SunOS |
| 22 |
.I exports |
| 23 |
file. Each line contains an export point and a whitespace-separated list |
| 24 |
of clients allowed to mount the file system at that point. Each listed |
| 25 |
client may be immediately followed by a parenthesized, comma-separated |
| 26 |
list of export options for that client. No whitespace is permitted |
| 27 |
between a client and its option list. |
| 28 |
.PP |
| 29 |
Also, each line may have one or more specifications for default options |
| 30 |
after the path name, in the form of a dash ("\-") followed by an option |
| 31 |
list. The option list is used for all subsequent exports on that line |
| 32 |
only. |
| 33 |
.PP |
| 34 |
Blank lines are ignored. A pound sign ("#") introduces a comment to the |
| 35 |
end of the line. Entries may be continued across newlines using a |
| 36 |
backslash. If an export name contains spaces it should be quoted using |
| 37 |
double quotes. You can also specify spaces or other unusual character in |
| 38 |
the export name using a backslash followed by the character code as three |
| 39 |
octal digits. |
| 40 |
.PP |
| 41 |
To apply changes to this file, run |
| 42 |
.BR "exportfs \-ra" |
| 43 |
or restart the NFS server. |
| 44 |
.PP |
| 45 |
.SS Machine Name Formats |
| 46 |
NFS clients may be specified in a number of ways: |
| 47 |
.IP "single host |
| 48 |
You may specify a host either by an |
| 49 |
abbreviated name recognized be the resolver, the fully qualified domain |
| 50 |
name, an IPv4 address, or an IPv6 address. IPv6 addresses must not be |
| 51 |
inside square brackets in /etc/exports lest they be confused with |
| 52 |
character-class wildcard matches. |
| 53 |
.IP "IP networks |
| 54 |
You can also export directories to all hosts on an IP (sub-) network |
| 55 |
simultaneously. This is done by specifying an IP address and netmask pair |
| 56 |
as |
| 57 |
.IR address/netmask |
| 58 |
where the netmask can be specified in dotted-decimal format, or as a |
| 59 |
contiguous mask length. |
| 60 |
For example, either `/255.255.252.0' or `/22' appended |
| 61 |
to the network base IPv4 address results in identical subnetworks with 10 bits |
| 62 |
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 |
| 63 |
may work by accident when reverse DNS lookups fail. |
| 64 |
.IP "wildcards |
| 65 |
Machine names may contain the wildcard characters \fI*\fR and \fI?\fR, or may contain character class lists within [square brackets]. |
| 66 |
This can be used to make the \fIexports\fR file more compact; for instance, |
| 67 |
\fI*.cs.foo.edu\fR matches all hosts in the domain |
| 68 |
\fIcs.foo.edu\fR. As these characters also match the dots in a domain |
| 69 |
name, the given pattern will also match all hosts within any subdomain |
| 70 |
of \fIcs.foo.edu\fR. |
| 71 |
.IP "netgroups |
| 72 |
NIS netgroups may be given as |
| 73 |
.IR @group . |
| 74 |
Only the host part of each |
| 75 |
netgroup members is consider in checking for membership. Empty host |
| 76 |
parts or those containing a single dash (\-) are ignored. |
| 77 |
.IP "anonymous |
| 78 |
This is specified by a single |
| 79 |
.I * |
| 80 |
character (not to be confused with the |
| 81 |
.I wildcard |
| 82 |
entry above) and will match all clients. |
| 83 |
.\".TP |
| 84 |
.\".B =public |
| 85 |
.\"This is a special ``hostname'' that identifies the given directory name |
| 86 |
.\"as the public root directory (see the section on WebNFS in |
| 87 |
.\".BR nfsd (8) |
| 88 |
.\"for a discussion of WebNFS and the public root handle). When using this |
| 89 |
.\"convention, |
| 90 |
.\".B =public |
| 91 |
.\"must be the only entry on this line, and must have no export options |
| 92 |
.\"associated with it. Note that this does |
| 93 |
.\".I not |
| 94 |
.\"actually export the named directory; you still have to set the exports |
| 95 |
.\"options in a separate entry. |
| 96 |
.\".PP |
| 97 |
.\"The public root path can also be specified by invoking |
| 98 |
.\".I nfsd |
| 99 |
.\"with the |
| 100 |
.\".B \-\-public\-root |
| 101 |
.\"option. Multiple specifications of a public root will be ignored. |
| 102 |
.PP |
| 103 |
If a client matches more than one of the specifications above, then |
| 104 |
the first match from the above list order takes precedence - regardless of |
| 105 |
the order they appear on the export line. However, if a client matches |
| 106 |
more than one of the same type of specification (e.g. two netgroups), |
| 107 |
then the first match from the order they appear on the export line takes |
| 108 |
precedence. |
| 109 |
.SS RPCSEC_GSS security |
| 110 |
You may use the special strings "gss/krb5", "gss/krb5i", or "gss/krb5p" |
| 111 |
to restrict access to clients using rpcsec_gss security. However, this |
| 112 |
syntax is deprecated; on linux kernels since 2.6.23, you should instead |
| 113 |
use the "sec=" export option: |
| 114 |
.TP |
| 115 |
.IR sec= |
| 116 |
The sec= option, followed by a colon-delimited list of security flavors, |
| 117 |
restricts the export to clients using those flavors. Available security |
| 118 |
flavors include sys (the default--no cryptographic security), krb5 |
| 119 |
(authentication only), krb5i (integrity protection), and krb5p (privacy |
| 120 |
protection). For the purposes of security flavor negotiation, order |
| 121 |
counts: preferred flavors should be listed first. The order of the sec= |
| 122 |
option with respect to the other options does not matter, unless you |
| 123 |
want some options to be enforced differently depending on flavor. |
| 124 |
In that case you may include multiple sec= options, and following options |
| 125 |
will be enforced only for access using flavors listed in the immediately |
| 126 |
preceding sec= option. The only options that are permitted to vary in |
| 127 |
this way are ro, rw, no_root_squash, root_squash, and all_squash. |
| 128 |
.SS Transport layer security |
| 129 |
The Linux NFS server allows the use of RPC-with-TLS (RFC 9289) to |
| 130 |
protect RPC traffic between itself and its clients. |
| 131 |
Alternately, administrators can secure NFS traffic using a VPN, |
| 132 |
or an ssh tunnel or similar mechanism, in a way that is transparent |
| 133 |
to the server. |
| 134 |
.PP |
| 135 |
To enable the use of RPC-with-TLS, the server's administrator must |
| 136 |
install and configure |
| 137 |
.BR tlshd |
| 138 |
to handle transport layer security handshake requests from the local |
| 139 |
kernel. |
| 140 |
Clients can then choose to use RPC-with-TLS or they may continue |
| 141 |
operating without it. |
| 142 |
.PP |
| 143 |
Administrators may require the use of RPC-with-TLS to protect access |
| 144 |
to individual exports. |
| 145 |
This is particularly useful when using non-cryptographic security |
| 146 |
flavors such as |
| 147 |
.IR sec=sys . |
| 148 |
The |
| 149 |
.I xprtsec= |
| 150 |
option, followed by an unordered colon-delimited list of security policies, |
| 151 |
can restrict access to the export to only clients that have negotiated |
| 152 |
transport-layer security. |
| 153 |
Currently supported transport layer security policies include: |
| 154 |
.TP |
| 155 |
.IR none |
| 156 |
The server permits clients to access the export |
| 157 |
without the use of transport layer security. |
| 158 |
.TP |
| 159 |
.IR tls |
| 160 |
The server permits clients that have negotiated an RPC-with-TLS session |
| 161 |
without peer authentication (confidentiality only) to access the export. |
| 162 |
Clients are not required to offer an x.509 certificate |
| 163 |
when establishing a transport layer security session. |
| 164 |
.TP |
| 165 |
.IR mtls |
| 166 |
The server permits clients that have negotiated an RPC-with-TLS session |
| 167 |
with peer authentication to access the export. |
| 168 |
The server requires clients to offer an x.509 certificate |
| 169 |
when establishing a transport layer security session. |
| 170 |
.PP |
| 171 |
If RPC-with-TLS is configured and enabled and the |
| 172 |
.I xprtsec= |
| 173 |
option is not specified, the default setting for an export is |
| 174 |
.IR xprtsec=none:tls:mtls . |
| 175 |
With this setting, the server permits clients to use any transport |
| 176 |
layer security mechanism or none at all to access the export. |
| 177 |
.SS General Options |
| 178 |
.BR exportfs |
| 179 |
understands the following export options: |
| 180 |
.TP |
| 181 |
.IR secure |
| 182 |
This option requires that requests not using gss originate on an |
| 183 |
Internet port less than IPPORT_RESERVED (1024). This option is on by default. |
| 184 |
To turn it off, specify |
| 185 |
.IR insecure . |
| 186 |
(NOTE: older kernels (before upstream kernel version 4.17) enforced this |
| 187 |
requirement on gss requests as well.) |
| 188 |
.TP |
| 189 |
.IR rw |
| 190 |
Allow both read and write requests on this NFS volume. The |
| 191 |
default is to disallow any request which changes the filesystem. |
| 192 |
This can also be made explicit by using |
| 193 |
the |
| 194 |
.IR ro " option. |
| 195 |
.TP |
| 196 |
.IR async |
| 197 |
This option allows the NFS server to violate the NFS protocol and |
| 198 |
reply to requests before any changes made by that request have been |
| 199 |
committed to stable storage (e.g. disc drive). |
| 200 |
|
| 201 |
Using this option usually improves performance, but at the cost that |
| 202 |
an unclean server restart (i.e. a crash) can cause data to be lost or |
| 203 |
corrupted. |
| 204 |
|
| 205 |
.TP |
| 206 |
.IR sync |
| 207 |
Reply to requests only after the changes have been committed to stable |
| 208 |
storage (see |
| 209 |
.IR async |
| 210 |
above). |
| 211 |
|
| 212 |
In releases of nfs-utils up to and including 1.0.0, the |
| 213 |
.I async |
| 214 |
option was the |
| 215 |
default. In all releases after 1.0.0, |
| 216 |
.I sync |
| 217 |
is the default, and |
| 218 |
.I async |
| 219 |
must be explicitly requested if needed. |
| 220 |
.TP |
| 221 |
.IR no_wdelay |
| 222 |
This option has no effect if |
| 223 |
.I async |
| 224 |
is also set. The NFS server will normally delay committing a write request |
| 225 |
to disc slightly if it suspects that another related write request may be in |
| 226 |
progress or may arrive soon. This allows multiple write requests to |
| 227 |
be committed to disc with the one operation which can improve |
| 228 |
performance. If an NFS server received mainly small unrelated |
| 229 |
requests, this behaviour could actually reduce performance, so |
| 230 |
.IR no_wdelay |
| 231 |
is available to turn it off. |
| 232 |
The default can be explicitly requested with the |
| 233 |
.IR wdelay " option. |
| 234 |
.TP |
| 235 |
.IR nohide |
| 236 |
This option is based on the option of the same name provided in IRIX |
| 237 |
NFS. Normally, if a server exports two filesystems one of which is |
| 238 |
mounted on the other, then the client will have to mount both |
| 239 |
filesystems explicitly to get access to them. If it just mounts the |
| 240 |
parent, it will see an empty directory at the place where the other |
| 241 |
filesystem is mounted. That filesystem is "hidden". |
| 242 |
|
| 243 |
Setting the |
| 244 |
.I nohide |
| 245 |
option on a filesystem causes it not to be hidden, and an |
| 246 |
appropriately authorised client will be able to move from the parent to |
| 247 |
that filesystem without noticing the change. |
| 248 |
|
| 249 |
However, some NFS clients do not cope well with this situation as, for |
| 250 |
instance, it is then possible for two files in the one apparent |
| 251 |
filesystem to have the same inode number. |
| 252 |
|
| 253 |
The |
| 254 |
.I nohide |
| 255 |
option is currently only effective on |
| 256 |
.I "single host |
| 257 |
exports. It does not work reliably with netgroup, subnet, or wildcard |
| 258 |
exports. |
| 259 |
|
| 260 |
This option can be very useful in some situations, but it should be |
| 261 |
used with due care, and only after confirming that the client system |
| 262 |
copes with the situation effectively. |
| 263 |
|
| 264 |
The option can be explicitly disabled for NFSv2 and NFSv3 with |
| 265 |
.IR hide . |
| 266 |
|
| 267 |
This option is not relevant when NFSv4 is use. NFSv4 never hides |
| 268 |
subordinate filesystems. Any filesystem that is exported will be |
| 269 |
visible where expected when using NFSv4. |
| 270 |
.TP |
| 271 |
.I crossmnt |
| 272 |
This option is similar to |
| 273 |
.I nohide |
| 274 |
but it makes it possible for clients to access all filesystems mounted |
| 275 |
on a filesystem marked with |
| 276 |
.IR crossmnt . |
| 277 |
Thus when a child filesystem "B" is mounted on a parent "A", setting |
| 278 |
crossmnt on "A" has a similar effect to setting "nohide" on B. |
| 279 |
|
| 280 |
With |
| 281 |
.I nohide |
| 282 |
the child filesystem needs to be explicitly exported. With |
| 283 |
.I crossmnt |
| 284 |
it need not. If a child of a |
| 285 |
.I crossmnt |
| 286 |
file is not explicitly exported, then it will be implicitly exported |
| 287 |
with the same export options as the parent, except for |
| 288 |
.IR fsid= . |
| 289 |
This makes it impossible to |
| 290 |
.B not |
| 291 |
export a child of a |
| 292 |
.I crossmnt |
| 293 |
filesystem. If some but not all subordinate filesystems of a parent |
| 294 |
are to be exported, then they must be explicitly exported and the |
| 295 |
parent should not have |
| 296 |
.I crossmnt |
| 297 |
set. |
| 298 |
|
| 299 |
The |
| 300 |
.I nocrossmnt |
| 301 |
option can explicitly disable |
| 302 |
.I crossmnt |
| 303 |
if it was previously set. This is rarely useful. |
| 304 |
.TP |
| 305 |
.IR subtree_check |
| 306 |
This option enables subtree checking, which can have mild security |
| 307 |
benefits, but can decrease reliability in some circumstances. |
| 308 |
|
| 309 |
If a subdirectory of a filesystem is exported, but the whole |
| 310 |
filesystem isn't then whenever a NFS request arrives, the server must |
| 311 |
check not only that the accessed file is in the appropriate filesystem |
| 312 |
(which is easy) but also that it is in the exported tree (which is |
| 313 |
harder). This check is called the |
| 314 |
.IR subtree_check . |
| 315 |
|
| 316 |
In order to perform this check, the server must include some |
| 317 |
information about the location of the file in the "filehandle" that is |
| 318 |
given to the client. This can cause problems with accessing files that |
| 319 |
are renamed while a client has them open (though in many simple cases |
| 320 |
it will still work). |
| 321 |
|
| 322 |
subtree checking is also used to make sure that files inside |
| 323 |
directories to which only root has access can only be accessed if the |
| 324 |
filesystem is exported with |
| 325 |
.I no_root_squash |
| 326 |
(see below), even if the file itself allows more general access. |
| 327 |
|
| 328 |
For more information about the security implications, refer to the |
| 329 |
Subdirectory Exports section. |
| 330 |
|
| 331 |
As a general guide, a home directory filesystem, which is normally |
| 332 |
exported at the root and may see lots of file renames, should be |
| 333 |
exported with subtree checking disabled. A filesystem which is mostly |
| 334 |
readonly, and at least doesn't see many file renames (e.g. /usr or |
| 335 |
/var) and for which subdirectories may be exported, should probably be |
| 336 |
exported with subtree checks enabled. |
| 337 |
|
| 338 |
The default of having subtree checks disabled, can be explicitly |
| 339 |
requested with |
| 340 |
.IR no_subtree_check . |
| 341 |
|
| 342 |
Before release 1.1.0 of nfs-utils, the default was |
| 343 |
.IR subtree_check . |
| 344 |
Since release 1.1.0, the default is |
| 345 |
.I no_subtree_check |
| 346 |
as subtree checking tends to cause more problems than it is worth. |
| 347 |
If you genuinely require subtree checking, you should explicitly put |
| 348 |
that option in the |
| 349 |
.B exports |
| 350 |
file. If you put neither option, |
| 351 |
.B exportfs |
| 352 |
will warn you that the change has occurred. |
| 353 |
|
| 354 |
.TP |
| 355 |
.IR sign_fh |
| 356 |
This option enforces signing filehandles on the export. If the server has |
| 357 |
been configured with a secret key for such purpose, filehandles will include |
| 358 |
a hash to verify the filehandle was created by the server in order to guard |
| 359 |
against filehandle guessing attacks which can bypass path-name based access |
| 360 |
restrictions. Note that for NFSv3 some exported filesystems may exceed the |
| 361 |
maximum filehandle size when the signing hash is added. |
| 362 |
|
| 363 |
.TP |
| 364 |
.IR insecure_locks |
| 365 |
.TP |
| 366 |
.IR no_auth_nlm |
| 367 |
This option (the two names are synonymous) tells the NFS server not to require authentication of |
| 368 |
locking requests (i.e. requests which use the NLM protocol). Normally |
| 369 |
the NFS server will require a lock request to hold a credential for a |
| 370 |
user who has read access to the file. With this flag no access checks |
| 371 |
will be performed. |
| 372 |
|
| 373 |
Early NFS client implementations did not send credentials with lock |
| 374 |
requests, and many current NFS clients still exist which are based on |
| 375 |
the old implementations. Use this flag if you find that you can only |
| 376 |
lock files which are world readable. |
| 377 |
|
| 378 |
The default behaviour of requiring authentication for NLM requests can |
| 379 |
be explicitly requested with either of the synonymous |
| 380 |
.IR auth_nlm , |
| 381 |
or |
| 382 |
.IR secure_locks . |
| 383 |
.\".TP |
| 384 |
.\".I noaccess |
| 385 |
.\"This makes everything below the directory inaccessible for the named |
| 386 |
.\"client. This is useful when you want to export a directory hierarchy to |
| 387 |
.\"a client, but exclude certain subdirectories. The client's view of a |
| 388 |
.\"directory flagged with noaccess is very limited; it is allowed to read |
| 389 |
.\"its attributes, and lookup `.' and `..'. These are also the only entries |
| 390 |
.\"returned by a readdir. |
| 391 |
.\".TP |
| 392 |
.\".IR link_relative |
| 393 |
.\"Convert absolute symbolic links (where the link contents start with a |
| 394 |
.\"slash) into relative links by prepending the necessary number of ../'s |
| 395 |
.\"to get from the directory containing the link to the root on the |
| 396 |
.\"server. This has subtle, perhaps questionable, semantics when the file |
| 397 |
.\"hierarchy is not mounted at its root. |
| 398 |
.\".TP |
| 399 |
.\".IR link_absolute |
| 400 |
.\"Leave all symbolic link as they are. This is the default operation. |
| 401 |
|
| 402 |
.TP |
| 403 |
.IR mountpoint= path |
| 404 |
.TP |
| 405 |
.I mp |
| 406 |
This option makes it possible to only export a directory if it has |
| 407 |
successfully been mounted. |
| 408 |
If no path is given (e.g. |
| 409 |
.IR mountpoint " or " mp ) |
| 410 |
then the export point must also be a mount point. If it isn't then |
| 411 |
the export point is not exported. This allows you to be sure that the |
| 412 |
directory underneath a mountpoint will never be exported by accident |
| 413 |
if, for example, the filesystem failed to mount due to a disc error. |
| 414 |
|
| 415 |
If a path is given (e.g. |
| 416 |
.IR mountpoint= "/path or " mp= /path) |
| 417 |
then the nominated path must be a mountpoint for the exportpoint to be |
| 418 |
exported. |
| 419 |
|
| 420 |
.TP |
| 421 |
.IR fsid= num|root|uuid |
| 422 |
NFS needs to be able to identify each filesystem that it exports. |
| 423 |
Normally it will use a UUID for the filesystem (if the filesystem has |
| 424 |
such a thing) or the device number of the device holding the |
| 425 |
filesystem (if the filesystem is stored on the device). |
| 426 |
|
| 427 |
As not all filesystems are stored on devices, and not all filesystems |
| 428 |
have UUIDs, it is sometimes necessary to explicitly tell NFS how to |
| 429 |
identify a filesystem. This is done with the |
| 430 |
.I fsid= |
| 431 |
option. |
| 432 |
|
| 433 |
For NFSv4, there is a distinguished filesystem which is the root of |
| 434 |
all exported filesystem. This is specified with |
| 435 |
.I fsid=root |
| 436 |
or |
| 437 |
.I fsid=0 |
| 438 |
both of which mean exactly the same thing. |
| 439 |
|
| 440 |
Other filesystems can be identified with a small integer, or a UUID |
| 441 |
which should contain 32 hex digits and arbitrary punctuation. |
| 442 |
|
| 443 |
Linux kernels version 2.6.20 and earlier do not understand the UUID |
| 444 |
setting so a small integer must be used if an fsid option needs to be |
| 445 |
set for such kernels. Setting both a small number and a UUID is |
| 446 |
supported so the same configuration can be made to work on old and new |
| 447 |
kernels alike. |
| 448 |
|
| 449 |
.TP |
| 450 |
.IR nordirplus |
| 451 |
This option will disable READDIRPLUS request handling. When set, |
| 452 |
READDIRPLUS requests from NFS clients return NFS3ERR_NOTSUPP, and |
| 453 |
clients fall back on READDIR. This option affects only NFSv3 clients. |
| 454 |
.TP |
| 455 |
.IR refer= path@host[+host][:path@host[+host]] |
| 456 |
A client referencing the export point will be directed to choose from |
| 457 |
the given list an alternative location for the filesystem. |
| 458 |
(Note that the server must have a mountpoint here, though a different |
| 459 |
filesystem is not required; so, for example, |
| 460 |
.IR "mount --bind" " /path /path" |
| 461 |
is sufficient.) |
| 462 |
|
| 463 |
This option affects only NFSv4 clients. Other clients will ignore |
| 464 |
all "refer=" parts. |
| 465 |
.TP |
| 466 |
.IR replicas= path@host[+host][:path@host[+host]] |
| 467 |
If the client asks for alternative locations for the export point, it |
| 468 |
will be given this list of alternatives. (Note that actual replication |
| 469 |
of the filesystem must be handled elsewhere.) |
| 470 |
|
| 471 |
.TP |
| 472 |
.IR pnfs |
| 473 |
This option enables the use of the pNFS extension if the protocol level |
| 474 |
is NFSv4.1 or higher, and the filesystem supports pNFS exports. With |
| 475 |
pNFS clients can bypass the server and perform I/O directly to storage |
| 476 |
devices. The default can be explicitly requested with the |
| 477 |
.I no_pnfs |
| 478 |
option. |
| 479 |
|
| 480 |
.TP |
| 481 |
.IR security_label |
| 482 |
With this option set, clients using NFSv4.2 or higher will be able to |
| 483 |
set and retrieve security labels (such as those used by SELinux). This |
| 484 |
will only work if all clients use a consistent security policy. Note |
| 485 |
that early kernels did not support this export option, and instead |
| 486 |
enabled security labels by default. |
| 487 |
|
| 488 |
.TP |
| 489 |
.IR reexport= auto-fsidnum|predefined-fsidnum |
| 490 |
This option helps when a NFS share is re-exported. Since the NFS server |
| 491 |
needs a unique identifier for each exported filesystem and a NFS share |
| 492 |
cannot provide such, usually a manual fsid is needed. |
| 493 |
As soon |
| 494 |
.IR crossmnt |
| 495 |
is used manually assigning fsid won't work anymore. This is where this |
| 496 |
option becomes handy. It will automatically assign a numerical fsid |
| 497 |
to exported NFS shares. The fsid and path relations are stored in a SQLite |
| 498 |
database. If |
| 499 |
.IR auto-fsidnum |
| 500 |
is selected, the fsid is also automatically allocated. |
| 501 |
.IR predefined-fsidnum |
| 502 |
assumes pre-allocated fsid numbers and will just look them up. |
| 503 |
This option depends also on the kernel, you will need at least kernel version |
| 504 |
5.19. |
| 505 |
Since |
| 506 |
.IR reexport= |
| 507 |
can automatically allocate and assign numerical fsids, it is no longer possible |
| 508 |
to have numerical fsids in other exports as soon this option is used in at least |
| 509 |
one export entry. |
| 510 |
|
| 511 |
The association between fsid numbers and paths is stored in a SQLite database. |
| 512 |
Don't edit or remove the database unless you know exactly what you're doing. |
| 513 |
.IR predefined-fsidnum |
| 514 |
is useful when you have used |
| 515 |
.IR auto-fsidnum |
| 516 |
before and don't want further entries stored. |
| 517 |
|
| 518 |
|
| 519 |
.SS User ID Mapping |
| 520 |
.PP |
| 521 |
.B nfsd |
| 522 |
bases its access control to files on the server machine on the uid and |
| 523 |
gid provided in each NFS RPC request. The normal behavior a user would |
| 524 |
expect is that she can access her files on the server just as she would |
| 525 |
on a normal file system. This requires that the same uids and gids are |
| 526 |
used on the client and the server machine. This is not always true, nor |
| 527 |
is it always desirable. |
| 528 |
.PP |
| 529 |
Very often, it is not desirable that the root user on a client machine |
| 530 |
is also treated as root when accessing files on the NFS server. To this |
| 531 |
end, uid 0 is normally mapped to a different id: the so-called |
| 532 |
anonymous or |
| 533 |
.I nobody |
| 534 |
uid. This mode of operation (called `root squashing') is the default, |
| 535 |
and can be turned off with |
| 536 |
.IR no_root_squash . |
| 537 |
.PP |
| 538 |
By default, |
| 539 |
.\".B nfsd |
| 540 |
.\"tries to obtain the anonymous uid and gid by looking up user |
| 541 |
.\".I nobody |
| 542 |
.\"in the password file at startup time. If it isn't found, a uid and gid |
| 543 |
.B exportfs |
| 544 |
chooses a uid and gid |
| 545 |
of 65534 for squashed access. These values can also be overridden by |
| 546 |
the |
| 547 |
.IR anonuid " and " anongid |
| 548 |
options. |
| 549 |
.\".PP |
| 550 |
.\"In addition to this, |
| 551 |
.\".B nfsd |
| 552 |
.\"lets you specify arbitrary uids and gids that should be mapped to user |
| 553 |
.\"nobody as well. |
| 554 |
Finally, you can map all user requests to the |
| 555 |
anonymous uid by specifying the |
| 556 |
.IR all_squash " option. |
| 557 |
.PP |
| 558 |
Here's the complete list of mapping options: |
| 559 |
.TP |
| 560 |
.IR root_squash |
| 561 |
Map requests from uid/gid 0 to the anonymous uid/gid. Note that this does |
| 562 |
not apply to any other uids or gids that might be equally sensitive, such as |
| 563 |
user |
| 564 |
.IR bin |
| 565 |
or group |
| 566 |
.IR staff . |
| 567 |
.TP |
| 568 |
.IR no_root_squash |
| 569 |
Turn off root squashing. This option is mainly useful for diskless clients. |
| 570 |
.TP |
| 571 |
.IR all_squash |
| 572 |
Map all uids and gids to the anonymous user. Useful for NFS-exported |
| 573 |
public FTP directories, news spool directories, etc. The opposite option |
| 574 |
is |
| 575 |
.IR no_all_squash , |
| 576 |
which is the default setting. |
| 577 |
.TP |
| 578 |
.IR anonuid " and " anongid |
| 579 |
These options explicitly set the uid and gid of the anonymous account. |
| 580 |
This option is primarily useful for PC/NFS clients, where you might want |
| 581 |
all requests appear to be from one user. As an example, consider the |
| 582 |
export entry for |
| 583 |
.B /home/joe |
| 584 |
in the example section below, which maps all requests to uid 150 (which |
| 585 |
is supposedly that of user joe). |
| 586 |
|
| 587 |
.SS Subdirectory Exports |
| 588 |
|
| 589 |
Normally you should only export only the root of a filesystem. The NFS |
| 590 |
server will also allow you to export a subdirectory of a filesystem, |
| 591 |
however, this has drawbacks: |
| 592 |
|
| 593 |
First, it may be possible for a malicious user to access files on the |
| 594 |
filesystem outside of the exported subdirectory, by guessing filehandles |
| 595 |
for those other files. |
| 596 |
In some cases a malicious user may also be able to access files on other |
| 597 |
filesystems that have not been exported by replacing the exported |
| 598 |
subdirectory with a symbolic link to any other directory. |
| 599 |
The only way to prevent this is by using the |
| 600 |
.IR subtree_check |
| 601 |
option, which can cause other problems. |
| 602 |
|
| 603 |
Second, export options may not be enforced in the way that you would |
| 604 |
expect. For example, the |
| 605 |
.IR security_label |
| 606 |
option will not work on subdirectory exports, and if nested subdirectory |
| 607 |
exports change the |
| 608 |
.IR security_label |
| 609 |
or |
| 610 |
.IR sec= |
| 611 |
options, NFSv4 clients will normally see only the options on the parent |
| 612 |
export. Also, where security options differ, a malicious client may use |
| 613 |
filehandle-guessing attacks to access the files from one subdirectory |
| 614 |
using the options from another. |
| 615 |
|
| 616 |
|
| 617 |
.SS Extra Export Tables |
| 618 |
After reading |
| 619 |
.I /etc/exports |
| 620 |
.B exportfs |
| 621 |
reads files in the |
| 622 |
.I /etc/exports.d |
| 623 |
directory as extra export tables. Only files ending in |
| 624 |
.I .exports |
| 625 |
are considered. Files beginning with a dot are ignored. |
| 626 |
The format for extra export tables is the same as |
| 627 |
.I /etc/exports |
| 628 |
. |
| 629 |
.IP |
| 630 |
.SH EXAMPLE |
| 631 |
.PP |
| 632 |
.nf |
| 633 |
.ta +3i |
| 634 |
# sample /etc/exports file |
| 635 |
/ master(rw) trusty(rw,no_root_squash) |
| 636 |
/projects proj*.local.domain(rw) |
| 637 |
/usr *.local.domain(ro) @trusted(rw) |
| 638 |
/home/joe pc001(rw,all_squash,anonuid=150,anongid=100) |
| 639 |
/pub *(ro,insecure,all_squash) |
| 640 |
/srv/www \-sync,rw server @trusted @external(ro) |
| 641 |
/foo 2001:db8:9:e54::/64(rw) 192.0.2.0/24(rw) |
| 642 |
/build buildhost[0-9].local.domain(rw) |
| 643 |
.\"/pub/private (noaccess) |
| 644 |
.fi |
| 645 |
.PP |
| 646 |
The first line exports the entire filesystem to machines master and trusty. |
| 647 |
In addition to write access, all uid squashing is turned off for host |
| 648 |
trusty. The second and third entry show examples for wildcard hostnames |
| 649 |
and netgroups (this is the entry `@trusted'). The fourth line shows the |
| 650 |
entry for the PC/NFS client discussed above. Line 5 exports the |
| 651 |
public FTP directory to every host in the world, executing all requests |
| 652 |
under the nobody account. The |
| 653 |
.I insecure |
| 654 |
option in this entry also allows clients with NFS implementations that |
| 655 |
don't use a reserved port for NFS. |
| 656 |
The sixth line exports a directory read-write to the machine 'server' |
| 657 |
as well as the `@trusted' netgroup, and read-only to netgroup `@external', |
| 658 |
all three mounts with the `sync' option enabled. The seventh line exports |
| 659 |
a directory to both an IPv6 and an IPv4 subnet. The eighth line demonstrates |
| 660 |
a character class wildcard match. |
| 661 |
.\" The last line denies all NFS clients |
| 662 |
.\"access to the private directory. |
| 663 |
.\".SH CAVEATS |
| 664 |
.\"Unlike other NFS server implementations, this |
| 665 |
.\".B nfsd |
| 666 |
.\"allows you to export both a directory and a subdirectory thereof to |
| 667 |
.\"the same host, for instance |
| 668 |
.\".IR /usr " and " /usr/X11R6 . |
| 669 |
.\"In this case, the mount options of the most specific entry apply. For |
| 670 |
.\"instance, when a user on the client host accesses a file in |
| 671 |
.\".IR /usr/X11R6 , |
| 672 |
.\"the mount options given in the |
| 673 |
.\".I /usr/X11R6 |
| 674 |
.\"entry apply. This is also true when the latter is a wildcard or netgroup |
| 675 |
.\"entry. |
| 676 |
.SH FILES |
| 677 |
/etc/exports |
| 678 |
/etc/exports.d |
| 679 |
.SH SEE ALSO |
| 680 |
.BR exportfs (8), |
| 681 |
.BR netgroup (5), |
| 682 |
.BR mountd (8), |
| 683 |
.BR nfsd (8), |
| 684 |
.BR showmount (8), |
| 685 |
.BR tlshd (8). |
| 686 |
.\".SH DIAGNOSTICS |
| 687 |
.\"An error parsing the file is reported using syslogd(8) as level NOTICE from |
| 688 |
.\"a DAEMON whenever |
| 689 |
.\".BR nfsd (8) |
| 690 |
.\"or |
| 691 |
.\".BR mountd (8) |
| 692 |
.\"is started up. Any unknown |
| 693 |
.\"host is reported at that time, but often not all hosts are not yet known |
| 694 |
.\"to |
| 695 |
.\".BR named (8) |
| 696 |
.\"at boot time, thus as hosts are found they are reported |
| 697 |
.\"with the same |
| 698 |
.\".BR syslogd (8) |
| 699 |
.\"parameters. |