FileLevelRedundancy.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="flr" condition="l2B">
   5   <title xml:id="flr.title">File Level Redundancy (FLR)</title>
   6   <para>This chapter describes File Level Redundancy (FLR).</para>
   7   <section xml:id="flr.intro">
   8     <title>Introduction</title>
   9     <para> The Lustre file system was initially designed and implemented for HPC
  10       use. It has been working well on high-end storage that has internal
  11       redundancy and fault-tolerance. However, despite the expense and
  12       complexity of these storage systems, storage failures still occur, and
  13       before release 2.11, Lustre could not be more reliable than the
  14       individual storage and servers’ components on which it was based. The
  15       Lustre file system had no mechanism to mitigate storage hardware
  16       failures and files would become inaccessible if a server was inaccessible
  17       or otherwise out of service.</para>
  18     <para>With the File Level Redundancy (FLR) feature introduced in Lustre
  19       Release 2.11, any Lustre file can store the same data on multiple OSTs in
  20       order for the system to be robust in the event of storage failures or
  21       other outages.  With the choice of multiple mirrors, the best suited
  22       mirror can be chosen to satisfy an individual request, which has a direct
  23       impact on IO availability.  Furthermore, for files that are concurrently
  24       read by many clients (e.g. input decks, shared libraries, or executables)
  25       the aggregate parallel read performance of a single file can be improved
  26       by creating multiple mirrors of the file data.</para>
  27     <para>The first phase of the FLR feature has been implemented with delayed
  28       write (<xref linkend="flr.delayedwrite.fig"/>). While writing to a
  29       mirrored file, only one primary or preferred mirror will be updated
  30       directly during the write, while other mirrors will be simply marked as
  31       stale. The file can subsequently return to a mirrored state again by
  32       synchronizing among mirrors with command line tools (run by the user or
  33       administrator directly or via automated monitoring tools).</para>
  34     <figure xml:id="flr.delayedwrite.fig">
  35       <title>FLR Delayed Write</title>
  36       <mediaobject>
  37         <imageobject>
  38           <imagedata scalefit="1" width="50%"
  39           fileref="figures/FLR_DelayedWrite.png" />
  40         </imageobject>
  41         <textobject><phrase>FLR Delayed Write Diagram</phrase></textobject>
  42       </mediaobject>
  43     </figure>
  44   </section>
  45   <section xml:id="flr.operations">
  46     <title>Operations</title>
  47     <para>Lustre provides <literal>lfs mirror</literal> command line tools for
  48       users to operate on mirrored files or directories.</para>
  49     <section xml:id="flr.operations.createmirror">
  50       <title>Creating a Mirrored File or Directory</title>
  51       <para><emphasis role="strong">Command:</emphasis></para>
  52       <screen>lfs mirror create &lt;--mirror-count|-N[mirror_count]
  53 [setstripe_options|[--flags&lt;=flags&gt;]]&gt; ... &lt;filename|directory&gt;</screen>
  54       <para>The above command will create a mirrored file or directory specified
  55         by <replaceable>filename</replaceable> or
  56         <replaceable>directory</replaceable>, respectively.</para>
  57       <informaltable>
  58         <tgroup cols="2">
  59           <colspec align="left" />
  60           <colspec align="left" />
  61           <thead>
  62             <row>
  63               <entry>Option</entry>
  64               <entry>Description</entry>
  65             </row>
  66           </thead>
  67           <tbody>
  68             <row>
  69               <entry>--mirror-count|-N[mirror_count]</entry>
  70               <entry>
  71                 <para>Indicates the number of mirrors to be created with the
  72                   following setstripe options. It can be repeated multiple
  73                   times to separate mirrors that have different layouts.
  74                 </para>
  75                 <para>The <replaceable>mirror_count</replaceable> argument is
  76                   optional and defaults to <literal>1</literal> if it is not
  77                   specified; if specified, it must follow the option without a
  78                   space.</para>
  79               </entry>
  80             </row>
  81             <row>
  82               <entry>setstripe_options</entry>
  83               <entry>
  84                 <para>Specifies a specific layout for the mirror. It can be a
  85                   plain layout with a specific striping pattern or a composite
  86                   layout, such as <xref linkend="pfl"/>. The options are
  87                   the same as those for the <literal>lfs setstripe</literal>
  88                   command.</para>
  89                 <para>If <replaceable>setstripe_options</replaceable> are not
  90                   specified, then the stripe options inherited from the previous
  91                   component will be used. If there is no previous component,
  92                   then the <literal>stripe_count</literal> and
  93                   <literal>stripe_size</literal> options inherited from the
  94                   filesystem-wide default values will be used, and the OST
  95                   <literal>pool_name</literal> inherited from the parent
  96                   directory will be used.</para>
  97               </entry>
  98             </row>
  99             <row>
 100               <entry>--flags&lt;=flags&gt;</entry>
 101               <entry>
 102                 <para>Sets flags to the mirror to be created.</para>
 103                 <para>Only the <literal>prefer</literal> flag is supported at
 104                   this time. This flag will be set to all components that belong
 105                   to the corresponding mirror. The <literal>prefer</literal>
 106                   flag gives a hint to Lustre for which mirrors should be used
 107                   to serve I/O.  When a mirrored file is being read, the
 108                   component(s) with the <literal>prefer</literal> flag is likely
 109                   to be picked to serve the read; and when a mirrored file is
 110                   prepared to be written, the MDT will tend to choose the
 111                   component with the <literal>prefer</literal> flag set and
 112                   mark the other components with overlapping extents as stale.
 113                   This flag just provides a hint to Lustre, which means Lustre
 114                   may still choose mirrors without this flag set, for instance,
 115                   if all preferred mirrors are unavailable when the I/O occurs.
 116                   This flag can be set on multiple components.</para>
 117                 <para><emphasis role="strong">Note:</emphasis>  This flag will
 118                   be set to all components that belong to the corresponding
 119                   mirror. The <literal>--comp-flags</literal> option also
 120                   exists, which can be set to individual components at mirror
 121                   creation time.</para>
 122               </entry>
 123             </row>
 124           </tbody>
 125         </tgroup>
 126       </informaltable>
 127       <para><emphasis role="strong">Note:</emphasis>  For redundancy and
 128         fault-tolerance, users need to make sure that different mirrors must
 129         be on different OSTs, even OSSs and racks. An understanding of cluster
 130         topology is necessary to achieve this architecture. In the initial
 131         implementation the use of the existing OST pools mechanism will allow
 132         separating OSTs by any arbitrary criteria:  i.e. fault domain.
 133         In practice, users can take advantage of OST pools by grouping OSTs
 134         by topological information. Therefore, when creating a mirrored file,
 135         users can indicate which OST pools can be used by mirrors.</para>
 136       <para><emphasis role="strong">Examples:</emphasis></para>
 137       <para>The following command creates a mirrored file with 2 plain layout
 138         mirrors:</para>
 139       <screen>client# lfs mirror create -N -S 4M -c 2 -p flash \
 140                           -N -c -1 -p archive /mnt/testfs/file1</screen>
 141       <para>The following command displays the layout information of the
 142         mirrored file <literal>/mnt/testfs/file1</literal>:</para>
 143       <screen>client# lfs getstripe /mnt/testfs/file1
 144 /mnt/testfs/file1
 145   lcm_layout_gen:    2
 146   lcm_mirror_count:  2
 147   lcm_entry_count:   2
 148     lcme_id:             65537
 149     lcme_mirror_id:      1
 150     lcme_flags:          init
 151     lcme_extent.e_start: 0
 152     lcme_extent.e_end:   EOF
 153       lmm_stripe_count:  2
 154       lmm_stripe_size:   4194304
 155       lmm_pattern:       raid0
 156       lmm_layout_gen:    0
 157       lmm_stripe_offset: 1
 158       lmm_pool:          flash
 159       lmm_objects:
 160       - 0: { l_ost_idx: 1, l_fid: [0x100010000:0x2:0x0] }
 161       - 1: { l_ost_idx: 0, l_fid: [0x100000000:0x2:0x0] }
 162
 163     lcme_id:             131074
 164     lcme_mirror_id:      2
 165     lcme_flags:          init
 166     lcme_extent.e_start: 0
 167     lcme_extent.e_end:   EOF
 168       lmm_stripe_count:  6
 169       lmm_stripe_size:   4194304
 170       lmm_pattern:       raid0
 171       lmm_layout_gen:    0
 172       lmm_stripe_offset: 3
 173       lmm_pool:          archive
 174       lmm_objects:
 175       - 0: { l_ost_idx: 3, l_fid: [0x100030000:0x2:0x0] }
 176       - 1: { l_ost_idx: 4, l_fid: [0x100040000:0x2:0x0] }
 177       - 2: { l_ost_idx: 5, l_fid: [0x100050000:0x2:0x0] }
 178       - 3: { l_ost_idx: 6, l_fid: [0x100060000:0x2:0x0] }
 179       - 4: { l_ost_idx: 7, l_fid: [0x100070000:0x2:0x0] }
 180       - 5: { l_ost_idx: 2, l_fid: [0x100020000:0x2:0x0] }</screen>
 181       <para> The first mirror has 4MB stripe size and two stripes across OSTs in
 182         the “flash” OST pool. The second mirror has 4MB stripe size inherited
 183         from the first mirror, and stripes across all of the available OSTs in
 184         the “archive” OST pool.</para>
 185       <para>As mentioned above, it is recommended to use the
 186         <literal>--pool|-p</literal> option (one of the
 187         <literal>lfs setstripe</literal> options) with OST pools configured with
 188         independent fault domains to ensure different mirrors will be placed on
 189         different OSTs, servers, and/or racks, thereby improving availability
 190         and performance.  If the setstripe options are not specified, it is
 191         possible to create mirrors with objects on the same OST(s), which would
 192         remove most of the benefit of using replication.</para>
 193       <para>In the layout information printed by <literal>lfs getstripe</literal>,
 194         <literal>lcme_mirror_id</literal> shows mirror ID, which is the unique
 195         numerical identifier for a mirror. And <literal>lcme_flags</literal> shows
 196         mirrored component flags. Valid flag names are:</para>
 197         <itemizedlist>
 198           <listitem>
 199             <para><literal>init</literal> - indicates mirrored component has been
 200               initialized (has allocated OST objects).</para>
 201           </listitem>
 202           <listitem>
 203             <para><literal>stale</literal> - indicates mirrored component does not
 204               have up-to-date data. Stale components will not be used for read or
 205               write operations, and need to be resynchronized by running
 206               <literal>lfs mirror resync</literal> command before they can be
 207               accessed again.</para>
 208           </listitem>
 209           <listitem>
 210             <para><literal>prefer</literal> - indicates mirrored component is
 211               preferred for read or write. For example, the mirror is located on
 212               SSD-based OSTs or is closer, fewer hops, on the network to the
 213               client. This flag can be set by users at mirror creation time.</para>
 214           </listitem>
 215         </itemizedlist>
 216       <para>The following command creates a mirrored file with 3 PFL mirrors:
 217       </para>
 218       <screen>client# lfs mirror create -N -E 4M -p flash --flags=prefer -E eof -c 2 \
 219 -N -E 16M -S 8M -c 4 -p archive --comp-flags=prefer -E eof -c -1 \
 220 -N -E 32M -c 1 -p none -E eof -c -1 /mnt/testfs/file2</screen>
 221       <para>The following command displays the layout information of the
 222         mirrored file <literal>/mnt/testfs/file2</literal>:</para>
 223       <screen>client# lfs getstripe /mnt/testfs/file2
 224 /mnt/testfs/file2
 225   lcm_layout_gen:    6
 226   lcm_mirror_count:  3
 227   lcm_entry_count:   6
 228     lcme_id:             65537
 229     lcme_mirror_id:      1
 230     lcme_flags:          init,prefer
 231     lcme_extent.e_start: 0
 232     lcme_extent.e_end:   4194304
 233       lmm_stripe_count:  1
 234       lmm_stripe_size:   1048576
 235       lmm_pattern:       raid0
 236       lmm_layout_gen:    0
 237       lmm_stripe_offset: 1
 238       lmm_pool:          flash
 239       lmm_objects:
 240       - 0: { l_ost_idx: 1, l_fid: [0x100010000:0x3:0x0] }
 241
 242     lcme_id:             65538
 243     lcme_mirror_id:      1
 244     lcme_flags:          prefer
 245     lcme_extent.e_start: 4194304
 246     lcme_extent.e_end:   EOF
 247       lmm_stripe_count:  2
 248       lmm_stripe_size:   1048576
 249       lmm_pattern:       raid0
 250       lmm_layout_gen:    0
 251       lmm_stripe_offset: -1
 252       lmm_pool:          flash
 253
 254     lcme_id:             131075
 255     lcme_mirror_id:      2
 256     lcme_flags:          init,prefer
 257     lcme_extent.e_start: 0
 258     lcme_extent.e_end:   16777216
 259       lmm_stripe_count:  4
 260       lmm_stripe_size:   8388608
 261       lmm_pattern:       raid0
 262       lmm_layout_gen:    0
 263       lmm_stripe_offset: 4
 264       lmm_pool:          archive
 265       lmm_objects:
 266       - 0: { l_ost_idx: 4, l_fid: [0x100040000:0x3:0x0] }
 267       - 1: { l_ost_idx: 5, l_fid: [0x100050000:0x3:0x0] }
 268       - 2: { l_ost_idx: 6, l_fid: [0x100060000:0x3:0x0] }
 269       - 3: { l_ost_idx: 7, l_fid: [0x100070000:0x3:0x0] }
 270
 271     lcme_id:             131076
 272     lcme_mirror_id:      2
 273     lcme_flags:          0
 274     lcme_extent.e_start: 16777216
 275     lcme_extent.e_end:   EOF
 276       lmm_stripe_count:  6
 277       lmm_stripe_size:   8388608
 278       lmm_pattern:       raid0
 279       lmm_layout_gen:    0
 280       lmm_stripe_offset: -1
 281       lmm_pool:          archive
 282
 283     lcme_id:             196613
 284     lcme_mirror_id:      3
 285     lcme_flags:          init
 286     lcme_extent.e_start: 0
 287     lcme_extent.e_end:   33554432
 288       lmm_stripe_count:  1
 289       lmm_stripe_size:   8388608
 290       lmm_pattern:       raid0
 291       lmm_layout_gen:    0
 292       lmm_stripe_offset: 0
 293       lmm_objects:
 294       - 0: { l_ost_idx: 0, l_fid: [0x100000000:0x3:0x0] }
 295
 296     lcme_id:             196614
 297     lcme_mirror_id:      3
 298     lcme_flags:          0
 299     lcme_extent.e_start: 33554432
 300     lcme_extent.e_end:   EOF
 301       lmm_stripe_count:  -1
 302       lmm_stripe_size:   8388608
 303       lmm_pattern:       raid0
 304       lmm_layout_gen:    0
 305       lmm_stripe_offset: -1</screen>
 306       <para>For the first mirror, the first component inherits the stripe count
 307         and stripe size from filesystem-wide default values. The second
 308         component inherits the stripe size and OST pool from the first
 309         component, and has two stripes. Both of the components are allocated
 310         from the “flash” OST pool.  Also, the flag <literal>prefer</literal> is
 311         applied to all the components of the first mirror, which tells the
 312         client to read data from those components whenever they are available.
 313       </para>
 314       <para>For the second mirror, the first component has an 8MB stripe size
 315         and 4 stripes across OSTs in the “archive” OST pool. The second
 316         component inherits the stripe size and OST pool from the first
 317         component, and stripes across all of the available OSTs in the “archive”
 318         OST pool. The flag <literal>prefer</literal> is only applied to the
 319         first component.</para>
 320       <para>For the third mirror, the first component inherits the stripe size
 321         of 8MB from the last component of the second mirror, and has one single
 322         stripe. The OST pool name is cleared and inherited from the parent
 323         directory (if it was set with OST pool name). The second component
 324         inherits stripe size from the first component, and stripes across all of
 325         the available OSTs.</para>
 326     </section>
 327     <section xml:id="flr.operations.extendmirror">
 328       <title>Extending a Mirrored File</title>
 329       <para><emphasis role="strong">Command:</emphasis></para>
 330       <screen>lfs mirror extend [--no-verify] &lt;--mirror-count|-N[mirror_count]
 331 [setstripe_options|-f &lt;victim_file&gt;]&gt; ... &lt;filename&gt;</screen>
 332       <para>The above command will append mirror(s) indicated by
 333         <literal>setstripe options</literal> or just take the layout from
 334         existing file <replaceable>victim_file</replaceable> into the file
 335         <replaceable>filename</replaceable>. The
 336         <replaceable>filename</replaceable> must be an existing file, however,
 337         it can be a mirrored or regular non-mirrored file. If it is a
 338         non-mirrored file, the command will convert it to a mirrored file.
 339       </para>
 340       <informaltable>
 341         <tgroup cols="2">
 342           <colspec align="left" />
 343           <colspec align="left" />
 344           <thead>
 345             <row>
 346               <entry>Option</entry>
 347               <entry>Description</entry>
 348             </row>
 349           </thead>
 350           <tbody>
 351             <row>
 352               <entry>--mirror-count|-N[mirror_count]</entry>
 353               <entry>
 354                 <para>Indicates the number of mirrors to be added with the
 355                   following <literal>setstripe options</literal>. It can be
 356                   repeated multiple times to separate mirrors that have
 357                   different layouts.</para>
 358                 <para>The <replaceable>mirror_count</replaceable> argument is
 359                   optional and defaults to <literal>1</literal> if it is not
 360                   specified; if specified, it must follow the option without a
 361                   space.</para>
 362               </entry>
 363             </row>
 364             <row>
 365               <entry>setstripe_options</entry>
 366               <entry>
 367                 <para>Specifies a specific layout for the mirror. It can be a
 368                   plain layout with specific striping pattern or a composite
 369                   layout, such as <xref linkend="pfl"/>.  The options are the
 370                   same as those for the <literal>lfs setstripe</literal>
 371                   command.</para>
 372                 <para>If <replaceable>setstripe_options</replaceable> are not
 373                   specified, then the stripe options inherited from the previous
 374                   component will be used.  If there is no previous component,
 375                   then the <literal>stripe_count</literal> and
 376                   <literal>stripe_size</literal> options inherited from
 377                   filesystem-wide default values will be used, and the OST
 378                   <literal>pool_name</literal> inherited from parent directory
 379                   will be used.</para>
 380               </entry>
 381             </row>
 382             <row>
 383               <entry>-f &lt;victim_file&gt;</entry>
 384               <entry>
 385                 <para>If <replaceable>victim_file</replaceable> exists, the
 386                   command will split the layout from that file and use it as a
 387                   mirror added to the mirrored file. After the command is
 388                   finished, the <replaceable>victim_file</replaceable> will be
 389                   removed.</para>
 390                 <para><emphasis role="strong">Note</emphasis>: The
 391                   <replaceable>setstripe_options</replaceable> cannot be
 392                   specified with <literal>-f &lt;victim_file&gt;</literal>
 393                   option in one command line.</para>
 394               </entry>
 395             </row>
 396             <row>
 397               <entry>--no-verify</entry>
 398               <entry>If <replaceable>victim_file</replaceable> is specified, the
 399                 command will verify that the file contents from
 400                 <replaceable>victim_file</replaceable> are the same as
 401                 <replaceable>filename</replaceable>.  Otherwise, the command
 402                 will return a failure.  However, the option
 403                 <literal>--no-verify</literal> can be used to override this
 404                 verification. This option can save significant time on file
 405                 comparison if the file size is large, but use it only when the
 406                 file contents are known to be the same.</entry>
 407             </row>
 408           </tbody>
 409         </tgroup>
 410       </informaltable>
 411       <para><emphasis role="strong">Note</emphasis>:  The
 412         <literal>lfs mirror extend</literal> operation won't be applied to the
 413         directory.</para>
 414       <para><emphasis role="strong">Examples:</emphasis></para>
 415       <para>The following commands create a non-mirrored file, convert it to
 416         a mirrored file, and extend it with a plain layout mirror:</para>
 417       <screen># lfs setstripe -p flash /mnt/testfs/file1
 418 # lfs getstripe /mnt/testfs/file1
 419 /mnt/testfs/file1
 420 lmm_stripe_count:  1
 421 lmm_stripe_size:   1048576
 422 lmm_pattern:       raid0
 423 lmm_layout_gen:    0
 424 lmm_stripe_offset: 0
 425 lmm_pool:          flash
 426         obdidx           objid           objid           group
 427              0               4            0x4                0
 428
 429 # lfs mirror extend -N -S 8M -c -1 -p archive /mnt/testfs/file1
 430 # lfs getstripe /mnt/testfs/file1
 431 /mnt/testfs/file1
 432   lcm_layout_gen:    2
 433   lcm_mirror_count:  2
 434   lcm_entry_count:   2
 435     lcme_id:             65537
 436     lcme_mirror_id:      1
 437     lcme_flags:          init
 438     lcme_extent.e_start: 0
 439     lcme_extent.e_end:   EOF
 440       lmm_stripe_count:  1
 441       lmm_stripe_size:   1048576
 442       lmm_pattern:       raid0
 443       lmm_layout_gen:    0
 444       lmm_stripe_offset: 0
 445       lmm_pool:          flash
 446       lmm_objects:
 447       - 0: { l_ost_idx: 0, l_fid: [0x100000000:0x4:0x0] }
 448
 449     lcme_id:             131073
 450     lcme_mirror_id:      2
 451     lcme_flags:          init
 452     lcme_extent.e_start: 0
 453     lcme_extent.e_end:   EOF
 454       lmm_stripe_count:  6
 455       lmm_stripe_size:   8388608
 456       lmm_pattern:       raid0
 457       lmm_layout_gen:    0
 458       lmm_stripe_offset: 3
 459       lmm_pool:          archive
 460       lmm_objects:
 461       - 0: { l_ost_idx: 3, l_fid: [0x100030000:0x3:0x0] }
 462       - 1: { l_ost_idx: 4, l_fid: [0x100040000:0x4:0x0] }
 463       - 2: { l_ost_idx: 5, l_fid: [0x100050000:0x4:0x0] }
 464       - 3: { l_ost_idx: 6, l_fid: [0x100060000:0x4:0x0] }
 465       - 4: { l_ost_idx: 7, l_fid: [0x100070000:0x4:0x0] }
 466       - 5: { l_ost_idx: 2, l_fid: [0x100020000:0x3:0x0] }</screen>
 467       <para>The following commands split the PFL layout from a
 468         <replaceable>victim_file</replaceable> and use it as a mirror added to
 469         the mirrored file <literal>/mnt/testfs/file1</literal> created in the
 470         above example without data verification:</para>
 471       <screen># lfs setstripe -E 16M -c 2 -p none \
 472                 -E eof -c -1 /mnt/testfs/victim_file
 473 # lfs getstripe /mnt/testfs/victim_file
 474 /mnt/testfs/victim_file
 475   lcm_layout_gen:    2
 476   lcm_mirror_count:  1
 477   lcm_entry_count:   2
 478     lcme_id:             1
 479     lcme_mirror_id:      0
 480     lcme_flags:          init
 481     lcme_extent.e_start: 0
 482     lcme_extent.e_end:   16777216
 483       lmm_stripe_count:  2
 484       lmm_stripe_size:   1048576
 485       lmm_pattern:       raid0
 486       lmm_layout_gen:    0
 487       lmm_stripe_offset: 5
 488       lmm_objects:
 489       - 0: { l_ost_idx: 5, l_fid: [0x100050000:0x5:0x0] }
 490       - 1: { l_ost_idx: 6, l_fid: [0x100060000:0x5:0x0] }
 491
 492     lcme_id:             2
 493     lcme_mirror_id:      0
 494     lcme_flags:          0
 495     lcme_extent.e_start: 16777216
 496     lcme_extent.e_end:   EOF
 497       lmm_stripe_count:  -1
 498       lmm_stripe_size:   1048576
 499       lmm_pattern:       raid0
 500       lmm_layout_gen:    0
 501       lmm_stripe_offset: -1
 502
 503 # lfs mirror extend --no-verify -N -f /mnt/testfs/victim_file \
 504                     /mnt/testfs/file1
 505 # lfs getstripe /mnt/testfs/file1
 506 /mnt/testfs/file1
 507   lcm_layout_gen:    3
 508   lcm_mirror_count:  3
 509   lcm_entry_count:   4
 510     lcme_id:             65537
 511     lcme_mirror_id:      1
 512     lcme_flags:          init
 513     lcme_extent.e_start: 0
 514     lcme_extent.e_end:   EOF
 515       lmm_stripe_count:  1
 516       lmm_stripe_size:   1048576
 517       lmm_pattern:       raid0
 518       lmm_layout_gen:    0
 519       lmm_stripe_offset: 0
 520       lmm_pool:          flash
 521       lmm_objects:
 522       - 0: { l_ost_idx: 0, l_fid: [0x100000000:0x4:0x0] }
 523
 524     lcme_id:             131073
 525     lcme_mirror_id:      2
 526     lcme_flags:          init
 527     lcme_extent.e_start: 0
 528     lcme_extent.e_end:   EOF
 529       lmm_stripe_count:  6
 530       lmm_stripe_size:   8388608
 531       lmm_pattern:       raid0
 532       lmm_layout_gen:    0
 533       lmm_stripe_offset: 3
 534       lmm_pool:          archive
 535       lmm_objects:
 536       - 0: { l_ost_idx: 3, l_fid: [0x100030000:0x3:0x0] }
 537       - 1: { l_ost_idx: 4, l_fid: [0x100040000:0x4:0x0] }
 538       - 2: { l_ost_idx: 5, l_fid: [0x100050000:0x4:0x0] }
 539       - 3: { l_ost_idx: 6, l_fid: [0x100060000:0x4:0x0] }
 540       - 4: { l_ost_idx: 7, l_fid: [0x100070000:0x4:0x0] }
 541       - 5: { l_ost_idx: 2, l_fid: [0x100020000:0x3:0x0] }
 542
 543     lcme_id:             196609
 544     lcme_mirror_id:      3
 545     lcme_flags:          init
 546     lcme_extent.e_start: 0
 547     lcme_extent.e_end:   16777216
 548       lmm_stripe_count:  2
 549       lmm_stripe_size:   1048576
 550       lmm_pattern:       raid0
 551       lmm_layout_gen:    0
 552       lmm_stripe_offset: 5
 553       lmm_objects:
 554       - 0: { l_ost_idx: 5, l_fid: [0x100050000:0x5:0x0] }
 555       - 1: { l_ost_idx: 6, l_fid: [0x100060000:0x5:0x0] }
 556
 557     lcme_id:             196610
 558     lcme_mirror_id:      3
 559     lcme_flags:          0
 560     lcme_extent.e_start: 16777216
 561     lcme_extent.e_end:   EOF
 562       lmm_stripe_count:  -1
 563       lmm_stripe_size:   1048576
 564       lmm_pattern:       raid0
 565       lmm_layout_gen:    0
 566       lmm_stripe_offset: -1</screen>
 567       <para>After extending, the <replaceable>victim_file</replaceable> was
 568         removed:</para>
 569       <screen># ls /mnt/testfs/victim_file
 570 ls: cannot access /mnt/testfs/victim_file: No such file or directory</screen>
 571     </section>
 572     <section xml:id="flr.operations.splitmirror">
 573       <title>Splitting a Mirrored File</title>
 574       <para><emphasis role="strong">Command:</emphasis></para>
 575       <screen>lfs mirror split &lt;--mirror-id &lt;mirror_id&gt;&gt;
 576 [--destroy|-d] [-f &lt;new_file&gt;] &lt;mirrored_file&gt;</screen>
 577       <para>The above command will split a specified mirror with ID
 578         <replaceable>&lt;mirror_id&gt;</replaceable> out of an existing mirrored
 579         file specified by
 580         <replaceable>mirrored_file</replaceable>. By default, a new file named
 581         <literal>&lt;mirrored_file&gt;.mirror~&lt;mirror_id&gt;</literal> will
 582         be created with the layout of the split mirror. If the
 583         <literal>--destroy|-d</literal> option is specified, then the split
 584         mirror will be destroyed. If the <literal>-f &lt;new_file&gt;</literal>
 585         option is specified, then a file named
 586         <replaceable>new_file</replaceable> will be created with the layout of
 587         the split mirror. If <replaceable>mirrored_file</replaceable> has only
 588         one mirror existing after split, it will be converted to a regular
 589         non-mirrored file. If the original
 590         <replaceable>mirrored_file</replaceable> is not a mirrored file, then
 591         the command will return an error.</para>
 592       <informaltable>
 593         <tgroup cols="2">
 594           <colspec align="left" />
 595           <colspec align="left" />
 596           <thead>
 597             <row>
 598               <entry>Option</entry>
 599               <entry>Description</entry>
 600             </row>
 601           </thead>
 602           <tbody>
 603             <row>
 604               <entry>--mirror-id &lt;mirror_id&gt;</entry>
 605               <entry>The unique numerical identifier for a mirror. The mirror
 606                 ID is unique within a mirrored file and is automatically
 607                 assigned at file creation or extension time. It can be fetched
 608                 by the <literal>lfs getstripe</literal> command.
 609               </entry>
 610             </row>
 611             <row>
 612               <entry>--destroy|-d</entry>
 613               <entry>Indicates the split mirror will be destroyed.</entry>
 614             </row>
 615             <row>
 616               <entry>-f &lt;new_file&gt;</entry>
 617               <entry>Indicates a file named <replaceable>new_file</replaceable>
 618                 will be created with the layout of the split mirror.</entry>
 619             </row>
 620           </tbody>
 621         </tgroup>
 622       </informaltable>
 623       <para><emphasis role="strong">Examples:</emphasis></para>
 624       <para>The following commands create a mirrored file with 4 mirrors, then
 625         split 3 mirrors separately from the mirrored file.</para>
 626       <para>Creating a mirrored file with 4 mirrors:</para>
 627       <screen># lfs mirror create -N2 -E 4M -p flash -E eof -c -1 \
 628                     -N2 -S 8M -c 2 -p archive /mnt/testfs/file1
 629 # lfs getstripe /mnt/testfs/file1
 630 /mnt/testfs/file1
 631   lcm_layout_gen:    6
 632   lcm_mirror_count:  4
 633   lcm_entry_count:   6
 634     lcme_id:             65537
 635     lcme_mirror_id:      1
 636     lcme_flags:          init
 637     lcme_extent.e_start: 0
 638     lcme_extent.e_end:   4194304
 639       lmm_stripe_count:  1
 640       lmm_stripe_size:   1048576
 641       lmm_pattern:       raid0
 642       lmm_layout_gen:    0
 643       lmm_stripe_offset: 1
 644       lmm_pool:          flash
 645       lmm_objects:
 646       - 0: { l_ost_idx: 1, l_fid: [0x100010000:0x4:0x0] }
 647
 648     lcme_id:             65538
 649     lcme_mirror_id:      1
 650     lcme_flags:          0
 651     lcme_extent.e_start: 4194304
 652     lcme_extent.e_end:   EOF
 653       lmm_stripe_count:  2
 654       lmm_stripe_size:   1048576
 655       lmm_pattern:       raid0
 656       lmm_layout_gen:    0
 657       lmm_stripe_offset: -1
 658       lmm_pool:          flash
 659
 660     lcme_id:             131075
 661     lcme_mirror_id:      2
 662     lcme_flags:          init
 663     lcme_extent.e_start: 0
 664     lcme_extent.e_end:   4194304
 665       lmm_stripe_count:  1
 666       lmm_stripe_size:   1048576
 667       lmm_pattern:       raid0
 668       lmm_layout_gen:    0
 669       lmm_stripe_offset: 0
 670       lmm_pool:          flash
 671       lmm_objects:
 672       - 0: { l_ost_idx: 0, l_fid: [0x100000000:0x5:0x0] }
 673
 674     lcme_id:             131076
 675     lcme_mirror_id:      2
 676     lcme_flags:          0
 677     lcme_extent.e_start: 4194304
 678     lcme_extent.e_end:   EOF
 679       lmm_stripe_count:  2
 680       lmm_stripe_size:   1048576
 681       lmm_pattern:       raid0
 682       lmm_layout_gen:    0
 683       lmm_stripe_offset: -1
 684       lmm_pool:          flash
 685
 686     lcme_id:             196613
 687     lcme_mirror_id:      3
 688     lcme_flags:          init
 689     lcme_extent.e_start: 0
 690     lcme_extent.e_end:   EOF
 691       lmm_stripe_count:  2
 692       lmm_stripe_size:   8388608
 693       lmm_pattern:       raid0
 694       lmm_layout_gen:    0
 695       lmm_stripe_offset: 4
 696       lmm_pool:          archive
 697       lmm_objects:
 698       - 0: { l_ost_idx: 4, l_fid: [0x100040000:0x5:0x0] }
 699       - 1: { l_ost_idx: 5, l_fid: [0x100050000:0x6:0x0] }
 700
 701     lcme_id:             262150
 702     lcme_mirror_id:      4
 703     lcme_flags:          init
 704     lcme_extent.e_start: 0
 705     lcme_extent.e_end:   EOF
 706       lmm_stripe_count:  2
 707       lmm_stripe_size:   8388608
 708       lmm_pattern:       raid0
 709       lmm_layout_gen:    0
 710       lmm_stripe_offset: 7
 711       lmm_pool:          archive
 712       lmm_objects:
 713       - 0: { l_ost_idx: 7, l_fid: [0x100070000:0x5:0x0] }
 714       - 1: { l_ost_idx: 2, l_fid: [0x100020000:0x4:0x0] }</screen>
 715       <para>Splitting the mirror with ID <literal>1</literal> from
 716         <literal>/mnt/testfs/file1</literal> and creating
 717         <literal>/mnt/testfs/file1.mirror~1</literal> with the layout of the
 718         split mirror:</para>
 719       <screen># lfs mirror split --mirror-id 1 /mnt/testfs/file1
 720 # lfs getstripe /mnt/testfs/file1.mirror~1
 721 /mnt/testfs/file1.mirror~1
 722   lcm_layout_gen:    1
 723   lcm_mirror_count:  1
 724   lcm_entry_count:   2
 725     lcme_id:             65537
 726     lcme_mirror_id:      1
 727     lcme_flags:          init
 728     lcme_extent.e_start: 0
 729     lcme_extent.e_end:   4194304
 730       lmm_stripe_count:  1
 731       lmm_stripe_size:   1048576
 732       lmm_pattern:       raid0
 733       lmm_layout_gen:    0
 734       lmm_stripe_offset: 1
 735       lmm_pool:          flash
 736       lmm_objects:
 737       - 0: { l_ost_idx: 1, l_fid: [0x100010000:0x4:0x0] }
 738
 739     lcme_id:             65538
 740     lcme_mirror_id:      1
 741     lcme_flags:          0
 742     lcme_extent.e_start: 4194304
 743     lcme_extent.e_end:   EOF
 744       lmm_stripe_count:  2
 745       lmm_stripe_size:   1048576
 746       lmm_pattern:       raid0
 747       lmm_layout_gen:    0
 748       lmm_stripe_offset: -1
 749       lmm_pool:          flash</screen>
 750       <para>Splitting the mirror with ID <literal>2</literal> from
 751         <literal>/mnt/testfs/file1</literal> and destroying it:</para>
 752       <screen># lfs mirror split --mirror-id 2 -d /mnt/testfs/file1
 753 # lfs getstripe /mnt/testfs/file1
 754 /mnt/testfs/file1
 755   lcm_layout_gen:    8
 756   lcm_mirror_count:  2
 757   lcm_entry_count:   2
 758     lcme_id:             196613
 759     lcme_mirror_id:      3
 760     lcme_flags:          init
 761     lcme_extent.e_start: 0
 762     lcme_extent.e_end:   EOF
 763       lmm_stripe_count:  2
 764       lmm_stripe_size:   8388608
 765       lmm_pattern:       raid0
 766       lmm_layout_gen:    0
 767       lmm_stripe_offset: 4
 768       lmm_pool:          archive
 769       lmm_objects:
 770       - 0: { l_ost_idx: 4, l_fid: [0x100040000:0x5:0x0] }
 771       - 1: { l_ost_idx: 5, l_fid: [0x100050000:0x6:0x0] }
 772
 773     lcme_id:             262150
 774     lcme_mirror_id:      4
 775     lcme_flags:          init
 776     lcme_extent.e_start: 0
 777     lcme_extent.e_end:   EOF
 778       lmm_stripe_count:  2
 779       lmm_stripe_size:   8388608
 780       lmm_pattern:       raid0
 781       lmm_layout_gen:    0
 782       lmm_stripe_offset: 7
 783       lmm_pool:          archive
 784       lmm_objects:
 785       - 0: { l_ost_idx: 7, l_fid: [0x100070000:0x5:0x0] }
 786       - 1: { l_ost_idx: 2, l_fid: [0x100020000:0x4:0x0] }</screen>
 787       <para>Splitting the mirror with ID <literal>3</literal> from
 788         <literal>/mnt/testfs/file1</literal> and creating
 789         <literal>/mnt/testfs/file2</literal> with the layout of the split
 790         mirror:</para>
 791       <screen># lfs mirror split --mirror-id 3 -f /mnt/testfs/file2 \
 792                    /mnt/testfs/file1
 793 # lfs getstripe /mnt/testfs/file2
 794 /mnt/testfs/file2
 795   lcm_layout_gen:    1
 796   lcm_mirror_count:  1
 797   lcm_entry_count:   1
 798     lcme_id:             196613
 799     lcme_mirror_id:      3
 800     lcme_flags:          init
 801     lcme_extent.e_start: 0
 802     lcme_extent.e_end:   EOF
 803       lmm_stripe_count:  2
 804       lmm_stripe_size:   8388608
 805       lmm_pattern:       raid0
 806       lmm_layout_gen:    0
 807       lmm_stripe_offset: 4
 808       lmm_pool:          archive
 809       lmm_objects:
 810       - 0: { l_ost_idx: 4, l_fid: [0x100040000:0x5:0x0] }
 811       - 1: { l_ost_idx: 5, l_fid: [0x100050000:0x6:0x0] }
 812
 813 # lfs getstripe /mnt/testfs/file1
 814 /mnt/testfs/file1
 815   lcm_layout_gen:    9
 816   lcm_mirror_count:  1
 817   lcm_entry_count:   1
 818     lcme_id:             262150
 819     lcme_mirror_id:      4
 820     lcme_flags:          init
 821     lcme_extent.e_start: 0
 822     lcme_extent.e_end:   EOF
 823       lmm_stripe_count:  2
 824       lmm_stripe_size:   8388608
 825       lmm_pattern:       raid0
 826       lmm_layout_gen:    0
 827       lmm_stripe_offset: 7
 828       lmm_pool:          archive
 829       lmm_objects:
 830       - 0: { l_ost_idx: 7, l_fid: [0x100070000:0x5:0x0] }
 831       - 1: { l_ost_idx: 2, l_fid: [0x100020000:0x4:0x0] }</screen>
 832       <para>The above layout information showed that mirrors with ID
 833         <literal>1, 2, and 3</literal> were all split from the mirrored file
 834         <literal>/mnt/testfs/file1</literal>.</para>
 835     </section>
 836     <section xml:id="flr.operations.resyncmirror">
 837       <title>Resynchronizing out-of-sync Mirrored File(s)</title>
 838       <para><emphasis role="strong">Command:</emphasis></para>
 839       <screen>lfs mirror resync [--only &lt;mirror_id[,...]&gt;]
 840 &lt;mirrored_file&gt; [&lt;mirrored_file2&gt;...]</screen>
 841       <para>The above command will resynchronize out-of-sync mirrored file(s)
 842         specified by <replaceable>mirrored_file</replaceable>. It
 843         supports specifying multiple mirrored files in one command line.</para>
 844       <para>If there is no stale mirror for the specified mirrored file(s), then
 845         the command does nothing. Otherwise, it will copy data from synced
 846         mirror to the stale mirror(s), and mark all successfully copied
 847         mirror(s) as SYNC. If the
 848         <literal>--only &lt;mirror_id[,...]&gt;</literal> option is specified,
 849         then the command will only resynchronize the mirror(s) specified by the
 850         <replaceable>mirror_id(s)</replaceable>. This option cannot be used when
 851         multiple mirrored files are specified.</para>
 852       <informaltable>
 853         <tgroup cols="2">
 854           <colspec align="left" />
 855           <colspec align="left" />
 856           <thead>
 857             <row>
 858               <entry>Option</entry>
 859               <entry>Description</entry>
 860             </row>
 861           </thead>
 862           <tbody>
 863             <row>
 864               <entry>--only &lt;mirror_id[,...]&gt;</entry>
 865               <entry>Indicates which mirror(s) specified by
 866                 <replaceable>mirror_id(s)</replaceable> needs to be
 867                 resynchronized. The <replaceable>mirror_id</replaceable> is the
 868                 unique numerical identifier for a mirror. Multiple
 869                 <replaceable>mirror_ids</replaceable> are separated by comma.
 870                 This option cannot be used when multiple mirrored files are
 871                 specified.</entry>
 872             </row>
 873           </tbody>
 874         </tgroup>
 875       </informaltable>
 876       <para><emphasis role="strong">Note:</emphasis>  With delayed write
 877         implemented in FLR phase 1, after writing to a mirrored file, users
 878         need to run <literal>lfs mirror resync</literal> command to get all
 879         mirrors synchronized.</para>
 880       <para><emphasis role="strong">Examples:</emphasis></para>
 881       <para>The following commands create a mirrored file with 3 mirrors, then
 882         write some data into the file and resynchronizes stale mirrors.</para>
 883       <para>Creating a mirrored file with 3 mirrors:</para>
 884       <screen># lfs mirror create -N -E 4M -p flash -E eof \
 885                     -N2 -p archive /mnt/testfs/file1
 886 # lfs getstripe /mnt/testfs/file1
 887 /mnt/testfs/file1
 888   lcm_layout_gen:    4
 889   lcm_mirror_count:  3
 890   lcm_entry_count:   4
 891     lcme_id:             65537
 892     lcme_mirror_id:      1
 893     lcme_flags:          init
 894     lcme_extent.e_start: 0
 895     lcme_extent.e_end:   4194304
 896       lmm_stripe_count:  1
 897       lmm_stripe_size:   1048576
 898       lmm_pattern:       raid0
 899       lmm_layout_gen:    0
 900       lmm_stripe_offset: 1
 901       lmm_pool:          flash
 902       lmm_objects:
 903       - 0: { l_ost_idx: 1, l_fid: [0x100010000:0x5:0x0] }
 904
 905     lcme_id:             65538
 906     lcme_mirror_id:      1
 907     lcme_flags:          0
 908     lcme_extent.e_start: 4194304
 909     lcme_extent.e_end:   EOF
 910       lmm_stripe_count:  1
 911       lmm_stripe_size:   1048576
 912       lmm_pattern:       raid0
 913       lmm_layout_gen:    0
 914       lmm_stripe_offset: -1
 915       lmm_pool:          flash
 916
 917     lcme_id:             131075
 918     lcme_mirror_id:      2
 919     lcme_flags:          init
 920     lcme_extent.e_start: 0
 921     lcme_extent.e_end:   EOF
 922       lmm_stripe_count:  1
 923       lmm_stripe_size:   1048576
 924       lmm_pattern:       raid0
 925       lmm_layout_gen:    0
 926       lmm_stripe_offset: 3
 927       lmm_pool:          archive
 928       lmm_objects:
 929       - 0: { l_ost_idx: 3, l_fid: [0x100030000:0x4:0x0] }
 930
 931     lcme_id:             196612
 932     lcme_mirror_id:      3
 933     lcme_flags:          init
 934     lcme_extent.e_start: 0
 935     lcme_extent.e_end:   EOF
 936       lmm_stripe_count:  1
 937       lmm_stripe_size:   1048576
 938       lmm_pattern:       raid0
 939       lmm_layout_gen:    0
 940       lmm_stripe_offset: 4
 941       lmm_pool:          archive
 942       lmm_objects:
 943       - 0: { l_ost_idx: 4, l_fid: [0x100040000:0x6:0x0] }</screen>
 944       <para>Writing some data into the mirrored file
 945         <literal>/mnt/testfs/file1</literal>:</para>
 946       <screen># yes | dd of=/mnt/testfs/file1 bs=1M count=2
 947 2+0 records in
 948 2+0 records out
 949 2097152 bytes (2.1 MB) copied, 0.0320613 s, 65.4 MB/s
 950
 951 # lfs getstripe /mnt/testfs/file1
 952 /mnt/testfs/file1
 953   lcm_layout_gen:    5
 954   lcm_mirror_count:  3
 955   lcm_entry_count:   4
 956     lcme_id:             65537
 957     lcme_mirror_id:      1
 958     lcme_flags:          init
 959     lcme_extent.e_start: 0
 960     lcme_extent.e_end:   4194304
 961     ......
 962
 963     lcme_id:             65538
 964     lcme_mirror_id:      1
 965     lcme_flags:          0
 966     lcme_extent.e_start: 4194304
 967     lcme_extent.e_end:   EOF
 968     ......
 969
 970     lcme_id:             131075
 971     lcme_mirror_id:      2
 972     lcme_flags:          init,stale
 973     lcme_extent.e_start: 0
 974     lcme_extent.e_end:   EOF
 975     ......
 976
 977     lcme_id:             196612
 978     lcme_mirror_id:      3
 979     lcme_flags:          init,stale
 980     lcme_extent.e_start: 0
 981     lcme_extent.e_end:   EOF
 982     ......
 983 </screen>
 984       <para>The above layout information showed that data were written into the
 985         first component of mirror with ID <literal>1</literal>, and mirrors with
 986         ID <literal>2</literal> and <literal>3</literal> were marked with
 987         “stale” flag.</para>
 988       <para>Resynchronizing the stale mirror with ID <literal>2</literal> for
 989         the mirrored file <literal>/mnt/testfs/file1</literal>:</para>
 990       <screen># lfs mirror resync --only 2 /mnt/testfs/file1
 991 # lfs getstripe /mnt/testfs/file1
 992 /mnt/testfs/file1
 993   lcm_layout_gen:    7
 994   lcm_mirror_count:  3
 995   lcm_entry_count:   4
 996     lcme_id:             65537
 997     lcme_mirror_id:      1
 998     lcme_flags:          init
 999     lcme_extent.e_start: 0
