protocol.txt

   1 Lustre Protocol Documentation
   2 =============================
   3 Andrew Uselton <andrew.c.uselton@intel.com>
   4 v0.0, January 2015
   5 :author: Andrew Uselton
   6 :doctype: article
   7 :Author Initials: ACU
   8 :toc:
   9 :icons:
  10 :numbered:
  11 :imagesdir: ./figures
  12 :website: http://lustre.org/
  13 :keywords: PtlRPC, Lustre, Protocol
  14
  15
  16 :numbered!: [abstract] Abstract -------- The Lustre parallel file
  17 system <<lustre>> provides a global POSIX <<POSIX>> namespace for the
  18 computing resources of a data center. Lustre runs on Linux-based hosts
  19 via kernel modules, and delegates block storage management to the
  20 back-end servers while providing object-based storage to its
  21 clients. Servers are responsible for both data objects (the contents
  22 of actual files) and index objects (for directory information). Data
  23 objects are gathered on Object Storage Servers (OSSs), and index
  24 objects are stored on MetaData Storage Servers (MDSs). Each back-end
  25 storage volume is a target with Object Storage Targets (OSTs) on OSSs,
  26 and MetaData Storage Targets (MDTs) on MDSs.  Clients assemble the
  27 data from the MDT(s) and OST(s) to present a single coherent
  28 POSIX-compliant file system. The clients and servers communicate and
  29 coordinate among themselves via network protocols. A low-level
  30 protocol, LNet, abstracts the details of the underlying networking
  31 hardware and presents a uniform interface, originally based on Sandia
  32 Portals <<PORTALS>>, to Lustre clients and servers. Lustre, in turn,
  33 layers its own protocol PtlRPC atop LNet. This document describes the
  34 Lustre protocols, including how they are implemeted via PtlRPC and the
  35 Lustre Distributed Lock Manager (based on the VAX/VMS Distributed Lock
  36 Manager <<VAX_DLM>>). This document does not describe Lustre itself in
  37 any detail, except where doing so explains concepts that allow this
  38 document to be self-contained.
  39
  40 :numbered:
  41
  42 Overview
  43 --------
  44
  45 'Content to be provided'
  46
  47 Messages
  48 --------
  49
  50 These are the messages that traverse the network using PTLRPC.
  51
  52 [NOTE]
  53 This initial list combines some actual message names or types with the
  54 POSIX semantic operations they are being used to implement, as well as
  55 a few other underlying mechanisms (cf. "grant"). A subsequent
  56 refinement will separate the various items and relate them to one
  57 another.
  58
  59 Client-MDS RPCs for POSIX namespace operations
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 'Content to be provided'
  63
  64 === mount ===
  65
  66 'Content to be provided'
  67
  68 === unmount ===
  69
  70 'Content to be provided'
  71
  72 === create ===
  73
  74 'Content to be provided'
  75
  76 === open ===
  77
  78 'Content to be provided'
  79
  80 === close ===
  81
  82 'Content to be provided'
  83
  84 === unlink ===
  85
  86 'Content to be provided'
  87
  88 === mkdir ===
  89
  90 image:mkdir1.png[mkdir]
  91
  92 === rmdir ===
  93
  94 'Content to be provided'
  95
  96 === rename ===
  97
  98 'Content to be provided'
  99
 100 === link ===
 101
 102 'Content to be provided'
 103
 104 === symlink ===
 105
 106 'Content to be provided'
 107
 108 === getattr ===
 109
 110 'Content to be provided'
 111
 112 === setattr ===
 113
 114 'Content to be provided'
 115
 116 === statfs ===
 117
 118 'Content to be provided'
 119
 120 === ... ===
 121
 122 'Content to be provided'
 123
 124
 125 Client-MDS RPCs for internal state management
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 'Content to be provided'
 129
 130 === connect ===
 131
 132 'Content to be provided'
 133
 134 === disconnect ===
 135
 136 'Content to be provided'
 137
 138 === FLD ===
 139
 140 'Content to be provided'
 141
 142 === SEQ ===
 143
 144 'Content to be provided'
 145
 146 === PING ===
 147
 148 'Content to be provided'
 149
 150 === LDLM ===
 151
 152 'Content to be provided'
 153
 154 === ... ===
 155
 156 'Content to be provided'
 157
 158 Client-OSS RPCs for IO Operations
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 'Content to be provided'
 162
 163 === read ===
 164
 165 'Content to be provided'
 166
 167 === write ===
 168
 169 'Content to be provided'
 170
 171 === truncate ===
 172
 173 'Content to be provided'
 174
 175 === setattr ===
 176
 177 'Content to be provided'
 178
 179 === grant ===
 180
 181 'Content to be provided'
 182
 183 === ... ===
 184
 185 'Content to be provided'
 186
 187 MDS-OSS RPCs for internal state management
 188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 'Content to be provided'
 191
 192 === object precreation ===
 193
 194 'Content to be provided'
 195
 196 === orphan recovery ===
 197
 198 'Content to be provided'
 199
 200 === UID/GID change ===
 201
 202 'Content to be provided'
 203
 204 === unlink ===
 205
 206 'Content to be provided'
 207
 208 === ... ===
 209
 210 'Content to be provided'
 211
 212 MDS-OSS RPCs for quota management
 213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 214
 215 'Content to be provided'
 216
 217
 218 MDS-OSS OUT RPCs for distributed updates
 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 'Content to be provided'
 222
 223 === DNE1 remote directories ===
 224
 225 'Content to be provided'
 226
 227 === DNE2 striped directories ===
 228
 229 'Content to be provided'
 230
 231 === LFSCK2/3 verification and repair ===
 232
 233 'Content to be provided'
 234
 235 Message Flows
 236 -------------
 237
 238   Each file operation (in Lustre) generates a set of messages in a
 239   particular sequence. There is one sequence for any particular
 240   concrete operation, but under varying circumstances the same file
 241   operation may generate a different sequence.
 242
 243 State Machines
 244 --------------
 245
 246   For each File operation, the collection of possible sequences of
 247   messages is governed by a state machine.
 248
 249 :numbered!:
 250
 251 [glossary]
 252 Glossary
 253 --------
 254 Here are some common terms used in discussing Lustre, POSIX semantics,
 255 and the prtocols used to implement them.
 256
 257 [glossary]
 258 Object Storage Server::
 259   An object storage server (OSS) is a computer responsible for
 260   running Lustre kernel services in support of managing bulk data
 261   objects on the underlying storage. There can be multiple OSSs in a
 262   Lustre file system.
 263
 264 MetaData Server::
 265   A metadata server (MDS) is a computer responsible for running the
 266   Lustre kernel services in support of managing the POSIX-compliant
 267   name space and the indices associating files in that name space with
 268   the locations of their corresponding objects. As of v2.4 there can
 269   be multiple MDSs in a Lustre file system.
 270
 271 Object Storage Target::
 272   An object storage target (OST) is the service provided by an OSS
 273   that mediates the placement of data objects on the specific
 274   underlying file system hardware. There can be multiple OSTs on a
 275   given OSS.
 276
 277 MetaData Target::
 278   A metadata target (MDT) is the service provided by an MDS that
 279   mediates the management of name space indices on the underlying file
 280   system hardware. As of v2.4 there can be multiple MDTs on an MDS.
 281
 282 server::
 283   A computer providing a service, such as an OSS or an MDS
 284
 285 target::
 286   Storage available to be served, such as an OST or an MDT. Also the
 287   service being provided.
 288
 289 protocol::
 290   An agreed upon formalism for communicating between two entities,
 291   such as between two servers or between a client and a server.
 292
 293 client::
 294   A computer taking advantage of a service provided by a server, such
 295   as a Lustre client using MDS(s) and OSS(s) to assemble a
 296   POSIX-compliant file system with its namespace and data storage
 297   capabilities.
 298
 299 PtlRPC::
 300   The protocol (or set of protocols) implemented via RPCs that is
 301   (are) employed by Lustre to communicate between its clients and
 302   servers.
 303
 304 Remote Procedure Call::
 305   A mechanism for implementing operations involving one computer
 306   acting on the behalf of another (RPC).
 307
 308 LNet::
 309   A lower level protocol employed by PtlRPC to abstract the mechanisms
 310   provided by various hardware centric protocols, such as TCP or
 311   Infiniband.
 312
 313 [appendix]
 314 Concepts
 315 --------
 316
 317 'Content to be provided'
 318
 319 [appendix]
 320 License
 321 -------
 322
 323 Copyright (C) Intel 2015
 324
 325 This work is licensed under a Creative Commons Attribution-ShareAlike
 326 4.0 International License (CC BY-SA 4.0). See
 327 <https://creativecommons.org/licenses/by-sa/4.0/> for more detail.
 328
 329 [bibliography]
 330 Bibliography
 331 ------------
 332 Here is a selected list of references, including those cited in the
 333 foregoing text.
 334
 335 [bibliography]
 336 - [[[lustre]]] 'Lustre'. http://lustre.opensfs.org
 337 - [[[POSIX]]] 'POSIX'. http://pubs.opengroup.org/onlinepubs/9699919799/
 338 - [[[PORTALS]]] 'The Portals 3.0 Message Passing
 339                Interface Revision 1.1.'. Ron Brightwell, Trammel
 340                Hudson, Rolf Riesen, and Arthur B. Maccabe. Technical
 341                report, December 1999.
 342 - [[[VAX_DLM]]] 'The VAX/VMS Distributed Lock Manager'. W Snaman and
 343                D Thiel.  Digital Technical Journal, September 1987.
 344 - [[[Barton_Dilger]]] 'Lustre'. Eric Barton and Andreas Dilger. A book
 345                     on parallel file systems. Chapter 8. High
 346                     Performance Parallel I/O, Prabhat and Quincey
 347                     Koziol, Chapman and Hall/CRC Press, 2014, ISBN:
 348                     978-1466582347.
 349
 350