LDP/LDP/guide/docbook/EVMSUG/install-ug.xml

488 lines
22 KiB
XML

<chapter id="evmsuginstall"><title>Downloading and installing EVMS </title>
<para>This chapter tells how to obtain and install EVMS, and offers guidelines to help you make decisions about your EVMS installation. If you are setting up EVMS to work in a cluster,
execute the steps described in this chapter on each of the nodes in the cluster.</para>
<sect1 id="beforebegin"><title>Preparing your system</title>
<para>Before you install EVMS, decide whether to implement certain kernel capabilities and ensure that you have a Linux kernel source tree. EVMS 2.0 is built on top of the already existing components MD and Device Mapper (DM). If you are using Linux kernel 2.5 or later, the MD and DM components are already available, but you need to apply some patches for bug fixes because the 2.5 kernel is still stabilizing. If you are using Linux kernel 2.4, you need to obtain all the DM patches from the Sistina website and then apply the bug fixes. Steps for performing these tasks are included later in this chapter.</para>
<sect2 id="selectcapabilities"><title>Choosing capabilities</title>
<para>In order to run EVMS, you need to configure the Device Mapper in your kernel either as a module or as a component built directly into the kernel. If you want to use the RAID functions of EVMS, turn on MD and the appropriate RAID personalities in the kernel.</para>
</sect2>
<sect2 id="kernelsource"><title>Obtaining the Device Mapper and a kernel source tree</title>
<para>EVMS 2.0 is built on top of the already existing components MD and Device Mapper. If you are using Linux kernel 2.5 or later, the MD and DM components are already available; however, you need to apply some patches for bug fixes because the 2.5 kernel is still stabilizing. If you are using Linux kernel 2.4, you need to patch the DM in from the <ulink url="http://people.sistina.com/~thornber/patches/">Sistina website</ulink> and then apply the bug fixes. The DM patches for the kernel are included in the EVMS package on the <ulink url="http://www.sourceforge.net/projects/evms/">EVMS project website</ulink>. The current EVMS package contains a patch for both the 2.4 and 2.5 kernel series.</para>
<note><title>NOTE</title>
<para>EVMS does not work with Linux kernels 2.3, 2.2, or earlier.
</para></note>
<para>If you do not have a Linux kernel source tree,
you can obtain one from <ulink url="http://www.kernel.org/">The Linux Kernel Archives </ulink>.
The current recommended
kernel is 2.4.20, but earlier 2.4 series kernels might
work.</para>
</sect2>
</sect1>
<sect1 id="DOWNLOADING">
<title>Downloading EVMS</title>
<para>To install EVMS, download the latest version of EVMS
(<filename>evms-2.0.0.tar.gz</filename>) from the
<ulink url="http://www.sourceforge.net/projects/evms/">EVMS project homepage</ulink>. This
file contains source code patches for the Linux kernel and
source code for all necessary user-space administration tools.</para>
<para>After downloading the file,
use the <command>tar</command> command to extract the files in the
appropriate place. In the following example, the files are
extracted in <filename>/usr/src</filename>. You can substitute
another directory.</para>
<programlisting>cd /usr/src
tar xvzf evms-2.0.0.tar.gz</programlisting>
</sect1>
<sect1 id="PATCHING">
<title>Patching the kernel</title>
<para>In addition to the base MD and Device Mapper support, EVMS requires a few
patches for the EVMS engine to work correctly with these drivers. These
patches are provided in the EVMS package, in the <filename>kernel/2.4.20/</filename>
subdirectory. See the INDEX files in the <filename>kernel/2.4.20</filename> directory
for descriptions of the patches.
</para>
<note><title>NOTE</title><para>If you are currently using the Sistina LVM2 tools,
the patches provided here are not compatible with the LVM2 tools.
EVMS has made some changes to the kernel ioctl packets so that they
work correctly on ppc-64 and sparc-64 architectures. These changes
have not yet been accepted by Sistina. Thus, for the time being, you
need to use separate kernels for running EVMS and LVM2.</para></note>
<para>Apply each of the patches for 2.4.20 to your kernel as follows:</para>
<programlisting>cd /usr/src/linux-2.4.20
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/1-dm-base.patch
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/2-syncio.patch
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/3-dm-bbr.patch
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/4-dm-sparse.patch
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/5-md.c.patc
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/6-vsprintf.c.patch
patch -p1 &lt; /src/src/evms-2.0.0/kernel/2.4.20/7-vfs-lock.patch</programlisting>
</sect1>
<sect1 id="configuring">
<title>Configuring the kernel</title>
<para>After patching the kernel, configure it with EVMS support. To
configure the kernel, complete the following steps:</para>
<orderedlist>
<listitem><para>Type the following command:</para>
<programlisting>make xconfig</programlisting>
<note><title>NOTE</title>
<para>You can also use <command>config</command> or <command>menuconfig</command> if you don't have an Xwindow system.</para></note>
<para>If you are using an Xwindow system, the following window opens. </para>
<figure><title>xconfig Window</title>
<mediaobject><imageobject><imagedata format="PNG" fileref="xconf.png"></imagedata></imageobject>
<textobject><phrase>xconfig Window</phrase></textobject></mediaobject></figure>
</listitem>
<listitem><para>To enable the kernel components that EVMS needs, select
<guimenuitem>Multi-device support (RAID and LVM)</guimenuitem>. The following window opens.</para>
<figure><title>Multi-device Support (RAID and LVM) Window</title>
<mediaobject><imageobject><imagedata format="PNG" fileref="mdconf.png"></imagedata></imageobject>
<textobject><phrase>MD Support (RAID and LVM) Window</phrase>
</textobject></mediaobject></figure>
<note><title>NOTE</title>
<para>If you are configuring the components as
modules, you can click the <guibutton>Help</guibutton> button beside each
module to see the name of each kernel module.</para></note></listitem>
<listitem><para>Select <option>y</option> for Multi-device support (RAID and LVM).
Select <option>y</option> (to build in the kernel) or <option>m</option> (to build
modules)
for Device Mapper support.
These options are the minimum required for EVMS.
The remaining options add additional capabilities to EVMS.</para>
<note><title>NOTE</title>
<para>The options you select in this step are the ones you selected in
<xref linkend="selectcapabilities"></xref>.</para></note>
</listitem>
</orderedlist>
<para>Continue configuring your kernel as required for your
system and hardware. For general instructions on configuring
and compiling a Linux kernel, please see <ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html"> <citetitle>The Kernel HOWTO</citetitle></ulink>.</para>
<para>When you have finished configuring your
kernel, choose <guibutton>Save and Exit</guibutton> to quit
the kernel configuration.</para>
</sect1>
<sect1 id="buildinstall">
<title>Building and installing the new kernel</title>
<para>After you have configured the kernel, build and install a new kernel image.
There are slight variations for different architectures,
but the general steps are the same.
For example, on Intel&reg; machines you might run
<command>lilo</command> to install the new kernel image.
On S/390 machines, you might
run <command>zipl</command> to install the new kernel image.
The following instructions
are based on an installation using an Intel machine. </para>
<orderedlist>
<listitem><para>Build the kernel:</para>
<programlisting>make dep clean bzImage modules modules_install</programlisting>
</listitem>
<listitem><para>Copy the new kernel to the <filename>/boot</filename> directory.</para>
<programlisting>cp /usr/src/linux/arch/i386/boot/bzImage /boot/vmlinuz-evms</programlisting>
<note><title>NOTE</title>
<para>The previous command assumes the file to be named
<filename>vmlinuz-evms</filename>, you can substitute
another name.</para></note></listitem>
<listitem><para>Open the file for the boot loader.
The LILO boot loader information is in <filename>/etc/lilo.conf</filename>.
The GRUB boot loader information is in <filename>/boot/menu.list</filename>.</para></listitem>
<listitem><para>Update the boot loader information as follows:</para>
<programlisting>image=/boot/vmlinuz-evms
label=EVMS</programlisting>
<note><title>NOTE</title>
<para>Currently, LILO does not support placing the <filename>/boot</filename> filesystem on a Device Mapper device. Thus, <filename>/boot</filename> must be mounted through the traditional partition device.</para></note>
</listitem>
<listitem><para>Run your boot loader to install the new kernel image.</para>
<note><title>NOTE</title>
<para>If you installed your kernel as modules, skip to
<xref linkend="INSTALLENGINE"></xref>. </para></note></listitem>
<listitem><para>Reboot your machine and choose the new
kernel image to run with EVMS support.</para></listitem>
</orderedlist>
</sect1>
<!-- Installing the Cluster Manager -->
<sect1 id="installclusmgr"><title>Installing the cluster manager</title>
<para>Skip this section if you do not require high-availability features.</para>
<para>EVMS currently supports the Linux-HA cluster manager, commonly known as
Heartbeat. You can download the latest version of the Linux-HA software from
<ulink url="http://www.linux-ha.org/download/">http://www.linux-ha.org/download/</ulink>. EVMS works
with Heartbeat V1.0.1 and later. For instructions on setting up a two-node cluster, see
<ulink url="http://www.linux-ha.org/download/GettingStarted.html">http://www.linux-ha.org/download/GettingStarted.html</ulink>. For additional information and a list of frequently asked questions, see
<ulink url="http://www.linux-ha.org/download/faqntips.html">http://www.linux-ha.org/download/faqntips.html</ulink>.</para>
<para>Linux-HA provides the following sub-packages:
<itemizedlist>
<listitem><para>heartbeat-xxx.arch.rpm</para>
</listitem>
<listitem><para>heartbeat-stonith-xxx.arch.rpm</para>
</listitem>
<listitem><para>heartbeat-pils-xxx.arch.rpm</para>
</listitem>
<listitem><para>heartbeat-ldirectord-xxx.arch.rpm</para>
</listitem>
</itemizedlist>
</para>
<para>&quot;xxx&quot; is the version of heartbeat; &quot;arch&quot; is the architecture of the target nodes.</para>
<para>You do not need to install <filename>heartbeat-ldirectord-xxx.arch.rpm</filename> because EVMS does not depend on its service.</para>
<para><note><title>NOTE</title>
<para>The download page also contains tarballs and source rpms.</para>
</note>
</para>
<para>To install the package, execute the following command on each cluster node:</para>
<programlisting>rpm -i heartbeat-pils-xxx.arch.rpm heartbeat-stonith-xxx.rpm \
heartbeat-xxx.arch.rpm</programlisting>
<para><note><title>NOTE</title>
<para>It is highly recommended that you configure the STONITH package on a two-node cluster because
data integrity on shared disks is at risk if STONITH is not configured. Although EVMS
operates even when STONITH is not configured (EVMS is not restricted to a two-node
cluster), EVMS's failover capability is limited by the support provided by the native
cluster manager.</para>
<para>Refer to the STONITH device manual for instructions on how to configure the
STONITH device.</para></note></para>
</sect1>
<!-- Installing the Engine -->
<sect1 id="INSTALLENGINE">
<title>Installing the Engine</title>
<para>The EVMS Engine consists of the user-space plug-ins and interfaces as well as a stand-alone
library, dlist, that the Engine uses for linked-list management.</para>
<sect2 id="installsource"><title>Installing from source</title>
<orderedlist>
<listitem><para>To build and install the Engine from source, first type the following command to change to the <filename>/usr/src/evms-2.0.0</filename> directory:</para>
<programlisting>cd /usr/src/evms-2.0.0</programlisting>
</listitem>
<listitem><para>Select the appropriate options for your configuration.</para>
<note><title>NOTE</title>
<para>A list of options can be found by typing:</para>
<programlisting>./configure -h</programlisting></note>
</listitem>
<listitem><para>Configure your engine:
<programlisting>./configure [--options]</programlisting>
</para></listitem>
<listitem><para>Type the following commands: </para>
<programlisting>make
make install
ldconfig
</programlisting>
<para>Unless you specified other directories when you configured the engine, the
following list describes where files will be installed
on your system:
<itemizedlist>
<listitem><para>The core Engine library is installed in
<filename>/lib</filename>.</para></listitem>
<listitem><para>The core dlist library is installed in
<filename>/lib</filename>.</para></listitem>
<listitem><para>All plug-in libraries is installed in
<filename>/lib/evms</filename>.</para></listitem>
<listitem><para>All user interface binaries are installed
in <filename>/sbin</filename>.</para></listitem>
<listitem><para>All header files are installed in
<filename>/usr/include/evms</filename>.</para></listitem>
<listitem><para>All manual pages are installed in <filename>/usr/man</filename>.</para> </listitem>
<listitem><para>Add the Engine library path to your
<varname>LD_LIBRARY_PATH</varname> environment variable, or to
your <filename>/etc/ld.so.conf</filename> file. Do not add the
plug-in library path because the Engine dynamically loads
these libraries directly.</para></listitem>
</itemizedlist></para>
</listitem>
<listitem><para>Examine the EVMS configuration file (<filename>evms.conf</filename>). This file contains settings to control how EVMS operates.
For example, the logging level, the location of the engine
log, and the list of disk devices to examine can all be
controlled through settings in the configuration file.
The sample file is well commented and advises you of appropriate
values for each setting.</para>
<para>The <filename>evms.conf</filename> file is normally installed in
<filename>/etc/evms.conf</filename>. However, if you already have a configuration
file, it is installed as <filename>/etc/evms.conf.sample</filename>. Examine the
new sample
to see if your existing file should be updated.</para>
</listitem>
</orderedlist>
<para>You can now begin using EVMS by typing <command>evmsgui</command>
to start the GUI, <command>evmsn</command> to
start the Ncurses UI, or <command>evms</command> to start the
command line interpreter.</para>
</sect2>
<sect2 id="INSTALLDEBIAN"><title>Installing the EVMS Debian packages</title>
<para>Debian packages of EVMS are maintained by Matt Zimmerman
at the <ulink url="http://www.debian.org">Debian</ulink> website.
You can download these packages for the <ulink url="http://packages.debian.org/testing/admin/evms.html">Woody
</ulink> (testing) release, or for the
<ulink url="http://packages.debian.org/unstable/admin/evms.html">Sid</ulink> (unstable) release.</para>
<para>For the Debian package, patch and recompile your kernel in order to use
EVMS. Debian has a packaged version of the EVMS kernel patches
that includes instructions for patching and building your kernel.</para>
</sect2>
<sect2 id="INSTALLCVS"><title>Installing from CVS</title>
<para>If you would like to use the most recently developed version of EVMS, you can get
the code directly from the CVS tree. </para>
<para>
<orderedlist>
<listitem><para>To download the code, type the
following commands:</para>
<programlisting>mkdir /usr/src/evms_cvs
cd /usr/src/evms_cvs
cvs -d:pserver:anonymous@cvs.evms.sf.net:/cvsroot/evms login
(press Enter when prompted for a password)
cvs -z3 -d:pserver:anonymous@cvs.evms.sf.net:/cvsroot/evms co engine2</programlisting>
</listitem>
<listitem><para>Alternatively, if you already have a copy of the CVS code checked out, you can update
to the latest code with the following commands:
</para>
<programlisting>cd /usr/src/evms_cvs/engine2
cvs update -d -P</programlisting></listitem>
<listitem><para>The EVMS Engine can be built directly into the CVS tree. To start, change
directory to <filename>/usr/src/evms_cvs/engine2</filename>:
</para>
<programlisting>cd /usr/src/evms_cvs/engine2
autoconf</programlisting>
<note><title>NOTE</title><para>The <command>autoconf</command> command is necessary only for code taken directly from CVS.</para></note></listitem>
<listitem><para>Select the appropriate options for your configuration.
<note><title>NOTE</title>
<para>You can find the list of options by typing:
<programlisting>./configure -h</programlisting></para></note>
</para>
</listitem>
<listitem><para>Configure your engine:</para>
<programlisting>./configure [--options]</programlisting></listitem>
<listitem><para>Type the following commands: </para>
<programlisting>make
make install
ldconfig</programlisting>
<para>Unless you specified other directories in Step 5, the
following list describes where files are installed
on your system:
<itemizedlist>
<listitem><para>The core Engine library is installed in
<filename>/lib</filename>.</para></listitem>
<listitem><para>The core dlist library is installed in
<filename>/lib</filename>.</para></listitem>
<listitem><para>All plug-in libraries is installed in
<filename>/lib/evms</filename>.</para></listitem>
<listitem><para>All user interface binaries are installed
in <filename>/sbin</filename>.</para></listitem>
<listitem><para>All header files are installed in
<filename>/usr/include/evms</filename>.</para></listitem>
<listitem><para>All manual pages are installed in <filename>/usr/man</filename>.</para></listitem>
</itemizedlist></para>
</listitem>
<listitem><para>Add the Engine library path to your
<varname>LD_LIBRARY_PATH</varname> environment variable, or to
your <filename>/etc/ld.so.conf</filename> file. Do not add the
plug-in library path because the Engine dynamically loads
these libraries directly.</para></listitem>
</orderedlist></para>
</sect2>
</sect1>
<sect1 id="voldisc"><title>Activating EVMS volumes</title>
<para>In the previous EVMS design (releases 1.2.1 and earlier), volume discovery
was performed in the kernel, and all volumes were immediately activated at boot time.
With the current EVMS design, volume discovery is performed in user-space, and
volumes are activated by communicating with the kernel. Thus, in order to activate
your volumes, you must open one of the EVMS user interfaces and perform a save,
which will activate all inactive volumes.</para>
<para>For example, start the GUI by running <command>evmsgui</command>. You should see all empty
checkboxes in the &quot;Active&quot; column. Press <guibutton>Save</guibutton>, which
activates all of the volumes and fills in each of the checkboxes.</para>
<para>In addition to manually starting one of the EVMS user interfaces, there is a new
utility called <command>evms_activate</command>.
The <command>evms_activate</command> utility simply opens the EVMS Engine
and tells the Engine to save the changes.
You might want to add a call to <command>evms_activate</command> to your
boot scripts in order to automatically activate your volumes at boot time. If
you have volumes listed in your <filename>/etc/fstab</filename> file,
you need to call <command>evms_activate</command> before the
<filename>fstab</filename> is processed.</para>
<note><title>NOTE</title>
<para>EVMS requires <filename>/proc</filename> to be mounted in order
to find the Device Mapper driver. If you run <command>evms_activate</command>
before processing the <filename>fstab</filename> file, you might need
to manually mount and unmount <filename>/proc</filename> around the call
to <command>evms_activate</command>.
</para>
</note>
<para>After the volumes are activated, you can mount them in the normal way with the dev-nodes in the <filename>/dev/evms</filename> directory.</para></sect1>
<sect1 id="rootfs"><title>The root filesystem on an EVMS volume</title>
<para>After volume discovery and activation are done in user space, there is an
issue with having your system's root file system on an EVMS volume.
In order for the root file system's volume to be activated, the EVMS tools must
run. However, in order to get to the EVMS tools, the root file system must be mounted.
The solution to this dilemma is to use an initial ramdisk (<command>initrd</command>).
An initial ramdisk
is a ram-based device that acts as a temporary root file system at boot time. The
initial ramdisk lets EVMS run programs and load modules that are necessary to
activate the true root file system.</para>
<para>For instructions on building an init-ramdisk for use with EVMS, see <xref linkend="appxinitram"></xref>.</para></sect1>
<sect1 id="setupclus"><title>Setting up clustered EVMS</title>
<para>The following steps show how to set up EVMS clustering. Perform these steps on
each cluster node:</para>
<orderedlist>
<listitem><para>Because EVMS depends on the CCM services offered by Heartbeat, the
Linux-HA CCM service must be configured on the system. Execute the following
line to configure CCM:</para>
<programlisting>echo 'respawn haclient /usr/lib/heartbeat/ccm' &gt;&gt; /etc/ha.d/ha.cf</programlisting>
</listitem>
<listitem><para>Because Linux-HA expects its consumers to set up a private communication
channel, create the following fifo with administrative privileges:</para>
<programlisting>mkfifo /var/lib/heartbeat/api/evms.req
mkfifo /var/lib/heartbeat/api/evms.rsp
chgrp haclient /var/lib/heartbeat/api/evms.req
chgrp haclient /var/lib/heartbeat/api/evms.rsp
chmod 200 /var/lib/heartbeat/api/evms.req
chmod 600 /var/lib/heartbeat/api/evms.rsp</programlisting>
</listitem>
<listitem><para>To ensure that clustered EVMS is activated whenever Linux-HA starts,
execute the following line:</para>
<programlisting>echo 'respawn root /sbin/evmsd' &gt;&gt; /etc/ha.d/ha.cf</programlisting>
<para>This step assumes that the <command>evmsd</command> daemon is installed in
<filename>/sbin/evmsd</filename>. If
the <command>evmsd</command> daemon is not installed in <filename>/sbin/evmsd</filename>,
change <filename>/sbin/evmsd</filename> to the correct location when executing
the command.</para>
</listitem>
</orderedlist>
<para>See <xref linkend="clusterops"></xref> for information about clustering
operations.</para>
</sect1>
</chapter>