LustreHSM.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook"
   3  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US"
   4  xml:id="lustrehsm" condition='l25'>
   5   <title xml:id="lustrehsm.title">Hierarchical Storage Management (HSM)</title>
   6   <para>This chapter describes how to bind Lustre to a Hierarchical Storage Management (HSM) solution.</para>
   7   <section xml:id="hsm_introduction">
   8       <title>
   9           <indexterm><primary>Hierarchical Storage Management (HSM)</primary><secondary>introduction</secondary></indexterm>Introduction</title>
  10         <para>The Lustre file system can bind to a Hierarchical Storage Management (HSM)
  11 solution using a specific set of functions. These functions enable connecting
  12 a Lustre file system to one or more external storage systems, typically HSMs.
  13 With a Lustre file system bound to a HSM solution, the Lustre file system acts
  14 as a high speed cache in front of these slower HSM storage systems. </para>
  15
  16         <para>The Lustre file system integration with HSM provides a mechanism for
  17 files to simultaneously exist in a HSM solution and have a metadata entry in
  18 the Lustre file system that can be examined. Reading, writing or truncating the
  19 file will trigger the file data to be fetched from the HSM storage back into
  20 the Lustre file system.</para>
  21
  22         <para>The process of copying a file into the HSM storage is known as
  23 <emphasis>archive</emphasis>. Once the archive is complete, the Lustre file
  24 data can be deleted (known as <emphasis>release</emphasis>.) The process of
  25 returning data from the HSM storage to the Lustre file system is called
  26 <emphasis>restore</emphasis>.  The archive and restore operations require a
  27 Lustre file system component called an <emphasis>Agent</emphasis>. </para>
  28
  29         <para>An Agent is a specially designed Lustre client node that mounts the
  30 Lustre file system in question. On an Agent, a user space program called a
  31 copytool is run to coordinate the archive and restore of files between the
  32 Lustre file system and the HSM solution.</para>
  33
  34         <para>Requests to restore a given file are registered and dispatched by a
  35 facet on the MDT called the Coordinator.
  36
  37         <figure xml:id='hsmcopytoolfig'>
  38                 <title>Overview of the Lustre file system HSM</title>
  39                 <mediaobject>
  40                         <imageobject>
  41                                 <imagedata fileref='figures/HSM_copytool.png' width="75%"/>
  42                         </imageobject>
  43                 </mediaobject>
  44         </figure>
  45 </para>
  46   </section>
  47
  48   <section xml:id="hsmsetup">
  49         <title>
  50           <indexterm><primary>HSM</primary><secondary>setup</secondary></indexterm>Setup</title>
  51
  52         <section xml:id='hsmrequirements'>
  53                 <title>
  54           <indexterm><primary>HSM</primary><secondary>requirements</secondary></indexterm>Requirements
  55                 </title>
  56         <para>To setup a Lustre/HSM configuration you need:</para>
  57       <itemizedlist>
  58         <listitem>
  59                         <para>a standard Lustre file system (version 2.5.0 and above)</para>
  60         </listitem>
  61         <listitem>
  62                         <para>a minimum of 2 clients, 1 used for your chosen computation task that generates
  63                         useful data, and 1 used as an agent.</para>
  64                 </listitem>
  65       </itemizedlist>
  66         <para>Multiple agents can be employed. All the agents need to share access
  67         to their backend storage. For the POSIX copytool, a POSIX namespace like NFS or
  68         another Lustre file system is suitable.</para>
  69         </section>
  70
  71         <section xml:id='hsmcoordinator'>
  72                 <title>
  73           <indexterm><primary>HSM</primary><secondary>coordinator</secondary></indexterm>Coordinator
  74                 </title>
  75
  76                         <para>To bind a Lustre file system to a HSM system a coordinator
  77                         must be activated on each of your filesystem MDTs. This can be achieved with the command:</para>
  78 <screen>$ lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm_control=enabled
  79 mdt.lustre-MDT0000.hsm_control=enabled</screen>
  80                         <para>To verify that the coordinator is running correctly</para>
  81
  82 <screen>$ lctl get_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm_control
  83 mdt.lustre-MDT0000.hsm_control=enabled</screen>
  84         </section>
  85
  86         <section xml:id='hsmagents'>
  87                 <title>
  88           <indexterm><primary>HSM</primary><secondary>agents</secondary></indexterm>Agents
  89                 </title>
  90
  91         <para>Once a coordinator is started, launch the copytool on each agent node to connect to your HSM storage. If your HSM storage has POSIX access this command will be of the form:</para>
  92         <screen>lhsmtool_posix --daemon --hsm-root <replaceable>$HSMPATH</replaceable> --archive=1 <replaceable>$LUSTREPATH</replaceable></screen>
  93         <para>The POSIX copytool must be stopped by sending it a TERM signal.</para>
  94         </section>
  95
  96         </section>
  97
  98   <section xml:id="hsmagentsandcopytool">
  99         <title>
 100           <indexterm><primary>HSM</primary><secondary>agents and copytools</secondary></indexterm>Agents and copytool</title>
 101         <para>
 102
 103 Agents are Lustre file system clients running copytool. copytool is a userspace
 104 daemon that transfers data between Lustre and a HSM solution. Because different
 105 HSM solutions use different APIs, copytools can typically only work with a
 106 specific HSM. Only one copytool can be run by an agent node.</para>
 107
 108 <para>The following rule applies regarding copytool instances: a Lustre file
 109 system only supports a single copytool process, per ARCHIVE ID (see below),
 110 per client node.  Due to a Lustre software limitation, this constraint is
 111 irrespective of the number of Lustre file systems mounted by the Agent.</para>
 112
 113 <para>Bundled with Lustre tools, the POSIX copytool can work with any HSM or
 114 external storage that exports a POSIX API.  </para>
 115
 116         <section xml:id='hsmarchivebackends'>
 117                 <title>
 118           <indexterm><primary>HSM</primary><secondary>archiveID backends</secondary></indexterm>Archive ID, multiple backends
 119                 </title>
 120
 121 <para>A Lustre file system can be bound to several different HSM solutions.
 122 Each bound HSM solution is identified by a number referred to as ARCHIVE ID. A
 123 unique value of ARCHIVE ID must be chosen for each bound HSM solution. ARCHIVE
 124 ID must be in the range 1 to 32.</para>
 125
 126 <para>A Lustre file system supports an unlimited number of copytool instances.
 127 You need, at least, one copytool per ARCHIVE ID. When using the POSIX copytool,
 128 this ID is defined using <literal>--archive</literal> switch.</para>
 129
 130 <para>For example: if a single Lustre file system is bound to 2 different HSMs (A and B,) ARCHIVE ID “1” can be chosen for HSM A and ARCHIVE ID “2” for HSM B. If you start 3 copytool instances for ARCHIVE ID 1, all of them will use Archive ID “1”. The same rule applies for copytool instances dealing with the HSM B, using Archive ID “2”. </para>
 131
 132 <para>When issuing HSM requests, you can use the <literal>--archive</literal> switch
 133 to choose the backend you want to use. In this example, file <literal>foo</literal> will be
 134 archived into backend ARCHIVE ID “5”:</para>
 135
 136         <screen>$ lfs hsm_archive --archive=5 /mnt/lustre/foo</screen>
 137
 138         <para>A default ARCHIVE ID can be defined which will be used when the <literal>--archive</literal> switch is not specified:</para>
 139
 140         <screen>$ lctl set_param -P mdt.<replaceable>lustre-MDT0000</replaceable>.hsm.default_archive_id=5</screen>
 141
 142 <para>The ARCHIVE ID of archived files can be checked using <literal>lfs
 143 hsm_state</literal> command:</para>
 144
 145         <screen>$ lfs hsm_state /mnt/lustre/foo
 146 /mnt/lustre/foo: (0x00000009) exists archived, archive_id:5</screen>
 147
 148         </section>
 149
 150         <section xml:id='hsmregisteredagents'>
 151                 <title>
 152           <indexterm><primary>HSM</primary><secondary>registered agents</secondary></indexterm>Registered agents
 153                 </title>
 154
 155         <para>A Lustre file system allocates a unique UUID per client mount point, for each
 156 filesystem. Only one copytool can be registered for each Lustre mount point.
 157 As a consequence, the UUID uniquely identifies a copytool, per filesystem.</para>
 158
 159 <para>The currently registered copytool instances (agents UUID) can be retrieved by running the following command, per MDT, on MDS nodes:</para>
 160
 161 <screen>$ lctl get_param -n mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm.agents
 162 uuid=a19b2416-0930-fc1f-8c58-c985ba5127ad archive_id=1 requests=[current:0 ok:0 errors:0]</screen>
 163
 164 <para>The returned fields have the following meaning:</para>
 165       <itemizedlist>
 166         <listitem>
 167                 <para><literal>uuid</literal> the client mount used by the corresponding copytool.</para>
 168         </listitem>
 169         <listitem>
 170                 <para><literal>archive_id</literal> comma-separated list of ARCHIVE IDs accessible by this copytool.</para>
 171         </listitem>
 172         <listitem>
 173                 <para><literal>requests</literal> various statistics on the number of requests processed by this copytool.</para>
 174         </listitem>
 175       </itemizedlist>
 176
 177         </section>
 178
 179         <section xml:id='hsmtimeout'>
 180                 <title>
 181           <indexterm><primary>HSM</primary><secondary>timeout</secondary></indexterm>Timeout
 182                 </title>
 183
 184                 <para>One or more copytool instances may experience conditions that
 185 cause them to become unresponsive. To avoid blocking access to the related
 186 files a timeout value is defined for request processing. A copytool must be
 187 able to fully complete a request within this time. The default is 3600 seconds.
 188                 </para>
 189 <screen>$ lctl set_param -n mdt.<replaceable>lustre-MDT0000</replaceable>.hsm.active_request_timeout
 190 </screen>
 191
 192         </section>
 193
 194         </section>
 195
 196         <section xml:id='hsmrequests'>
 197                 <title>
 198           <indexterm><primary>HSM</primary><secondary>requests</secondary></indexterm>Requests
 199                 </title>
 200
 201         <para>Data management between a Lustre file system and HSM solutions is driven by requests. There are five types:</para>
 202
 203       <itemizedlist>
 204         <listitem>
 205                 <para><literal>ARCHIVE</literal> Copy data from a Lustre file system file into the HSM solution.</para>
 206         </listitem>
 207         <listitem>
 208                 <para><literal>RELEASE</literal> Remove file data from the Lustre file system.</para>
 209         </listitem>
 210         <listitem>
 211                 <para><literal>RESTORE</literal> Copy back data from the HSM solution into the corresponding Lustre file system file.</para>
 212         </listitem>
 213         <listitem>
 214                 <para><literal>REMOVE</literal> Delete the copy of the data from the HSM solution.</para>
 215         </listitem>
 216         <listitem>
 217                 <para><literal>CANCEL</literal> Cancel an in-progress or pending request.</para>
 218         </listitem>
 219       </itemizedlist>
 220
 221         <para>Only the <literal>RELEASE</literal> is performed synchronously and
 222 does not involve the coordinator. Other requests are handled by Coordinators.
 223 Each MDT coordinator is resiliently managing them.</para>
 224
 225         <section xml:id='hsmcommands'>
 226                 <title>
 227           <indexterm><primary>HSM</primary><secondary>commands</secondary></indexterm>Commands
 228                 </title>
 229
 230         <para>Requests are submitted using <literal>lfs</literal> command:</para>
 231                 <screen>$ lfs hsm_archive [--archive=<replaceable>ID</replaceable>] <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]
 232 $ lfs hsm_release <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]
 233 $ lfs hsm_restore <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]
 234 $ lfs hsm_remove  <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]
 235 </screen>
 236
 237 <para>Requests are sent to the default ARCHIVE ID unless an ARCHIVE ID is specified with the <literal>--archive</literal> option (See <xref linkend="hsmarchivebackends"/>).</para>
 238         </section>
 239
 240         <section xml:id='hsmautorestore'>
 241                 <title>
 242           <indexterm><primary>HSM</primary><secondary>automatic restore</secondary></indexterm>Automatic restore
 243                 </title>
 244
 245                 <para>Released files are automatically restored when a process tries to read or modify them. The corresponding I/O will block waiting for the file to be restored.  This is transparent to the process. For example, the following command automatically restores the file if released.</para>
 246 <screen>$ cat <replaceable>/mnt/lustre/released_file</replaceable></screen>
 247         </section>
 248
 249         <section xml:id='hsmrequestmonitoring'>
 250                 <title>
 251           <indexterm><primary>HSM</primary><secondary>request monitoring</secondary></indexterm>Request monitoring
 252                 </title>
 253
 254         <para>The list of registered requests and their status can be monitored, per MDT, with the following command:</para>
 255
 256         <screen>$ lctl get_param -n mdt.<replaceable>lustre-MDT0000</replaceable>.hsm.actions</screen>
 257
 258         <para>The list of requests currently being processed by a copytool is available with:</para>
 259
 260 <screen>$ lctl get_param -n mdt.<replaceable>lustre-MDT0000</replaceable>.hsm.active_requests</screen>
 261
 262         </section>
 263         </section>
 264
 265         <section xml:id='hsmfilestates'>
 266                 <title>
 267           <indexterm><primary>HSM</primary><secondary>file states</secondary></indexterm>File states
 268                 </title>
 269
 270                 <para>When files are archived or released, their state in the Lustre file system changes. This state can be read using the following <literal>lfs</literal> command:</para>
 271
 272 <screen>$ lfs hsm_state <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]</screen>
 273
 274 <para>There is also a list of specific policy flags which could be set to have a per-file specific policy:
 275 </para>
 276
 277       <itemizedlist>
 278         <listitem>
 279                 <para><literal>NOARCHIVE</literal> This file will never be archived.</para>
 280         </listitem>
 281         <listitem>
 282                 <para><literal>NORELEASE</literal> This file will never be released. This value cannot be set if the flag is currently set to <literal>RELEASED</literal></para>
 283         </listitem>
 284         <listitem>
 285                 <para><literal>DIRTY</literal> This file has been modified since a copy of it was made in the HSM solution. <literal>DIRTY</literal> files should be archived again. The <literal>DIRTY</literal> flag can only be set if <literal>EXIST</literal> is set.</para>
 286         </listitem>
 287                 </itemizedlist>
 288
 289 <para>The following options can only be set by the root user.</para>
 290
 291       <itemizedlist>
 292         <listitem>
 293
 294                 <para><literal>LOST</literal> This file was previously archived but the
 295 copy was lost on the HSM solution for some reason in the backend (for example,
 296 by a corrupted tape), and could not be restored. If the file is not in the
 297 <literal>RELEASE</literal> state it needs to be archived again. If the file
 298 is in the <literal>RELEASE</literal> state, the file data is lost.</para>
 299
 300         </listitem>
 301       </itemizedlist>
 302
 303         <para>Some flags can be manually set or cleared using the following commands:</para>
 304
 305 <screen>$ lfs hsm_set [<replaceable>FLAGS</replaceable>] <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]
 306 $ lfs hsm_clear [<replaceable>FLAGS</replaceable>] <replaceable>FILE1</replaceable> [<replaceable>FILE2</replaceable>...]</screen>
 307
 308         </section>
 309
 310         <section xml:id='hsmtuning'>
 311                 <title>
 312           <indexterm><primary>HSM</primary><secondary>tuning</secondary></indexterm>Tuning
 313                 </title>
 314
 315         <section xml:id='hsmhsm_control'>
 316                 <title>
 317           <indexterm><primary>HSM</primary><secondary>hsm_control</secondary></indexterm><literal>hsm_controlpolicy</literal>
 318                 </title>
 319
 320                 <para><literal>hsm_control</literal> controls coordinator activity and can also purge the action list.</para>
 321
 322                 <screen>$ lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm_control=purge</screen>
 323
 324                 <para>Possible values are:</para>
 325
 326       <itemizedlist>
 327         <listitem>
 328                 <para><literal>enabled</literal> Start coordinator thread. Requests are dispatched on available copytool instances.</para>
 329         </listitem>
 330         <listitem>
 331                 <para><literal>disabled</literal> Pause coordinator activity. No new request will be scheduled. No timeout will be handled. New requests will be registered but will be handled only when the coordinator is enabled again.</para>
 332         </listitem>
 333         <listitem>
 334                 <para><literal>shutdown</literal> Stop coordinator thread. No request can be submitted.</para>
 335         </listitem>
 336         <listitem>
 337                 <para><literal>purge</literal> Clear all recorded requests. Do not change coordinator state.</para>
 338         </listitem>
 339       </itemizedlist>
 340
 341         </section>
 342
 343         <section xml:id='hsmmax_requests'>
 344                 <title>
 345           <indexterm><primary>HSM</primary><secondary>max_requests</secondary></indexterm><literal>max_requests</literal>
 346                 </title>
 347
 348                 <para><literal>max_requests</literal> is the maximum number of active
 349 requests at the same time. This is a per coordinator value, and independent of
 350 the number of agents.</para>
 351
 352 <para>For example, if 2 MDT and 4 agents are present, the agents will never have to handle more than 2 x <literal>max_requests</literal>.</para>
 353
 354 <screen>$ lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm.max_requests=10</screen>
 355
 356         </section>
 357
 358         <section xml:id='hsmpolicy'>
 359                 <title>
 360           <indexterm><primary>HSM</primary><secondary>policy</secondary></indexterm><literal>policy</literal>
 361                 </title>
 362
 363         <para>Change system behavior. Values can be added or removed by prefixing them with '+' or '-'.</para>
 364
 365         <screen>$ lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm.policy=+NRA</screen>
 366
 367         <para>Possible values are a combination of:</para>
 368
 369       <itemizedlist>
 370         <listitem>
 371                 <para><literal>NRA</literal> No Retry Action. If a restore fails, do not reschedule it automatically.</para>
 372         </listitem>
 373         <listitem>
 374                 <para><literal>NBR</literal> Non Blocking Restore. Restore is triggered but does not block clients. Access to a released file returns <literal>ENODATA</literal>.</para>
 375         </listitem>
 376       </itemizedlist>
 377         </section>
 378
 379         <section xml:id='hsmgrace_delay'>
 380                 <title>
 381           <indexterm><primary>HSM</primary><secondary>grace_delay</secondary></indexterm><literal>grace_delay</literal>
 382                 </title>
 383
 384         <para><literal>grace_delay</literal> is the delay, expressed in seconds,
 385 before a successful or failed request is cleared from the whole request
 386 list.</para>
 387
 388                 <screen>$ lctl set_param mdt.<replaceable>$FSNAME-MDT0000</replaceable>.hsm.grace_delay=10</screen>
 389
 390         </section>
 391         </section>
 392
 393         <section xml:id='hsmchangelogs'>
 394                 <title>
 395           <indexterm><primary>HSM</primary><secondary>changelogs</secondary></indexterm>change logs
 396                 </title>
 397
 398                 <para>A changelog record type “HSM“ was added for Lustre file system
 399 logs that relate to HSM events.</para>
 400 <screen>16HSM   13:49:47.469433938 2013.10.01 0x280 t=[0x200000400:0x1:0x0]</screen>
 401
 402                 <para>Two items of information are available for each HSM record: the
 403 FID of the modified file and a bit mask.  The bit mask codes the following
 404 information (lowest bits first):</para>
 405
 406       <itemizedlist>
 407         <listitem>
 408                         <para>Error code, if any (7 bits)</para>
 409         </listitem>
 410         <listitem>
 411                         <para>HSM event (3 bits)</para>
 412                   <itemizedlist>
 413                         <listitem>
 414                                 <para><literal>HE_ARCHIVE = 0</literal> File has been archived.</para>
 415                         </listitem>
 416                         <listitem>
 417                                 <para><literal>HE_RESTORE = 1</literal> File has been restored.</para>
 418                         </listitem>
 419                         <listitem>
 420                                 <para><literal>HE_CANCEL = 2</literal> A request for this file has been canceled.</para>
 421                         </listitem>
 422                         <listitem>
 423                                 <para><literal>HE_RELEASE = 3</literal> File has been released.</para>
 424                         </listitem>
 425                         <listitem>
 426                                 <para><literal>HE_REMOVE = 4</literal> A remove request has been executed automatically.</para>
 427                         </listitem>
 428                         <listitem>
 429                                 <para><literal>HE_STATE = 5</literal> File flags have changed.</para>
 430                         </listitem>
 431                   </itemizedlist>
 432         </listitem>
 433         <listitem>
 434                         <para>HSM flags (3 bits)</para>
 435                   <itemizedlist>
 436                         <listitem>
 437                                 <para><literal>CLF_HSM_DIRTY=0x1</literal></para>
 438                         </listitem>
 439                   </itemizedlist>
 440         </listitem>
 441       </itemizedlist>
 442         <para>In the above example, <literal>0x280</literal> means the error code is 0 and the event is HE_STATE.</para>
 443
 444         <para>When using <literal>liblustreapi</literal>, there is a list of helper functions to easily extract the different values from this bitmask, like: <literal>hsm_get_cl_event()</literal>, <literal>hsm_get_cl_flags()</literal>, and <literal>hsm_get_cl_error()</literal></para>
 445
 446         </section>
 447
 448         <section xml:id='hsmpolicyengine'>
 449                 <title>
 450           <indexterm><primary>HSM</primary><secondary>policy engine</secondary></indexterm>Policy engine
 451                 </title>
 452
 453                 <para>A Lustre file system does not have an internal component responsible for automatically scheduling archive requests and release requests under any conditions (like low space). Automatically scheduling archive operations is the role of the policy engine.</para>
 454
 455         <para>It is recommended that the Policy Engine run on a dedicated client, similar to an agent node, with a Lustre version 2.5+.</para>
 456
 457         <para>A policy engine is a userspace program using the Lustre file system HSM specific API to monitor the file system and schedule requests.</para>
 458
 459         <para>Robinhood is the recommended policy engine.</para>
 460
 461
 462         <section xml:id='hsmrobinhood'>
 463                 <title>
 464           <indexterm><primary>HSM</primary><secondary>robinhood</secondary></indexterm>Robinhood
 465                 </title>
 466
 467         <para>Robinhood is a Policy engine and reporting tool for large file
 468 systems. It maintains a replicate of file system metadata in a database that
 469 can be queried at will. Robinhood makes it possible to schedule mass action on
 470 file system entries by defining attribute-based policies, provides fast <literal>find</literal>
 471 and <literal>du</literal> enhanced clones, and provides administrators with an overall
 472 view of file system content through a web interface and command line tools.</para>
 473
 474 <para>Robinhood can be used for various configurations. Robinhood is an external project, and further information can be found on the project website: <link xl:href='https://sourceforge.net/apps/trac/robinhood/wiki/Doc'>https://sourceforge.net/apps/trac/robinhood/wiki/Doc</link>.</para>
 475
 476         </section>
 477         </section>
 478
 479 </chapter>
 480 <!--
 481   vim:expandtab:shiftwidth=2:tabstop=8:
 482   -->