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