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