mount.txt

   1 Mount
   2 ~~~~~
   3
   4 Before any other interaction can take place between a client and a
   5 Lustre file system the client must 'mount' the file system, and Lustre
   6 services must already be in place (on the servers). A file system
   7 mount may be initiated at the Linux shell command line, which in turn
   8 invokes the 'mount()' system call. Kernel modules for Lustre
   9 exchange a series of messages with the servers, beginning with
  10 messages that retrieve details about the file system from the
  11 management server (MGS). This provides the client with the identities
  12 of all the metadata servers (MDSs) and targets (MDTs) as well as all
  13 the object storage servers (OSSs) and targets (OSTs). The client then
  14 sequences through each of the targets exchanging additional messages
  15 to initiate the connections with them. The following sections present
  16 the details of the Lustre operations that accomplish the file system
  17 mount.
  18
  19 Messages Between the Client and the MGS
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 In order to be able to mount the Lustre file system the client needs
  23 to know the identities of the various servers and targets so that it
  24 can initiate connections to them. The following sequence of operations
  25 accomplishes this.
  26
  27 .Connect RPCs Between the Client and the MGS
  28 [[client-mgs-connect-rpcs]
  29 image::client_mgs_connect_rpcs.png["Connect RPCs Between the Client and the MGS", height=600]
  30
  31 //////////////////////////////////////////////////////////////////////
  32 The client_mgs_connect_rpcs.png diagram resembles this text art:
  33
  34 Time
  35 Step Client                         MGS                            MDT   OST
  36      -------                        -------                        ---   ---
  37 1    MGS_CONNECT-------------------->
  38 2              <--------------------MGS_CONNECT
  39 3    LDLM_ENQUEUE------------------->
  40 4               <-------------------LDLM_ENQUEUE
  41 5    LLOG_ORIGIN_HANDLE_CREATE------>
  42 6                            <------LLOG_ORIGIN_HANDLE_CREATE
  43 7    LDLM_ENQUEUE------------------->
  44 8               <-------------------LDLM_ENQUEUE
  45 9    LLOG_ORIGIN_HANDLE_CREATE------>
  46 10                           <------LLOG_ORIGIN_HANDLE_CREATE
  47 11   LLOG_ORIGIN_HANDLE_READ_HEADER->
  48 12                                <-LLOG_ORIGIN_HANDLE_READ_HEADER
  49 13   LLOG_ORIGIN_HANDLE_NEXT_BLOCK->
  50 14                               <-LLOG_ORIGIN_HANDLE_NEXT_BLOCK
  51 15   LDLM_ENQUEUE------------------->
  52 16              <-------------------LDLM_ENQUEUE
  53 17   MGS_CONFIG_READ---------------->
  54 18                 <----------------MGS_CONFIG_READ
  55 19   LDLM_ENQUEUE------------------->
  56 20              <-------------------LDLM_ENQUEUE
  57 21   LLOG_ORIGIN_HANDLE_CREATE------>
  58 22                           <------LLOG_ORIGIN_HANDLE_CREATE
  59 23   LLOG_ORIGIN_HANDLE_READ_HEADER->
  60 24                                <-LLOG_ORIGIN_HANDLE_READ_HEADER
  61 //////////////////////////////////////////////////////////////////////
  62
  63 Prior to any other interaction between a client and a Lustre server
  64 (or between two servers) the client must establish a 'connection'. The
  65 connection establishes shared state between the two hosts. On the
  66 client this connection state information is called an 'import', and
  67 there is an import on the client for each target it connects to. On
  68 the server this connection state is referred to as an 'export', and
  69 again the server has an export for each client that has connected to
  70 it. There a separate export for each client for each target.
  71
  72 The client begins by carrying out the MGS_CONNECT Lustre operation,
  73 which establishes the connection (creates the import and the export)
  74 between the client and the MGS. The connect message from the client
  75 includes a 'handle' to uniquely identify itself (subsequent messages
  76 to the LDLM will refer to that client-handle). The connection data
  77 from the client also proposes the set of <<connect-flags,connection
  78 flags>> appropriate to connecting to an MGS.
  79
  80 .Flags for the client connection to an MGS
  81 [options="header"]
  82 |====
  83 | obd_connect_data->ocd_connect_flags
  84 | OBD_CONNECT_VERSION
  85 | OBD_CONNECT_AT
  86 | OBD_CONNECT_FULL20
  87 | OBD_CONNECT_IMP_RECOV
  88 | OBD_CONNECT_MNE_SWAB
  89 | OBD_CONNECT_PINGLESS
  90 |====
  91
  92 The MGS's reply to the connection request will include the handle that
  93 the server and client will both use to identify this connection in
  94 subsequent messages. This is the 'connection-handle' (as opposed to
  95 the client-handle mentioned a moment ago).  The MGS also replies with
  96 the same set of connection flags.
  97
  98 Once the connection is established the client gets configuration
  99 information for the file system from the MGS in four stages. First,
 100 the two exchange messages establishing the file system wide security
 101 policy that will be followed in all subsequent communications. Second,
 102 the client gets a bitmap instructing it as to which among the
 103 configuration records on the MGS it needs. Third, reading those
 104 records from the MGS gives the client the list of all the servers and
 105 targets it will need to communicate with. Fourth, the client reads
 106 cluster wide configuration data (the sort that might be set at the
 107 client command line with a 'lctl conf_param' command). The following
 108 paragraphs go into these four stages in more detail.
 109
 110 Each time the client is going to read information from server storage
 111 it needs to first acquire the appropriate lock. Since the client is
 112 only reading data, the locks will be 'concurrent read' locks. The
 113 LDLM_ENQUEUE command communicates this lock request to the MGS
 114 target. The request identifies the target via the connection-handle
 115 from the connection reply, and identifies the client (itself) with the
 116 client-handle from its original connection request.  The MGS's reply
 117 grants that lock, if appropriate. If other clients were making some
 118 sort of modification to the MGS data then the lock exchange might
 119 result in a delay while the client waits. More details about the
 120 behavior of the <<ldlm,Distributed Lock Manager>> are in that
 121 section. For now, let's assume the locks are granted for each of these
 122 four operations. The first LLOG_ORIGIN_HANDLE_CREATE operation (the
 123 client is creating its own local handle not the target's file) asks
 124 for the security configuration file ("lfs-sptlrpc"). <<security>>
 125 discusses security, and for now let's assume there is nothing to be
 126 done for security. That is, subsequent messages will all use an "empty
 127 security flavor" and no encryption will take place. In this case the
 128 MGS's reply ('pb_status' == -2, ENOENT) indicated that there was no
 129 such file, so nothing actually gets read.
 130
 131 Another LDLM_ENQUEUE and LLOG_ORIGIN_HANDLE_CREATE pair of operations
 132 identifies the configuration client data ("lfs-client") file, and in
 133 this case there is data to read. The LLOG_ORIGIN_HANDLE_CREATE reply
 134 identifies the actual object of interest on the MGS via the
 135 'llog_logid' field in the 'struct llogd_body'. The MGS stores
 136 configuration data in log records. A header at the beginning of
 137 "lfs-client" uses a bitmap to identify the log records that are
 138 actually needed.  The header includes both which records to retrieve
 139 and how large those records are. The LLOG_ORIGIN_HANDLE_READ_HEADER
 140 request uses the 'llog_logid' to identify desired log file, and the
 141 reply provides the bitmap and size information identifying the
 142 records that are actually needed. The
 143 LLOG_ORIGIN_HANDLE_NEXT_BLOCK operations retrieves the data thus
 144 identified.
 145
 146 Knowing the specific configuration records it wants, the client then
 147 proceeds to retrieve them. This requires another LDLM_ENQUEUE
 148 operation, followed this time by the MGS_CONFIG_READ operation, which
 149 get the UUIDs for the servers and targets from the configuration log
 150 ("lfs-cliir").
 151
 152 A final LDLM_ENQUEUE, LLOG_ORIGIN_HANDLE_CREATE, and
 153 LLOG_ORIGIN_HANDLE_READ_HEADER then retrieve the cluster wide
 154 configuration data ("params").
 155
 156 Messages Between the Client and the MDSs
 157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 158
 159 After the foregoing interaction with the MGS the client has a list of
 160 the MDSs and MDTs in the file system.  Next, the client invokes four
 161 Lustre operations with each MDT on the list.
 162
 163 .Connect RPCs Between the Client and each MDT
 164 [[client-mdt-connect-rpcs]
 165 image::client_mdt_connect_rpcs.png["Connect RPCs Between the Client and each MDT", height=200]
 166
 167 //////////////////////////////////////////////////////////////////////
 168 The client_mdt_connect_rpcs.png diagram resembles this text art:
 169
 170 Time
 171 Step Client         MGS             MDT            OST
 172      -------        -------         --------       ------
 173 1    MDS_CONNECT-------------------->
 174 2              <--------------------MDS_CONNECT
 175 3    MDS_STATFS--------------------->
 176 4             <---------------------MDS_STATFS
 177 5    MDS_GETSTATUS------------------>
 178 6                <------------------MDS_GETSTATUS
 179 7    MDS_GETATTR-------------------->
 180 8              <--------------------MDS_GETATTR
 181 //////////////////////////////////////////////////////////////////////
 182
 183 The MDS_CONNECT operation establishes a connection between the client
 184 and a specific target (MDT) on an MDS. Thus, if an MDS has multiple
 185 targets, there is a separate MDS_CONNECT operation for each. This
 186 creates an import for the target on the client and an export for the
 187 client and target on the MDS. As with the connect operation for the
 188 MGS, the connect message from the client includes a UUID to uniquely
 189 identify this connection, and subsequent messages to the lock manager
 190 on the server will refer to that UUID. The connection data from the
 191 client also proposes the set of <<connect-flags,connection flags>>
 192 appropriate to connecting to an MDS. The following are the flags
 193 always included.
 194
 195 .Always included flags for the client connection to an MDS
 196 [options="header"]
 197 |====
 198 | obd_connect_data->ocd_connect_flags
 199 | OBD_CONNECT_RDONLY
 200 | OBD_CONNECT_VERSION
 201 | OBD_CONNECT_ACL
 202 | OBD_CONNECT_XATTR
 203 | OBD_CONNECT_IBITS
 204 | OBD_CONNECT_NODEVOH
 205 | OBD_CONNECT_ATTRFID
 206 | OBD_CONNECT_CANCELSET
 207 | OBD_CONNECT_AT
 208 | OBD_CONNECT_RMT_CLIENT
 209 | OBD_CONNECT_RMT_CLIENT_FORCE
 210 | OBD_CONNECT_BRW_SIZE
 211 | OBD_CONNECT_MDS_CAPA
 212 | OBD_CONNECT_OSS_CAPA
 213 | OBD_CONNECT_MDS_MDS
 214 | OBD_CONNECT_FID
 215 | LRU_RESIZE_CONNECT_FLAG
 216 | OBD_CONNECT_VBR
 217 | OBD_CONNECT_LOV_V3
 218 | OBD_CONNECT_SOM
 219 | OBD_CONNECT_FULL20
 220 | OBD_CONNECT_64BITHASH
 221 | OBD_CONNECT_JOBSTATS
 222 | OBD_CONNECT_EINPROGRESS
 223 | OBD_CONNECT_LIGHTWEIGHT
 224 | OBD_CONNECT_UMASK
 225 | OBD_CONNECT_LVB_TYPE
 226 | OBD_CONNECT_LAYOUTLOCK
 227 | OBD_CONNECT_PINGLESS
 228 | OBD_CONNECT_MAX_EASIZE
 229 | OBD_CONNECT_FLOCK_DEAD
 230 | OBD_CONNECT_DISP_STRIPE
 231 | OBD_CONNECT_LFSCK
 232 | OBD_CONNECT_OPEN_BY_FID
 233 | OBD_CONNECT_DIR_STRIPE
 234 |====
 235
 236 .Optional flags for the client connection to an MDS
 237 [options="header"]
 238 |====
 239 | obd_connect_data->ocd_connect_flags
 240 | OBD_CONNECT_SOM
 241 | OBD_CONNECT_LRU_RESIZE
 242 | OBD_CONNECT_ACL
 243 | OBD_CONNECT_UMASK
 244 | OBD_CONNECT_RDONLY
 245 | OBD_CONNECT_XATTR
 246 | OBD_CONNECT_XATTR
 247 | OBD_CONNECT_RMT_CLIENT_FORCE
 248 |====
 249
 250 The MDS replies to the connect message with a subset of the flags
 251 proposed by the client, and the client notes those values in its
 252 import.  The MDS's reply to the connection request will include a UUID
 253 that the server and client will both use to identify this connection
 254 in subsequent messages.
 255
 256 The client next uses an MDS_STATFS operation to request 'statfs'
 257 information from the target, and that data is returned in the reply
 258 message. The actual fields closely resemble the results of a 'statfs'
 259 system call. See the 'obd_statfs' structure in the <<data-structs,Data
 260 Structures and Defines Section>>.
 261
 262 The client uses the MDS_GETSTATUS operation to request information
 263 about the mount point of the file system. fixme: Does MDS_GETSTATUS
 264 only ask about the root (so it would seem)? The server reply contains
 265 the 'fid' of the root directory of the file system being mounted. If
 266 there is a security policy the capabilities of that security policy
 267 are included in the reply.
 268
 269 The client then uses the MDS_GETATTR operation to get get further
 270 information about the root directory of the file system. The request
 271 message includes the above fid. It will also include the security
 272 capability (if appropriate). The reply also holds the same fid, and in
 273 this case the 'mdt_body' has several additional fields filled
 274 in. These include the mtime, atime, ctime, mode, uid, and gid. It also
 275 includes the size of the extended attributes and the size of the ACL
 276 information. The reply message also includes the extended attributes
 277 and the ACL. From the extended attributes the client can find out
 278 about striping information for the root, if any.
 279
 280 Messages Between the Client and the OSSs
 281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 282
 283 Additional CONNECT messages flow between the client and each OST
 284 enumerated by the MGS.
 285
 286 .Connect RPCs Between the Client and each OST
 287 [[client-ost-connect-rpcs]
 288 image::client_ost_connect_rpcs.png["Connect RPCs Between the Client and each OST", height=75]
 289
 290 //////////////////////////////////////////////////////////////////////
 291 The client_ost_connect_rpcs.png diagram resembles this text art:
 292
 293 Time
 294 Step Client         MGS             MDT            OST
 295      -------        -------         --------       ------
 296 1    OST_CONNECT----------------------------------->
 297 2              <-----------------------------------OST_CONNECT
 298 //////////////////////////////////////////////////////////////////////
 299
 300