ZFSSnapshots.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="zfssnapshots" condition='l2A'>
   5   <title xml:id="zfssnapshots.title">Lustre ZFS Snapshots</title>
   6   <para>This chapter describes the ZFS Snapshot feature support in Lustre and
   7       contains following sections:</para>
   8   <itemizedlist>
   9     <listitem>
  10       <para><xref linkend="zfssnapshotIntro"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="zfssnapshotConfig"/></para>
  14     </listitem>
  15     <listitem>
  16         <para><xref linkend="zfssnapshotOps"/></para>
  17     </listitem>
  18     <listitem>
  19         <para><xref linkend="zfssnapshotBarrier"/></para>
  20     </listitem>
  21     <listitem>
  22         <para><xref linkend="zfssnapshotLogs"/></para>
  23     </listitem>
  24     <listitem>
  25         <para><xref linkend="zfssnapshotLustreLogs"/></para>
  26     </listitem>
  27   </itemizedlist>
  28   <section xml:id="zfssnapshotIntro">
  29       <title><indexterm><primary>Introduction</primary>
  30       </indexterm>Introduction</title>
  31       <para>Snapshots provide fast recovery of files from a previously created
  32       checkpoint without recourse to an offline backup or remote replica.
  33       Snapshots also provide a means to version-control storage, and can be used
  34       to recover lost files or previous versions of files.</para>
  35       <para>Filesystem snapshots are intended to be mounted on user-accessible
  36       nodes, such as login nodes, so that users can restore files (e.g. after
  37       accidental delete or overwrite) without administrator intervention.  It
  38       would be possible to mount the snapshot filesystem(s) via automount when
  39       users access them, rather than mounting all snapshots, to reduce overhead
  40       on login nodes when the snapshots are not in use.</para>
  41       <para>Recovery of lost files from a snapshot is usually considerably
  42       faster than from any offline backup or remote replica. However, note that
  43       snapshots do not improve storage reliability and are just as exposed to
  44       hardware failure as any other storage volume.</para>
  45       <section xml:id="zfssnapshotsReq">
  46           <title><indexterm><primary>Introduction</primary>
  47               <secondary>Requirements</secondary></indexterm>Requirements
  48           </title>
  49           <para>All Lustre server targets must be ZFS file systems running
  50           Lustre version 2.10 or later.  In addition, the MGS must be able to
  51           communicate via ssh or another remote access protocol, without
  52           password authentication, to all other servers.</para>
  53           <para>The feature is enabled by default and cannot be disabled.  The
  54           management of snapshots is done through <literal>lctl</literal>
  55           commands on the MGS.</para>
  56           <para>Lustre snapshot is based on Copy-On-Write; the snapshot and file
  57           system may share a single copy of the data until a file is changed on
  58           the file system.  The snapshot will prevent the space of deleted or
  59           overwritten files from being released until the snapshot(s)
  60           referencing those files is deleted.  The file system administrator
  61           needs to establish a snapshot create/backup/remove policy according to
  62           their system’s actual size and usage.</para>
  63       </section>
  64   </section>
  65   <section xml:id="zfssnapshotConfig">
  66         <title><indexterm><primary>feature overview</primary>
  67             <secondary>configuration</secondary></indexterm>Configuration
  68         </title>
  69         <para>The snapshot tool loads system configuration from the
  70         <literal>/etc/ldev.conf</literal> file on the MGS and calls related
  71         ZFS commands to maintian the Lustre snapshot pieces on all targets
  72         (MGS/MDT/OST).  Please note that the <literal>/etc/ldev.conf</literal>
  73         file is used for other purposes as well.</para>
  74         <para>The format of the file is:</para>
  75         <screen>&lt;host&gt; foreign/- &lt;label&gt; &lt;device&gt; [journal-path]/- [raidtab]</screen>
  76         <para>The format of <literal>&lt;label&gt;</literal> is:</para>
  77         <screen>fsname-&lt;role&gt;&lt;index&gt; or &lt;role&gt;&lt;index&gt;</screen>
  78         <para>The format of &lt;device&gt; is:</para>
  79         <screen>[md|zfs:][pool_dir/]&lt;pool&gt;/&lt;filesystem&gt;</screen>
  80         <para>Snapshot only uses the fields &lt;host&gt;, &lt;label&gt; and
  81         &lt;device&gt;.</para>
  82         <para>Example 1:</para>
  83         <screen>mgs# cat /etc/ldev.conf
  84 host-mdt1 - myfs-MDT0000 zfs:/tmp/myfs-mdt1/mdt1
  85 host-mdt2 - myfs-MDT0001 zfs:myfs-mdt2/mdt2
  86 host-ost1 - OST0000 zfs:/tmp/myfs-ost1/ost1
  87 host-ost2 - OST0001 zfs:myfs-ost2/ost2</screen>
  88         <para>Example 2:</para>
  89         <screen>
  90 <emphasis role="bold">For the given mounted MGS/OST on single node:</emphasis>
  91 singlenode# mount | grep "lustre-[m|o]"
  92 lustre-mdt1/mdt1 on /mnt/lustre-mds1 type lustre (rw,svname=lustre-MDT0000,mgs,osd=osd-zfs)
  93 lustre-ost1/ost1 on /mnt/lustre-ost1 type lustre (rw,svname=lustre-OST0000, mgsnode=x.x.x.x@tcp, osd=osd-zfs)
  94
  95 <emphasis role="bold">The corresponding /etc/ldev.conf would be</emphasis>
  96 singlenode# cat /etc/ldev.conf
  97 centos79z1 - lustre-MDT0000 zfs:/tmp/lustre-mdt1/mdt1 - -
  98 centos79z1 - lustre-OST0000 zfs:/tmp/lustre-ost1/ost1 - -
  99
 100 <emphasis role="Bold">Where:</emphasis>
 101         </screen>
 102         <informaltable frame="all">
 103           <tgroup cols="2">
 104             <colspec colwidth="50*"/>
 105             <colspec colwidth="50*"/>
 106               <thead>
 107                 <row>
 108                   <entry>
 109                    <para><emphasis role="bold">Fields</emphasis></para>
 110                      </entry>
 111                      <entry>
 112                        <para><emphasis role="bold">Description</emphasis></para>
 113                      </entry>
 114                 </row>
 115               </thead>
 116               <tbody>
 117                 <row><entry>centos79z1</entry><entry>Hostname</entry></row>
 118                 <row><entry>-</entry><entry>Not Used</entry></row>
 119                 <row><entry>lustre-OST0000</entry><entry>Device label</entry></row>
 120                 <row><entry>zfs:/tmp/lustre-ost1/ost1</entry><entry>Device Name</entry></row>
 121                 <row><entry>-</entry><entry>Not Used</entry></row>
 122                 <row><entry>-</entry><entry>Not Used</entry></row>
 123               </tbody>
 124           </tgroup>
 125         </informaltable>
 126
 127         <para>The configuration file is edited manually.</para>
 128         <para> Once the configuration file is updated to reflect the current
 129         file system setup, you are ready to create a file system snapshot.
 130         </para>
 131   </section>
 132   <section xml:id="zfssnapshotOps">
 133       <title><indexterm><primary>operations</primary>
 134       </indexterm>Snapshot Operations</title>
 135   <section xml:id="zfssnapshotCreate">
 136       <title><indexterm><primary>operations</primary>
 137           <secondary>create</secondary></indexterm>Creating a Snapshot
 138       </title>
 139       <para>To create a snapshot of an existing Lustre file system, run the
 140       following <literal>lctl</literal> command on the MGS:</para>
 141       <screen>lctl snapshot_create [-b | --barrier [on | off]] [-c | --comment
 142 comment] -F | --fsname fsname> [-h | --help] -n | --name ssname>
 143 [-r | --rsh remote_shell][-t | --timeout timeout]</screen>
 144       <informaltable frame="all">
 145           <tgroup cols="2">
 146               <colspec colname="c1" colwidth="50*"/>
 147               <colspec colname="c2" colwidth="50*"/>
 148               <thead>
 149                   <row>
 150                       <entry>
 151                           <para><emphasis role="bold">Option</emphasis></para>
 152                       </entry>
 153                       <entry>
 154                           <para><emphasis role="bold">Description</emphasis></para>
 155                       </entry>
 156                   </row>
 157               </thead>
 158               <tbody>
 159                   <row>
 160                       <entry>
 161                           <para> <literal>-b</literal></para>
 162                       </entry>
 163                       <entry>
 164                           <para>set write barrier before creating snapshot.  The
 165                           default value is 'on'.</para>
 166                       </entry>
 167                   </row>
 168                   <row>
 169                       <entry>
 170                           <para> <literal>-c</literal></para>
 171                       </entry>
 172                       <entry>
 173                           <para>a description for the purpose of the snapshot
 174                           </para>
 175                       </entry>
 176                   </row>
 177                   <row>
 178                       <entry>
 179                           <para> <literal>-F</literal></para>
 180                       </entry>
 181                       <entry>
 182                           <para>the filesystem name</para>
 183                       </entry>
 184                   </row>
 185                   <row>
 186                       <entry>
 187                           <para> <literal>-h</literal></para>
 188                       </entry>
 189                       <entry>
 190                           <para>help information</para>
 191                       </entry>
 192                   </row>
 193                   <row>
 194                       <entry>
 195                           <para> <literal>-n</literal></para>
 196                       </entry>
 197                       <entry>
 198                           <para>the name of the snapshot</para>
 199                       </entry>
 200                   </row>
 201                   <row>
 202                       <entry>
 203                           <para> <literal>-r</literal></para>
 204                       </entry>
 205                       <entry>
 206                           <para>the remote shell used for communication with
 207                           remote target.  The default value is 'ssh'</para>
 208                       </entry>
 209                   </row>
 210                   <row>
 211                       <entry>
 212                           <para> <literal>-t</literal></para>
 213                       </entry>
 214                       <entry>
 215                           <para>the lifetime (seconds) for write barrier.  The
 216                           default value is 30 seconds</para>
 217                       </entry>
 218                   </row>
 219               </tbody>
 220           </tgroup>
 221       </informaltable>
 222   </section>
 223   <section xml:id="zfssnapshotDelete">
 224       <title><indexterm><primary>operations</primary>
 225           <secondary>delete</secondary></indexterm>Delete a Snapshot
 226       </title>
 227       <para>To delete an existing snapshot, run the following
 228       <literal>lctl</literal> command on the MGS:</para>
 229       <screen>lctl snapshot_destroy [-f | --force] &lt;-F | --fsname fsname&gt;
 230 &lt;-n | --name ssname&gt; [-r | --rsh remote_shell]</screen>
 231       <informaltable frame="all">
 232           <tgroup cols="2">
 233               <colspec colname="c1" colwidth="50*"/>
 234               <colspec colname="c2" colwidth="50*"/>
 235               <thead>
 236                   <row>
 237                       <entry>
 238                           <para><emphasis role="bold">Option</emphasis></para>
 239                       </entry>
 240                       <entry>
 241                           <para><emphasis role="bold">Description</emphasis>
 242                           </para>
 243                       </entry>
 244                   </row>
 245               </thead>
 246               <tbody>
 247                   <row>
 248                       <entry>
 249                           <para> <literal>-f</literal></para>
 250                       </entry>
 251                       <entry>
 252                           <para>destroy the snapshot by force</para>
 253                       </entry>
 254                   </row>
 255                   <row>
 256                       <entry>
 257                           <para> <literal>-F</literal></para>
 258                       </entry>
 259                       <entry>
 260                           <para>the filesystem name</para>
 261                       </entry>
 262                   </row>
 263                   <row>
 264                       <entry>
 265                           <para> <literal>-h</literal></para>
 266                       </entry>
 267                       <entry>
 268                           <para>help information</para>
 269                       </entry>
 270                   </row>
 271                   <row>
 272                       <entry>
 273                           <para> <literal>-n</literal></para>
 274                       </entry>
 275                       <entry>
 276                           <para>the name of the snapshot</para>
 277                       </entry>
 278                   </row>
 279                   <row>
 280                       <entry>
 281                           <para> <literal>-r</literal></para>
 282                       </entry>
 283                       <entry>
 284                           <para>the remote shell used for communication with
 285                               remote target.  The default value is 'ssh'</para>
 286                       </entry>
 287                   </row>
 288               </tbody>
 289           </tgroup>
 290       </informaltable>
 291   </section>
 292   <section xml:id="zfssnapshotMount">
 293       <title><indexterm><primary>operations</primary>
 294           <secondary>mount</secondary></indexterm>Mounting a Snapshot
 295       </title>
 296       <para>Snapshots are treated as separate file systems and can be mounted on
 297       Lustre clients. The snapshot file system must be mounted as a
 298       read-only file system with the <literal>-o ro</literal> option.
 299       If the <literal>mount</literal> command does not include the read-only
 300       option, the mount will fail.</para>
 301       <note><para>Before a snapshot can be mounted on the client, the snapshot
 302       must first be mounted on the servers using the <literal>lctl</literal>
 303       utility.</para></note>
 304       <para>To mount a snapshot on the server, run the following lctl command
 305       on the MGS:</para>
 306       <screen>lctl snapshot_mount &lt;-F | --fsname fsname&gt; [-h | --help]
 307 &lt;-n | --name ssname&gt; [-r | --rsh remote_shell]</screen>
 308       <informaltable frame="all">
 309           <tgroup cols="2">
 310               <colspec colname="c1" colwidth="50*"/>
 311               <colspec colname="c2" colwidth="50*"/>
 312               <thead>
 313                   <row>
 314                       <entry>
 315                           <para><emphasis role="bold">Option</emphasis></para>
 316                       </entry>
 317                       <entry>
 318                           <para><emphasis role="bold">Description</emphasis>
 319                           </para>
 320                       </entry>
 321                   </row>
 322               </thead>
 323               <tbody>
 324                   <row>
 325                       <entry>
 326                           <para> <literal>-F</literal></para>
 327                       </entry>
 328                       <entry>
 329                           <para>the filesystem name</para>
 330                       </entry>
 331                   </row>
 332                   <row>
 333                       <entry>
 334                           <para> <literal>-h</literal></para>
 335                       </entry>
 336                       <entry>
 337                           <para>help information</para>
 338                       </entry>
 339                   </row>
 340                   <row>
 341                       <entry>
 342                           <para> <literal>-n</literal></para>
 343                       </entry>
 344                       <entry>
 345                           <para>the name of the snapshot</para>
 346                       </entry>
 347                   </row>
 348                   <row>
 349                       <entry>
 350                           <para> <literal>-r</literal></para>
 351                       </entry>
 352                       <entry>
 353                           <para>the remote shell used for communication with
 354                               remote target.  The default value is 'ssh'</para>
 355                       </entry>
 356                   </row>
 357               </tbody>
 358           </tgroup>
 359       </informaltable>
 360       <para>After the successful mounting of the snapshot on the server, clients
 361       can now mount the snapshot as a read-only filesystem.  For example, to
 362       mount a snapshot named <replaceable>snapshot_20170602</replaceable> for a
 363       filesystem named <replaceable>myfs</replaceable>, the following mount
 364       command would be used:</para>
 365       <screen>mgs# lctl snapshot_mount -F myfs -n snapshot_20170602</screen>
 366       <para>After mounting on the server, use
 367       <literal>lctl snapshot_list</literal> to get the fsname for the snapshot
 368       itself as follows:</para>
 369       <screen>ss_fsname=$(lctl snapshot_list -F myfs -n snapshot_20170602 |
 370           awk '/^snapshot_fsname/ { print $2 }')</screen>
 371       <para>Finally, mount the snapshot on the client:</para>
 372       <screen>mount -t lustre -o ro $MGS_nid:/$ss_fsname $local_mount_point</screen>
 373   </section>
 374   <section xml:id="zfssnapshotUnmount">
 375       <title><indexterm><primary>operations</primary>
 376           <secondary>unmount</secondary></indexterm>Unmounting a Snapshot
 377       </title>
 378       <para>To unmount a snapshot from the servers, first unmount the snapshot
 379       file system from all clients, using the standard <literal>umount</literal>
 380       command on each client.  For example, to unmount the snapshot file system
 381       named <replaceable>snapshot_20170602</replaceable> run the following
 382       command on each client that has it mounted:</para>
 383       <screen>client# umount $local_mount_point</screen>
 384       <para>After all clients have unmounted the snapshot file system, run the
 385       following <literal>lctl</literal>command on a server node where the
 386       snapshot is mounted:</para>
 387       <screen>lctl snapshot_umount [-F | --fsname fsname] [-h | --help]
 388 &lt;-n | -- name ssname&gt; [-r | --rsh remote_shell]</screen>
 389       <informaltable frame="all">
 390           <tgroup cols="2">
 391               <colspec colname="c1" colwidth="50*"/>
 392               <colspec colname="c2" colwidth="50*"/>
 393               <thead>
 394                   <row>
 395                       <entry>
 396                           <para><emphasis role="bold">Option</emphasis></para>
 397                       </entry>
 398                       <entry>
 399                           <para><emphasis role="bold">Description</emphasis>
 400                           </para>
 401                       </entry>
 402                   </row>
 403               </thead>
 404               <tbody>
 405                   <row>
 406                       <entry>
 407                           <para> <literal>-F</literal></para>
 408                       </entry>
 409                       <entry>
 410                           <para>the filesystem name</para>
 411                       </entry>
 412                   </row>
 413                   <row>
 414                       <entry>
 415                           <para> <literal>-h</literal></para>
 416                       </entry>
 417                       <entry>
 418                           <para>help information</para>
 419                       </entry>
 420                   </row>
 421                   <row>
 422                       <entry>
 423                           <para> <literal>-n</literal></para>
 424                       </entry>
 425                       <entry>
 426                           <para>the name of the snapshot</para>
 427                       </entry>
 428                   </row>
 429                   <row>
 430                       <entry>
 431                           <para> <literal>-r</literal></para>
 432                       </entry>
 433                       <entry>
 434                           <para>the remote shell used for communication with
 435                               remote target.  The default value is 'ssh'</para>
 436                       </entry>
 437                   </row>
 438               </tbody>
 439           </tgroup>
 440       </informaltable>
 441       <para>For example:</para>
 442       <screen>lctl snapshot_umount -F myfs -n snapshot_20170602</screen>
 443   </section>
 444   <section xml:id="zfssnapshotList">
 445       <title><indexterm><primary>operations</primary>
 446           <secondary>list</secondary></indexterm>List Snapshots
 447       </title>
 448       <para>To list the available snapshots for a given file system, use the
 449           following <literal>lctl</literal> command on the MGS:</para>
 450       <screen>lctl snapshot_list [-d | --detail] &lt;-F | --fsname fsname&gt;
 451 [-h | -- help] [-n | --name ssname] [-r | --rsh remote_shell]</screen>
 452       <informaltable frame="all">
 453           <tgroup cols="2">
 454               <colspec colname="c1" colwidth="50*"/>
 455               <colspec colname="c2" colwidth="50*"/>
 456               <thead>
 457                   <row>
 458                       <entry>
 459                           <para><emphasis role="bold">Option</emphasis></para>
 460                       </entry>
 461                       <entry>
 462                           <para><emphasis role="bold">Description</emphasis>
 463                           </para>
 464                       </entry>
 465                   </row>
 466               </thead>
 467               <tbody>
 468                   <row>
 469                       <entry>
 470                           <para> <literal>-d</literal></para>
 471                       </entry>
 472                       <entry>
 473                           <para>list every piece for the specified snapshot
 474                           </para>
 475                       </entry>
 476                   </row>
 477                   <row>
 478                       <entry>
 479                           <para> <literal>-F</literal></para>
 480                       </entry>
 481                       <entry>
 482                           <para>the filesystem name</para>
 483                       </entry>
 484                   </row>
 485                   <row>
 486                       <entry>
 487                           <para> <literal>-h</literal></para>
 488                       </entry>
 489                       <entry>
 490                           <para>help information</para>
 491                       </entry>
 492                   </row>
 493                   <row>
 494                       <entry>
 495                           <para> <literal>-n</literal></para>
 496                       </entry>
 497                       <entry>
 498                           <para>the snapshot's name. If the snapshot name is not
 499                           supplied, all snapshots for this file system will be
 500                           displayed</para>
 501                       </entry>
 502                   </row>
 503                   <row>
 504                       <entry>
 505                           <para> <literal>-r</literal></para>
 506                       </entry>
 507                       <entry>
 508                           <para>the remote shell used for communication with
 509                               remote target.  The default value is 'ssh'</para>
 510                       </entry>
 511                   </row>
 512               </tbody>
 513           </tgroup>
 514       </informaltable>
 515   </section>
 516   <section xml:id="zfssnapshotModify">
 517       <title><indexterm><primary>operations</primary>
 518           <secondary>modify</secondary></indexterm>Modify Snapshot Attributes
 519       </title>
 520       <para>Currently, Lustre snapshot has five user visible attributes;
 521       snapshot name, snapshot comment, create time, modification time, and
 522       snapshot file system name. Among them, the former two attributes can be
 523       modified. Renaming follows the general ZFS snapshot name rules, such as
 524       the maximum length is 256 bytes, cannot conflict with the reserved names,
 525       and so on.</para>
 526       <para>To modify a snapshot’s attributes, use the following
 527       <literal>lctl</literal> command on the MGS:</para>
 528       <screen>lctl snapshot_modify [-c | --comment comment]
 529 &lt;-F | --fsname fsname&gt; [-h | --help] &lt;-n | --name ssname&gt;
 530 [-N | --new new_ssname] [-r | --rsh remote_shell]</screen>
 531       <informaltable frame="all">
 532           <tgroup cols="2">
 533               <colspec colname="c1" colwidth="50*"/>
 534               <colspec colname="c2" colwidth="50*"/>
 535               <thead>
 536                   <row>
 537                       <entry>
 538                           <para><emphasis role="bold">Option</emphasis></para>
 539                       </entry>
 540                       <entry>
 541                           <para><emphasis role="bold">Description</emphasis>
 542                           </para>
 543                       </entry>
 544                   </row>
 545               </thead>
 546               <tbody>
 547                   <row>
 548                       <entry>
 549                           <para> <literal>-c</literal></para>
 550                       </entry>
 551                       <entry>
 552                           <para>update the snapshot's comment</para>
 553                       </entry>
 554                   </row>
 555                   <row>
 556                       <entry>
 557                           <para> <literal>-F</literal></para>
 558                       </entry>
 559                       <entry>
 560                           <para>the filesystem name</para>
 561                       </entry>
 562                   </row>
 563                   <row>
 564                       <entry>
 565                           <para> <literal>-h</literal></para>
 566                       </entry>
 567                       <entry>
 568                           <para>help information</para>
 569                       </entry>
 570                   </row>
 571                   <row>
 572                       <entry>
 573                           <para> <literal>-n</literal></para>
 574                       </entry>
 575                       <entry>
 576                           <para>the snapshot's name</para>
 577                       </entry>
 578                   </row>
 579                   <row>
 580                       <entry>
 581                           <para> <literal>-N</literal></para>
 582                       </entry>
 583                       <entry>
 584                           <para>rename the snapshot's name as
 585                           <replaceable>new_ssname</replaceable></para>
 586                       </entry>
 587                   </row>
 588                   <row>
 589                       <entry>
 590                           <para> <literal>-r</literal></para>
 591                       </entry>
 592                       <entry>
 593                           <para>the remote shell used for communication with
 594                               remote target.  The default value is 'ssh'</para>
 595                       </entry>
 596                   </row>
 597               </tbody>
 598           </tgroup>
 599       </informaltable>
 600   </section>
 601   </section>
 602   <section xml:id="zfssnapshotBarrier">
 603       <title><indexterm><primary>barrier</primary>
 604       </indexterm>Global Write Barriers</title>
 605       <para>Snapshots are non-atomic across multiple MDTs and OSTs, which means
 606       that if there is activity on the file system while a snapshot is being
 607       taken, there may be user-visible namespace inconsistencies with files
 608       created or destroyed in the interval between the MDT and OST snapshots.
 609       In order to create a consistent snapshot of the file system, we are able
 610       to set a global write barrier, or “freeze” the system. Once set, all
 611       metadata modifications will be blocked until the write barrier is actively
 612       removed (“thawed”) or expired. The user can set a timeout parameter on a
 613       global barrier or the barrier can be explicitly removed. The default
 614       timeout period is 30 seconds.</para>
 615       <para>It is important to note that snapshots are usable without the global
 616       barrier.  Only files that are currently being modified by clients (write,
 617       create, unlink) may be inconsistent as noted above if the barrier is not
 618       used.  Other files not curently being modified would be usable even
 619       without the barrier.</para>
 620       <para>The snapshot create command will call the write barrier internally
 621       when requested using the <literal>-b</literal> option to
 622       <literal>lctl snapshot_create</literal>. So, explicit use of the barrier
 623       is not required when using snapshots but included here as an option to
 624       quiet the file system before a snapshot is created.</para>
 625       <section xml:id="zfssnapshotBarrierImpose">
 626           <title><indexterm><primary>barrier</primary>
 627               <secondary>impose</secondary></indexterm>Impose Barrier
 628           </title>
 629           <para>To impose a global write barrier, run the
 630           <literal>lctl barrier_freeze</literal> command on the MGS:</para>
 631           <screen>lctl barrier_freeze &lt;fsname&gt; [timeout (in seconds)]
 632 where timeout default is 30.</screen>
 633           <para>For example, to freeze the filesystem
 634           <replaceable>testfs</replaceable> for <literal>15</literal> seconds:
 635           </para>
 636           <screen>mgs# lctl barrier_freeze testfs 15</screen>
 637           <para>If the command is successful, there will be no output from
 638           the command.  Otherwise, an error message will be printed.</para>
 639       </section>
 640       <section xml:id="zfssnapshotBarrierRemove">
 641           <title><indexterm><primary>barrier</primary>
 642                   <secondary>remove</secondary></indexterm>Remove Barrier
 643               </title>
 644           <para>To remove a global write barrier, run the
 645           <literal>lctl barrier_thaw</literal> command on the MGS:</para>
 646           <screen>lctl barrier_thaw &lt;fsname&gt;</screen>
 647           <para>For example, to thaw the write barrier for the filesystem
 648               <replaceable>testfs</replaceable>:
 649           </para>
 650           <screen>mgs# lctl barrier_thaw testfs</screen>
 651           <para>If the command is successful, there will be no output from
 652               the command.  Otherwise, an error message will be printed.</para>
 653       </section>
 654       <section xml:id="zfssnapshotBarrierQuery">
 655           <title><indexterm><primary>barrier</primary>
 656               <secondary>query</secondary></indexterm>Query Barrier
 657           </title>
 658           <para>To see how much time is left on a global write barrier, run the
 659           <literal>lctl barrier_stat</literal> command on the MGS:</para>
 660           <screen># lctl barrier_stat &lt;fsname&gt;</screen>
 661           <para>For example, to stat the write barrier for the filesystem
 662               <replaceable>testfs</replaceable>:
 663           </para>
 664           <screen>mgs# lctl barrier_stat testfs
 665 The barrier for testfs is in 'frozen'
 666 The barrier will be expired after 7 seconds</screen>
 667           <para>If the command is successful, a status from the table below
 668           will be printed.  Otherwise, an error message will be printed.</para>
 669           <para>The possible status and related meanings for the write barrier
 670           are as follows:</para>
 671           <table frame="all" xml:id="writebarrierstatus.tab1">
 672               <title>Write Barrier Status</title>
 673               <tgroup cols="2">
 674                   <colspec colname="c1" colwidth="50*"/>
 675                   <colspec colname="c2" colwidth="50*"/>
 676                   <thead>
 677                       <row>
 678                           <entry>
 679                               <para><emphasis role="bold">Status</emphasis>
 680                               </para>
 681                           </entry>
 682                           <entry>
 683                               <para><emphasis role="bold">Meaning</emphasis>
 684                               </para>
 685                           </entry>
 686                       </row>
 687                   </thead>
 688                   <tbody>
 689                       <row>
 690                           <entry>
 691                               <para> <literal>init</literal></para>
 692                           </entry>
 693                           <entry>
 694                               <para>barrier has never been set on the system
 695                               </para>
 696                           </entry>
 697                       </row>
 698                       <row>
 699                           <entry>
 700                               <para> <literal>freezing_p1</literal></para>
 701                           </entry>
 702                           <entry>
 703                               <para>In the first stage of setting the write
 704                               barrier</para>
 705                           </entry>
 706                       </row>
 707                       <row>
 708                           <entry>
 709                               <para> <literal>freezing_p2</literal></para>
 710                           </entry>
 711                           <entry>
 712                               <para> the second stage of setting the write
 713                               barrier</para>
 714                           </entry>
 715                       </row>
 716                       <row>
 717                           <entry>
 718                               <para> <literal>frozen</literal></para>
 719                           </entry>
 720                           <entry>
 721                               <para>the write barrier has been set successfully
 722                               </para>
 723                           </entry>
 724                       </row>
 725                       <row>
 726                           <entry>
 727                               <para> <literal>thawing</literal></para>
 728                           </entry>
 729                           <entry>
 730                               <para>In thawing the write barrier</para>
 731                           </entry>
 732                       </row>
 733                       <row>
 734                           <entry>
 735                               <para> <literal>thawed</literal></para>
 736                           </entry>
 737                           <entry>
 738                               <para>The write barrier has been thawed</para>
 739                           </entry>
 740                       </row>
 741                       <row>
 742                           <entry>
 743                               <para> <literal>failed</literal></para>
 744                           </entry>
 745                           <entry>
 746                               <para>Failed to set write barrier</para>
 747                           </entry>
 748                       </row>
 749                       <row>
 750                           <entry>
 751                               <para> <literal>expired</literal></para>
 752                           </entry>
 753                           <entry>
 754                               <para>The write barrier is expired</para>
 755                           </entry>
 756                       </row>
 757                       <row>
 758                           <entry>
 759                               <para> <literal>rescan</literal></para>
 760                           </entry>
 761                           <entry>
 762                               <para>In scanning the MDTs status, see the command
 763                               <literal>barrier_rescan</literal></para>
 764                           </entry>
 765                       </row>
 766                       <row>
 767                           <entry>
 768                               <para> <literal>unknown</literal></para>
 769                           </entry>
 770                           <entry>
 771                               <para>Other cases</para>
 772                           </entry>
 773                       </row>
 774                   </tbody>
 775               </tgroup>
 776           </table>
 777           <para>If the barrier is in ’freezing_p1’, ’freezing_p2’ or ’frozen’
 778           status, then the remaining lifetime will be returned also.</para>
 779       </section>
 780       <section xml:id="zfssnapshotBarrierRescan">
 781           <title><indexterm><primary>barrier</primary>
 782               <secondary>rescan</secondary></indexterm>Rescan Barrier
 783           </title>
 784           <para> To rescan a global write barrier to check which MDTs are
 785           active, run the <literal>lctl barrier_rescan</literal> command on the
 786           MGS:</para>
 787           <screen>lctl barrier_rescan &lt;fsname&gt; [timeout (in seconds)],
 788 where the default timeout is 30 seconds.</screen>
 789           <para>For example, to rescan the barrier for filesystem
 790           <replaceable>testfs</replaceable>:</para>
 791           <screen>mgs# lctl barrier_rescan testfs
 792 1 of 4 MDT(s) in the filesystem testfs are inactive</screen>
 793           <para>If the command is successful, the number of MDTs that are
 794           unavailable against the total MDTs will be reported.  Otherwise, an
 795           error message will be printed.</para>
 796       </section>
 797   </section>
 798   <section xml:id="zfssnapshotLogs">
 799       <title><indexterm><primary>logs</primary>
 800       </indexterm>Snapshot Logs</title>
 801       <para>A log of all snapshot activity can be found in the following file:
 802       <literal>/var/log/lsnapshot.log</literal>.  This file contains information
 803       on when a snapshot was created, an attribute was changed, when it was
 804       mounted, and other snapshot information.</para>
 805       <para>The following is a sample <literal>/var/log/lsnapshot</literal>
 806       file:</para>
 807       <screen>Mon Mar 21 19:43:06 2016
 808 (15826:jt_snapshot_create:1138:scratch:ssh): Create snapshot lss_0_0
 809 successfully with comment &lt;(null)&gt;, barrier &lt;enable&gt;, timeout &lt;30&gt;
 810 Mon Mar 21 19:43:11 2016(13030:jt_snapshot_create:1138:scratch:ssh):
 811 Create snapshot lss_0_1 successfully with comment &lt;(null)&gt;, barrier
 812 &lt;disable&gt;, timeout &lt;-1&gt;
 813 Mon Mar 21 19:44:38 2016 (17161:jt_snapshot_mount:2013:scratch:ssh):
 814 The snapshot lss_1a_0 is mounted
 815 Mon Mar 21 19:44:46 2016
 816 (17662:jt_snapshot_umount:2167:scratch:ssh): the snapshot lss_1a_0
 817 have been umounted
 818 Mon Mar 21 19:47:12 2016
 819 (20897:jt_snapshot_destroy:1312:scratch:ssh): Destroy snapshot
 820 lss_2_0 successfully with force &lt;disable&gt;</screen>
 821   </section>
 822   <section xml:id="zfssnapshotLustreLogs">
 823       <title><indexterm><primary>configlogs</primary>
 824       </indexterm>Lustre Configuration Logs</title>
 825       <para>A snapshot is independent from the original file system that it is
 826       derived from and is treated as a new file system name that can be mounted
 827       by Lustre client nodes. The file system name is part of the configuration
 828       log names and exists in configuration log entries. Two commands exist to
 829       manipulate configuration logs:  <literal>lctl fork_lcfg</literal> and
 830       <literal>lctl erase_lcfg</literal>.</para>
 831       <para>The snapshot commands will use configuration log functionality
 832       internally when needed. So, use of the barrier is not required to use
 833       snapshots but included here as an option. The following configuration log
 834       commands are independent of snapshots and can be used independent of
 835       snapshot use.</para>
 836       <para>To fork a configuration log, run the following
 837       <literal>lctl</literal> command on the MGS:</para>
 838       <screen>lctl fork_lcfg</screen>
 839       <para>Usage:  fork_lcfg &lt;fsname&gt; &lt;newname&gt;</para>
 840       <para>To erase a configuration log, run the following
 841       <literal>lctl</literal> command on the MGS:</para>
 842       <screen>lctl erase_lcfg</screen>
 843       <para>Usage:  erase_lcfg &lt;fsname&gt;</para>
 844   </section>
 845 </chapter>
 846 <!--
 847   vim:expandtab:shiftwidth=2:tabstop=8:
 848   -->