file_id.txt

   1 Lustre File Identifiers
   2 ~~~~~~~~~~~~~~~~~~~~~~~
   3 [[struct-lu-fid]]
   4
   5 Each resource stored on a target is assigned an identifier that is
   6 unique to that resource.
   7
   8 [source,c]
   9 --------
  10 struct lu_fid {
  11         __u64 f_seq;
  12         __u32 f_oid;
  13         __u32 f_ver;
  14 };
  15 --------
  16
  17 A file identifier ('FID') is a 128-bit numbers that uniquely identifies a
  18 single file or directory on an MDTs or OSTs within a single Lustre file
  19 system. The FID for a Lustre file or directory is the FID from the
  20 corresponding MDT entry for the file. Each of the data resource for that
  21 file will also have a FID for each corresponding OST resource on which the
  22 file stores data.
  23
  24 The 'f_seq' field holds the sequence number, or SEQ, and is used in
  25 conjunction with the 'FID location database' (FLDB) to
  26 determine on which target the resource is located.  All resources with the
  27 same 'f_seq' value will be on the same target. A target can have more
  28 than one 'f_seq' value assigned to it.
  29
  30 The 'f_oid' field holds the unique 'object identifier' (OID) within the
  31 sequence to identify a particular object.
  32
  33 The 'f_ver' value identifies which version of a resource is being
  34 identified, in the event that the resource is being updated, and
  35 different hosts might be referring to different versions of the same
  36 resource. It has never been used as of Lustre 2.8.
  37
  38 ----
  39 enum fid_seq {
  40         FID_SEQ_OST_MDT0        = 0,
  41         FID_SEQ_LLOG            = 1, /* unnamed llogs */
  42         FID_SEQ_ECHO            = 2,
  43         FID_SEQ_UNUSED_START    = 3,
  44         FID_SEQ_UNUSED_END      = 9,
  45         FID_SEQ_LLOG_NAME       = 10, /* named llogs */
  46         FID_SEQ_RSVD            = 11,
  47         FID_SEQ_IGIF            = 12,
  48         FID_SEQ_IGIF_MAX        = 0x0ffffffffULL,
  49         FID_SEQ_IDIF            = 0x100000000ULL,
  50         FID_SEQ_IDIF_MAX        = 0x1ffffffffULL,
  51         /* Normal FID sequence starts from this value, i.e. 1<<33 */
  52         FID_SEQ_START           = 0x200000000ULL,
  53         /* sequence for local pre-defined FIDs listed in local_oid */
  54         FID_SEQ_LOCAL_FILE      = 0x200000001ULL,
  55         FID_SEQ_DOT_LUSTRE      = 0x200000002ULL,
  56         /* sequence is used for local named objects FIDs generated
  57          * by local_object_storage library */
  58         FID_SEQ_LOCAL_NAME      = 0x200000003ULL,
  59         /* Because current FLD will only cache the fid sequence, instead
  60          * of oid on the client side, if the FID needs to be exposed to
  61          * clients sides, it needs to make sure all of fids under one
  62          * sequence will be located in one MDT. */
  63         FID_SEQ_SPECIAL         = 0x200000004ULL,
  64         FID_SEQ_QUOTA           = 0x200000005ULL,
  65         FID_SEQ_QUOTA_GLB       = 0x200000006ULL,
  66         FID_SEQ_ROOT            = 0x200000007ULL,  /* Located on MDT0 */
  67         FID_SEQ_LAYOUT_RBTREE   = 0x200000008ULL,
  68         /* sequence is used for update logs of cross-MDT operation */
  69         FID_SEQ_UPDATE_LOG      = 0x200000009ULL,
  70         /* Sequence is used for the directory under which update logs
  71          * are created. */
  72         FID_SEQ_UPDATE_LOG_DIR  = 0x20000000aULL,
  73         FID_SEQ_NORMAL          = 0x200000400ULL,
  74         FID_SEQ_LOV_DEFAULT     = 0xffffffffffffffffULL
  75 };
  76 ----
  77
  78 There are several reserved ranges of FID sequence values, to allow for
  79 interoperability with older Lustre filesystems, to identify "well known"
  80 objects for internal or external use, as well as for future expansion.
  81
  82 The 'FID_SEQ_OST_MDT0' (0x0) range is reserved for OST objects created
  83 by MDT0 in non-DNE filesystems.  Since all such OST objects used an
  84 'f_seq' value of zero these FIDs are not unique across the filesystem,
  85 but the reservation of 'FID_SEQ_OST_MDT0' allows these FIDs to co-exist
  86 with other FIDs in the same 128-bit identifier space.
  87
  88 The 'FID_SEQ_LLOG' (0x1) range is reserved for unnamed Lustre log (llog)
  89 files, used only internally on the MDS since Lustre 2.4, but previously
  90 exposed over the network.
  91
  92 The 'FID_SEQ_ECHO' (0x2) range is used for temporary objects for
  93 testing purposes such as obdfiler-survey.
  94
  95 The 'FID_SEQ_LLOG_NAME' (0x10) range is used for named llog files such
  96 as configuration logs and the ChangeLog.
  97
  98 The 'FID_SEQ_IGIF' (0xb-0xffffffff) range is reserved for 'inode and
  99 generation in FID' (IGIF) inodes allocated by MDSes before Lustre 2.0.
 100 This corresponds to the 4 billion maximum inode number that could be
 101 allocated for such filesystems.  The 'f_oid' field for IGIF FIDs
 102 contains the inode version number, and as such there is normally only
 103 a single object for each 'f_seq' value.
 104
 105 The 'FID_SEQ_IDIF' (0x100000000-0x1fffffffff) range is reserved for
 106 mapping OST objects that were created by MDT0 using 'FID_SEQ_OST_MDT0'
 107 to filesystem-unique FIDs.  The second 16-bit field (bits 16-31) of the
 108 'f_seq' field contains the OST index (0-65535).  The low 16-bit field
 109 (bits 0-15) of 'f_seq' contains the high (bits 32-47) bits of the OST
 110 object ID, and the 32-bit 'f_oid' field contains the low 32 bits of
 111 the OST object ID.
 112
 113 The 'FID_SEQ_LOCAL_FILE' (0x200000001) range is reserved for "well
 114 known" objects internal to the server and is not exposed to the network.
 115
 116 The 'FID_SEQ_DOT_LUSTRE' (0x200000002) range is reserved for files
 117 under the hidden ".lustre" directory in the root of the filesystem.
 118
 119 The 'FID_SEQ_LOCAL_NAME' (0x200000003) range is reserved for objects
 120 internal to the server that are allocated by name.
 121
 122 The 'FID_SEQ_NORMAL' (0x200000400+) range is used for normal object
 123 identifiers.  These objects are visible in the namespace if allocated
 124 by an MDT, or may be OST objects.