tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
nfs: reexport documentation
We've supported reexport for a while but documentation is limited. This
is mainly a simplified version of the text I wrote for the linux-nfs
wiki at https://wiki.linux-nfs.org/wiki/index.php/NFS_re-export.
Signed-off-by: J. Bruce Fields <bfields@redhat.com>
+114
+1
Documentation/filesystems/nfs/index.rst
+1
Documentation/filesystems/nfs/index.rst
+113
Documentation/filesystems/nfs/reexport.rst
+113
Documentation/filesystems/nfs/reexport.rst
···
1
+
Reexporting NFS filesystems
2
+
===========================
3
+
4
+
Overview
5
+
--------
6
+
7
+
It is possible to reexport an NFS filesystem over NFS. However, this
8
+
feature comes with a number of limitations. Before trying it, we
9
+
recommend some careful research to determine whether it will work for
10
+
your purposes.
11
+
12
+
A discussion of current known limitations follows.
13
+
14
+
"fsid=" required, crossmnt broken
15
+
---------------------------------
16
+
17
+
We require the "fsid=" export option on any reexport of an NFS
18
+
filesystem. You can use "uuidgen -r" to generate a unique argument.
19
+
20
+
The "crossmnt" export does not propagate "fsid=", so it will not allow
21
+
traversing into further nfs filesystems; if you wish to export nfs
22
+
filesystems mounted under the exported filesystem, you'll need to export
23
+
them explicitly, assigning each its own unique "fsid= option.
24
+
25
+
Reboot recovery
26
+
---------------
27
+
28
+
The NFS protocol's normal reboot recovery mechanisms don't work for the
29
+
case when the reexport server reboots. Clients will lose any locks
30
+
they held before the reboot, and further IO will result in errors.
31
+
Closing and reopening files should clear the errors.
32
+
33
+
Filehandle limits
34
+
-----------------
35
+
36
+
If the original server uses an X byte filehandle for a given object, the
37
+
reexport server's filehandle for the reexported object will be X+22
38
+
bytes, rounded up to the nearest multiple of four bytes.
39
+
40
+
The result must fit into the RFC-mandated filehandle size limits:
41
+
42
+
+-------+-----------+
43
+
| NFSv2 | 32 bytes |
44
+
+-------+-----------+
45
+
| NFSv3 | 64 bytes |
46
+
+-------+-----------+
47
+
| NFSv4 | 128 bytes |
48
+
+-------+-----------+
49
+
50
+
So, for example, you will only be able to reexport a filesystem over
51
+
NFSv2 if the original server gives you filehandles that fit in 10
52
+
bytes--which is unlikely.
53
+
54
+
In general there's no way to know the maximum filehandle size given out
55
+
by an NFS server without asking the server vendor.
56
+
57
+
But the following table gives a few examples. The first column is the
58
+
typical length of the filehandle from a Linux server exporting the given
59
+
filesystem, the second is the length after that nfs export is reexported
60
+
by another Linux host:
61
+
62
+
+--------+-------------------+----------------+
63
+
| | filehandle length | after reexport |
64
+
+========+===================+================+
65
+
| ext4: | 28 bytes | 52 bytes |
66
+
+--------+-------------------+----------------+
67
+
| xfs: | 32 bytes | 56 bytes |
68
+
+--------+-------------------+----------------+
69
+
| btrfs: | 40 bytes | 64 bytes |
70
+
+--------+-------------------+----------------+
71
+
72
+
All will therefore fit in an NFSv3 or NFSv4 filehandle after reexport,
73
+
but none are reexportable over NFSv2.
74
+
75
+
Linux server filehandles are a bit more complicated than this, though;
76
+
for example:
77
+
78
+
- The (non-default) "subtreecheck" export option generally
79
+
requires another 4 to 8 bytes in the filehandle.
80
+
- If you export a subdirectory of a filesystem (instead of
81
+
exporting the filesystem root), that also usually adds 4 to 8
82
+
bytes.
83
+
- If you export over NFSv2, knfsd usually uses a shorter
84
+
filesystem identifier that saves 8 bytes.
85
+
- The root directory of an export uses a filehandle that is
86
+
shorter.
87
+
88
+
As you can see, the 128-byte NFSv4 filehandle is large enough that
89
+
you're unlikely to have trouble using NFSv4 to reexport any filesystem
90
+
exported from a Linux server. In general, if the original server is
91
+
something that also supports NFSv3, you're *probably* OK. Re-exporting
92
+
over NFSv3 may be dicier, and reexporting over NFSv2 will probably
93
+
never work.
94
+
95
+
For more details of Linux filehandle structure, the best reference is
96
+
the source code and comments; see in particular:
97
+
98
+
- include/linux/exportfs.h:enum fid_type
99
+
- include/uapi/linux/nfsd/nfsfh.h:struct nfs_fhbase_new
100
+
- fs/nfsd/nfsfh.c:set_version_and_fsid_type
101
+
- fs/nfs/export.c:nfs_encode_fh
102
+
103
+
Open DENY bits ignored
104
+
----------------------
105
+
106
+
NFS since NFSv4 supports ALLOW and DENY bits taken from Windows, which
107
+
allow you, for example, to open a file in a mode which forbids other
108
+
read opens or write opens. The Linux client doesn't use them, and the
109
+
server's support has always been incomplete: they are enforced only
110
+
against other NFS users, not against processes accessing the exported
111
+
filesystem locally. A reexport server will also not pass them along to
112
+
the original server, so they will not be enforced between clients of
113
+
different reexport servers.