src/ceph/doc/dev/mds_internals/exports.rst

   1
   2 ===============
   3 Subtree exports
   4 ===============
   5
   6 Normal Migration
   7 ----------------
   8
   9 The exporter begins by doing some checks in export_dir() to verify
  10 that it is permissible to export the subtree at this time.  In
  11 particular, the cluster must not be degraded, the subtree root may not
  12 be freezing or frozen (\ie already exporting, or nested beneath
  13 something that is exporting), and the path must be pinned (\ie not
  14 conflicted with a rename).  If these conditions are met, the subtree
  15 freeze is initiated, and the exporter is committed to the subtree
  16 migration, barring an intervening failure of the importer or itself.
  17
  18 The MExportDirDiscover serves simply to ensure that the base directory
  19 being exported is open on the destination node.  It is pinned by the
  20 importer to prevent it from being trimmed.  This occurs before the
  21 exporter completes the freeze of the subtree to ensure that the
  22 importer is able to replicate the necessary metadata.  When the
  23 exporter receives the MExportDirDiscoverAck, it allows the freeze to proceed.
  24
  25 The MExportDirPrep message then follows to populate a spanning tree that
  26 includes all dirs, inodes, and dentries necessary to reach any nested
  27 exports within the exported region.  This replicates metadata as well,
  28 but it is pushed out by the exporter, avoiding deadlock with the
  29 regular discover and replication process.  The importer is responsible
  30 for opening the bounding directories from any third parties before
  31 acknowledging.  This ensures that the importer has correct dir_auth
  32 information about where authority is delegated for all points nested
  33 within the subtree being migrated.  While processing the MExportDirPrep,
  34 the importer freezes the entire subtree region to prevent any new
  35 replication or cache expiration.
  36
  37 The warning stage occurs only if the base subtree directory is open by
  38 nodes other than the importer and exporter.  If so, then a
  39 MExportDirNotify message informs any bystanders that the authority for
  40 the region is temporarily ambiguous.  In particular, bystanders who
  41 are trimming items from their cache must send MCacheExpire messages to
  42 both the old and new authorities.  This is necessary to ensure that
  43 the surviving authority reliably receives all expirations even if the
  44 importer or exporter fails.  While the subtree is frozen (on both the
  45 importer and exporter), expirations will not be immediately processed;
  46 instead, they will be queued until the region is unfrozen and it can
  47 be determined that the node is or is not authoritative for the region.
  48
  49 The MExportDir message sends the actual subtree metadata to the importer.
  50 Upon receipt, the importer inserts the data into its cache, logs a
  51 copy in the EImportStart, and replies with an MExportDirAck.  The exporter
  52 can now log an EExport, which ultimately specifies that
  53 the export was a success.  In the presence of failures, it is the
  54 existence  of the EExport that disambiguates authority during recovery.
  55
  56 Once logged, the exporter will send an MExportDirNotify to any
  57 bystanders, informing them that the authority is no longer ambiguous
  58 and cache expirations should be sent only to the new authority (the
  59 importer).  Once these are acknowledged, implicitly flushing the
  60 bystander to exporter message streams of any stray expiration notices,
  61 the exporter unfreezes the subtree, cleans up its state, and sends a
  62 final MExportDirFinish to the importer.  Upon receipt, the importer logs
  63 an EImportFinish(true), unfreezes its subtree, and cleans up its
  64 state.
  65
  66
  67 PARTIAL FAILURE RECOVERY
  68
  69
  70
  71 RECOVERY FROM JOURNAL
  72
  73
  74
  75
  76