UpgradingLustre.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="upgradinglustre">
   5   <title xml:id="upgradinglustre.title">Upgrading a Lustre File System</title>
   6   <para>This chapter describes interoperability between Lustre software
   7   releases. It also provides procedures for upgrading from Lustre software
   8   release 1.8 to Lustre software release 2.x , from a Lustre software release
   9   2.x to a more recent Lustre software release 2.x (major release upgrade), and
  10   from a a Lustre software release 2.x.y to a more recent Lustre software
  11   release 2.x.y (minor release upgrade). It includes the following
  12   sections:</para>
  13   <itemizedlist>
  14     <listitem>
  15       <para>
  16         <xref linkend="dbdoclet.50438205_82079" />
  17       </para>
  18     </listitem>
  19     <listitem>
  20       <para>
  21         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
  22         linkend="Upgrading_2.x" />
  23       </para>
  24     </listitem>
  25     <listitem>
  26       <para>
  27         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
  28         linkend="Upgrading_2.x.x" />
  29       </para>
  30     </listitem>
  31   </itemizedlist>
  32   <section xml:id="dbdoclet.50438205_82079">
  33     <title>
  34     <indexterm>
  35       <primary>Lustre</primary>
  36       <secondary>upgrading</secondary>
  37       <see>upgrading</see>
  38     </indexterm>
  39     <indexterm>
  40       <primary>upgrading</primary>
  41     </indexterm>Release Interoperability and Upgrade Requirements</title>
  42     <para>
  43       <emphasis role="italic">
  44         <emphasis role="bold">Lustre software release 2.x (major)
  45         upgrade:</emphasis>
  46       </emphasis>
  47       <itemizedlist>
  48         <listitem>
  49           <para>All servers must be upgraded at the same time, while some or
  50           all clients may be upgraded independently of the servers.</para>
  51         </listitem>
  52         <listitem>
  53           <para>All servers must be be upgraded to a Linux kernel supported by
  54           the Lustre software. See the Lustre Release Notes for your Lustre
  55           version for a list of tested Linux distributions.</para>
  56         </listitem>
  57         <listitem>
  58           <para>Clients to be upgraded must be running a compatible Linux
  59           distribution as described in the Release Notes.</para>
  60         </listitem>
  61       </itemizedlist>
  62     </para>
  63     <para>
  64       <emphasis role="italic">
  65         <emphasis role="bold">Lustre software release 2.x.y release (minor)
  66         upgrade:</emphasis>
  67       </emphasis>
  68     </para>
  69     <itemizedlist>
  70       <listitem>
  71         <para>All servers must be upgraded at the same time, while some or all
  72         clients may be upgraded.</para>
  73       </listitem>
  74       <listitem>
  75         <para>Rolling upgrades are supported for minor releases allowing
  76         individual servers and clients to be upgraded without stopping the
  77         Lustre file system.</para>
  78       </listitem>
  79     </itemizedlist>
  80   </section>
  81   <section xml:id="Upgrading_2.x">
  82     <title>
  83     <indexterm>
  84       <primary>upgrading</primary>
  85       <secondary>major release (2.x to 2.x)</secondary>
  86     </indexterm>
  87     <indexterm>
  88       <primary>wide striping</primary>
  89     </indexterm>
  90     <indexterm>
  91       <primary>MDT</primary>
  92       <secondary>multiple MDSs</secondary>
  93     </indexterm>
  94     <indexterm>
  95       <primary>large_xattr</primary>
  96       <secondary>ea_inode</secondary>
  97     </indexterm>
  98     <indexterm>
  99       <primary>wide striping</primary>
 100       <secondary>large_xattr</secondary>
 101       <tertiary>ea_inode</tertiary>
 102     </indexterm>Upgrading to Lustre Software Release 2.x (Major
 103     Release)</title>
 104     <para>The procedure for upgrading from a Lustre software release 2.x to a
 105     more recent 2.x release of the Lustre software is described in this
 106     section.</para>
 107     <note>
 108       <para>This procedure can also be used to upgrade Lustre software release
 109       1.8.6-wc1 or later to any Lustre software release 2.x. To upgrade other
 110       versions of Lustre software release 1.8.x, contact your support
 111       provider.</para>
 112     </note>
 113     <note>
 114       <para condition="l22">In Lustre software release 2.2, a feature has been
 115       added that allows striping across up to 2000 OSTs. By default, this "wide
 116       striping" feature is disabled. It is activated by setting the
 117       <literal>large_xattr</literal> or
 118       <literal>ea_inode</literal> option on the MDT using either
 119       <literal>mkfs.lustre</literal> or
 120       <literal>tune2fs</literal>. For example after upgrading an existing file
 121       system to Lustre software release 2.2 or later, wide striping can be
 122       enabled by running the following command on the MDT device before
 123       mounting it:
 124       <screen>tune2fs -O large_xattr</screen>
 125       Once the wide striping feature is enabled and in use on the MDT, it is
 126       not possible to directly downgrade the MDT file system to an earlier
 127       version of the Lustre software that does not support wide striping. To
 128       disable wide striping:
 129       <orderedlist>
 130         <listitem>
 131           <para>Delete all wide-striped files.</para>
 132           <para>OR</para>
 133           <para>Use
 134           <literal>lfs_migrate</literal> with the option
 135           <literal>-c</literal>
 136           <replaceable>stripe_count</replaceable>(set
 137           <replaceable>stripe_count</replaceable>to 160) to move the files to
 138           another location.</para>
 139         </listitem>
 140         <listitem>
 141           <para>Unmount the MDT.</para>
 142         </listitem>
 143         <listitem>
 144           <para>Run the following command to turn off the
 145           <literal>large_xattr</literal> option:
 146           <screen>tune2fs -O ^large_xattr</screen></para>
 147         </listitem>
 148       </orderedlist>Using either
 149       <literal>mkfs.lustre</literal> or
 150       <literal>tune2fs</literal> with
 151       <literal>large_xattr</literal> or
 152       <literal>ea_inode</literal> option reseults in
 153       <literal>ea_inode</literal> in the file system feature list.</para>
 154     </note>
 155     <note condition="l23">
 156       <para>To generate a list of all files with more than 160 stripes use
 157       <literal>lfs find</literal> with the
 158       <literal>--stripe-count</literal> option:
 159       <screen>lfs find ${mountpoint} --stripe-count=+160</screen></para>
 160     </note>
 161     <note condition="l24">
 162       <para>In Lustre software release 2.4, a new feature allows using multiple
 163       MDTs, which can each serve one or more remote sub-directories in the file
 164       system. The
 165       <literal>root</literal> directory is always located on MDT0.</para>
 166       <para>Note that clients running a release prior to the Lustre software
 167       release 2.4 can only see the namespace hosted by MDT0 and will return an
 168       IO error if an attempt is made to access a directory on another
 169       MDT.</para>
 170     </note>
 171     <para>To upgrade a Lustre software release 2.x to a more recent major
 172     release, complete these steps:</para>
 173     <orderedlist>
 174       <listitem>
 175         <para>Create a complete, restorable file system backup.</para>
 176         <caution>
 177           <para>Before installing the Lustre software, back up ALL data. The
 178           Lustre software contains kernel modifications that interact with
 179           storage devices and may introduce security issues and data loss if
 180           not installed, configured, or administered properly. If a full backup
 181           of the file system is not practical, a device-level backup of the MDT
 182           file system is recommended. See
 183           <xref linkend="backupandrestore" /> for a procedure.</para>
 184         </caution>
 185       </listitem>
 186       <listitem>
 187         <para>Shut down the file system by unmounting all clients and servers
 188         in the order shown below (unmounting a block device causes the Lustre
 189         software to be shut down on that node):</para>
 190         <orderedlist numeration="loweralpha">
 191           <listitem>
 192             <para>Unmount the clients. On each client node, run:</para>
 193             <screen>umount -a -t lustre</screen>
 194           </listitem>
 195           <listitem>
 196             <para>Unmount the MDT. On the MDS node, run:</para>
 197             <screen>umount -a -t lustre</screen>
 198           </listitem>
 199           <listitem>
 200             <para>Unmount all the OSTs. On each OSS node, run:</para>
 201             <screen>umount -a -t lustre</screen>
 202           </listitem>
 203         </orderedlist>
 204       </listitem>
 205       <listitem>
 206         <para>Upgrade the Linux operating system on all servers to a compatible
 207         (tested) Linux distribution and reboot.</para>
 208       </listitem>
 209       <listitem>
 210         <para>Upgrade the Linux operating system on all clients to Red Hat
 211         Enterprise Linux 6 or other compatible (tested) distribution and
 212         reboot.</para>
 213       </listitem>
 214       <listitem>
 215         <para>Download the Lustre server RPMs for your platform from the
 216         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 217         Lustre Releases</link>repository. See
 218         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 219         linkend="table_cnh_5m3_gk" />for a list of required packages.</para>
 220       </listitem>
 221       <listitem>
 222         <para>Install the Lustre server packages on all Lustre servers (MGS,
 223         MDSs, and OSSs).</para>
 224         <orderedlist numeration="loweralpha">
 225           <listitem>
 226             <para>Log onto a Lustre server as the
 227             <literal>root</literal> user</para>
 228           </listitem>
 229           <listitem>
 230             <para>Use the
 231             <literal>yum</literal> command to install the packages:</para>
 232             <para>
 233               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 234             </para>
 235           </listitem>
 236           <listitem>
 237             <para>Verify the packages are installed correctly:</para>
 238             <para>
 239               <screen>rpm -qa|egrep "lustre|wc"</screen>
 240             </para>
 241           </listitem>
 242           <listitem>
 243             <para>Repeat these steps on each Lustre server.</para>
 244           </listitem>
 245         </orderedlist>
 246       </listitem>
 247       <listitem>
 248         <para>Download the Lustre client RPMs for your platform from the
 249         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 250         Lustre Releases</link>repository. See
 251         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 252         linkend="table_j3r_ym3_gk" />for a list of required packages.</para>
 253         <note>
 254           <para>The version of the kernel running on a Lustre client must be
 255           the same as the version of the
 256           <literal>lustre-client-modules-</literal>
 257           <replaceable>ver</replaceable>package being installed. If not, a
 258           compatible kernel must be installed on the client before the Lustre
 259           client packages are installed.</para>
 260         </note>
 261       </listitem>
 262       <listitem>
 263         <para>Install the Lustre client packages on each of the Lustre clients
 264         to be upgraded.</para>
 265         <orderedlist numeration="loweralpha">
 266           <listitem>
 267             <para>Log onto a Lustre client as the
 268             <literal>root</literal> user.</para>
 269           </listitem>
 270           <listitem>
 271             <para>Use the
 272             <literal>yum</literal> command to install the packages:</para>
 273             <para>
 274               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 275             </para>
 276           </listitem>
 277           <listitem>
 278             <para>Verify the packages were installed correctly:</para>
 279             <para>
 280               <screen># rpm -qa|egrep "lustre|kernel"</screen>
 281             </para>
 282           </listitem>
 283           <listitem>
 284             <para>Repeat these steps on each Lustre client.</para>
 285           </listitem>
 286         </orderedlist>
 287       </listitem>
 288       <listitem>
 289         <para>(Optional) For upgrades to Lustre software release 2.2 or higher,
 290         to enable wide striping on an existing MDT, run the following command
 291         on the MDT :
 292         <screen>mdt# tune2fs -O large_xattr <replaceable>device</replaceable></screen></para>
 293         <para>For more information about wide striping, see
 294         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 295         linkend="section_syy_gcl_qk" />.</para>
 296       </listitem>
 297       <listitem>
 298         <para>(Optional) For upgrades to Lustre software release 2.4 or higher,
 299         to format an additional MDT, complete these steps:
 300         <orderedlist numeration="loweralpha">
 301           <listitem>
 302             <para>Determine the index used for the first MDT (each MDT must
 303             have unique index). Enter:
 304             <screen>client$ lctl dl | grep mdc
 305 36 UP mdc lustre-MDT0000-mdc-ffff88004edf3c00
 306       4c8be054-144f-9359-b063-8477566eb84e 5</screen></para>
 307             <para>In this example, the next available index is 1.</para>
 308           </listitem>
 309           <listitem>
 310             <para>Add the new block device as a new MDT at the next available
 311             index by entering (on one line):
 312             <screen>mds# mkfs.lustre --reformat --fsname=<replaceable>filesystem_name</replaceable> --mdt \
 313     --mgsnode=<replaceable>mgsnode</replaceable> --index <replaceable>1</replaceable>
 314 <replaceable>/dev/mdt1_device</replaceable></screen></para>
 315           </listitem>
 316         </orderedlist></para>
 317       </listitem>
 318       <listitem>
 319         <para>(Optional) If you are upgrading to Lustre software release 2.3 or
 320         higher from Lustre software release 2.2 or earlier and want to enable
 321         the quota feature, complete these steps:
 322         <orderedlist numeration="loweralpha">
 323           <listitem>
 324             <para>Before setting up the file system, enter on both the MDS and
 325             OSTs:
 326             <screen>tunefs.lustre --quota</screen></para>
 327           </listitem>
 328           <listitem>
 329             <para>When setting up the file system, enter:
 330             <screen>conf_param $FSNAME.quota.mdt=$QUOTA_TYPE
 331 conf_param $FSNAME.quota.ost=$QUOTA_TYPE</screen></para>
 332           </listitem>
 333         </orderedlist></para>
 334       </listitem>
 335       <listitem>
 336         <para>(Optional) If you are upgrading from Lustre software release 1.8,
 337         you must manually enable the FID-in-dirent feature. On the MDS, enter:
 338         <screen>tune2fs –O dirdata /dev/<replaceable>mdtdev</replaceable></screen></para>
 339         <warning>
 340           <para>This step is not reversible. Do not complete this step until
 341           you are sure you will not be downgrading the Lustre software.</para>
 342         </warning>
 343         <para condition='l24'>This step only enables FID-in-dirent for newly
 344         created files. If you are upgrading to Lustre software release 2.4,
 345         you can use namespace LFSCK to enable FID-in-dirent for the existing
 346         files. For the case of upgrading from Lustre software release 1.8, it is
 347     important to note that if you do NOT enable <literal>dirdata</literal> via
 348     the <literal>tune2fs</literal> command above, the namespace LFSCK will NOT
 349         generate FID-in-dirent for the existing files. For more information about
 350         FID-in-dirent and related functionalities in LFSCK, see
 351     <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 352     linkend="understandinglustre.storageio" />.</para>
 353       </listitem>
 354       <listitem>
 355         <para>Start the Lustre file system by starting the components in the
 356         order shown in the following steps:</para>
 357         <orderedlist numeration="loweralpha">
 358           <listitem>
 359             <para>Mount the MGT. On the MGS, run
 360             <screen>mgs# mount -a -t lustre</screen></para>
 361           </listitem>
 362           <listitem>
 363             <para>Mount the MDT(s). On each MDT, run:
 364             <screen>mds# mount -a -t lustre</screen></para>
 365           </listitem>
 366           <listitem>
 367             <para>Mount all the OSTs. On each OSS node, run:</para>
 368             <screen>oss# mount -a -t lustre</screen>
 369             <note>
 370               <para>This command assumes that all the OSTs are listed in the
 371               <literal>/etc/fstab</literal> file. OSTs that are not listed in
 372               the
 373               <literal>/etc/fstab</literal> file, must be mounted individually
 374               by running the mount command:</para>
 375               <screen>mount -t lustre <replaceable>/dev/block_device</replaceable><replaceable>/mount_point</replaceable></screen>
 376             </note>
 377           </listitem>
 378           <listitem>
 379             <para>Mount the file system on the clients. On each client node,
 380             run:</para>
 381             <screen>client# mount -a -t lustre</screen>
 382           </listitem>
 383         </orderedlist>
 384       </listitem>
 385     </orderedlist>
 386     <note>
 387       <para>The mounting order described in the steps above must be followed
 388       for the initial mount and registration of a Lustre file system after an
 389       upgrade. For a normal start of a Lustre file system, the mounting order
 390       is MGT, OSTs, MDT(s), clients.</para>
 391     </note>
 392     <para>If you have a problem upgrading a Lustre file system, see
 393     <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 394     linkend="dbdoclet.50438198_30989" />for some ways to get help.</para>
 395   </section>
 396   <section xml:id="Upgrading_2.x.x">
 397     <title>
 398     <indexterm>
 399       <primary>upgrading</primary>
 400       <secondary>2.X.y to 2.X.y (minor release)</secondary>
 401     </indexterm>Upgrading to Lustre Software Release 2.x.y (Minor
 402     Release)</title>
 403     <para>Rolling upgrades are supported for upgrading from any Lustre software
 404     release 2.x.y to a more recent Lustre software release 2.X.y. This allows
 405     the Lustre file system to continue to run while individual servers (or
 406     their failover partners) and clients are upgraded one at a time. The
 407     procedure for upgrading a Lustre software release 2.x.y to a more recent
 408     minor release is described in this section.</para>
 409     <para>To upgrade Lustre software release 2.x.y to a more recent minor
 410     release, complete these steps:</para>
 411     <orderedlist>
 412       <listitem>
 413         <para>Create a complete, restorable file system backup.</para>
 414         <caution>
 415           <para>Before installing the Lustre software, back up ALL data. The
 416           Lustre software contains kernel modifications that interact with
 417           storage devices and may introduce security issues and data loss if
 418           not installed, configured, or administered properly. If a full backup
 419           of the file system is not practical, a device-level backup of the MDT
 420           file system is recommended. See
 421           <xref linkend="backupandrestore" /> for a procedure.</para>
 422         </caution>
 423       </listitem>
 424       <listitem>
 425         <para>Download the Lustre server RPMs for your platform from the
 426         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 427         Lustre Releases</link>repository. See
 428         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 429         linkend="table_cnh_5m3_gk" />for a list of required packages.</para>
 430       </listitem>
 431       <listitem>
 432         <para>For a rolling upgrade, complete any procedures required to keep
 433         the Lustre file system running while the server to be upgraded is
 434         offline, such as failing over a primary server to its secondary
 435         partner.</para>
 436       </listitem>
 437       <listitem>
 438         <para>Unmount the Lustre server to be upgraded (MGS, MDS, or
 439         OSS)</para>
 440       </listitem>
 441       <listitem>
 442         <para>Install the Lustre server packages on the Lustre server.</para>
 443         <orderedlist numeration="loweralpha">
 444           <listitem>
 445             <para>Log onto the Lustre server as the
 446             <literal>root</literal> user</para>
 447           </listitem>
 448           <listitem>
 449             <para>Use the
 450             <literal>yum</literal> command to install the packages:</para>
 451             <para>
 452               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 453             </para>
 454           </listitem>
 455           <listitem>
 456             <para>Verify the packages are installed correctly:</para>
 457             <para>
 458               <screen>rpm -qa|egrep "lustre|wc"</screen>
 459             </para>
 460           </listitem>
 461           <listitem>
 462             <para>Mount the Lustre server to restart the Lustre software on the
 463             server:
 464             <screen>server# mount -a -t lustre</screen></para>
 465           </listitem>
 466           <listitem>
 467             <para>Repeat these steps on each Lustre server.</para>
 468           </listitem>
 469         </orderedlist>
 470       </listitem>
 471       <listitem>
 472         <para>Download the Lustre client RPMs for your platform from the
 473         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 474         Lustre Releases</link>repository. See
 475         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 476         linkend="table_j3r_ym3_gk" />for a list of required packages.</para>
 477       </listitem>
 478       <listitem>
 479         <para>Install the Lustre client packages on each of the Lustre clients
 480         to be upgraded.</para>
 481         <orderedlist numeration="loweralpha">
 482           <listitem>
 483             <para>Log onto a Lustre client as the
 484             <literal>root</literal> user.</para>
 485           </listitem>
 486           <listitem>
 487             <para>Use the
 488             <literal>yum</literal> command to install the packages:</para>
 489             <para>
 490               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 491             </para>
 492           </listitem>
 493           <listitem>
 494             <para>Verify the packages were installed correctly:</para>
 495             <para>
 496               <screen># rpm -qa|egrep "lustre|kernel"</screen>
 497             </para>
 498           </listitem>
 499           <listitem>
 500             <para>Mount the Lustre client to restart the Lustre software on the
 501             client:
 502             <screen>client# mount -a -t lustre</screen></para>
 503           </listitem>
 504           <listitem>
 505             <para>Repeat these steps on each Lustre client.</para>
 506           </listitem>
 507         </orderedlist>
 508       </listitem>
 509     </orderedlist>
 510     <para>If you have a problem upgrading a Lustre file system, see
 511     <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 512     linkend="dbdoclet.50438198_30989" />for some suggestions for how to get
 513     help.</para>
 514   </section>
 515 </chapter>