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 LFSCK to enable FID-in-dirent for existing files. For
 346         more information about FID-in-dirent and related functionalities in
 347         LFSCK, see <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 348         linkend="understandinglustre.storageio" />.</para>
 349       </listitem>
 350       <listitem>
 351         <para>Start the Lustre file system by starting the components in the
 352         order shown in the following steps:</para>
 353         <orderedlist numeration="loweralpha">
 354           <listitem>
 355             <para>Mount the MGT. On the MGS, run
 356             <screen>mgs# mount -a -t lustre</screen></para>
 357           </listitem>
 358           <listitem>
 359             <para>Mount the MDT(s). On each MDT, run:
 360             <screen>mds# mount -a -t lustre</screen></para>
 361           </listitem>
 362           <listitem>
 363             <para>Mount all the OSTs. On each OSS node, run:</para>
 364             <screen>oss# mount -a -t lustre</screen>
 365             <note>
 366               <para>This command assumes that all the OSTs are listed in the
 367               <literal>/etc/fstab</literal> file. OSTs that are not listed in
 368               the
 369               <literal>/etc/fstab</literal> file, must be mounted individually
 370               by running the mount command:</para>
 371               <screen>mount -t lustre <replaceable>/dev/block_device</replaceable><replaceable>/mount_point</replaceable></screen>
 372             </note>
 373           </listitem>
 374           <listitem>
 375             <para>Mount the file system on the clients. On each client node,
 376             run:</para>
 377             <screen>client# mount -a -t lustre</screen>
 378           </listitem>
 379         </orderedlist>
 380       </listitem>
 381     </orderedlist>
 382     <note>
 383       <para>The mounting order described in the steps above must be followed
 384       for the initial mount and registration of a Lustre file system after an
 385       upgrade. For a normal start of a Lustre file system, the mounting order
 386       is MGT, OSTs, MDT(s), clients.</para>
 387     </note>
 388     <para>If you have a problem upgrading a Lustre file system, see
 389     <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 390     linkend="dbdoclet.50438198_30989" />for some ways to get help.</para>
 391   </section>
 392   <section xml:id="Upgrading_2.x.x">
 393     <title>
 394     <indexterm>
 395       <primary>upgrading</primary>
 396       <secondary>2.X.y to 2.X.y (minor release)</secondary>
 397     </indexterm>Upgrading to Lustre Software Release 2.x.y (Minor
 398     Release)</title>
 399     <para>Rolling upgrades are supported for upgrading from any Lustre software
 400     release 2.x.y to a more recent Lustre software release 2.X.y. This allows
 401     the Lustre file system to continue to run while individual servers (or
 402     their failover partners) and clients are upgraded one at a time. The
 403     procedure for upgrading a Lustre software release 2.x.y to a more recent
 404     minor release is described in this section.</para>
 405     <para>To upgrade Lustre software release 2.x.y to a more recent minor
 406     release, complete these steps:</para>
 407     <orderedlist>
 408       <listitem>
 409         <para>Create a complete, restorable file system backup.</para>
 410         <caution>
 411           <para>Before installing the Lustre software, back up ALL data. The
 412           Lustre software contains kernel modifications that interact with
 413           storage devices and may introduce security issues and data loss if
 414           not installed, configured, or administered properly. If a full backup
 415           of the file system is not practical, a device-level backup of the MDT
 416           file system is recommended. See
 417           <xref linkend="backupandrestore" /> for a procedure.</para>
 418         </caution>
 419       </listitem>
 420       <listitem>
 421         <para>Download the Lustre server RPMs for your platform from the
 422         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 423         Lustre Releases</link>repository. See
 424         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 425         linkend="table_cnh_5m3_gk" />for a list of required packages.</para>
 426       </listitem>
 427       <listitem>
 428         <para>For a rolling upgrade, complete any procedures required to keep
 429         the Lustre file system running while the server to be upgraded is
 430         offline, such as failing over a primary server to its secondary
 431         partner.</para>
 432       </listitem>
 433       <listitem>
 434         <para>Unmount the Lustre server to be upgraded (MGS, MDS, or
 435         OSS)</para>
 436       </listitem>
 437       <listitem>
 438         <para>Install the Lustre server packages on the Lustre server.</para>
 439         <orderedlist numeration="loweralpha">
 440           <listitem>
 441             <para>Log onto the Lustre server as the
 442             <literal>root</literal> user</para>
 443           </listitem>
 444           <listitem>
 445             <para>Use the
 446             <literal>yum</literal> command to install the packages:</para>
 447             <para>
 448               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 449             </para>
 450           </listitem>
 451           <listitem>
 452             <para>Verify the packages are installed correctly:</para>
 453             <para>
 454               <screen>rpm -qa|egrep "lustre|wc"</screen>
 455             </para>
 456           </listitem>
 457           <listitem>
 458             <para>Mount the Lustre server to restart the Lustre software on the
 459             server:
 460             <screen>server# mount -a -t lustre</screen></para>
 461           </listitem>
 462           <listitem>
 463             <para>Repeat these steps on each Lustre server.</para>
 464           </listitem>
 465         </orderedlist>
 466       </listitem>
 467       <listitem>
 468         <para>Download the Lustre client RPMs for your platform from the
 469         <link xl:href="https://wiki.hpdd.intel.com/display/PUB/Lustre+Releases">
 470         Lustre Releases</link>repository. See
 471         <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 472         linkend="table_j3r_ym3_gk" />for a list of required packages.</para>
 473       </listitem>
 474       <listitem>
 475         <para>Install the Lustre client packages on each of the Lustre clients
 476         to be upgraded.</para>
 477         <orderedlist numeration="loweralpha">
 478           <listitem>
 479             <para>Log onto a Lustre client as the
 480             <literal>root</literal> user.</para>
 481           </listitem>
 482           <listitem>
 483             <para>Use the
 484             <literal>yum</literal> command to install the packages:</para>
 485             <para>
 486               <screen># yum --nogpgcheck install pkg1.rpm pkg2.rpm ... </screen>
 487             </para>
 488           </listitem>
 489           <listitem>
 490             <para>Verify the packages were installed correctly:</para>
 491             <para>
 492               <screen># rpm -qa|egrep "lustre|kernel"</screen>
 493             </para>
 494           </listitem>
 495           <listitem>
 496             <para>Mount the Lustre client to restart the Lustre software on the
 497             client:
 498             <screen>client# mount -a -t lustre</screen></para>
 499           </listitem>
 500           <listitem>
 501             <para>Repeat these steps on each Lustre client.</para>
 502           </listitem>
 503         </orderedlist>
 504       </listitem>
 505     </orderedlist>
 506     <para>If you have a problem upgrading a Lustre file system, see
 507     <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 508     linkend="dbdoclet.50438198_30989" />for some suggestions for how to get
 509     help.</para>
 510   </section>
 511 </chapter>