Extend the exportfs interface to pass fslocations info into the kernel.

[nfs-utils.git] / utils / exportfs / exports.man

diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
index 3ab11163ea04f3016f5da937cca8a9270aaf7d37..27a30f9448a73abe3aaba240cd0c2dfd4845d7f6 100644 (file)
--- a/utils/exportfs/exports.man
+++ b/utils/exportfs/exports.man
@@ -126,7 +126,7 @@ default.  In all subsequence releases,
 .I sync
 is the default, and
 .I async
-must be explicit requested if needed.
+must be explicitly requested if needed.
 To help make system administrators aware of this change, 'exportfs'
 will issue a warning if neither
 .I sync
@@ -306,26 +306,47 @@ 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).
 
-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.
+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.
 
-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).
+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.
 
-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
@@ -504,7 +525,7 @@ is supposedly that of user joe).
 /usr            *.local.domain(ro) @trusted(rw)
 /home/joe       pc001(rw,all_squash,anonuid=150,anongid=100)
 /pub            (ro,insecure,all_squash)
-/srv/www        -sync,rw server @trusted @external(ro)
+/srv/www        \-sync,rw server @trusted @external(ro)
 '''/pub/private    (noaccess)
 .fi
 .PP