RPC 38: MDS CONNECT - Client connection to an MDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[mds-connect-rpc]]

.MDS_CONNECT (38)
[options="header"]
|====
| request
| ptlrpc_body | tgt_uuid | client_uuid | lustre_handle | obd_connect_data |
|
| reply
| ptlrpc_body | obd_connect_data |
|====

N.B. This is nearly identical to the explanation for OST_CONNECT and
for MGS_CONNECT.  We may want to simplify and/or unify the discussion
and only call out how this one differs from a generic CONNECT
operation.

When a client initiates a connection to a specific target on an MDS,
it does so by sending an 'obd_connect_client' message and awaiting the
reply from the MDS of an 'obd_connect_server' message. From a previous
interaction with the MGS the client knows the UUID of the target MDT,
and must fill that value into the 'tgt_uuid' buffer of the request.

The 'client_uuid' buffer holds the randomly-generated 128-bit UUID of
the client.  The 'client_uuid' is unique for each mount of the client.
Even if the same client mounts the same filesystem multiple times it
will generate a new 'client_uuid' value for each mount.

The 'lustre_handle' buffer contains the cookie for this connection,
and is zero for a new mount.  If the client is reconnecting to a
server after a loss of communication, the 'lustre_handle' contains
the connection cookie previously assigned by the server and returned
to the client in the reply.  This allows the server to determine if
the client connection matches any previous connection from this client.

The 'ocd_connect_flags' buffer is initialized to the set of features
that the client supports for metadata targets.  For Lustre 2.7 clients
these features are OBD_CONNECT_IBITS, OBD_CONNECT_NODEVOH,
OBD_CONNECT_ATTRFID, OBD_CONNECT_VERSION, OBD_CONNECT_BRW_SIZE,
OBD_CONNECT_CANCELSET, OBD_CONNECT_FID, OBD_CONNECT_AT, OBD_CONNECT_LOV_V3,
OBD_CONNECT_VBR, OBD_CONNECT_FULL20, OBD_CONNECT_64BITHASH,
OBD_CONNECT_EINPROGRESS, OBD_CONNECT_JOBSTATS, OBD_CONNECT_LVB_TYPE,
OBD_CONNECT_LAYOUTLOCK, OBD_CONNECT_PINGLESS, OBD_CONNECT_MAX_EASIZE,
OBD_CONNECT_FLOCK_DEAD, OBD_CONNECT_DISP_STRIPE, OBD_CONNECT_LFSCK, and
OBD_CONNECT_OPEN_BY_FID, as described in <<obd-connect-flags>>.

The 'ocd_brw_size' field is set to the largest size in bytes that the
client can use for bulk transfers. The 'ocd_ibits_known' field is set to
the supported set of IBITS locks, as of Lustre 2.7 these are
MDS_INODELOCK_LOOKUP, MDS_INODELOCK_UPDATE, MDS_INODELOCK_OPEN,
MDS_INODELOCK_LAYOUT, MDS_INODELOCK_PERM, and MDS_INODELOCK_XATTR,
as described in <<mds-inode-bits-locks>>.

The 'ocd_version' field contains the version of Lustre
running on the client. Other fields in the 'obd_connect_data'
structures are zero.

Once the server receives the 'obd_connect_client' message on behalf of
the given target it replies with an 'obd_connect_server' message. In
the reply message the server sets the 'pb_handle' to uniquely
identify this connection for subsequent communication. The client notes
that handle in its import for the given target.  The reply also returns
the 'obd_connect_data' as interpreted by the MDS.  Any features that
the MDS does not support are masked out of 'ocd_feature_flags'.  Supported
features that have assigned fields are filled in by the MDS.

fixme: Are there circumstances that could lead to the 'status'
value in the reply being non-zero? What would lead to that and what
error values would result?
ans: yes, at least the standard errors

The target maintains the last committed transaction for a client in
its export for that client. If this is the first connection, then that
last transaction value would just be zero. If there were previous
transactions for the client, then the transaction number for the last
such committed transaction is put in the <<struct-ptlrpc-body>>
'pb_last_committed' field.

In a connection request the operation is not file system modifying, so
the 'pb_transno' value will be zero in the reply as well.

fixme: there is still some work to be done about how the fields are
managed.