UpgradingLustre.xml

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