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