LUDOC-296 protocol: Reorganize the document ot be top-down

[doc/protocol.git] / mgs_connect.txt

diff --git a/mgs_connect.txt b/mgs_connect.txt
new file mode 100644 (file)
index 0000000..2579f57
--- /dev/null
+++ b/mgs_connect.txt
@@ -0,0 +1,48 @@
+RPC 250: MGS CONNECT - Client connection to an MGS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[[mgs-connect-rpc]]
+
+.MGS_CONNECT (250)
+[options="header"]
+|====
+| request            | reply
+| obd_connect_client | obd_connect_server
+|====
+
+When a client initiates a connection to the MGS,
+it does so by sending an 'obd_connect_client' message and awaiting the
+reply from the MGS of an 'obd_connect_server' message. This is the
+first operation carried out by a client upon the issue of a 'mount'
+command, and the target UUID is provided on the command line.
+
+The target UUID is just "MGS", and the client UUID is set to the
+32byte string it gets from ... where?
+
+The 'struct lustre_handle' (the fourth buffer in the message) has its
+cookie set to .. what? It is set, but where does it come from?
+
+The 'ocd_connect_flags' field is set to (fixme: what?) reflecting the
+capabilities appropriate to the client. The 'ocd_brw_size' is set to the
+largest value for the size of an RPC that the client can handle. The
+'ocd_ibits_known' and 'ocd_checksum_types' values are set to what the client
+considers appropriate. Other fields in the descriptor and
+'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
+that message the server sends the 'pb__handle' to uniquely
+identify the connection for subsequent communication. The client notes
+that handle in its import for the given target.
+
+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?
+
+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 '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.