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.