InstallingLustreFromSourceCode.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="installinglustrefromsourcecode">
   3   <title xml:id="installinglustrefromsourcecode.title">Installing Lustre from Source Code</title>
   4   <para>If you need to build a customized Lustre server kernel or are using a Linux kernel that has not been tested with the version of Lustre you are installing, you may need to build and install Lustre from source code. This chapter describes:</para>
   5   <itemizedlist>
   6     <listitem>
   7       <para><xref linkend="dbdoclet.50438210_69313"/></para>
   8     </listitem>
   9     <listitem>
  10       <para><xref linkend="dbdoclet.50438210_65411"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="dbdoclet.50438210_47529"/></para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="dbdoclet.50438210_27248"/></para>
  17     </listitem>
  18   </itemizedlist>
  19   <section xml:id="dbdoclet.50438210_69313">
  20       <title>
  21           <indexterm><primary>installing</primary><secondary>from source</secondary></indexterm>
  22           Overview and Prerequisites</title>
  23       <para>Lustre can be installed from either pre-built binary packages (RPMs) or freely-available source code. Installing from the package release is recommended unless you need to customize the Lustre server kernel or will be using an Linux kernel that has not been tested with Lustre. For a list of supported Linux distributions and architectures, visit the <link xl:href="http://wiki.whamcloud.com/display/PUB/Lustre+Support+Matrix">Lustre Support Matrix</link> on the Lustre wiki. The procedure for installing Lustre from RPMs is describe in <xref linkend="installinglustre"/>.</para>
  24     <para>To install Lustre from source code, the following are required:</para>
  25     <itemizedlist>
  26       <listitem>
  27         <para> Linux kernel patched with Lustre-specific patches</para>
  28       </listitem>
  29       <listitem>
  30         <para> Lustre modules compiled for the Linux kernel</para>
  31       </listitem>
  32       <listitem>
  33         <para> Lustre utilities required for Lustre configuration</para>
  34       </listitem>
  35     </itemizedlist>
  36     <para>The installation procedure involves several steps:</para>
  37     <itemizedlist>
  38       <listitem>
  39         <para> Patching the core kernel</para>
  40       </listitem>
  41       <listitem>
  42         <para> Configuring the kernel to work with Lustre</para>
  43       </listitem>
  44       <listitem>
  45         <para> Creating Lustre and kernel RPMs from source code.</para>
  46       </listitem>
  47     </itemizedlist>
  48     <note>
  49       <para>When using third-party network hardware with Lustre, the third-party modules (typically, the drivers) must be linked against the Linux kernel. The LNET modules in Lustre also need these references. To meet these requirements, a specific process must be followed to install and recompile Lustre. See <xref linkend="dbdoclet.50438210_27248"/>, for an example showing how to install Lustre 1.6.6 using the Myricom MX 1.2.7 driver. The same process can be used for other third-party network stacks.</para>
  50     </note>
  51   </section>
  52   <section xml:id="dbdoclet.50438210_65411">
  53     <title><indexterm><primary>installing</primary><secondary>from source</secondary><tertiary>patching the kernel</tertiary></indexterm>Patching the Kernel</title>
  54     <para>If you are using non-standard hardware, plan to apply a Lustre patch, or have another reason not to use packaged Lustre binaries, you have to apply several Lustre patches to the core kernel and run the Lustre configure script against the kernel.</para>
  55     <section remap="h3">
  56       <title><indexterm><primary>quilt</primary></indexterm>Introducing the <literal>quilt</literal> Utility</title>
  57       <para>To simplify the process of applying Lustre patches to the kernel, we recommend that you use the <literal>quilt</literal> utility.</para>
  58       <para><literal>quilt</literal> manages a stack of patches on a single source tree. A series file lists the patch files and the order in which they are applied. Patches are applied, incrementally, on the base tree and all preceding patches. You can:</para>
  59       <itemizedlist>
  60         <listitem>
  61           <para>Apply patches from the stack (<literal>quilt push</literal>)</para>
  62         </listitem>
  63         <listitem>
  64           <para>Remove patches from the stack (<literal>quilt pop</literal>)</para>
  65         </listitem>
  66         <listitem>
  67           <para>Query the contents of the series file (<literal>quilt series</literal>), the contents of the stack (<literal>quilt applied,</literal> <literal>quilt previous</literal>, <literal>quilt top</literal>), and the patches that are not applied at a particular moment (<literal>quilt next</literal>, <literal>quilt unapplied</literal>).</para>
  68         </listitem>
  69         <listitem>
  70           <para>Edit and refresh (update) patches with <literal>quilt</literal>, as well as revert inadvertent changes, and fork or clone patches and show the diffs before and after work.</para>
  71         </listitem>
  72       </itemizedlist>
  73       <para>A variety of <literal>quilt</literal> packages (RPMs, SRPMs and tarballs) are available from various sources. Use the most recent version you can find. <literal>quilt</literal> depends on several other utilities, e.g., the coreutils RPM that is only available in RedHat 9. For other RedHat kernels, you have to get the required packages to successfully install <literal>quilt</literal>. If you cannot locate a <literal>quilt</literal> package or fulfill its dependencies, you can build <literal>quilt</literal> from a tarball, available at the <literal>quilt</literal> project website:</para>
  74       <para><link xl:href="http://savannah.nongnu.org/projects/quilt">http://savannah.nongnu.org/projects/quilt</link></para>
  75       <para>For additional information on using Quilt, including its commands, see <link xl:href="http://www.suse.de/~agruen/quilt.pdf">Introduction to Quilt</link> and the <link xl:href="http://linux.die.net/man/1/quilt"><literal>quilt(1</literal>) man page.</link></para>
  76     </section>
  77     <section remap="h3">
  78       <title>Get the Lustre Source and Unpatched Kernel</title>
  79       <para>The Lustre Engineering Team has targeted several Linux kernels for use with Lustre servers (MDS/OSS) and provides a series of patches for each one. The Lustre patches are maintained in the kernel_patch directory bundled with the Lustre source code.</para>
  80       <caution>
  81         <para>Lustre contains kernel modifications which interact with storage devices and may introduce security issues and data loss if not installed, configured and administered correctly. Before installing Lustre, be cautious and back up ALL data.</para>
  82       </caution>
  83       <note>
  84         <para>Each patch series has been tailored to a specific kernel version, and may or may not apply cleanly to other versions of the kernel.</para>
  85       </note>
  86       <para>To obtain the Lustre source and unpatched kernel:</para>
  87       <orderedlist>
  88         <listitem>
  89           <para>Verify that all of the Lustre installation requirements have been met.</para>
  90           <para>For more information on these prerequisites, see:</para>
  91           <itemizedlist>
  92             <listitem>
  93               <para> Hardware requirements in <xref linkend="settinguplustresystem"/>.</para>
  94             </listitem>
  95             <listitem>
  96               <para> Software and environmental requirements in <xref linkend="dbdoclet.50438261_99193"/></para>
  97             </listitem>
  98           </itemizedlist>
  99         </listitem>
 100         <listitem>
 101           <para>Download the Lustre source code.</para>
 102           <para>On the <link xl:href="http://git.whamcloud.com/">Lustre download site</link>, select a version of Lustre to download and then select &apos;Source&apos; as the platform.</para>
 103         </listitem>
 104         <listitem>
 105           <para>Download the unpatched kernel.</para>
 106           <para>Visit your Linux distributor for the Kernel source.</para>
 107         </listitem>
 108       </orderedlist>
 109     </section>
 110     <section remap="h3">
 111       <title>Patch the Kernel</title>
 112       <para>This procedure describes how to use Quilt to apply the Lustre patches to the kernel. To illustrate the steps in this procedure, a RHEL 5 kernel is patched for Lustre 1.6.5.1.</para>
 113       <orderedlist>
 114         <listitem>
 115           <para>Unpack the Lustre source and kernel to separate source trees.</para>
 116           <orderedlist>
 117             <listitem>
 118               <para>Unpack the Lustre source.</para>
 119               <para>For this procedure, we assume that the resulting source tree is in <literal>/tmp/lustre-1.6.5.1</literal></para>
 120             </listitem>
 121             <listitem>
 122               <para>Unpack the kernel.</para>
 123               <para>For this procedure, we assume that the resulting source tree (also known as the destination tree) is in <literal>/tmp/kernels/linux-2.6.18</literal></para>
 124             </listitem>
 125           </orderedlist>
 126         </listitem>
 127         <listitem>
 128           <para>Select a <literal>config</literal> file for your kernel, located in the <literal>kernel_configs</literal> directory (<literal>lustre/kernel_patches/kernel_config</literal>).</para>
 129           <para>The <literal>kernel_config</literal> directory contains the <literal>.config</literal> files, which are named to indicate the kernel and architecture with which they are associated. For example, the configuration file for the 2.6.18 kernel shipped with RHEL 5 (suitable for i686 SMP systems) is <literal>kernel-2.6.18-2.6-rhel5-i686-smp.config</literal>.</para>
 130         </listitem>
 131         <listitem>
 132           <para>Select the series file for your kernel, located in the series directory (<literal>lustre/kernel_patches/series)</literal>.</para>
 133           <para>The series file contains the patches that need to be applied to the kernel.</para>
 134         </listitem>
 135         <listitem>
 136           <para>Set up the necessary symlinks between the kernel patches and the Lustre source.</para>
 137           <para>This example assumes that the Lustre source files are unpacked under <literal>/tmp/lustre-1.6.5.1</literal> and you have chosen the <literal>2.6-rhel5.series</literal> file). Run:</para>
 138           <screen>$ cd /tmp/kernels/linux-2.6.18
 139 $ rm -f patches series
 140 $ ln -s /tmp/lustre-1.6.5.1/lustre/kernel_patches/series/2.6-rhel5.series ./series
 141 $ ln -s /tmp/lustre-1.6.5.1/lustre/kernel_patches/patches .</screen>
 142         </listitem>
 143         <listitem>
 144           <para>Use <literal>quilt</literal> to apply the patches in the selected series file to the unpatched kernel. Run:</para>
 145           <screen>$ cd /tmp/kernels/linux-2.6.18
 146 $ quilt push -av</screen>
 147           <para>The patched destination tree acts as a base Linux source tree for Lustre.</para>
 148         </listitem>
 149       </orderedlist>
 150     </section>
 151   </section>
 152   <section xml:id="dbdoclet.50438210_47529">
 153       <title>
 154           <indexterm><primary>installing</primary><secondary>from source</secondary><tertiary>packaging</tertiary></indexterm>
 155
 156           Creating and Installing the Lustre Packages</title>
 157     <para>After patching the kernel, configure it to work with Lustre, create the Lustre packages (RPMs) and install them.</para>
 158     <orderedlist>
 159       <listitem>
 160         <para>Configure the patched kernel to run with Lustre. Run:</para>
 161         <screen>$ cd &lt;path to kernel tree&gt;
 162 $ cp /boot/config-`uname -r` .config
 163 $ make oldconfig || make menuconfig
 164 $ make include/asm
 165 $ make include/linux/version.h
 166 $ make SUBDIRS=scripts
 167 $ make include/linux/utsrelease.h</screen>
 168       </listitem>
 169       <listitem>
 170         <para>Run the Lustre configure script against the patched kernel and create the Lustre packages.</para>
 171         <screen>$ cd &lt;path to lustre source tree&gt;
 172 $ ./configure --with-linux=&lt;path to kernel tree&gt;
 173 $ make rpms</screen>
 174         <para>This creates a set of <literal>.rpms</literal> in <literal>/usr/src/redhat/RPMS/&lt;arch&gt;</literal> with an appended date-stamp. The SuSE path is <literal>/usr/src/packages</literal>.</para>
 175         <note>
 176           <para>You do not need to run the Lustre configure script against an unpatched kernel.</para>
 177         </note>
 178         <para><emphasis role="bold">Example set of RPMs:</emphasis></para>
 179         <screen>lustre-1.6.5.1-\2.6.18_53.xx.xx.el5_lustre.1.6.5.1.custom_20081021.i686.rpm
 180
 181 lustre-debuginfo-1.6.5.1-\2.6.18_53.xx.xx.el5_lustre.1.6.5.1.custom_20081021.i686.rpm
 182
 183 lustre-modules-1.6.5.1-\2.6.18_53.xx.xxel5_lustre.1.6.5.1.custom_20081021.i686.rpm
 184
 185 lustre-source-1.6.5.1-\2.6.18_53.xx.xx.el5_lustre.1.6.5.1.custom_20081021.i686.rpm</screen>
 186         <note>
 187           <para>If the steps to create the RPMs fail, contact Lustre Support by reporting a bug. See <xref linkend="dbdoclet.50438198_30989"/>.</para>
 188         </note>
 189         <note>
 190           <para>Several features and packages are available that extend the core functionality of Lustre. These features/packages can be enabled at the build time by issuing appropriate arguments to the configure command. For a list of these features and packages, run <literal>./configure -help</literal> in the Lustre source tree. The configs/ directory of the kernel source contains the config files matching each the kernel version. Copy one to <literal>.config</literal> at the root of the kernel tree.</para>
 191         </note>
 192       </listitem>
 193       <listitem xml:id="dbdoclet.50438210_41207">
 194         <para>Create the kernel package. Navigate to the kernel source directory and run:</para>
 195         <screen>$ make rpm</screen>
 196         <para>Example result:</para>
 197         <screen>kernel-2.6.95.0.3.EL_lustre.1.6.5.1custom-1.i686.rpm</screen>
 198         <note>
 199           <para>Step <xref linkend="dbdoclet.50438210_41207"/> is only valid for RedHat and SuSE kernels. If you are using a stock Linux kernel, you need to get a script to create the kernel RPM.</para>
 200         </note>
 201       </listitem>
 202       <listitem>
 203         <para>Install the Lustre packages.</para>
 204         <para>Some Lustre packages are installed on servers (MDS and OSSs), and others are installed on Lustre clients. For guidance on where to install specific packages, see <xref linkend="installinglustre.tab.req"/> that lists required packages and for each package and where to install it. Depending on the selected platform, not all of the packages listed in <xref linkend="installinglustre.tab.req"/> need to be installed.</para>
 205         <note>
 206           <para>Running the patched server kernel on the clients is optional. It is not necessary unless the clients will be used for multiple purposes, for example, to run as a client and an OST.</para>
 207         </note>
 208         <para>Lustre packages should be installed in this order:</para>
 209         <orderedlist>
 210           <listitem>
 211             <para>Install the kernel, modules and <literal>ldiskfs</literal> packages.</para>
 212             <para>Navigate to the directory where the RPMs are stored, and use the <literal>rpm -ivh</literal> command to install the kernel, module and ldiskfs packages.</para>
 213             <screen>$ rpm -ivh kernel-lustre-smp-&lt;ver&gt; \
 214 kernel-ib-&lt;ver&gt; \
 215 lustre-modules-&lt;ver&gt; \
 216 lustre-ldiskfs-&lt;ver&gt;</screen>
 217           </listitem>
 218           <listitem>
 219             <para>Install the utilities/userspace packages.</para>
 220             <para>Use the <literal>rpm -ivh</literal> command to install the utilities packages. For example:</para>
 221             <screen>$ rpm -ivh lustre-&lt;ver&gt;</screen>
 222           </listitem>
 223           <listitem>
 224             <para>Install the <literal>e2fsprogs</literal> package.</para>
 225             <para>Make sure the <literal>e2fsprogs</literal> package is unpacked, and use the <literal>rpm -i</literal> command to install it. For example:</para>
 226             <screen>$ rpm -i e2fsprogs-&lt;ver&gt;</screen>
 227           </listitem>
 228           <listitem>
 229             <para>(Optional) If you want to add optional packages to your Lustre system, install them now.</para>
 230           </listitem>
 231         </orderedlist>
 232       </listitem>
 233       <listitem>
 234         <para>Verify that the boot loader (<literal>grub.conf</literal> or <literal>lilo.conf</literal>) has been updated to load the patched kernel.</para>
 235       </listitem>
 236       <listitem>
 237         <para>Reboot the patched clients and the servers.</para>
 238         <orderedlist>
 239           <listitem>
 240             <para>If you applied the patched kernel to any clients, reboot them.</para>
 241             <para>Unpatched clients do not need to be rebooted.</para>
 242           </listitem>
 243           <listitem>
 244             <para>Reboot the servers.</para>
 245             <para>Once all the machines have rebooted, the next steps are to configure Lustre Networking (LNET) and the Lustre file system. See <xref linkend="configuringlustre"/>.</para>
 246           </listitem>
 247         </orderedlist>
 248       </listitem>
 249     </orderedlist>
 250   </section>
 251   <section xml:id="dbdoclet.50438210_27248">
 252       <title>
 253           <indexterm><primary>installing</primary><secondary>from source</secondary><tertiary>3rd-party network</tertiary></indexterm>
 254           Installing Lustre with a Third-Party Network Stack</title>
 255     <para>When using third-party network hardware, you must follow a specific process to install and recompile Lustre. This section provides an installation example, describing how to install Lustre 1.6.6 while using the Myricom MX 1.2.7 driver. The same process is used for other third-party network stacks, by replacing MX-specific references in <xref linkend="dbdoclet.50438210_12366"/>  with the stack-specific build and using the proper <literal>--with</literal> option when configuring the Lustre source code.</para>
 256     <orderedlist>
 257       <listitem xml:id="dbdoclet.50438210_12366">
 258         <para>Compile and install the Lustre kernel.</para>
 259         <orderedlist>
 260           <listitem>
 261             <para>Install the necessary build tools.</para>
 262             <para>GCC and related tools must be installed. For more information, see <xref linkend="dbdoclet.50438261_37079"/>.</para>
 263             <screen>$ yum install rpm-build redhat-rpm-config
 264 $ mkdir -p rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
 265 $ echo &apos;%_topdir %(echo $HOME)/rpmbuild&apos; &gt; .rpmmacros</screen>
 266           </listitem>
 267           <listitem>
 268             <para>Install the patched Lustre source code.</para>
 269             <para>This RPM is available at the <link xl:href="http://build.whamcloud.com">Lustre download site</link>.</para>
 270             <screen>$ rpm -ivh \
 271 kernel-lustre-source-2.6.18-92.1.10.el5_lustre.1.6.6.x86_64.rpm</screen>
 272           </listitem>
 273           <listitem>
 274             <para>Build the Linux kernel RPM.</para>
 275             <screen>$ cd /usr/src/linux-2.6.18-92.1.10.el5_lustre.1.6.6
 276 $ make distclean
 277 $ make oldconfig dep bzImage modules
 278 $ cp /boot/config-`uname -r` .config
 279 $ make oldconfig || make menuconfig
 280 $ make include/asm
 281 $ make include/linux/version.h
 282 $ make SUBDIRS=scripts
 283 $ make rpm</screen>
 284           </listitem>
 285           <listitem>
 286             <para>Install the Linux kernel RPM.</para>
 287             <para>If you are building a set of RPMs for a cluster installation, this step is not necessary. Source RPMs are only needed on the build machine.</para>
 288             <screen>$ rpm -ivh \
 289 ~/rpmbuild/kernel-lustre-2.6.18-92.1.10.el5_\lustre.1.6.6.x86_64.rpm
 290 $ mkinitrd /boot/2.6.18-92.1.10.el5_lustre.1.6.6</screen>
 291           </listitem>
 292           <listitem>
 293             <para>Update the boot loader (<literal>/etc/grub.conf</literal>) with the new kernel boot information.</para>
 294             <screen>$ /sbin/shutdown 0 -r</screen>
 295           </listitem>
 296         </orderedlist>
 297       </listitem>
 298       <listitem>
 299         <para>Compile and install the MX stack.</para>
 300         <screen>$ cd /usr/src/
 301 $ gunzip mx_1.2.7.tar.gz (can be obtained from www.myri.com/scs/)
 302 $ tar -xvf mx_1.2.7.tar
 303 $ cd mx-1.2.7
 304 $ ln -s common include
 305 $ ./configure --with-kernel-lib
 306 $ make
 307 $ make install</screen>
 308       </listitem>
 309       <listitem>
 310         <para>Compile and install the Lustre source code.</para>
 311         <orderedlist>
 312           <listitem>
 313             <para>Install the Lustre source (this can be done via RPM or tarball). The source file is available at the <link xl:href="http://git.whamcloud.com/">Lustre download site</link>. This example shows installation via the tarball.</para>
 314             <screen>$ cd /usr/src/
 315 $ gunzip lustre-1.6.6.tar.gz
 316 $ tar -xvf lustre-1.6.6.tar
 317 </screen>
 318           </listitem>
 319           <listitem>
 320             <para>Configure and build the Lustre source code.</para>
 321             <para>The <literal>./configure --help</literal> command shows a list of all of the <literal>--with</literal> options. All third-party network stacks are built in this manner.</para>
 322             <screen>$ cd lustre-1.6.6
 323 $ ./configure --with-linux=/usr/src/linux \
 324 --with-mx=/usr/src/mx-1.2.7
 325 $ make
 326 $ make rpms</screen>
 327             <para>The <literal>make rpms</literal> command output shows the location of the generated RPMs</para>
 328           </listitem>
 329         </orderedlist>
 330       </listitem>
 331       <listitem>
 332         <para>Use the <literal>rpm -ivh</literal> command to install the RPMS.</para>
 333         <screen>$ rpm -ivh \
 334 lustre-1.6.6-2.6.18_92.1.10.el5_lustre.1.6.6smp.x86_64.rpm
 335 $ rpm -ivh \
 336 lustre-modules-1.6.6-2.6.18_92.1.10.el5_lustre.1.6.6\
 337 smp.x86_64.rpm
 338 $ rpm -ivh \
 339 lustre-ldiskfs-3.0.6-2.6.18_92.1.10.el5_lustre.1.6.6\
 340 smp.x86_64.rpm</screen>
 341       </listitem>
 342       <listitem>
 343         <para>Add the following lines to the <literal>/etc/modprobe.d/lustre.conf</literal> file.</para>
 344         <screen>options kmxlnd hosts=/etc/hosts.mxlnd
 345 options lnet networks=mx0(myri0),tcp0(eth0)</screen>
 346       </listitem>
 347       <listitem>
 348         <para>Populate the <literal>myri0</literal> configuration with the proper IP addresses.</para>
 349         <screen>vim /etc/sysconfig/network-scripts/myri0</screen>
 350       </listitem>
 351       <listitem>
 352         <para>Add the following line to the <literal>/etc/hosts.mxlnd</literal> file.</para>
 353         <screen>$ IP HOST BOARD EP_ID </screen>
 354       </listitem>
 355       <listitem>
 356         <para>Start Lustre.</para>
 357         <para>Once all the machines have rebooted, the next steps are to configure Lustre Networking (LNET) and the Lustre file system. See <xref linkend="configuringlustre"/>.</para>
 358       </listitem>
 359     </orderedlist>
 360   </section>
 361 </chapter>