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