file_system_operations.txt

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