1000     lcme_extent.e_end:   4194304
1001     ......
1002
1003     lcme_id:             65538
1004     lcme_mirror_id:      1
1005     lcme_flags:          0
1006     lcme_extent.e_start: 4194304
1007     lcme_extent.e_end:   EOF
1008     ......
1009
1010     lcme_id:             131075
1011     lcme_mirror_id:      2
1012     lcme_flags:          init
1013     lcme_extent.e_start: 0
1014     lcme_extent.e_end:   EOF
1015     ......
1016
1017     lcme_id:             196612
1018     lcme_mirror_id:      3
1019     lcme_flags:          init,stale
1020     lcme_extent.e_start: 0
1021     lcme_extent.e_end:   EOF
1022     ......
1023 </screen>
1024       <para>The above layout information showed that after resynchronizing, the
1025         “stale” flag was removed from mirror with ID <literal>2</literal>.</para>
1026       <para>Resynchronizing all of the stale mirrors for the mirrored file
1027         <literal>/mnt/testfs/file1</literal>:</para>
1028       <screen># lfs mirror resync /mnt/testfs/file1
1029 # lfs getstripe /mnt/testfs/file1
1030 /mnt/testfs/file1
1031   lcm_layout_gen:    9
1032   lcm_mirror_count:  3
1033   lcm_entry_count:   4
1034     lcme_id:             65537
1035     lcme_mirror_id:      1
1036     lcme_flags:          init
1037     lcme_extent.e_start: 0
1038     lcme_extent.e_end:   4194304
1039     ......
1040
1041     lcme_id:             65538
1042     lcme_mirror_id:      1
1043     lcme_flags:          0
1044     lcme_extent.e_start: 4194304
1045     lcme_extent.e_end:   EOF
1046     ......
1047
1048     lcme_id:             131075
1049     lcme_mirror_id:      2
1050     lcme_flags:          init
1051     lcme_extent.e_start: 0
1052     lcme_extent.e_end:   EOF
1053     ......
1054
1055     lcme_id:             196612
1056     lcme_mirror_id:      3
1057     lcme_flags:          init
1058     lcme_extent.e_start: 0
1059     lcme_extent.e_end:   EOF
1060     ......
1061 </screen>
1062       <para>The above layout information showed that after resynchronizing, none
1063         of the mirrors were marked as stale.</para>
1064     </section>
1065     <section xml:id="flr.operations.verifymirror">
1066       <title>Verifying Mirrored File(s)</title>
1067       <para><emphasis role="strong">Command:</emphasis></para>
1068       <screen>lfs mirror verify [--only &lt;mirror_id,mirror_id2[,...]&gt;]
1069 [--verbose|-v] &lt;mirrored_file&gt; [&lt;mirrored_file2&gt; ...]</screen>
1070       <para>The above command will verify that each SYNC mirror (contains
1071         up-to-date data) of a mirrored file, specified by
1072         <replaceable>mirrored_file</replaceable>, has exactly the same data.  It
1073         supports specifying multiple mirrored files in one command line.</para>
1074       <para>This is a scrub tool that should be run on regular basis to make
1075         sure that mirrored files are not corrupted. The command won't repair the
1076         file if it turns out to be corrupted. Usually, an administrator should
1077         check the file content from each mirror and decide which one is correct
1078         and then invoke <literal>lfs mirror resync</literal> to repair it
1079         manually.</para>
1080       <informaltable>
1081         <tgroup cols="2">
1082           <colspec align="left" />
1083           <colspec align="left" />
1084           <thead>
1085             <row>
1086               <entry>Option</entry>
1087               <entry>Description</entry>
1088             </row>
1089           </thead>
1090           <tbody>
1091             <row>
1092               <entry>--only &lt;mirror_id,mirror_id2[,...]&gt;</entry>
1093               <entry><para>Indicates which mirrors specified by
1094                 <replaceable>mirror_ids</replaceable> need to be verified. The
1095                 <replaceable>mirror_id</replaceable> is the unique numerical
1096                 identifier for a mirror. Multiple
1097                 <replaceable>mirror_ids</replaceable> are separated by comma.
1098                 </para>
1099                 <para>Note: At least two <replaceable>mirror_ids</replaceable>
1100                   are required. This option cannot be used when multiple
1101                   mirrored files are specified.</para>
1102               </entry>
1103             </row>
1104             <row>
1105               <entry>--verbose|-v</entry>
1106               <entry>Indicates the command will print where the differences are
1107                 if the data do not match. Otherwise, the command will just
1108                 return an error in that case. This option can be repeated for
1109                 multiple times to print more information.</entry>
1110             </row>
1111           </tbody>
1112         </tgroup>
1113       </informaltable>
1114       <para><emphasis role="strong">Note:</emphasis></para>
1115       <para>Mirror components that have “stale” or “offline” flags will be
1116         skipped and not verified.</para>
1117       <para><emphasis role="strong">Examples:</emphasis></para>
1118       <para>The following command verifies that each mirror of a mirrored file
1119         contains exactly the same data:</para>
1120       <screen># lfs mirror verify /mnt/testfs/file1</screen>
1121       <para>The following command has the <literal>-v</literal> option specified
1122         to print where the differences are if the data does not match:</para>
1123       <screen># lfs mirror verify -vvv /mnt/testfs/file2
1124 Chunks to be verified in /mnt/testfs/file2:
1125 [0, 0x200000)   [1, 2, 3, 4]    4
1126 [0x200000, 0x400000)    [1, 2, 3, 4]    4
1127 [0x400000, 0x600000)    [1, 2, 3, 4]    4
1128 [0x600000, 0x800000)    [1, 2, 3, 4]    4
1129 [0x800000, 0xa00000)    [1, 2, 3, 4]    4
1130 [0xa00000, 0x1000000)   [1, 2, 3, 4]    4
1131 [0x1000000, 0xffffffffffffffff) [1, 2, 3, 4]    4
1132
1133 Verifying chunk [0, 0x200000) on mirror: 1 2 3 4
1134 CRC-32 checksum value for chunk [0, 0x200000):
1135 Mirror 1:       0x207b02f1
1136 Mirror 2:       0x207b02f1
1137 Mirror 3:       0x207b02f1
1138 Mirror 4:       0x207b02f1
1139
1140 Verifying chunk [0, 0x200000) on mirror: 1 2 3 4 PASS
1141
1142 Verifying chunk [0x200000, 0x400000) on mirror: 1 2 3 4
1143 CRC-32 checksum value for chunk [0x200000, 0x400000):
1144 Mirror 1:       0x207b02f1
1145 Mirror 2:       0x207b02f1
1146 Mirror 3:       0x207b02f1
1147 Mirror 4:       0x207b02f1
1148
1149 Verifying chunk [0x200000, 0x400000) on mirror: 1 2 3 4 PASS
1150
1151 Verifying chunk [0x400000, 0x600000) on mirror: 1 2 3 4
1152 CRC-32 checksum value for chunk [0x400000, 0x600000):
1153 Mirror 1:       0x42571b66
1154 Mirror 2:       0x42571b66
1155 Mirror 3:       0x42571b66
1156 Mirror 4:       0xabdaf92
1157
1158 lfs mirror verify: chunk [0x400000, 0x600000) has different
1159 checksum value on mirror 1 and mirror 4.
1160 Verifying chunk [0x600000, 0x800000) on mirror: 1 2 3 4
1161 CRC-32 checksum value for chunk [0x600000, 0x800000):
1162 Mirror 1:       0x1f8ad0d8
1163 Mirror 2:       0x1f8ad0d8
1164 Mirror 3:       0x1f8ad0d8
1165 Mirror 4:       0x18975bf9
1166
1167 lfs mirror verify: chunk [0x600000, 0x800000) has different
1168 checksum value on mirror 1 and mirror 4.
1169 Verifying chunk [0x800000, 0xa00000) on mirror: 1 2 3 4
1170 CRC-32 checksum value for chunk [0x800000, 0xa00000):
1171 Mirror 1:       0x69c17478
1172 Mirror 2:       0x69c17478
1173 Mirror 3:       0x69c17478
1174 Mirror 4:       0x69c17478
1175
1176 Verifying chunk [0x800000, 0xa00000) on mirror: 1 2 3 4 PASS
1177
1178 lfs mirror verify: '/mnt/testfs/file2' chunk [0xa00000, 0x1000000]
1179 exceeds file size 0xa00000: skipped</screen>
1180       <para>The following command uses the <literal>--only</literal> option to
1181         only verify the specified mirrors:</para>
1182       <screen># lfs mirror verify -v --only 1,4 /mnt/testfs/file2
1183 CRC-32 checksum value for chunk [0, 0x200000):
1184 Mirror 1:       0x207b02f1
1185 Mirror 4:       0x207b02f1
1186
1187 CRC-32 checksum value for chunk [0x200000, 0x400000):
1188 Mirror 1:       0x207b02f1
1189 Mirror 4:       0x207b02f1
1190
1191 CRC-32 checksum value for chunk [0x400000, 0x600000):
1192 Mirror 1:       0x42571b66
1193 Mirror 4:       0xabdaf92
1194
1195 lfs mirror verify: chunk [0x400000, 0x600000) has different
1196 checksum value on mirror 1 and mirror 4.
1197 CRC-32 checksum value for chunk [0x600000, 0x800000):
1198 Mirror 1:       0x1f8ad0d8
1199 Mirror 4:       0x18975bf9
1200
1201 lfs mirror verify: chunk [0x600000, 0x800000) has different
1202 checksum value on mirror 1 and mirror 4.
1203 CRC-32 checksum value for chunk [0x800000, 0xa00000):
1204 Mirror 1:       0x69c17478
1205 Mirror 4:       0x69c17478
1206
1207 lfs mirror verify: '/mnt/testfs/file2' chunk [0xa00000, 0x1000000]
1208 exceeds file size 0xa00000: skipped</screen>
1209     </section>
1210     <section xml:id="flr.operations.findingmirror">
1211       <title>Finding Mirrored File(s)</title>
1212       <para>The <literal>lfs find</literal> command is used to list files and
1213         directories with specific attributes. The following two attribute
1214         parameters are specific to a mirrored file or directory:</para>
1215       <screen>lfs find &lt;directory|filename ...&gt;
1216     [[!] --mirror-count|-N [+-]n]
1217     [[!] --mirror-state &lt;[^]state&gt;]</screen>
1218       <informaltable>
1219         <tgroup cols="2">
1220           <colspec align="left" />
1221           <colspec align="left" />
1222           <thead>
1223             <row>
1224               <entry>Option</entry>
1225               <entry>Description</entry>
1226             </row>
1227           </thead>
1228           <tbody>
1229             <row>
1230               <entry>--mirror-count|-N [+-]n</entry>
1231               <entry>Indicates mirror count.</entry>
1232             </row>
1233             <row>
1234               <entry>--mirror-state &lt;[^]state&gt;</entry>
1235               <entry>
1236                 <para>Indicates mirrored file state.</para>
1237                 <para>If <replaceable>^state</replaceable> is used, print only
1238                   files not matching <replaceable>state</replaceable>. Only one
1239                   state can be specified.</para>
1240                 <para>Valid state names are:</para>
1241                 <para><literal>ro</literal> – indicates the mirrored file is in
1242                   read-only state. All of the mirrors contain the up-to-date
1243                   data.</para>
1244                 <para><literal>wp</literal> – indicates the mirrored file is in
1245                   a state of being written.</para>
1246                 <para><literal>sp</literal> – indicates the mirrored file is in
1247                   a state of being resynchronized.</para>
1248               </entry>
1249             </row>
1250           </tbody>
1251         </tgroup>
1252       </informaltable>
1253       <para><emphasis role="strong">Note:</emphasis></para>
1254       <para>Specifying <literal>!</literal> before an option negates its meaning
1255         (files NOT matching the parameter). Using <literal>+</literal> before a
1256         numeric value means 'more than n', while <literal>-</literal> before a
1257         numeric value means 'less than n'. If neither is used, it means
1258         'equal to n', within the bounds of the unit specified (if any).</para>
1259       <para><emphasis role="strong">Examples:</emphasis></para>
1260       <para>The following command recursively lists all mirrored files that have
1261         more than 2 mirrors under directory <literal>/mnt/testfs</literal>:
1262       </para>
1263       <screen># lfs find --mirror-count +2 --type f /mnt/testfs</screen>
1264       <para>The following command recursively lists all out-of-sync mirrored
1265         files under directory <literal>/mnt/testfs</literal>:</para>
1266       <screen># lfs find --mirror-state=^ro --type f /mnt/testfs</screen>
1267     </section>
1268   </section>
1269   <section xml:id="flr.interop">
1270     <title>Interoperability</title>
1271     <para>Introduced in Lustre release 2.11.0, the FLR feature is based on the
1272       <xref linkend="pfl"/> feature introduced in Lustre 2.10.0</para>
1273     <para>For Lustre release 2.9 and older clients, which do not understand the
1274       PFL layout, they cannot access and open mirrored files created in the
1275       Lustre 2.11 filesystem.</para>
1276     <para>The following example shows the errors returned by accessing and
1277       opening a mirrored file (created in Lustre 2.11 filesystem) on a Lustre
1278       2.9 client:</para>
1279     <screen># ls /mnt/testfs/mirrored_file
1280 ls: cannot access /mnt/testfs/mirrored_file: Invalid argument
1281
1282 # cat /mnt/testfs/mirrored_file
1283 cat: /mnt/testfs/mirrored_file: Operation not supported</screen>
1284     <para>For Lustre release 2.10 clients, which understand the PFL layout, but
1285       do not understand a mirrored layout, they can access mirrored files
1286       created in Lustre 2.11 filesystem, however, they cannot open them. This is
1287       because the Lustre 2.10 clients do not verify overlapping components so
1288       they would read and write mirrored files just as if they were normal PFL
1289       files, which will cause a problem where synced mirrors actually contain
1290       different data.</para>
1291     <para>The following example shows the results returned by accessing and
1292       opening a mirrored file (created in Lustre 2.11 filesystem) on a Lustre
1293       2.10 client:</para>
1294     <screen># ls /mnt/testfs/mirrored_file
1295 /mnt/testfs/mirrored_file
1296
1297 # cat /mnt/testfs/mirrored_file
1298 cat: /mnt/testfs/mirrored_file: Operation not supported</screen>
1299   </section>
1300 </chapter>
1301 <!--
1302   vim:expandtab:shiftwidth=2:tabstop=8:
1303   -->