InstallingLustre.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <!-- This document was created with Syntext Serna Free. --><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="installinglustre">
   3   <title xml:id="installinglustre.title">Installing the Lustre Software</title>
   4   <para>This chapter describes how to install the Lustre software. It includes:</para>
   5   <itemizedlist>
   6     <listitem>
   7       <para>
   8               <xref linkend="dbdoclet.50438261_99193"/>
   9           </para>
  10     </listitem>
  11     <listitem>
  12       <para>
  13               <xref linkend="dbdoclet.50438261_41900"/>
  14           </para>
  15     </listitem>
  16   </itemizedlist>
  17   <para>For hardware/system requirements, see <xref linkend="settinguplustresystem"/>.</para>
  18   <section xml:id="dbdoclet.50438261_99193">
  19       <title>
  20           <indexterm><primary>installing</primary><secondary>preparation</secondary></indexterm>
  21           Preparing to Install the Lustre Software</title>
  22     <para>If you are using a supported Linux distribution and architecture, you can install Lustre from downloaded packages (RPMs). For a list of available packages, see the <link xl:href="http://wiki.whamcloud.com/display/PUB/Lustre+Releases">Lustre Downloads</link> page.</para>
  23     <para>A list of available Lustre LNET drivers can be found in <xref linkend="understandinglustrenetworking"/>.</para>
  24     <para>If you are not using a configuration with pre-built packages, you can install Lustre directly from the source code. For more information on this installation method, see <xref linkend="installinglustrefromsourcecode"/>.</para>
  25     <section xml:id="dbdoclet.50438261_37079">
  26       <title><indexterm><primary>installing</primary><secondary>requirements</secondary></indexterm>
  27 Required Software</title>
  28       <para>To install Lustre, the following are required:</para>
  29       <itemizedlist>
  30         <listitem>
  31           <para><emphasis>(On Linux servers only)</emphasis>  Linux kernel patched with Lustre-specific patches for your platform and architecture. A Linux patched kernel can be installed on a client if it is desireable to use the same kernel on all nodes, but this is not required.</para>
  32         </listitem>
  33         <listitem>
  34           <para>Lustre modules compiled for the Linux kernel (see <xref linkend="installinglustre.tab.req"/> for which packages are required for servers and clients in your configuration).</para>
  35         </listitem>
  36         <listitem>
  37           <para>Lustre utilities required for configuring Lustre (see <xref linkend="installinglustre.tab.req"/> for which packages are required for servers and clients in your configuration).</para>
  38         </listitem>
  39         <listitem>
  40           <para><emphasis>(On Linux servers only) </emphasis><literal>e2fsprogs</literal>  package containing Lustre-specific tools (<literal>e2fsck</literal> and <literal>lfsck</literal>) used to repair a backing file system. This replaces the existing <literal>e2fsprogs</literal> package but provides complete <literal>e2fsprogs</literal> functionality</para>
  41         </listitem>
  42         <listitem>
  43           <para><emphasis>(Optional)</emphasis>  Network-specific kernel modules and libraries such as the Lustre-specific OFED package required for an InfiniBand network interconnect.</para>
  44         </listitem>
  45       </itemizedlist>
  46       <para>At least one Lustre RPM must be installed on each server and on each client in a Lustre file system. <xref linkend="installinglustre.tab.req"/> lists required Lustre packages and indicates where they are to be installed. Some Lustre packages are installed on Lustre servers (MGS, MDS, and OSSs), some are installed on Lustre clients, and some are installed on all Lustre nodes.</para>
  47       <para>.</para>
  48       <table xml:id="installinglustre.tab.req" frame="all">
  49         <title>Lustre required packages, descriptions and installation guidance</title>
  50         <tgroup cols="5">
  51           <colspec colname="c1" colwidth="2*"/>
  52           <colspec colname="c2" colwidth="12*"/>
  53           <colspec colname="c3" colwidth="20*"/>
  54           <colspec colname="c4" colwidth="6*"/>
  55           <colspec colname="c5" colwidth="6*"/>
  56           <thead>
  57             <row>
  58               <entry nameend="c2" namest="c1">
  59                 <para><emphasis role="bold">Lustre Package</emphasis></para>
  60               </entry>
  61               <entry>
  62                 <para><emphasis role="bold">Description</emphasis></para>
  63               </entry>
  64               <entry>
  65                 <para><emphasis role="bold">Install on servers</emphasis>
  66                         <footnote>
  67                     <para>Installing a patched kernel on a client node is not required. However, if a client node will be used as both a client and a server, or if you want to install the same kernel on all nodes for any reason, install the server packages designated with an asterisk (*) on the client node.</para>
  68                   </footnote></para>
  69               </entry>
  70               <entry>
  71                 <para><emphasis role="bold">Install on clients</emphasis></para>
  72               </entry>
  73             </row>
  74           </thead>
  75           <tbody>
  76             <row>
  77               <entry nameend="c3" namest="c1">
  78                 <para> <emphasis role="bold"> Lustre patched kernel RPMs:</emphasis></para>
  79               </entry>
  80               <entry>
  81                 <para> &#160;</para>
  82               </entry>
  83               <entry>
  84                 <para> &#160;</para>
  85               </entry>
  86             </row>
  87             <row>
  88               <entry>
  89                 <para> &#160;</para>
  90               </entry>
  91               <entry>
  92                 <para>kernel-<replaceable>ver</replaceable>_lustre.<replaceable>arch</replaceable></para>
  93               </entry>
  94               <entry>
  95                 <para>Lustre patched server kernel.</para>
  96               </entry>
  97               <entry>
  98                 <para> X*</para>
  99               </entry>
 100               <entry>
 101                 <para> &#160;</para>
 102               </entry>
 103             </row>
 104             <row>
 105               <entry nameend="c2" namest="c1">
 106                 <para> <emphasis> Lustre module RPMs:</emphasis></para>
 107               </entry>
 108               <entry>
 109                 <para> &#160;</para>
 110               </entry>
 111               <entry>
 112                 <para> &#160;</para>
 113               </entry>
 114               <entry>
 115                 <para> &#160;</para>
 116               </entry>
 117             </row>
 118             <row>
 119               <entry>
 120                 <para> &#160;</para>
 121               </entry>
 122               <entry>
 123                 <para> lustre-modules-<replaceable>ver</replaceable></para>
 124               </entry>
 125               <entry>
 126                 <para> For Lustre-patched kernel.</para>
 127               </entry>
 128               <entry>
 129                 <para> X*</para>
 130               </entry>
 131               <entry>
 132                 <para> &#160;</para>
 133               </entry>
 134             </row>
 135             <row>
 136               <entry>
 137                 <para> &#160;</para>
 138               </entry>
 139               <entry>
 140                 <para> lustre-client-modules-<replaceable>ver</replaceable></para>
 141               </entry>
 142               <entry>
 143                 <para> For clients.</para>
 144               </entry>
 145               <entry>
 146                 <para> &#160;</para>
 147               </entry>
 148               <entry>
 149                 <para> X</para>
 150               </entry>
 151             </row>
 152             <row>
 153               <entry nameend="c2" namest="c1">
 154                 <para> <emphasis> Lustre utilities:</emphasis></para>
 155               </entry>
 156               <entry>
 157                 <para> &#160;</para>
 158               </entry>
 159               <entry>
 160                 <para> &#160;</para>
 161               </entry>
 162               <entry>
 163                 <para> &#160;</para>
 164               </entry>
 165             </row>
 166             <row>
 167               <entry>
 168                 <para> &#160;</para>
 169               </entry>
 170               <entry>
 171                 <para> lustre-<replaceable>ver</replaceable></para>
 172               </entry>
 173               <entry>
 174                 <para> Lustre utilities package. This includes userspace utilities to configure and run Lustre.</para>
 175               </entry>
 176               <entry>
 177                 <para> &#160;</para>
 178                 <para>&#160;</para>
 179                 <para>X*</para>
 180               </entry>
 181               <entry>
 182                 <para> &#160;</para>
 183                 <para>&#160;</para>
 184               </entry>
 185             </row>
 186             <row>
 187               <entry>
 188                 <para> &#160;</para>
 189               </entry>
 190               <entry>
 191                 <para> lustre-client-<replaceable>ver</replaceable></para>
 192               </entry>
 193               <entry>
 194                 <para> Lustre utilities for clients.</para>
 195               </entry>
 196               <entry>
 197                 <para> &#160;</para>
 198               </entry>
 199               <entry>
 200                 <para> X</para>
 201               </entry>
 202             </row>
 203             <row>
 204               <entry>
 205                 <para> &#160;</para>
 206               </entry>
 207               <entry>
 208                 <para> lustre-ldiskfs-<replaceable>ver</replaceable></para>
 209               </entry>
 210               <entry>
 211                 <para> Lustre-patched backing file system kernel module package for the ldiskfs file system.</para>
 212               </entry>
 213               <entry>
 214                 <para> &#160;</para>
 215                 <para>X</para>
 216               </entry>
 217               <entry>
 218                 <para> &#160;</para>
 219               </entry>
 220             </row>
 221             <row>
 222               <entry>
 223                 <para> &#160;</para>
 224               </entry>
 225               <entry>
 226                 <para> e2fsprogs-<replaceable>ver</replaceable></para>
 227               </entry>
 228               <entry>
 229                 <para> Utilities package used to maintain the ldiskfs backing file system.</para>
 230               </entry>
 231               <entry>
 232                 <para> &#160;</para>
 233                 <para>X</para>
 234               </entry>
 235               <entry>
 236                 <para> &#160;</para>
 237               </entry>
 238             </row>
 239           </tbody>
 240         </tgroup>
 241       </table>
 242       <para>In all supported Lustre installations, a patched kernel must be run on each server, including the the MGS, the MDS, and all OSSs. Running a patched kernel on a Lustre client is only required if the client will be used for multiple purposes, such as running as both a client and an OST or if you want to use the same kernel on all nodes.</para>
 243       <para>Lustre RPM packages are available on the <link xl:href="http://downloads.whamcloud.com">Intel download site</link>. They must be installed in the order described in the <xref linkend="dbdoclet.50438261_41900"/>.</para>
 244       <section remap="h4">
 245         <title><indexterm><primary>installing</primary><secondary>network</secondary></indexterm>
 246 Network-specific Kernel Modules and Libraries</title>
 247         <para>Network-specific kernel modules and libraries may be needed such as the Lustre-specific OFED package required for an InfiniBand network interconnect.</para>
 248       </section>
 249       <section remap="h4">
 250         <title><indexterm><primary>installing</primary><secondary>tools and utilities</secondary></indexterm>
 251 Lustre-Specific Tools and Utilities</title>
 252         <para>Several third-party utilities must be installed on servers:</para>
 253         <itemizedlist>
 254           <listitem>
 255             <para><emphasis role="bold">e2fsprogs</emphasis> : Lustre requires a recent version of e2fsprogs that understands extents and large xattr. Use <literal>e2fsprogs-1.41.90.wc4</literal> or later, available at:</para>
 256             <para><link xl:href="http://downloads.whamcloud.com/">http://downloads.whamcloud.com/</link></para>
 257             <para>A quilt patchset of all changes to the vanilla e2fsprogs is available in <literal>e2fsprogs-{version}-patches.tgz</literal>.</para>
 258             <note>
 259               <para>The Lustre-patched <literal>e2fsprogs</literal> utility is only required on machines that mount backend (<literal>ldiskfs</literal>) file systems, such as the OSS, MDS and MGS nodes. It does not need to be loaded on clients.</para>
 260             </note>
 261           </listitem>
 262           <listitem>
 263             <para><emphasis role="bold">Perl</emphasis>  - Various userspace utilities are written in Perl. Any recent version of Perl will work with Lustre.</para>
 264           </listitem>
 265         </itemizedlist>
 266       </section>
 267       <section remap="h4">
 268         <title><indexterm><primary>installing</primary><secondary>high-availability</secondary></indexterm>
 269 (Optional) High-Availability Software</title>
 270         <para>If you plan to enable failover server functionality with Lustre (either on an OSS or the MDS), you must add high-availability (HA) software to your cluster software. For more information, see <xref linkend="dbdoclet.50438188_92688"/>.</para>
 271       </section>
 272       <section remap="h4">
 273         <title>(Optional) Debugging Tools and Other Optional Packages</title>
 274         <para>A variety of optional packages are provided on the
 275             <link xl:href="http://downloads.whamcloud.com">Intel download site</link>.
 276           These include debugging tools, test programs and scripts, Linux kernel and Lustre source code, and other packages.</para>
 277         <para>For more information about debugging tools, see the topic
 278             <link xl:href="http://wiki.lustre.org/index.php/Debugging_Lustre">Debugging Lustre</link>
 279           on the Lustre wiki.</para>
 280       </section>
 281     </section>
 282     <section xml:id="dbdoclet.50438261_19503">
 283       <title><indexterm><primary>installing</primary><secondary>environment</secondary></indexterm>
 284 Environmental Requirements</title>
 285       <para>Make sure the following environmental requirements are met before installing Lustre:</para>
 286       <itemizedlist>
 287         <listitem>
 288           <para><emphasis role="bold">
 289               <emphasis role="italic">
 290                 <emphasis>(Required)</emphasis>
 291               </emphasis>
 292             </emphasis><emphasis role="bold"> Disable Security-Enhanced Linux (SELinux) on servers and clients</emphasis> . Lustre does not support SELinux. Therefore, disable the SELinux system extension on all Lustre nodes and make sure other security extensions, like Novell AppArmorand network packet filtering tools (such as iptables) do not interfere with Lustre. See <xref linkend="dbdoclet.50438261_88296"/> in <xref linkend="dbdoclet.50438261_41900"/> below.</para>
 293         </listitem>
 294         <listitem>
 295           <para><emphasis role="bold">
 296               <emphasis role="italic">
 297                 <emphasis>(Required)</emphasis>
 298               </emphasis>
 299             </emphasis><emphasis role="bold"> Maintain uniform user and group databases on all cluster nodes</emphasis> . Use the same user IDs (UID) and group IDs (GID) on all clients. If use of supplemental groups is required, verify that the identity_upcall requirements have been met. See <xref linkend="dbdoclet.50438291_32926"/>.</para>
 300         </listitem>
 301         <listitem>
 302           <para><emphasis role="bold">
 303               <emphasis role="italic">
 304                 <emphasis>(Recommended)</emphasis>
 305               </emphasis>
 306             </emphasis><emphasis role="bold"> Provide remote shell access to clients</emphasis> . Although not strictly required to run Lustre, we recommend that all cluster nodes have remote shell client access to facilitate the use of Lustre configuration and monitoring scripts. Parallel Distributed SHell (pdsh) is preferable, although Secure SHell (SSH) is acceptable.</para>
 307         </listitem>
 308         <listitem>
 309           <para><emphasis role="bold">
 310               <emphasis role="italic">
 311                 <emphasis>(Recommended)</emphasis>
 312               </emphasis>
 313             </emphasis><emphasis role="bold"> Ensure client clocks are synchronized</emphasis> . Lustre uses client clocks for timestamps. If clocks are out of sync between clients, files will appear with different time stamps when accessed by different clients. Drifting clocks can also cause problems, for example, by making it difficult to debug multi-node issues or correlate logs, which depend on timestamps. We recommend that you use Network Time Protocol (NTP) to keep client and server clocks in sync with each other. For more information about NTP, see: <link xl:href="http://www.ntp.org/">http://www.ntp.org</link>.</para>
 314         </listitem>
 315       </itemizedlist>
 316     </section>
 317   </section>
 318   <section xml:id="dbdoclet.50438261_41900">
 319     <title>Lustre Installation Procedure</title>
 320     <caution>
 321       <para>Before installing Lustre, back up ALL data. Lustre contains kernel modifications which interact with storage devices and may introduce security issues and data loss if not installed, configured or administered properly.</para>
 322     </caution>
 323     <para>Use this procedure to install Lustre from RPMs.</para>
 324     <orderedlist>
 325       <listitem>
 326         <para>Verify that all Lustre installation requirements have been met.</para>
 327         <para>For more information on these prerequisites, see:</para>
 328         <itemizedlist>
 329           <listitem>
 330             <para> Hardware requirements in <xref linkend="settinguplustresystem"/></para>
 331           </listitem>
 332           <listitem>
 333             <para>Software and environmental requirements in <xref linkend="installinglustre"/></para>
 334           </listitem>
 335         </itemizedlist>
 336       </listitem>
 337       <listitem>
 338         <para>Download the Lustre RPMs.</para>
 339         <orderedlist>
 340           <listitem>
 341             <para>On the <link xl:href="http://downloads.whamcloud.com/">Lustre download site</link>, select your platform.</para>
 342             <para>The files required to install Lustre (kernels, modules and utilities RPMs) are listed for the selected platform.</para>
 343           </listitem>
 344           <listitem>
 345             <para>Download the required files.</para>
 346           </listitem>
 347         </orderedlist>
 348       </listitem>
 349       <listitem xml:id="dbdoclet.50438261_88296">
 350         <para>Install the Lustre packages on the servers.</para>
 351         <orderedlist>
 352           <listitem>
 353             <para>Refer to <xref linkend="installinglustre.tab.req"/> to determine which Lustre packages are to be installed on servers for your platform and architecture.</para>
 354             <para>Some Lustre packages are installed on the Lustre servers (MGS, MDS, and OSSs). Others are installed on Lustre clients.</para>
 355             <para>Lustre packages must be installed in the order specified in the following steps.</para>
 356           </listitem>
 357           <listitem>
 358             <para>Install the kernel, modules and <literal>ldiskfs</literal> packages.</para>
 359             <para>Use the <literal>rpm -ivh</literal> command to install the kernel, module and ldiskfs packages.</para>
 360             <note>
 361               <para>It is not recommended that you use the <literal>rpm -Uvh</literal> command to install a kernel, because this may leave you with an unbootable system if the new kernel doesn&apos;t work for some reason.</para>
 362             </note>
 363             <para>For example, the command in the following example would install required packages on a server with Infiniband networking</para>
 364             <screen>$ rpm -ivh kernel-<replaceable>ver</replaceable>_lustre-<replaceable>ver</replaceable> kernel-ib-<replaceable>ver</replaceable> \
 365 lustre-modules-<replaceable>ver</replaceable> lustre-ldiskfs-<replaceable>ver</replaceable>
 366 </screen>
 367           </listitem>
 368           <listitem>
 369             <para>Update the bootloader (<literal>grub.conf</literal> or <literal>lilo.conf</literal>) configuration file as needed.</para>
 370             <orderedlist>
 371               <listitem>
 372                 <para>Verify that the bootloader configuration file has been updated with an entry for the patched kernel.</para>
 373                 <para>Before you can boot to a new distribution or kernel, there must be an entry for it in the bootloader configuration file. Often this is added automatically when the kernel RPM is installed.</para>
 374               </listitem>
 375               <listitem>
 376                 <para>Disable security-enhanced (SE) Linux on servers and clients by including an entry in the bootloader configuration file as shown below:</para>
 377                 <screen>selinux=0
 378 </screen>
 379               </listitem>
 380             </orderedlist>
 381           </listitem>
 382           <listitem>
 383             <para>Install the utilities/userspace packages.</para>
 384             <para>Use the <literal>rpm -ivh</literal> command to install the utilities packages. For example:</para>
 385             <screen>$ rpm -ivh lustre-<replaceable>ver</replaceable>
 386 </screen>
 387           </listitem>
 388           <listitem>
 389             <para>Install the <literal>e2fsprogs</literal> package.</para>
 390             <para>Use the <literal>rpm -ivh</literal> command to install the <literal>e2fsprogs</literal> package. For example:</para>
 391             <screen>$ rpm -ivh e2fsprogs-<replaceable>ver</replaceable>
 392
 393 </screen>
 394             <para>If <literal>e2fsprogs</literal> is already installed on your Linux system, install the Lustre-specific <literal>e2fsprogs</literal> version by using <literal>rpm -Uvh</literal> to upgrade the existing <literal>e2fsprogs</literal> package. For example:</para>
 395             <screen>$ rpm -Uvh e2fsprogs-<replaceable>ver</replaceable> </screen>
 396             <note>
 397               <para>The <literal>rpm</literal> command options <literal>--force</literal> or <literal>--nodeps</literal> should not be used to install or update the Lustre-specific <literal>e2fsprogs</literal> package. If errors are reported, file a bug (for instructions see the topic
 398                   <link xl:href="http://wiki.lustre.org/index.php/Reporting_Bugs">Reporting Bugs</link>
 399                 on the Lustre wiki).</para>
 400             </note>
 401           </listitem>
 402           <listitem>
 403             <para><emphasis role="italic">
 404                 <emphasis role="italic">(Optional)</emphasis>
 405               </emphasis> To add optional packages to your Lustre file system, install them now.</para>
 406             <para>Optional packages include file system creation and repair tools, debugging tools, test programs and scripts, Linux kernel and Lustre source code, and other packages. A complete list of optional packages for your platform is provided on the <link xl:href="http://downloads.whamcloud.com/">Lustre Downloads</link> page.</para>
 407           </listitem>
 408         </orderedlist>
 409       </listitem>
 410       <listitem>
 411         <para>Install the Lustre packages on the clients.</para>
 412         <orderedlist>
 413           <listitem>
 414             <para>Refer to <xref linkend="installinglustre.tab.req"/> to determine which Lustre packages are to be installed on clients for your platform and architecture.</para>
 415           </listitem>
 416           <listitem>
 417             <para>Install the module packages for clients.</para>
 418             <para>Use the <literal>rpm -ivh</literal> command to install the lustre-client and <literal>lustre-client-modules-<replaceable>ver</replaceable></literal> packages. For example:</para>
 419             <screen>$ rpm -ivh lustre-client-modules-<replaceable>ver</replaceable> kernel-ib-<replaceable>ver</replaceable></screen>
 420           </listitem>
 421           <listitem>
 422             <para>Install the utilities/userspace packages for clients.</para>
 423             <para>Use the <literal>rpm -ivh</literal> command to install the utilities packages. For example:</para>
 424             <screen>$ rpm -ivh lustre-client</screen>
 425           </listitem>
 426           <listitem>
 427             <para>Update the bootloader (grub.conf or lilo.conf) configuration file as needed.</para>
 428             <orderedlist>
 429               <listitem>
 430                 <para>Verify that the bootloader configuration file has been updated with an entry for the patched kernel.</para>
 431                 <para>Before you can boot to a new distribution or kernel, there must be an entry for it in the bootloader configuration file. Often this is added automatically when the kernel RPM is installed.</para>
 432               </listitem>
 433               <listitem>
 434                 <para>Disable security-enhanced (SE) Linux on servers and clients by including an entry in the bootloader configuration file as shown below:</para>
 435                 <screen>selinux=0 </screen>
 436               </listitem>
 437             </orderedlist>
 438           </listitem>
 439         </orderedlist>
 440       </listitem>
 441       <listitem>
 442         <para>Reboot the patched clients and the servers.</para>
 443         <orderedlist>
 444           <listitem>
 445             <para>If you applied the patched kernel to any clients, reboot them.</para>
 446             <para>Unpatched clients do not need to be rebooted.</para>
 447           </listitem>
 448           <listitem>
 449             <para>Reboot the servers.</para>
 450           </listitem>
 451         </orderedlist>
 452         <para>To configure LNET, go next to <xref linkend="configuringlnet"/>. If default settings will be used for LNET, go to <xref linkend="configuringlustre"/>.</para>
 453       </listitem>
 454     </orderedlist>
 455   </section>
 456 </chapter>