Lustre File Identifiers
~~~~~~~~~~~~~~~~~~~~~~~
[[struct-lu-fid]]

Each resource stored on a target is assigned an identifier that is
unique to that resource.

[source,c]
--------
struct lu_fid {
	__u64 f_seq;
	__u32 f_oid;
	__u32 f_ver;
};
--------

A file identifier ('FID') is a 128-bit numbers that uniquely identifies a
single file or directory on an MDTs or OSTs within a single Lustre file
system. The FID for a Lustre file or directory is the FID from the
corresponding MDT entry for the file. Each of the data resource for that
file will also have a FID for each corresponding OST resource on which the
file stores data.

The 'f_seq' field holds the sequence number, or SEQ, and is used in
conjunction with the 'FID location database' (FLDB) to
determine on which target the resource is located.  All resources with the
same 'f_seq' value will be on the same target. A target can have more
than one 'f_seq' value assigned to it.

The 'f_oid' field holds the unique 'object identifier' (OID) within the
sequence to identify a particular object.

The 'f_ver' value identifies which version of a resource is being
identified, in the event that the resource is being updated, and
different hosts might be referring to different versions of the same
resource. It has never been used as of Lustre 2.8.

----
enum fid_seq {
	FID_SEQ_OST_MDT0	= 0,
	FID_SEQ_LLOG		= 1, /* unnamed llogs */
	FID_SEQ_ECHO		= 2,
	FID_SEQ_UNUSED_START	= 3,
	FID_SEQ_UNUSED_END	= 9,
	FID_SEQ_LLOG_NAME	= 10, /* named llogs */
	FID_SEQ_RSVD		= 11,
	FID_SEQ_IGIF		= 12,
	FID_SEQ_IGIF_MAX	= 0x0ffffffffULL,
	FID_SEQ_IDIF		= 0x100000000ULL,
	FID_SEQ_IDIF_MAX	= 0x1ffffffffULL,
	/* Normal FID sequence starts from this value, i.e. 1<<33 */
	FID_SEQ_START		= 0x200000000ULL,
	/* sequence for local pre-defined FIDs listed in local_oid */
	FID_SEQ_LOCAL_FILE	= 0x200000001ULL,
	FID_SEQ_DOT_LUSTRE	= 0x200000002ULL,
	/* sequence is used for local named objects FIDs generated
	 * by local_object_storage library */
	FID_SEQ_LOCAL_NAME	= 0x200000003ULL,
	/* Because current FLD will only cache the fid sequence, instead
	 * of oid on the client side, if the FID needs to be exposed to
	 * clients sides, it needs to make sure all of fids under one
	 * sequence will be located in one MDT. */
	FID_SEQ_SPECIAL		= 0x200000004ULL,
	FID_SEQ_QUOTA		= 0x200000005ULL,
	FID_SEQ_QUOTA_GLB	= 0x200000006ULL,
	FID_SEQ_ROOT		= 0x200000007ULL,  /* Located on MDT0 */
	FID_SEQ_LAYOUT_RBTREE	= 0x200000008ULL,
	/* sequence is used for update logs of cross-MDT operation */
	FID_SEQ_UPDATE_LOG	= 0x200000009ULL,
	/* Sequence is used for the directory under which update logs
	 * are created. */
	FID_SEQ_UPDATE_LOG_DIR	= 0x20000000aULL,
	FID_SEQ_NORMAL		= 0x200000400ULL,
	FID_SEQ_LOV_DEFAULT	= 0xffffffffffffffffULL
};
----

There are several reserved ranges of FID sequence values, to allow for
interoperability with older Lustre filesystems, to identify "well known"
objects for internal or external use, as well as for future expansion.

The 'FID_SEQ_OST_MDT0' (0x0) range is reserved for OST objects created
by MDT0 in non-DNE filesystems.  Since all such OST objects used an
'f_seq' value of zero these FIDs are not unique across the filesystem,
but the reservation of 'FID_SEQ_OST_MDT0' allows these FIDs to co-exist
with other FIDs in the same 128-bit identifier space.

The 'FID_SEQ_LLOG' (0x1) range is reserved for unnamed Lustre log (llog)
files, used only internally on the MDS since Lustre 2.4, but previously
exposed over the network.

The 'FID_SEQ_ECHO' (0x2) range is used for temporary objects for
testing purposes such as obdfiler-survey.

The 'FID_SEQ_LLOG_NAME' (0x10) range is used for named llog files such
as configuration logs and the ChangeLog.

The 'FID_SEQ_IGIF' (0xb-0xffffffff) range is reserved for 'inode and
generation in FID' (IGIF) inodes allocated by MDSes before Lustre 2.0.
This corresponds to the 4 billion maximum inode number that could be
allocated for such filesystems.  The 'f_oid' field for IGIF FIDs
contains the inode version number, and as such there is normally only
a single object for each 'f_seq' value.

The 'FID_SEQ_IDIF' (0x100000000-0x1fffffffff) range is reserved for
mapping OST objects that were created by MDT0 using 'FID_SEQ_OST_MDT0'
to filesystem-unique FIDs.  The second 16-bit field (bits 16-31) of the
'f_seq' field contains the OST index (0-65535).  The low 16-bit field
(bits 0-15) of 'f_seq' contains the high (bits 32-47) bits of the OST
object ID, and the 32-bit 'f_oid' field contains the low 32 bits of
the OST object ID.

The 'FID_SEQ_LOCAL_FILE' (0x200000001) range is reserved for "well
known" objects internal to the server and is not exposed to the network.

The 'FID_SEQ_DOT_LUSTRE' (0x200000002) range is reserved for files
under the hidden ".lustre" directory in the root of the filesystem.

The 'FID_SEQ_LOCAL_NAME' (0x200000003) range is reserved for objects
internal to the server that are allocated by name.

The 'FID_SEQ_NORMAL' (0x200000400+) range is used for normal object
identifiers.  These objects are visible in the namespace if allocated
by an MDT, or may be OST objects.