more updates to bring into line with a real installation attempt;
authorSteve Sheppard <ssheps@gmail.com>
Thu, 18 Nov 2010 22:35:45 +0000 (17:35 -0500)
committerSteve Sheppard <ssheps@gmail.com>
Thu, 18 Nov 2010 22:35:45 +0000 (17:35 -0500)
add links to previous steps where mentioned;

1.6/admin/serversideinstallation.xml

index 074da34..7ea420e 100644 (file)
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter xml:id="serversideinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">
-       <info>
-               <title>Server-side Installation of Evergreen Software</title>
-               <abstract>
-                       <para>This section describes installation of the Evergreen server-side software and its associated components.
-                       Installation, configuration, testing and verification 
-                       of the software is straightforward if you follow some simple directions.</para>
-               </abstract>
-       </info>
-       <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current
-       stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to
-       installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating
-       system.</para>
-       <para>The current version of the Evergreen server-side software runs as a native application on any of several
-       well-known <systemitem class="osname">Linux</systemitem> distributions 
-       (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>). 
-       It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem> 
-       operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP
-       Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be
-       installed and run on <systemitem class="osname">Windows</systemitem> via a so-called
-       <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,
-       <application>"VirtualBox"</application>, or <application>"VMware"</application>, or
-       <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>
-       environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem> 
-       systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or
-       <application>"VMware"</application>). More information on virtualized environments can be found in 
-       <xref linkend="serversideinstallation-virtual"/>.</para>
-       <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>
-       <para>The Evergreen server-side software has dependencies on particular versions of certain major software
-       sub-components. Successful installation of Evergreen software requires that software versions agree with those
-       listed here:</para>
-       <table xml:id="serversideinstall-software-dependencies">
-               <title>Evergreen Software Dependencies</title>
-               <indexterm>
-                       <primary>Evergreen software dependencies</primary>
-               </indexterm>
-               <tgroup align="left" cols="3" colsep="1" rowsep="1">
-                       <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>
-                       <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>
-                       <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>
-                       <thead>
-                               <row>
-                                       <entry>Evergreen</entry>
-                                       <entry>OpenSRF</entry>
-                                       <entry>PostgreSQL</entry>
-                               </row>
-                       </thead>
-                       <tbody>
-                               <row>
-                                       <entry>1.6.1.x</entry>
-                                       <entry>1.4.0</entry>
-                                       <entry>8.2 / 8.3</entry>
-                               </row>
-                               <row>
-                                       <entry>1.6.0.x</entry>
-                                       <entry>1.2</entry>
-                                       <entry>8.2 / 8.3</entry>
-                               </row>
-                               <row>
-                                       <entry>1.4.x</entry>
-                                       <entry>1.0</entry>
-                                       <entry>8.1 / 8.2</entry>
-                               </row>
-                               <row>
-                                       <entry>1.2.x</entry>
-                                       <entry>0.9</entry>
-                                       <entry>8.1 / 8.2</entry>
-                               </row>
-                       </tbody>
-               </tgroup>
-       </table>
-       <section xml:id="serversideinstallation-all">
-               <title>Installing Server-Side Software</title>
-               <para>This section describes the installation of the major components of Evergreen server-side software.</para>
-               <para>As far as possible, you should perform the following steps in the exact order given since the
-               success of many steps relies on the successful completion of earlier steps. You should make backup
-               copies of files and environments when you are instructed to do so. In the event of installation problems
-               those copies can allow you to back out of a step gracefully and resume the installation from a known
-               state. See <xref linkend="backingup"/> for further information.</para>
-               <para>Of course, after you successfully complete and test the entire Evergreen installation you should
-               take a final snapshot backup of your system(s). This can be the first in the series of regularly
-               scheduled system backups that you should probably also begin.</para>
-               <section xml:id="serversideinstallation-opensrf">
-                       <indexterm>
-                               <primary>OpenSRF</primary>
-                               <secondary>installation</secondary>
-                       </indexterm>
-                       <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or
-                               <systemitem class="osname">Debian</systemitem></title>
-                       <indexterm>
-                               <primary>Linux</primary>
-                               <secondary>Debian</secondary>
-                       </indexterm>
-                       <indexterm>
-                               <primary>Linux</primary>
-                               <secondary>Ubuntu</secondary>
-                       </indexterm>
-                       <para>This section describes the installation of the latest version of the Open Service Request
-                       Framework (OpenSRF), a major component of the Evergreen server-side software, on 
-                       <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>
-                       systems. Evergreen software is integrated with and depends on the OpenSRF software
-                       system.</para>
-                       <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is
-                       properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>
-                       continue with any further Evergreen installation steps
-                       until you have verified that OpenSRF has been successfully installed and tested.</para>
-                       <note>
-                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
-                               platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch
-                               (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and
-                               <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>
-                               <para>In the following instructions, you are asked to perform certain steps as either
-                               the <systemitem class="username">root</systemitem> user, the 
-                               <systemitem class="username">opensrf</systemitem> user, or the 
-                               <systemitem class="username">postgres</systemitem> user.</para>
-                               <itemizedlist>
-                                       <listitem>
-                                               <para><systemitem class="osname">Debian</systemitem> -- To become the
-                                               <systemitem class="username">root</systemitem> user, issue the command
-                                               <command>su -</command> and enter the password of the
-                                               <systemitem class="username">root</systemitem> user.</para>
-                                       </listitem>
-                                       <listitem>
-                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
-                                               <systemitem class="username">root</systemitem> user, issue the command
-                                               <command>sudo su -</command> and enter the password of the 
-                                               <systemitem class="username">root</systemitem> user.</para>
-                                       </listitem>
-                               </itemizedlist>
-                               <para>To switch from the <systemitem class="username">root</systemitem> user to a
-                               different user, issue the command <command>su - USERNAME</command>. For example, to
-                               switch from the <systemitem class="username">root</systemitem> user to the 
-                               <systemitem class="username">opensrf</systemitem> user, issue the command 
-                               <command>su - opensrf</command>. Once you have become a non-root user, to become 
-                               the <systemitem class="username">root</systemitem> user again, simply issue the command
-                               <command>exit</command>.</para>
-                       </note>
-                       <procedure>
-                               <step>
-                                       <title>Add the OpenSRF User</title>
-                                       <para>As the <systemitem class="username">root</systemitem> user, add the
-                                       opensrf user to the system. The default shell for the new user is automatically
-                                       set to <command>/bin/bash</command> to inherit a reasonable environment:</para>
-                                       <screen>
-                                               <userinput>useradd -m -s /bin/bash opensrf</userinput>
-                                               <userinput>passwd opensrf</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Download and Unpack Latest OpenSRF Version</title>
-                                       <indexterm>
-                                               <primary>OpenSRF</primary>
-                                               <secondary>download</secondary>
-                                       </indexterm>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, change to
-                                       the directory <filename class="directory">/home/opensrf</filename> then download
-                                       and extract the latest version of OpenSRF. The latest version can be found here:
-                                       <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>
-                                       <screen>
-                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
-                                               <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>
-                                               <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>
-                                       </screen>
-                                       <para>The new directory
-                                       <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>
-                               </step>
-                               <step>
-                                       <title>Install Prerequisites to Build OpenSRF</title>
-                                       <para>In this section you will install and configure a set of prerequisites that will be
-                                       used to build OpenSRF. In a following step you will actually build the OpenSRF software 
-                                       using the <command>make</command> utility.</para>
-                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
-                                       below to build the prerequisites from the software distribution that you just downloaded
-                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
-                                       example with the keyword corresponding to the name of one of the
-                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following
-                                       distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> . 
-                                       For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would
-                                       enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>
-                                       <screen>
-                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
-                                               <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
-                                       </screen>
-                                       <table xml:id="serversideinstallation-keywords-opensrf">
-                                               <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
-                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">
-                                                       <colspec colnum="1" colwidth="1.0*"/>
-                                                       <colspec colnum="2" colwidth="3.0*"/>
-                                                       <thead>
-                                                               <row>
-                                                                       <entry>Keyword</entry>
-                                                                       <entry>Linux Version</entry>
-                                                               </row>
-                                                       </thead>
-                                                       <tbody>
-                                                               <row>
-                                                                       <entry>debian-etch</entry>
-                                                                       <entry>Debian "Etch" (4.0)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>debian-lenny</entry>
-                                                                       <entry>Debian "Lenny" (5.0)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-hardy</entry>
-                                                                       <entry>Ubuntu "Hardy Heron" (8.04)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-karmic</entry>
-                                                                       <entry>Ubuntu "Karmic Koala" (9.10)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-lucid</entry>
-                                                                       <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>fedora13</entry>
-                                                                       <entry>Fedora "Goddard" (13)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>centos</entry>
-                                                                       <entry>Centos</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>rhel</entry>
-                                                                       <entry>RHEL</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>gentoo</entry>
-                                                                       <entry>Gentoo</entry>
-                                                               </row>
-                                                       </tbody>
-                                               </tgroup>
-                                       </table>
-                                       <para>This will install a number of packages on the system that are required by OpenSRF,
-                                       including some Perl modules from CPAN. You can say <literal>No</literal> to the initial
-                                       CPAN configuration prompt to allow it to automatically configure itself to download and
-                                       install Perl modules from CPAN. The CPAN installer will ask you a number of times whether
-                                       it should install prerequisite modules - say <literal>Yes</literal>.</para>
-                               </step>
-                               <step>
-                                       <title>Build OpenSRF</title>
-                                       <para>In this section you will configure, build and install the OpenSRF
-                                       components that support other Evergreen services.</para>
-                                       <substeps>
-                                               <step>
-                                                       <title>Configure OpenSRF</title>
-                                                       <indexterm>
-                                                               <primary>OpenSRF</primary>
-                                                               <secondary>configure</secondary>
-                                                       </indexterm>
-                                                       <para>As the <systemitem class="username">opensrf</systemitem>
-                                                       user, return to the OpenSRF build directory and use the
-                                                       <command>configure</command> utility to prepare for the next
-                                                       step of compiling and linking the software. If you wish to
-                                                       include support for Python and Java, add the configuration
-                                                       options <option>--enable-python</option> and
-                                                       <option>--enable-java</option>, respectively:</para>
-                                                       <screen>
-                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
-                                                               <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
-                                                               <userinput>make</userinput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Compile, Link and Install OpenSRF</title>
-                                                       <para>As the <systemitem class="username">root</systemitem>
-                                                       user, return to the OpenSRF build directory and use the
-                                                       <command>make</command> utility to compile, link and install
-                                                       OpenSRF:</para>
-                                                       <screen>
-                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>
-                                                               <userinput>make install</userinput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Update the System Dynamic Library Path</title>
-                                                       <para>You must update the system dynamic library path to force
-                                                       your system to recognize the newly installed libraries. As the
-                                                       <systemitem class="username">root</systemitem> user, do this by
-                                                       creating the new file
-                                                       <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a
-                                                       new library path, then run the command
-                                                       <command>ldconfig</command> to automatically read the file and
-                                                       modify the system dynamic library path:</para>
-                                                       <screen>
-                                                               <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>
-                                                               <userinput>ldconfig</userinput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Define Public and Private OpenSRF Domains</title>
-                                                       <para>For security purposes, OpenSRF uses Jabber domains to separate services
-                                                       into public and private realms. On a single-server system the easiest way to
-                                                       define public and private OpenSRF domains is to define separate host names by 
-                                                       adding entries to the file <filename>/etc/hosts</filename>.</para>
-                                                       <para>In the following steps we will use the example domains
-                                                       <systemitem class="domainname">public.localhost</systemitem> for the public
-                                                       domain and <systemitem class="domainname">private.localhost</systemitem> 
-                                                       for the private domain. In an upcoming step, you will configure two special
-                                                       <systemitem class="service">ejabberd</systemitem> users
-                                                       to handle communications for these two domains.</para>
-                                                       <para>As the <systemitem class="username">root</systemitem> user, edit the file
-                                                       <filename>/etc/hosts</filename> and add the following example domains:</para>
-                                                       <indexterm>
-                                                               <primary>Jabber</primary>
-                                                       </indexterm>
-                                                       <screen>
-                                                               <userinput>127.0.1.2    public.localhost        public</userinput>
-                                                               <userinput>127.0.1.3    private.localhost       private</userinput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Change File Ownerships</title>
-                                                       <para>Finally, as the <systemitem class="username">root</systemitem>
-                                                       user, change the ownership of all files installed in the
-                                                       directory <filename class="directory">/openils</filename> to the
-                                                       user <systemitem class="username">opensrf</systemitem>:</para>
-                                                       <screen>
-                                                               <userinput>chown -R opensrf:opensrf /openils</userinput>
-                                                       </screen>
-                                               </step>
-                                       </substeps>
-                               </step>
-                               <step>
-                                       <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>
-                                       <indexterm>
-                                               <primary>ejabberd</primary>
-                                       </indexterm>
-                                       <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>
-                                       you must stop that service. As the <systemitem class="username">root</systemitem> user,
-                                       execute the following command to stop the service:</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/ejabberd stop</userinput>
-                                       </screen>
-                                       <para>If <systemitem class="service">ejabberd</systemitem> reports that it 
-                                       is already stopped, there may have been a problem when it started back
-                                       in the installation step. If there are any remaining daemon processes such as
-                                       <systemitem class="daemon">beam</systemitem> or
-                                       <systemitem class="daemon">epmd</systemitem> 
-                                       you may need to perform the following commands to kill them:</para>
-                                       <screen>
-                                               <userinput>epmd -kill</userinput>
-                                               <userinput>killall beam; killall beam.smp</userinput>
-                                               <userinput>rm /var/lib/ejabberd/*</userinput>
-                                               <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>
-                                       <para>You must make several configuration changes for the
-                                       <systemitem class="service">ejabberd</systemitem> service before
-                                       it is started again.
-                                       As the <systemitem class="username">root</systemitem> user, edit the file
-                                       <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>
-                                       <itemizedlist>
-                                               <listitem>
-                                                       <para>Change the line:
-                                                       <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>
-                                                       to:
-                                                       <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Change the line:
-                                                       <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to:
-                                                       <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>
-                                                       <para>If the line looks something like this:
-                                                       <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>
-                                                       then change it to:
-                                                       <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Change all three occurrences of: <literal>max_stanza_size</literal>
-                                                       to: <literal>2000000</literal>.</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Change both occurrences of: <literal>maxrate</literal> to:
-                                                       <literal>500000</literal>.</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Comment out the line <literal>{mod_offline, []}</literal> 
-                                                       by placing two <literal>%</literal> comment signs in front.</para>
-                                               </listitem>
-                                       </itemizedlist>
-                               </step>
-                               <step xml:id="serversideinstallation-opensrf-continued">
-                                       <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>
-                                       <para>As the <systemitem class="username">root</systemitem> user, restart the
-                                       <systemitem class="service">ejabberd</systemitem> service to test the
-                                       configuration changes and to register your users:</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/ejabberd start</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Register <systemitem class="username">router</systemitem> and
-                                               <systemitem class="username">ejabberd</systemitem> users</title>
-                                       <para>The two <systemitem class="service">ejabberd</systemitem> users 
-                                       <systemitem class="username">router</systemitem> and 
-                                       <systemitem class="username">opensrf</systemitem> must be registered 
-                                       and configured to manage OpenSRF router service and communications 
-                                       for the two domains <literal>public.localhost</literal> and
-                                       <literal>private.localhost</literal>
-                                       that you added to the file <filename>/etc/hosts</filename>
-                                       in a previous step:</para>
-                                       <itemizedlist>
-                                               <listitem>
-                                                       <para>the <systemitem class="username">router</systemitem> user,
-                                                       to whom all requests to connect to an OpenSRF service will be
-                                                       routed;</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>the <systemitem class="username">opensrf</systemitem> user,
-                                                       which clients use to connect to OpenSRF services (you may name
-                                                       the user anything you like, but we use
-                                                       <literal>opensrf</literal> in these examples)</para>
-                                               </listitem>
-                                       </itemizedlist>
-                                       <para>As the <systemitem class="username">root</systemitem> user, execute the
-                                       <command>ejabberdctl</command> utility as shown below to register and create passwords
-                                       for the users <systemitem class="username">router</systemitem> and
-                                       <systemitem class="username">opensrf</systemitem> on each domain:</para>
-                                       <screen>
-                                               <prompt># The syntax for registering a user with ejabberdctl is:</prompt>
-                                               <prompt>#    ejabberdctl register USER DOMAIN PASSWORD</prompt>
-                                               <userinput>ejabberdctl register router  private.localhost NEWPASSWORD</userinput>
-                                               <userinput>ejabberdctl register router  public.localhost  NEWPASSWORD</userinput>
-                                               <userinput>ejabberdctl register opensrf private.localhost NEWPASSWORD</userinput>
-                                               <userinput>ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>
-                                       </screen>
-                                       <para>Note that the users <systemitem class="username">router</systemitem> and
-                                       <systemitem class="username">opensrf</systemitem> and their respective passwords 
-                                       will be used again in the file <filename>/openils/conf/opensrf_core.xml</filename>
-                                       in the next steps.</para>
-                               </step>
-                               <step>
-                                       <title>Create OpenSRF configuration files</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, 
-                                       execute the following commands to create the new configuration files
-                                       <filename>/openils/conf/opensrf_core.xml</filename> and
-                                       <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>
-                                       <screen>
-                                               <userinput>cd /openils/conf</userinput>
-                                               <userinput>cp opensrf.xml.example      opensrf.xml</userinput>
-                                               <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Update usernames and passwords in the OpenSRF configuration file</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
-                                       OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
-                                       and update the usernames and passwords to match the values shown in the
-                                       following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>
-                                       shows common XPath syntax to indicate the approximate position within the XML
-                                       file that needs changes. The right-hand side of the table shows the replacement
-                                       values:</para>
-                                       <table xml:id="serversideinstallation-xpath-table-1">
-                                               <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
-                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">
-                                                       <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
-                                                       <colspec colname="Value" colnum="2" colwidth="2.0*"/>
-                                                       <thead>
-                                                               <row>
-                                                                       <entry>XPath location</entry>
-                                                                       <entry>Value</entry>
-                                                               </row>
-                                                       </thead>
-                                                       <tbody>
-                                                               <row>
-                                                                       <entry>/config/opensrf/username</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">opensrf</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/opensrf/passwd </entry>
-                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">opensrf</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/gateway/username</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">opensrf</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/gateway/passwd</entry>
-                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">opensrf</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/username, 
-                                                                       first entry where server == public.localhost</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">router</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/password,
-                                                                       first entry where server == public.localhost</entry>
-                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">router</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/username,
-                                                                       second entry where server == private.localhost</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">router</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/password,
-                                                                       second entry where server == private.localhost</entry>
-                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">router</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                       </tbody>
-                                               </tgroup>
-                                       </table>
-                                       <para>You may also need to modify the file to specify the domains from which 
-                                       <systemitem class="service">OpenSRF</systemitem> will accept connections,
-                                       and to which it will make connections.
-                                       If you are installing <application>OpenSRF</application> on a single server
-                                       and using the <systemitem class="domainname">private.localhost</systemitem> and
-                                       <systemitem class="domainname">public.localhost</systemitem> domains, 
-                                       these will already be set to the correct values. Otherwise, search and replace
-                                       to match values for your own systems.</para>
-                               </step>
-                               <step>
-                                       <title>Set location of the persistent database</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
-                                       file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the 
-                                       element <literal>dbfile</literal> (near the end of the file) to set the 
-                                       location of the persistent database:</para>
-                                       <programlisting language="xml"><![CDATA[
-<!-- Example of an app-specific setting override -->
-<opensrf.persist>
-  <app_settings>
-    <dbfile>/tmp/persist.db</dbfile>
-  </app_settings>
-</opensrf.persist>
-]]></programlisting>
-                               </step>
-                               <step xml:id="serversideinstallation-srfsh">
-                                       <title>Create configuration files for users needing <command>srfsh</command></title>
-                                       <para>In this section you will set up a special configuration file for each user
-                                       who will need to run the <command>srfsh</command> (pronounced <emphasis>surf
-                                       shell</emphasis>) utility.</para>
-                                       <indexterm>
-                                               <primary>srfsh</primary>
-                                       </indexterm>
-                                       <para>The software installation will automatically create a utility named
-                                       <command>srfsh</command> (surf shell). This is a command line diagnostic tool for testing 
-                                       and interacting with <application>OpenSRF</application>. It will be used in a future
-                                       step to complete and test the Evergreen installation. 
-                                       See  <xref linkend="serversideinstallation-testing"/> for further information.</para>
-                                       <para>As the <systemitem class="username">root</systemitem> user, copy the short
-                                       sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
-                                       to <filename>~/.srfsh.xml</filename> (note the leading dot!), the home
-                                       directory of each user who will use <command>srfsh</command>. Finally, edit each
-                                       file <filename>~/.srfsh.xml</filename> and make the following changes; when you
-                                       finish, remember to change the owner of the file to match the owner of the home
-                                       directory:</para>
-                                       <itemizedlist>
-                                               <listitem>
-                                                       <para>Modify <literal>domain</literal> to be the router hostname
-                                                       (following our domain examples,
-                                                       <systemitem class="domainname">private.localhost</systemitem> will give
-                                                       <command>srfsh</command> access to all OpenSRF services, while
-                                                       <systemitem class="domainname">public.localhost</systemitem>
-                                                       will only allow access to those OpenSRF services that are
-                                                       publicly exposed).</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Modify <literal>username</literal> and
-                                                       <literal>password</literal> to match the
-                                                       <literal>opensrf</literal> Jabber user for the chosen
-                                                       domain</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Modify <literal>logfile</literal> to be the full path for
-                                                       a log file to which the user has write access</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>Modify <literal>loglevel</literal> as needed for testing</para>
-                                               </listitem>
-                                       </itemizedlist>
-                                       <programlisting language="xml"><![CDATA[
-<?xml version="1.0"?>
-<!-- This file follows the standard bootstrap config file layout -->
-<!-- found in opensrf_core.xml -->
-<srfsh>
-<router_name>router</router_name>
-<domain>private.localhost</domain>
-<username>opensrf</username>
-<passwd>SOMEPASSWORD</passwd>
-<port>5222</port>
-<logfile>/tmp/srfsh.log</logfile>
-<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->
-<loglevel>4</loglevel>
-</srfsh>
-]]></programlisting>
-                               </step>
-                               <step>
-                                       <title>Modify the environmental variable <envar>PATH</envar> for the
-                                               <systemitem class="username">opensrf</systemitem> user</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, modify the
-                                       environmental variable <envar>PATH</envar> by adding a new file path to the
-                                       <systemitem class="username">opensrf</systemitem> user's shell configuration
-                                       file <filename>~/.bashrc</filename>:</para>
-                                       <screen>
-                                               <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Start OpenSRF</title>
-                                       <para>As the <systemitem class="username">root</systemitem> user, start the
-                                       <systemitem class="service">ejabberd</systemitem> and 
-                                       <systemitem class="service">memcached</systemitem> services:</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/ejabberd start</userinput>
-                                               <userinput>/etc/init.d/memcached start</userinput>
-                                       </screen>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user,
-                                       start OpenSRF as follows:</para>
-                                       <screen>
-                                               <userinput>osrf_ctl.sh -l -a start_all</userinput>
-                                       </screen>
-                                       <para>The flag <option>-l</option> forces Evergreen to use 
-                                       <systemitem class="domainname">localhost</systemitem> (your current system) 
-                                       as the hostname. The flag <option>-a start_all</option>  starts the other 
-                                       OpenSRF <systemitem class="service">router</systemitem> , 
-                                       <systemitem class="service">Perl</systemitem> , and
-                                       <systemitem class="service">C</systemitem> services.</para>
-                                       <itemizedlist>
-                                               <listitem>
-                                                       <para>You can also start Evergreen without the
-                                                       <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
-                                                       utility must know the fully qualified domain name for the system
-                                                       on which it will execute. That hostname was probably specified
-                                                       in the configuration file <filename>opensrf.xml</filename> which
-                                                       you configured in a previous step.</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>If you receive an error message similar to
-                                                       <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
-                                                       environment variable <envar>PATH</envar> does not include the
-                                                       directory <filename class="directory">/openils/bin</filename>.
-                                                       As the <systemitem class="username">opensrf</systemitem> user,
-                                                       edit the configuration file <filename>~/.bashrc</filename> and
-                                                       add the following line: 
-                                                       <literal>export PATH=$PATH:/openils/bin</literal></para>
-                                               </listitem>
-                                       </itemizedlist>
-                               </step>
-                               <step>
-                                       <title>Test connections to OpenSRF</title>
-                                       <para>Once you have installed and started OpenSRF, as the 
-                                       <systemitem class="username">root</systemitem> user, test your connection to 
-                                       <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command> 
-                                       utility and trying to call the <command>add</command> method on the OpenSRF 
-                                       <systemitem class="service">math</systemitem> service:</para>
-                                       <screen>
-                                               <userinput>/openils/bin/srfsh</userinput>
-                                               <computeroutput>srfsh#</computeroutput>
-                                               <computeroutput>request opensrf.math add 2 2</computeroutput>
-                                               <computeroutput>Received Data: 4</computeroutput>
-                                               <computeroutput>------------------------------------</computeroutput>
-                                               <computeroutput>Request Completed Successfully</computeroutput>
-                                               <computeroutput>Request Time in seconds: 0.007519</computeroutput>
-                                               <computeroutput>------------------------------------</computeroutput>
-                                               <computeroutput>srfsh#</computeroutput>
-                                       </screen>
-                                       <para>For other <command>srfsh</command> commands, type in
-                                       <userinput>help</userinput> at the prompt.</para>
-                               </step>
-                               <step>
-                                       <title>Stop OpenSRF</title>
-                                       <para>After OpenSRF has started, you can stop it at any time by using the
-                                       <command>osrf_ctl.sh</command> again. As the 
-                                       <systemitem class="username">opensrf</systemitem> 
-                                       user, stop OpenSRF as follows:</para>
-                                       <screen>
-                                               <userinput>osrf_ctl.sh -l -a stop_all</userinput>
-                                       </screen>
-                               </step>
-                       </procedure>
-               </section>
-               <section xml:id="serversideinstallation-ubuntudebian">
-                       <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or
-                               <systemitem class="osname">Debian</systemitem></title>
-                       <indexterm>
-                               <primary>Linux</primary>
-                               <secondary>Debian</secondary>
-                       </indexterm>
-                       <indexterm>
-                               <primary>Linux</primary>
-                               <secondary>Ubuntu</secondary>
-                       </indexterm>
-                       <para>This section outlines the installation process for the latest stable version of
-                       Evergreen.</para>
-                       <para>In this section you will download, unpack, install, configure and test the Evergreen
-                       system, including the Evergreen server and the PostgreSQL database system. You will make several
-                       configuration changes and adjustments to the software, including updates to configure the system
-                       for your own locale, and some updates needed to work around a few known issues.</para>
-                       <note>
-                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)
-                               architectures. There may be differences between the Desktop and Server editions of
-                               <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server
-                               edition.</para>
-                               <para>In the following instructions, you are asked to perform certain steps as 
-                               either the <systemitem class="username">root</systemitem> user, the 
-                               <systemitem class="username">opensrf</systemitem> user, or the 
-                               <systemitem class="username">postgres</systemitem> user.</para>
-                               <itemizedlist>
-                                       <listitem>
-                                               <para><systemitem class="osname">Debian</systemitem> -- To become the
-                                               <systemitem class="username">root</systemitem> user, issue the command
-                                               <command>su -</command> and enter the password of the 
-                                               <systemitem class="username">root</systemitem> user.</para>
-                                       </listitem>
-                                       <listitem>
-                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the
-                                               <systemitem class="username">root</systemitem> user, issue the command
-                                               <command>sudo su -</command> and enter the password of the 
-                                               <systemitem class="username">root</systemitem> user.</para>
-                                       </listitem>
-                               </itemizedlist>
-                               <para>To switch from the <systemitem class="username">root</systemitem> user to a
-                               different user, issue the command <command>su - USERNAME</command>. For example, to
-                               switch from the <systemitem class="username">root</systemitem> user to the 
-                               <systemitem class="username">opensrf</systemitem> user, issue the command 
-                               <command>su - opensrf</command>. Once you have become a non-root user, to become the
-                               <systemitem class="username">root</systemitem> user again, simply issue the command
-                               <command>exit</command>.</para>
-                       </note>
-                       <procedure>
-                               <step>
-                                       <title>Install OpenSRF</title>
-                                       <para>Evergreen software is integrated with and depends on the Open Service
-                                       Request Framework (OpenSRF) software system. For further information on
-                                       installing, configuring and testing OpenSRF, see 
-                                       <xref linkend="serversideinstallation-opensrf"/>.</para>
-                                       <para>Follow the steps outlined in that section and run the specified tests to
-                                       ensure that OpenSRF is properly installed and configured. Do 
-                                       <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with
-                                       any further Evergreen installation steps until you have verified that OpenSRF
-                                       has been successfully installed and tested.</para>
-                               </step>
-                               <step>
-                                       <title>Download and Unpack Latest Evergreen Version</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, download
-                                       and extract the latest version of Evergreen. The latest version can be found here:
-                                       <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>
-                                       <screen>
-                                               <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>
-                                               <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>
-                                       </screen>
-                                       <para>The new directory
-                                       <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>
-                                       will be created.</para>
-                               </step>
-                               <step>
-                                       <title>Install Prerequisites to Build Evergreen</title>
-                                       <para>In this section you will install and configure a set of prerequisites that
-                                       will be used to build Evergreen. In a following step you will actually build the
-                                       Evergreen software using the <command>make</command> utility.</para>
-                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show
-                                       below to build the prerequisites from the software distribution that you just downloaded
-                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following
-                                       example with the keyword corresponding to the name of one of the 
-                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following distribution
-                                       keywords table <xref linkend="serversideinstallation-keywords-evergreen"/> . For example,
-                                       to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would enter this
-                                       command: <command>make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic</command>.</para>
-                                       <screen>
-                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
-                                               <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
-                                       </screen>
-                                       <table xml:id="serversideinstallation-keywords-evergreen">
-                                               <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>
-                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">
-                                                       <colspec colnum="1" colwidth="1.0*"/>
-                                                       <colspec colnum="2" colwidth="3.0*"/>
-                                                       <thead>
-                                                               <row>
-                                                                       <entry>Keyword</entry>
-                                                                       <entry>Linux Version</entry>
-                                                               </row>
-                                                       </thead>
-                                                       <tbody>
-                                                               <row>
-                                                                       <entry>debian-etch</entry>
-                                                                       <entry>Debian "Etch" (4.0)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>debian-lenny</entry>
-                                                                       <entry>Debian "Lenny" (5.0)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-hardy</entry>
-                                                                       <entry>Ubuntu "Hardy Heron" (8.04)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-intrepid</entry>
-                                                                       <entry>Ubuntu "Intrepid Ibex" (8.10)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-karmic</entry>
-                                                                       <entry>Ubuntu "Karmic Koala" (9.10)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>ubuntu-karmic</entry>
-                                                                       <entry>Ubuntu "Lucid Lynx" (10.04)</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>centos</entry>
-                                                                       <entry>Centos</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>rhel</entry>
-                                                                       <entry>RHEL</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>gentoo</entry>
-                                                                       <entry>Gentoo</entry>
-                                                               </row>
-                                                       </tbody>
-                                               </tgroup>
-                                       </table>
-                               </step>
-                               <step performance="optional" xml:id="serversideinstallation-postgresql-default">
-                                       <title>(OPTIONAL) Install the PostgreSQL Server</title>
-                                       <indexterm>
-                                               <primary>databases</primary>
-                                               <secondary>PostgreSQL</secondary>
-                                       </indexterm>
-                                       <para>Since the PostgreSQL server is usually a standalone server in multi-server
-                                       production systems, the prerequisite installer Makefile in the previous step
-                                       does not automatically install PostgreSQL. You must install the PostgreSQL server
-                                       yourself, either on the same system as Evergreen itself or on another system.
-                                       If your PostgreSQL server is on a different system, just skip this step.</para>
-                                       <para>For further information on manually installing PostgreSQL, visit the official
-                                       <link xl:href="http://www.postgresql.org/">PostgreSQL Site</link>.</para>
-                                       <para>If your PostgreSQL server will be on the same system as your Evergreen
-                                       software, then as the <systemitem class="username">root</systemitem> user
-                                       install the required PostgreSQL server packages:</para>
-                                       <para>For <systemitem class="osname">Debian Lenny</systemitem> and 
-                                       <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>
-                                       <screen>
-                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>
-                                       </screen>
-                                       <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and
-                                       <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>
-                                       <screen>
-                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>
-                                       </screen>
-                                       <note>
-                                               <para>PostgreSQL versions 8.3 or 8.4 are the recommended versions to work 
-                                               with Evergreen 1.6. If you have an older version of PostgreSQL, you should
-                                               upgrade before installing Evergreen. To find the running version of
-                                               PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
-                                               user, run the <command>psql</command>. Then type <userinput>SELECT
-                                               version();</userinput> to get detailed information about your version 
-                                               of PostgreSQL.</para>
-                                       </note>
-                               </step>
-                               <step performance="optional">
-                                       <title>Install Perl Modules on PostgreSQL Server</title>
-                                       <para>If PostgreSQL is running on the same system as your Evergreen software,
-                                       then the Perl modules will automatically be available. Just skip this step.
-                                       Otherwise, continue if your PostgreSQL server is running on another system.</para>
-                                       <para>You will need to install several Perl modules on the other system. As the
-                                       <systemitem class="username">root</systemitem> user install the following Perl
-                                       modules:</para>
-                                       <screen>
-                                               <prompt># first, ensure the gcc compiler is installed:</prompt>
-                                               <userinput>apt-get install gcc</userinput>
-                                               <prompt># then install the Perl modules:</prompt>
-                                               <userinput>perl -MCPAN -e shell</userinput>
-                                               <computeroutput>cpan></computeroutput>
-                                               <userinput>install JSON::XS</userinput>
-                                               <computeroutput>cpan></computeroutput>
-                                               <userinput>install MARC::Record</userinput>
-                                               <computeroutput>cpan></computeroutput>
-                                               <userinput>install MARC::File::XML</userinput>
-                                       </screen>
-                                       <para>For more information on installing Perl Modules vist the official
-                                       <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>
-                                       <indexterm>
-                                               <primary>Perl</primary>
-                                               <secondary>CPAN</secondary>
-                                       </indexterm>
-                               </step>
-                               <step>
-                                       <title>Update the System Dynamic Library Path</title>
-                                       <para>You must update the system dynamic library path to force your system to recognize
-                                       the newly installed libraries. As the <systemitem class="username">root</systemitem> user,
-                                       do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>
-                                       containing a new library path, then run the command <command>ldconfig</command> to
-                                       automatically read the file and modify the system dynamic library path:</para>
-                                       <screen>
-                                               <userinput>echo "/usr/local/lib"     >> /etc/ld.so.conf.d/osrf.conf</userinput>
-                                               <userinput>echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf</userinput>
-                                               <userinput>ldconfig</userinput>
-                                       </screen>
-                               </step>
-                               <step performance="optional">
-                                       <title>Restart the PostgreSQL Server</title>
-                                       <para>If PostgreSQL is running on the same system as the rest of Evergreen, as
-                                       the <systemitem class="username">root</systemitem> user you must restart
-                                       PostgreSQL to re-read the new library paths just configured. If PostgreSQL is
-                                       running on another system, you may skip this step.
-                                       As the <systemitem class="username">opensrf</systemitem> user,
-                                       execute the following command, where
-                                       <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL version
-                                       (e.g. <literal>8.3</literal>):</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>
-                                       </screen>
-                               </step>
-                               <step xml:id="serversideinstallation-configure">
-                                       <title>Configure Evergreen</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, return to
-                                       the Evergreen build directory and use the <command>configure</command> and
-                                       <command>make</command> utilities to configure Evergreen so it can be compiled
-                                       and linked in the next step:</para>
-                                       <screen>
-                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
-                                               <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>
-                                               <userinput>make</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Compile, Link and Install Evergreen</title>
-                                       <para>In this step you will actually compile, link and install Evergreen and the 
-                                       default Evergreen Staff Client.</para>
-                                       <para>As the <systemitem class="username">root</systemitem> user, return to the
-                                       Evergreen build directory and use the <command>make</command> utility as shown below:</para>
-                                       <screen>
-                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
-                                               <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>
-                                       </screen>
-                                       <para>The Staff Client will also be automatically built, but you must remember
-                                       to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the Staff
-                                       Client you will use to connect to the Evergreen server. For further information on manually
-                                       building the Staff Client, see 
-                                       <xref linkend="staffclientinstallation-building-staffclient"/>.</para>
-                                       <para>The above commands will create a new subdirectory
-                                       <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename> 
-                                       containing the Staff Client.</para>
-                                       <para>To complete the Staff Client installation, 
-                                       as the <systemitem class="username">root</systemitem> user create a symbolic link 
-                                       named <emphasis>server</emphasis> in the head of the Staff Client directory 
-                                       <filename class="directory">/openils/var/web/xul</filename> that points to the
-                                       subdirectory <filename class="directory">/server</filename> of the new Staff
-                                       Client build:</para>
-                                       <screen>
-                                               <userinput>cd /openils/var/web/xul</userinput>
-                                               <userinput>ln -sf rel_1_6_1_2/server server</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Copy the OpenSRF Configuration Files</title>
-                                       <para>As the <systemitem class="username">root</systemitem> user, execute the
-                                       following commands to copy the example OpenSRF configuration files into place
-                                       after first creating backup copies of the old files for troubleshooting purposes.
-                                       These files replace the configuration files that you set up in a previous step
-                                       when you installed and tested OpenSRF. Finally, change the ownership on
-                                       the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>
-                                       <screen>
-                                               <userinput>cd /openils/conf</userinput>
-                                               <userinput>cp opensrf.xml             opensrf.xml.BAK</userinput>
-                                               <userinput>cp opensrf_core.xml   opensrf_core.xml.BAK</userinput>
-                                               <userinput>cp opensrf.xml.example      opensrf.xml</userinput>
-                                               <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>
-                                               <userinput>cp oils_web.xml.example     oils_web.xml</userinput>
-                                               <userinput>chown -R opensrf:opensrf /openils/</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>Create and Configure PostgreSQL Database</title>
-                                       <indexterm>
-                                               <primary>databases</primary>
-                                               <secondary>PostgreSQL</secondary>
-                                       </indexterm>
-                                       <para>In this step you will create the Evergreen database. In the commands
-                                       below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>
-                                       repository to match your PostgreSQL server
-                                       layout. For example, if you built PostgreSQL from source the path would be
-                                       <filename class="directory">/usr/local/share/contrib</filename>; if you
-                                       installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>,
-                                       the path would be 
-                                       <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem>.</para>
-                                       <substeps>
-                                               <step>
-                                                       <para>
-                                                               <emphasis role="bold">Create and configure the database</emphasis>
-                                                       </para>
-                                                       <para>As the <systemitem class="username">postgres</systemitem>
-                                                       user on the PostgreSQL system create the PostgreSQL database,
-                                                       then set some internal paths:</para>
-                                                       <screen>
-                                                               <userinput>createdb evergreen -E UTF8 -T template0</userinput>
-                                                               <userinput>createlang plperl   evergreen</userinput>
-                                                               <userinput>createlang plperlu  evergreen</userinput>
-                                                               <userinput>createlang plpgsql  evergreen</userinput>
-                                                       </screen>
-                                                       <para>Continue as user <systemitem class="username">postgres</systemitem>
-                                                       and execute the SQL scripts as shown below, adjusting the paths as needed, where
-                                                       <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL
-                                                       version (e.g. <literal>8.3</literal>).</para>
-                                                       <screen>
-                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>
-                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql  evergreen</userinput>
-                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql     evergreen</userinput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>
-                                                       <para>As the <systemitem class="username">postgres</systemitem>
-                                                       user on the PostgreSQL system, create a new PostgreSQL user
-                                                       named <systemitem class="username">evergreen</systemitem> and
-                                                       assign a password:</para>
-                                                       <screen>
-                                                               <userinput>createuser -P -s evergreen</userinput>
-                                                               <computeroutput>Enter password for new role: <userinput>MYNEWPASSWORD</userinput></computeroutput>
-                                                               <computeroutput>Enter it again: <userinput>MYNEWPASSWORD</userinput></computeroutput>
-                                                       </screen>
-                                               </step>
-                                               <step>
-                                                       <title>Create database schema</title>
-                                                       <para>As the <systemitem class="username">root</systemitem>
-                                                       user, create the database schema and configure your system with
-                                                       the corresponding database authentication details for the
-                                                       <emphasis>evergreen</emphasis> database user that you created in
-                                                       the previous step.</para>
-                                                       <para>Enter the following commands and replace
-                                                       <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and
-                                                       <emphasis>DATABASENAME</emphasis> with appropriate
-                                                       values:</para>
-                                                       <screen>
-                                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
-                                                               <userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>
-                                                               <userinput>  --service all --create-schema --create-bootstrap --create-offline \</userinput>
-                                                               <userinput>  --hostname HOSTNAME --port PORT \</userinput>
-                                                               <userinput>  --user evergreen --password PASSWORD --database DATABASENAME</userinput>
-                                                       </screen>
-                                                       <para>On most systems, <emphasis>HOSTNAME</emphasis> will be
-                                                       <emphasis role="bold">localhost</emphasis> and
-                                                       <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.
-                                                       Of course, values for <emphasis>PASSWORD</emphasis> and
-                                                       <emphasis>DATABASENAME</emphasis> must match the values you used in the
-                                                       previous step when you created the database and and set a password for the
-                                                       <systemitem class="username">evergreen</systemitem> user.</para>
-                                                       <para>As the command executes, you may see warnings similar to:
-                                                       <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,
-                                                       you may see one warning per schema) but they can be safely ignored.</para>
-                                                       <note>
-                                                               <para>If you are entering the above command on a single
-                                                               line, do not include the <literal>\</literal>
-                                                               (backslash) characters. If you are using the
-                                                               <command>bash</command> shell, these should only be used
-                                                               at the end of a line at a bash prompt to indicate that
-                                                               the command is continued on the next line.</para>
-                                                       </note>
-                                               </step>
-                                               <step>
-                                                       <title>Configure the Apache web server</title>
-                                                       <indexterm>
-                                                               <primary>web server</primary>
-                                                               <secondary>Apache</secondary>
-                                                       </indexterm>
-                                                       <para>In this step you will configure the Apache web server to
-                                                       support Evergreen software.</para>
-                                                       <para>First, you must enable some built-in Apache modules and install
-                                                       some additional Apache configuration files. Then you will create a new
-                                                       Security Certificate. Finally, you must make several changes to the Apache
-                                                       configuration file.</para>
-                                                       <substeps>
-                                                               <step>
-                                                                       <title>Enable the required Apache Modules</title>
-                                                                       <para>As the <systemitem class="username">root</systemitem> 
-                                                                       user, enable some modules in the Apache server, then 
-                                                                       copy the new configuration files to the Apache server
-                                                                       directories:</para>
-                                                                       <screen>
-                                                                               <userinput>a2enmod ssl     # enable mod_ssl</userinput>
-                                                                               <userinput>a2enmod rewrite # enable mod_rewrite</userinput>
-                                                                               <userinput>a2enmod expires # enable mod_expires</userinput>
-                                                                       </screen>
-                                                                       <para>As the commands execute, you may see warnings similar to:
-                                                                       <literal>Module SOMEMODULE already enabled</literal>
-                                                                       but you can safely ignore them.</para>
-                                                               </step>
-                                                               <step>
-                                                                       <title>Copy Apache configuration files</title>
-                                                                       <para>You must copy the Apache configuration
-                                                                       files from the Evergreen installation directory
-                                                                       to the Apache directory. As the 
-                                                                       <systemitem class="username">root</systemitem> 
-                                                                       user, perform the following commands:</para>
-                                                                       <screen>
-                                                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>
-                                                                               <userinput>cp Open-ILS/examples/apache/eg.conf  /etc/apache2/sites-available/</userinput>
-                                                                               <userinput>cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/</userinput>
-                                                                               <userinput>cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>
-                                                                       </screen>
-                                                               </step>
-                                                               <step>
-                                                                       <title>Create a Security Certificate</title>
-                                                                       <para>You must create a new Security Certificate (SSL Key)
-                                                                       for the Apache server using the <command>openssl</command>
-                                                                       command. For a public production server you must configure
-                                                                       or purchase a signed SSL certificate, but for now you can
-                                                                       just use a self-signed certificate and accept the warnings
-                                                                       in the Staff Client and browser during testing and
-                                                                       development. As the
-                                                                       <systemitem class="username">root</systemitem> user, 
-                                                                       perform the following commands:</para>
-                                                                       <screen>
-                                                                               <userinput>mkdir /etc/apache2/ssl</userinput>
-                                                                               <userinput>cd /etc/apache2/ssl</userinput>
-                                                                               <userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
-                                                                       </screen>
-                                                                       <note>
-                                                                               <para>This step generates a self-signed SSL
-                                                                               certificate. You must install a proper SSL
-                                                                               certificate for a public production system to
-                                                                               avoid warning messages when users login to their
-                                                                               account through the OPAC or when staff login
-                                                                               through the Staff Client.</para>
-                                                                               <para>For further information on getting a proper
-                                                                               SSL certificate, see
-                                                                               <xref linkend="serversideinstallation-ssl"/>.</para>
-                                                                       </note>
-                                                               </step>
-                                                               <step xml:id="serversideinstallation-modify-apache">
-                                                                       <title>Update Apache configuration file</title>
-                                                                       <para>You must make several changes to the new Apache
-                                                                       configuration file
-                                                                       <filename>/etc/apache2/sites-available/eg.conf</filename> . 
-                                                                       As the <systemitem class="username">root</systemitem> user,
-                                                                       edit the file and make the following changes:</para>
-                                                                       <itemizedlist>
-                                                                               <listitem>
-                                                                                       <para>In the section
-                                                                                       <literal>&lt;Directory "/openils/var/cgi-bin"></literal>
-                                                                                       replace this line:
-                                                                                       <literal>Allow from 10.0.0.0/8</literal> 
-                                                                                       with this line: <literal>Allow from all</literal>.</para>
-                                                                                       <warning>This change allows access to your
-                                                                                       configuration CGI scripts from any workstation on
-                                                                                       any network. This is only a temporary change to
-                                                                                       expedite testing and should be removed after you
-                                                                                       have finished and successfully tested the Evergreen
-                                                                                       installation. See 
-                                                                                       <xref linkend="serversideinstallation-postinstallation"/>
-                                                                                       for further details on removing this change after
-                                                                                       the Evergreen installation is complete.
-                                                                                       </warning>
-                                                                               </listitem>
-                                                                               <listitem>
-                                                                                       <para>Comment out the line <literal>Listen
-                                                                                       443</literal>, since it conflicts with the
-                                                                                       same declaration in the configuration file:
-                                                                                       <filename>/etc/apache2/ports.conf</filename>.
-                                                                                       Note that <systemitem class="osname">Debian
-                                                                                       </systemitem> users should not do this
-                                                                                       since the conflict does not apply to that
-                                                                                       operating system.</para>
-                                                                               </listitem>
-                                                                               <listitem>
-                                                                                       <para>The following updates are needed to allow
-                                                                                       the logs to function properly, but it may break
-                                                                                       other Apache applications on your server:</para>
-                                                                                       <para>For the <systemitem class="osname">Linux</systemitem> 
-                                                                                       distributions <systemitem class="osname">Ubuntu
-                                                                                       Hardy</systemitem> or
-                                                                                       <systemitem class="osname">Debian Etch</systemitem>, 
-                                                                                       as the <systemitem class="username">root</systemitem>
-                                                                                       user, edit the Apache configuration file
-                                                                                       <filename>/etc/apache2/apache2.conf</filename> and
-                                                                                       change the line <literal>User www-data</literal>
-                                                                                       to <literal>User opensrf</literal>.</para>
-                                                                                       <para>For the <systemitem class="osname">Linux</systemitem> 
-                                                                                       distributions <systemitem class="osname">Ubuntu
-                                                                                       Karmic</systemitem>, 
-                                                                                       <systemitem class="osname">Ubuntu Lucid</systemitem> 
-                                                                                       or <systemitem class="osname">Debian Lenny</systemitem>,
-                                                                                       as the <systemitem class="username">root</systemitem> 
-                                                                                       user, edit the Apache configuration file
-                                                                                       and change these lines:</para>
-                                                                                       <screen>
-                                                                                               <userinput>export APACHE_RUN_USER=www-data</userinput>
-                                                                                               <userinput>export APACHE_RUN_GROUP=www-data</userinput>
-                                                                                       </screen>
-                                                                                       <para>to instead read:</para>
-                                                                                       <screen>
-                                                                                               <userinput>export APACHE_RUN_USER=opensrf</userinput>
-                                                                                               <userinput>export APACHE_RUN_GROUP=opensrf</userinput>
-                                                                                       </screen>
-                                                                               </listitem>
-                                                                               <listitem>
-                                                                                       <para>As the 
-                                                                                       <systemitem class="username">root</systemitem> user,
-                                                                                       edit the Apache configuration file
-                                                                                       <filename>/etc/apache2/apache2.conf</filename> and
-                                                                                       modify the values for <literal>KeepAliveTimeout</literal>
-                                                                                       and <literal>MaxKeepAliveRequests</literal> to match
-                                                                                       the following:</para>
-                                                                                       <screen>
-                                                                                               <userinput>KeepAliveTimeout       1</userinput>
-                                                                                               <userinput>MaxKeepAliveRequests 100</userinput>
-                                                                                       </screen>
-                                                                               </listitem>
-                                                                               <listitem>
-                                                                                       <para>Further configuration changes to
-                                                                                       Apache may be necessary for busy systems. These
-                                                                                       changes increase the number of Apache server
-                                                                                       processes that are started to support additional
-                                                                                       browser connections.</para>
-                                                                                       <para>As the <systemitem
-                                                                                       class="username">root</systemitem> user, edit the
-                                                                                       Apache configuration file
-                                                                                       <filename>/etc/apache2/apache2.conf</filename>,
-                                                                                       locate and modify the section related to
-                                                                                       <emphasis>prefork configuration</emphasis> to suit
-                                                                                       the load on your system:</para>
-                                                                                       <programlisting language="xml"><![CDATA[
-<IfModule mpm_prefork_module>
-   StartServers           20
-   MinSpareServers         5
-   MaxSpareServers        15
-   MaxClients            150
-   MaxRequestsPerChild 10000
-</IfModule>
-]]></programlisting>
-                                                                               </listitem>
-                                                                       </itemizedlist>
-                                                               </step>
-                                                               <step>
-                                                                       <title>Enable the Evergreen web site</title>
-                                                                       <para>Finally, you must enable the Evergreen web site. As the 
-                                                                       <systemitem class="username">root</systemitem> user, execute
-                                                                       the following Apache configuration commands to disable the default
-                                                                       <emphasis>It Works</emphasis> web page and enable the
-                                                                       Evergreen web site, and then restart the Apache server:</para>
-                                                                       <screen>
-                                                                               <prompt># disable/enable web sites</prompt>
-                                                                               <userinput>a2dissite default</userinput>
-                                                                               <userinput>a2ensite eg.conf</userinput>
-                                                                               <prompt># restart the server</prompt>
-                                                                               <userinput>/etc/init.d/apache2 reload</userinput>
-                                                                       </screen>
-                                                               </step>
-                                                       </substeps>
-                                               </step>
-                                       </substeps>
-                               </step>
-                               <step xml:id="serversideinstallation-opensrf-config">
-                                       <title>Update the OpenSRF Configuration File</title>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the
-                                       OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>
-                                       to update the Jabber usernames and passwords, and to specify the domain from
-                                       which we will accept and to which we will make connections.</para>
-                                       <para>If you are installing Evergreen on a single server and using the
-                                       <systemitem class="domainname">private.localhost</systemitem> / 
-                                       <systemitem class="domainname">public.localhost</systemitem> domains, 
-                                       these will already be set to the correct values. Otherwise, search and replace
-                                       to match your customized values.</para>
-                                       <para>The left-hand side of  <xref linkend="serversideinstallation-xpath-table-2"/>
-                                       shows common XPath syntax to indicate the approximate position within the XML
-                                       file that needs changes. The right-hand side of the table shows the replacement
-                                       values:</para>
-                                       <table xml:id="serversideinstallation-xpath-table-2">
-                                               <title>Sample XPath syntax for editing "opensrf_core.xml"</title>
-                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">
-                                                       <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>
-                                                       <colspec colname="Value" colnum="2" colwidth="2.0*"/>
-                                                       <thead>
-                                                               <row>
-                                                                       <entry>XPath location</entry>
-                                                                       <entry>Value</entry>
-                                                               </row>
-                                                       </thead>
-                                                       <tbody>
-                                                               <row>
-                                                                       <entry>/config/opensrf/username</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">opensrf</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/opensrf/passwd </entry>
-                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">opensrf</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/gateway/username</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">opensrf</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/gateway/passwd</entry>
-                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">opensrf</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/username,
-                                                                       first entry where server == public.localhost</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">router</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/password,
-                                                                       first entry where server == public.localhost</entry>
-                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">router</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/username,
-                                                                       second entry where server == private.localhost</entry>
-                                                                       <entry>
-                                                                               <systemitem class="username">router</systemitem>
-                                                                       </entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>/config/routers/router/transport/password,
-                                                                       second entry where server == private.localhost</entry>
-                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>
-                                                                       password for
-                                                                       <systemitem class="username">router</systemitem> user
-                                                                       </entry>
-                                                               </row>
-                                                       </tbody>
-                                               </tgroup>
-                                       </table>
-                               </step>
-                               <step>
-                                       <title>Create Configuration Files for Users Needing <command>srfsh</command></title>
-                                       <para>When OpenSRF was installed in a previous step (see
-                                       <xref linkend="serversideinstallation-opensrf"/> for further information),
-                                       the software installation automatically created a utility named
-                                       <command>srfsh</command> (surf shell). This is a command line diagnostic tool
-                                       for testing and interacting with <application>OpenSRF</application> It will be used
-                                       in a future step to complete and test the Evergreen installation. See 
-                                       <xref linkend="serversideinstallation-testing"/> for further information.</para>
-                               </step>
-                               <step xml:id="serversideinstallation-opensrf-env">
-                                       <title>Modify the OpenSRF Environment</title>
-                                       <para>Modify the shell configuration file <filename>~/.bashrc</filename> for
-                                       user <systemitem class="username">opensrf</systemitem> by adding a Perl environmental
-                                       variable, then execute the shell configuration file to load the new variables into
-                                       your current environment.</para>
-                                       <note>
-                                               <para>
-                                                       <emphasis>In a multi-server environment, you must add any
-                                                       modifications to <filename>~/.bashrc</filename> to the top of
-                                                       the file <emphasis>before</emphasis> the line 
-                                                       <literal>[ -z "$PS1" ] &amp;&amp; return </literal>.
-                                                       This will allow headless (scripted) logins to load the correct
-                                                       environment.</emphasis>
-                                               </para>
-                                       </note>
-                                       <screen>
-                                               <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>
-                                               <userinput>. ~/.bashrc</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <title>(OPTIONAL) Enable and Disable Language Localizations</title>
-                                       <para>You can load translations such as Armenian (hy-AM), Canadian French
-                                       (fr-CA), and others into the database to complete the translations available in
-                                       the OPAC and Staff Client. For further information, see <xref linkend="enabling_and_disabling_localization"/>.</para>
-                               </step>
-                       </procedure>
-               </section>
-               <section xml:id="serversideinstallation-starting">
-                       <title>Starting Evergreen</title>
-                       <procedure>
-                               <step>
-                                       <para>As the <systemitem class="username">root</systemitem>
-                                       user, start the <systemitem class="service">ejabberd</systemitem> and 
-                                       <systemitem class="service">memcached</systemitem> services as follows:</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/ejabberd start</userinput>
-                                               <userinput>/etc/init.d/memcached start</userinput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user,
-                                       start Evergreen as follows:</para>
-                                       <screen>
-                                               <userinput>osrf_ctl.sh -l -a start_all</userinput>
-                                       </screen>
-                                       <para>The flag <option>-l</option> forces Evergreen to use 
-                                       <systemitem class="domainname">localhost</systemitem> (your current system) 
-                                       as the hostname. The flag <option>-a start_all</option>  starts the other 
-                                       OpenSRF <systemitem class="service">router</systemitem> , 
-                                       <systemitem class="service">Perl</systemitem> , and
-                                       <systemitem class="service">C</systemitem> services.</para>
-                                       <itemizedlist>
-                                               <listitem>
-                                                       <para>You can also start Evergreen without the
-                                                       <option>-l</option> flag, but the <command>osrf_ctl.sh</command>
-                                                       utility must know the fully qualified domain name for the system
-                                                       on which it will execute. That hostname was probably specified
-                                                       in the configuration file <filename>opensrf.xml</filename> which
-                                                       you configured in a previous step.</para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>If you receive an error message similar to
-                                                       <emphasis>osrf_ctl.sh: command not found</emphasis>, then your
-                                                       environment variable <envar>PATH</envar> does not include the
-                                                       directory <filename class="directory">/openils/bin</filename>.
-                                                       As the <systemitem class="username">opensrf</systemitem> user,
-                                                       edit the configuration file <filename>~/.bashrc</filename> and
-                                                       add the following line: 
-                                                       <literal>export PATH=$PATH:/openils/bin</literal></para>
-                                               </listitem>
-                                               <listitem>
-                                                       <para>If you receive an error message similar to <emphasis>Can't
-                                                       locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation
-                                                       aborted</emphasis>, then your environment variable 
-                                                       <emphasis role="bold">PERL5LIB</emphasis> does not include the 
-                                                       directory <filename class="directory">/openils/lib/perl5</filename>.
-                                                       As the <systemitem class="username">opensrf</systemitem> user, 
-                                                       edit the configuration file <filename>~/.bashrc</filename> and
-                                                       add the following line: 
-                                                       <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>
-                                               </listitem>
-                                       </itemizedlist>
-                               </step>
-                               <step>
-                                       <para>In this step you will generate the Web files needed by the Staff Client
-                                       and catalog, and calculate the proximity of locations in the Organizational Unit
-                                       tree (which allows <emphasis>Holds</emphasis> to work properly). You must do
-                                       this the first time you start Evergreen and after making any changes to the
-                                       library hierarchy. As the <systemitem class="username">opensrf</systemitem>
-                                       user, execute the following commands:</para>
-                                       <screen>
-                                               <userinput>cd /openils/bin</userinput>
-                                               <userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>
-                                               <computeroutput>Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'</computeroutput>
-                                               <computeroutput>Updating fieldmapper</computeroutput>
-                                       </screen>
-                               </step>
-                               <step>
-                                       <para>As the <systemitem class="username">root</systemitem> user, restart the
-                                       Apache Web server:</para>
-                                       <screen>
-                                               <userinput>/etc/init.d/apache2 restart</userinput>
-                                       </screen>
-                                       <note>
-                                               <para>If the Apache Web server was running when you started the OpenSRF
-                                               services, you might not be able to successfully log into the OPAC or
-                                               Staff Client until the Apache Web server has been restarted.</para>
-                                       </note>
-                               </step>
-                       </procedure>
-               </section>
-               <section xml:id="serversideinstallation-testing">
-                       <title>Testing Your Evergreen Installation</title>
-                       <para>This section describes several simple tests you can perform to verify that the Evergreen
-                       server-side software has been installed and configured properly and is running as
-                       expected.</para>
-                       <simplesect xml:id="serversideinstallation-testing-connections">
-                               <title>Testing Connections to Evergreen</title>
-
-                               <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the
-                               <command>srfsh</command> application and try logging onto the Evergreen server using the default
-                               administrator username and password. Following is sample output generated by executing
-                               <command>srfsh</command> after a successful Evergreen installation. For help with
-                               <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.
-                               Execute the following commands to test your Evergreen connection:</para>
-                               <screen>
-                                       <userinput>/openils/bin/srfsh</userinput>
-                                       <computeroutput>srfsh%</computeroutput>
-                                       <userinput>login admin open-ils</userinput>
-                                       <computeroutput>Received Data: "250bf1518c7527a03249858687714376"</computeroutput>
-                                       <computeroutput>------------------------------------</computeroutput>
-                                       <computeroutput>Request Completed Successfully</computeroutput>
-                                       <computeroutput>Request Time in seconds: 0.045286</computeroutput>
-                                       <computeroutput>------------------------------------</computeroutput>
-                                       <computeroutput>Received Data: {</computeroutput>
-                                       <computeroutput>   "ilsevent":0,</computeroutput>
-                                       <computeroutput>   "textcode":"SUCCESS",</computeroutput>
-                                       <computeroutput>   "desc":" ",</computeroutput>
-                                       <computeroutput>   "pid":21616,</computeroutput>
-                                       <computeroutput>   "stacktrace":"oils_auth.c:304",</computeroutput>
-                                       <computeroutput>   "payload":{</computeroutput>
-                                       <computeroutput>      "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",</computeroutput>
-                                       <computeroutput>      "authtime":420</computeroutput>
-                                       <computeroutput>   }</computeroutput>
-                                       <computeroutput>}</computeroutput>
-                                       <computeroutput>------------------------------------</computeroutput>
-                                       <computeroutput>Request Completed Successfully</computeroutput>
-                                       <computeroutput>Request Time in seconds: 1.336568</computeroutput>
-                                       <computeroutput>------------------------------------</computeroutput>
-                               </screen>
-                               <para>If this does not work, try the following:</para>
-                               <itemizedlist>
-                                       <listitem>
-                                               <para>As the <systemitem class="username">opensrf</systemitem> user, run the
-                                               <filename>settings-tester.pl</filename> utility to review your Evergreen
-                                               installation for any system configuration problems:</para>
-                                               <screen>
-                                                       <userinput>cd /home/opensrf</userinput>
-                                                       <userinput>./Evergreen-ILS-1.6.1.2/Open-ILS/src/support-scripts/settings-tester.pl</userinput>
-                                               </screen>
-                                               <para>If the output of <command>settings-tester.pl</command> does not help you
-                                               find the problem, please do not make any significant changes to your
-                                               configuration.</para>
-                                       </listitem>
-                                       <listitem>
-                                               <para>Follow the steps in the troubleshooting guide in 
-                                               <xref linkend="troubleshooting"/>.</para>
-                                       </listitem>
-                                       <listitem>
-                                               <para>If you have followed the entire set of installation steps listed here
-                                               closely, you are probably extremely close to a working system. Gather your
-                                               configuration files and log files and contact the 
-                                               <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>
-                                               list for assistance before making any drastic changes to your system
-                                               configuration.</para>
-                                       </listitem>
-                               </itemizedlist>
-                       </simplesect>
-               </section>
-               <section xml:id="serversideinstallation-postinstallation">
-                       <title>Post-Installation Chores</title>
-                       <para>There are several additional steps you may need to complete after Evergreen has been
-                       successfully installed and tested. Some steps may not be needed (e.g., setting up support for
-                       Reports).</para>
-                       <section>
-                               <title>Remove temporary Apache configuration changes</title>
-                               <para>You modified the Apache configuration file
-                               <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a
-                               temporary measure to expedite testing (see 
-                               <xref linkend="serversideinstallation-modify-apache"/> for further information).
-                               Those changes must now be reversed in order to deny unwanted access to your CGI 
-                               scripts from users on other public networks.</para>
-                               <warning>
-                                       <para>
-                                               <emphasis>This temporary network update was done to expedite
-                                               testing. You <emphasis role="bold"> must</emphasis> correct
-                                               this for a public production system.</emphasis>
-                                       </para>
-                               </warning>
-                               <para>As the <systemitem class="username">root</systemitem> user, edit the configuration
-                               file again and comment out the line <literal>Allow from all</literal> and uncomment the
-                               line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network
-                               address scheme.</para>
-                       </section>
-                       <section>
-                               <title>Configure a permanent SSL key</title>
-                               <para>In a previous step, you used the command <command>openssl</command> to temporarily
-                               create a new SSL key for the Apache server. This self-signed certificate was adequate
-                               during testing and development, but will continue to generate warnings in the Staff Client 
-                               and browser. For a public production server you should configure or purchase a signed SSL
-                               certificate.</para>
-                               <warning>
-                                       <para>
-                                               <emphasis>The temporary SSL key was only created to expedite
-                                               testing. You should install a proper SSL certificate for a public
-                                               production system.</emphasis>
-                                       </para>
-                               </warning>
-                       </section>
-                       <section>
-                               <title>Set Up Support For Reports</title>
-                               <para>Evergreen reports are extremely powerful but require some simple configuration.
-                               This section describes starting and stopping the Reporter daemon processes.</para>
-                               <itemizedlist>
-                                       <listitem>
-                                               <para>Starting the Reporter Daemon</para>
-                                               <para>Once the <systemitem class="daemon">open-ils.reporter</systemitem>
-                                               process is running and enabled on the gateway, you can start the
-                                               Reporter daemon. That process periodically checks for requests for new
-                                               or scheduled reports, then starts them as required.</para>
-                                               <para>As the <systemitem class="username">opensrf</systemitem> user,
-                                               start the Reporter daemon using the following command:</para>
-                                               <screen>
-                                                       <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter</userinput>
-                                                       <userinput>./clark-kent.pl --daemon</userinput>
-                                               </screen>
-                                               <para>You can control how the <command>clark-kent.pl</command> utility behaves
-                                               by specifying any of several command-line options:</para>
-                                               <itemizedlist>
-                                                       <listitem><option>--sleep=interval</option> : number of seconds
-                                                       to sleep between checks for new reports to run; defaults to
-                                                       <literal>10</literal></listitem>
-                                                       <listitem><option>--lockfile=filename</option> : where to place
-                                                       the lockfile for the process; defaults to
-                                                       <filename>/tmp/reporter-LOCK</filename></listitem>
-                                                       <listitem><option>--concurrency=integer</option> : number of
-                                                       Reporter daemon processes to run; defaults to
-                                                       <literal>1</literal></listitem>
-                                                       <listitem><option>--bootstrap=filename</option> : OpenSRF
-                                                       bootstrap configuration file; defaults to
-                                                       <filename>/openils/conf/opensrf_core.xml</filename></listitem>
-                                               </itemizedlist>
-                                       </listitem>
-                                       <listitem>
-                                               <para>Stopping the Reporter Daemon</para>
-                                               <para>To stop the Reporter daemon, you must kill the process and remove
-                                               the lockfile. The daemon may have just a single associated process or
-                                               there may be several processes if the daemon was started with the optional
-                                               <literal>--concurrency</literal> switch. It will also have a lockfile
-                                               in the default location.</para>
-                                               <para>As the <systemitem class="username">opensrf</systemitem> user,
-                                               execute the following shell commands:</para>
-                                               <screen>
-                                                       <prompt># find and kill the process ID number(s)</prompt>
-                                                       <userinput>kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`</userinput>
-                                                       <prompt># remove the lock file</prompt>
-                                                       <userinput>rm /tmp/reporter-LOCK</userinput>
-                                               </screen>
-                                       </listitem>
-                               </itemizedlist>
-                       </section>
-               </section>
-               <section xml:id="serversideinstallation-virtual">
-                       <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>
-                       <para>This section describes the installation of Evergreen software in so-called "virtualized"
-                       software environments. Evergreen software runs as a native application on any of several
-                       well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>
-                       distributions including <systemitem class="osname">Ubuntu</systemitem> and 
-                       <systemitem class="osname">Debian</systemitem> but it does not run as a native application 
-                       on the <systemitem class="osname">Microsoft Windows</systemitem> operating system. 
-                       However, it is possible to execute Evergreen on a <systemitem class="osname">Windows</systemitem> 
-                       host system by running it within a virtual Linux-guest installation, which itself executes 
-                       on the <systemitem class="osname">Windows</systemitem> system. 
-                       The <systemitem class="osname">Linux</systemitem> environment is fully emulated and acts 
-                       (within limits) just as if it were executing on a real standalone system.</para>
-                       <para>This technique of emulating a <systemitem class="osname">Linux</systemitem> environment on
-                       a <systemitem class="osname">Windows</systemitem> host is a practical way to install and run an
-                       Evergreen system if it is not possible to dedicate a physical machine solely as a 
-                       <systemitem class="osname">Linux</systemitem> host for Evergreen. This architecture is not
-                       recommended for large scale systems since there are performance limitations to running Evergreen
-                       in a virtualized environment. However, it is a reasonable architecture for smaller experimental
-                       systems, as a proof of concept, or as a conference-room pilot.</para>
-                       <simplesect>
-                               <title>Installing Virtualization Software</title>
-                               <para>As described above, Evergreen can be installed on top of an emulated
-                               <systemitem class="osname">Linux</systemitem> environment. The 
-                               <systemitem class="osname">Linux</systemitem> environment, in turn, is installed 
-                               on top of a software application such as <application>"VirtualBox"</application>,
-                               <application>"VMware"</application> or <application>"VirtualPC"</application> which must
-                               first be installed on the <systemitem class="osname">Windows</systemitem> system. This
-                               section contains step-by-step examples that show installing popular virtualization
-                               applications on a <systemitem class="osname">Windows</systemitem> host system. Following
-                               this section are further descriptions of installing 
-                               <systemitem class="osname">Linux</systemitem> and Evergreen systems using that 
-                               virtualization software.</para>
-                               <simplesect>
-                                       <title>Installing <application>"VirtualBox"</application> Virtualization Software</title>
-                                       <para>This section reviews installation of the
-                                       <application>"VirtualBox"</application> application on 
-                                       <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. 
-                                       Download the latest edition of <application>VirtualBox</application> from their official website: 
-                                       <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link>
-                                       and follow the on screen instructions to install the software.</para>
-                               </simplesect>
-                               <simplesect>
-                                       <title>Installing VMware Virtualization Software</title>
-                                       <indexterm>
-                                               <primary>virtualization software</primary>
-                                               <secondary>VMware</secondary>
-                                       </indexterm>
-                                       <para>This section reviews installation of the
-                                       <application>"VMware"</application> application on
-                                       <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. 
-                                       Find and Download the free virtual machine software of from the VMware
-                                       official website:
-                                       <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink> 
-                                       and follow the on-screen instructions.</para>
-                               </simplesect>
-                       </simplesect>
-                       <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">
-                               <title>Installing <systemitem class="osname">Linux</systemitem> / 
-                                               Evergreen on Virtualization Software</title>
-                               <para>After the virtualization software is installed and running, there are two ways to
-                               continue with installing <systemitem class="osname">Linux</systemitem> and Evergreen
-                               software in the new virtualized environment:</para>
-                               <orderedlist>
-                                       <listitem>
-                                               <para>Download and install a prebuilt software image that contains a
-                                               working <systemitem class="osname">Linux</systemitem> / Evergreen system
-                                               (see <xref linkend="serversideinstall-virtual-prebuilt"/> for
-                                               details)</para>
-                                       </listitem>
-                                       <listitem>
-                                               <para>Manually install a <systemitem class="osname">Linux</systemitem>
-                                               guest system, then manually install Evergreen on it.</para>
-                                       </listitem>
-                               </orderedlist>
-                               <para>We review each method in the following sections.</para>
-                               <simplesect xml:id="serversideinstall-virtual-prebuilt">
-                                       <title>Download and install a prebuilt software image</title>
-                                       <para>You can download a prebuilt software image that, when installed with your
-                                       virtualization software, emulates a 
-                                       <systemitem class="osname">Linux</systemitem> guest system containing a running 
-                                       Evergreen distribution. The image is essentially a snapshot of a hard disk from
-                                       a fully configured, functional <systemitem class="osname">Linux</systemitem>
-                                       system with Evergreen already installed.</para>
-                                       <para>We recommend this approach if you wish to get Evergreen running quickly
-                                       with minimal attention to configuration. After reviewing only a few
-                                       configuration details you can have a working Evergreen system that integrates
-                                       smoothly with the rest of your network. See 
-                                       <xref linkend="serversideinstall-virtual-versions"/> for a list of prebuilt 
-                                       software images that are currently available to download and install</para>
-                                       <note>DISCLAIMER: The following virtual images have been contributed by members
-                                       of the Evergreen community for the purposes of testing, evaluation, training,
-                                       and development.</note>
-                                       <table xml:id="serversideinstall-virtual-versions">
-                                               <title>Linux / Evergreen Virtual Images</title>
-                                               <tgroup align="left" cols="4" colsep="1" rowsep="1">
-                                                       <colspec colnum="1" colwidth="1.0*"/>
-                                                       <colspec colnum="2" colwidth="1.0*"/>
-                                                       <colspec colnum="3" colwidth="3.0*"/>
-                                                       <colspec colnum="4" colwidth="1.0*"/>
-                                                       <thead>
-                                                               <row>
-                                                                       <entry>Linux Version</entry>
-                                                                       <entry>Evergreen Version</entry>
-                                                                       <entry>Image</entry>
-                                                                       <entry>Comments</entry>
-                                                               </row>
-                                                       </thead>
-                                                       <tbody>
-                                                               <row>
-                                                                       <entry>Debian lenny (5.0)</entry>
-                                                                       <entry>1.6.0.1</entry>
-                                                                       <entry>
-                                                                               <ulink url="http://www.open-ils.org/~denials/Evergreen1601_DebianLenny.zip"> download </ulink>
-                                                                       </entry>
-                                                                       <entry>VirtualBox image</entry>
-                                                               </row>
-                                                               <row>
-                                                                       <entry>Ubuntu karmic koala (9.10)</entry>
-                                                                       <entry>1.6.0.0</entry>
-                                                                       <entry>
-                                                                               <ulink url="http://www.open-ils.org/~denials/Evergreen-1600-Karmic.zip"> download </ulink>
-                                                                       </entry>
-                                                                       <entry>VirtualBox image</entry>
-                                                               </row>
-                                                       </tbody>
-                                               </tgroup>
-                                       </table>
-                                       <procedure>
-                                               <title>VirtualBox Example</title>
-                                               <indexterm>
-                                                       <primary>virtualization software</primary>
-                                                       <secondary>VirtualBox</secondary>
-                                               </indexterm>
-                                               <step>
-                                                       <para>Start VirtualBox for the first time and select
-                                                       <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media
-                                                       Manager</guimenuitem><guimenuitem>Add</guimenuitem></menuchoice>
-                                                       to locate the prebuilt software image just downloaded (the
-                                                       example shows it was extracted from the original
-                                                       <filename class="extension">zip</filename> file into a temporary directory
-                                                       <filename class="directory">C:\temp</filename>).</para>
-                                               </step>
-                                               <step>
-                                                       <para>After selecting the file, click <guibutton>Open</guibutton> to import it.</para>
-                                               </step>
-                                               <step>
-                                                       <para>Then click <guibutton>OK</guibutton> to save the selection
-                                                       and return to the VirtualBox Media Manager</para>
-                                               </step>
-                                               <step>
-                                                       <para>Click <guibutton>New</guibutton>, then <guibutton>Next</guibutton> to continue
-                                                       and create a new virtual machine (VM).</para>
-                                               </step>
-                                               <step>
-                                                       <para>Create a new name for the VM and set the operating system
-                                                       type, then click <guibutton>Next</guibutton>.</para>
-                                               </step>
-                                               <step>
-                                                       <para>Set the memory size (at least 512Mb),
-                                                       then click <guibutton>Next</guibutton>.</para>
-                                               </step>
-                                               <step>
-                                                       <para>Edit the Virtual Hard Disk configuration settings; click
-                                                       the radio boxes <guilabel>Boot Hard Disk</guilabel> and
-                                                       <guilabel>Use existing hard disk</guilabel>
-                                                       and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel>
-                                                       is selected. Click <guibutton>Finish</guibutton> to finish the
-                                                       setup.</para>
-                                               </step>
-                                               <step>
-                                                       <para>Install the <application>VirtualBox Guest
-                                                       Additions</application> (really a required upgrade to
-                                                       VirtualBox)</para>
-                                               </step>
-                                               <step>
-                                                       <para>Return to VirtualBox and see the summary of the VM just
-                                                       created. Click <guibutton>Start</guibutton> to boot the new VM.</para>
-                                               </step>
-                                               <step>
-                                                       <para>See the start of the <systemitem class="osname">Linux</systemitem>
-                                                       boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel
-                                                       2.6.26-2-686</guimenuitem> from the startup menu and click
-                                                       <guibutton>Enter</guibutton> to start 
-                                                       <systemitem class="osname">Linux</systemitem> and Evergreen. 
-                                                       After some delay you should see the command line prompt 
-                                                       <prompt>debian-lenny login:</prompt>. Log in with username
-                                                       <userinput>root</userinput> and password <userinput>evergreen</userinput>
-                                                       to continue.</para>
-                                               </step>
-                                       </procedure>
-                               </simplesect>
-                       </simplesect>
-               </section>
-       </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>\r
+<chapter xml:id="serversideinstallation" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">\r
+       <info>\r
+               <title>Server-side Installation of Evergreen Software</title>\r
+               <abstract>\r
+                       <para>This section describes installation of the Evergreen server-side software and its associated components.\r
+                       Installation, configuration, testing and verification \r
+                       of the software is straightforward if you follow some simple directions.</para>\r
+               </abstract>\r
+       </info>\r
+       <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current\r
+       stable software release. See <xref linkend="serversideinstallation-all"/> for instructions tailored to\r
+       installing on some particular distributions of the <systemitem class="osname">Linux</systemitem> operating\r
+       system.</para>\r
+       <para>The current version of the Evergreen server-side software runs as a native application on any of several\r
+       well-known <systemitem class="osname">Linux</systemitem> distributions \r
+       (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>). \r
+       It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem> \r
+       operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP\r
+       Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be\r
+       installed and run on <systemitem class="osname">Windows</systemitem> via a so-called\r
+       <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,\r
+       <application>"VirtualBox"</application>, or <application>"VMware"</application>, or\r
+       <application>"VirtualPC"</application> to emulate a <systemitem class="osname">Linux</systemitem>\r
+       environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem> \r
+       systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or\r
+       <application>"VMware"</application>). More information on virtualized environments can be found in \r
+       <xref linkend="serversideinstallation-virtual"/>.</para>\r
+       <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>\r
+       <para>The Evergreen server-side software has dependencies on particular versions of certain major software\r
+       sub-components. Successful installation of Evergreen software requires that software versions agree with those\r
+       listed here:</para>\r
+       <table xml:id="serversideinstall-software-dependencies">\r
+               <title>Evergreen Software Dependencies</title>\r
+               <indexterm>\r
+                       <primary>Evergreen software dependencies</primary>\r
+               </indexterm>\r
+               <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
+                       <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>\r
+                       <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>\r
+                       <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>\r
+                       <thead>\r
+                               <row>\r
+                                       <entry>Evergreen</entry>\r
+                                       <entry>OpenSRF</entry>\r
+                                       <entry>PostgreSQL</entry>\r
+                               </row>\r
+                       </thead>\r
+                       <tbody>\r
+                               <row>\r
+                                       <entry>1.6.1.x</entry>\r
+                                       <entry>1.4.0</entry>\r
+                                       <entry>8.2 / 8.3</entry>\r
+                               </row>\r
+                               <row>\r
+                                       <entry>1.6.0.x</entry>\r
+                                       <entry>1.2</entry>\r
+                                       <entry>8.2 / 8.3</entry>\r
+                               </row>\r
+                               <row>\r
+                                       <entry>1.4.x</entry>\r
+                                       <entry>1.0</entry>\r
+                                       <entry>8.1 / 8.2</entry>\r
+                               </row>\r
+                               <row>\r
+                                       <entry>1.2.x</entry>\r
+                                       <entry>0.9</entry>\r
+                                       <entry>8.1 / 8.2</entry>\r
+                               </row>\r
+                       </tbody>\r
+               </tgroup>\r
+       </table>\r
+       <section xml:id="serversideinstallation-all">\r
+               <title>Installing Server-Side Software</title>\r
+               <para>This section describes the installation of the major components of Evergreen server-side software.</para>\r
+               <para>As far as possible, you should perform the following steps in the exact order given since the\r
+               success of many steps relies on the successful completion of earlier steps. You should make backup\r
+               copies of files and environments when you are instructed to do so. In the event of installation problems\r
+               those copies can allow you to back out of a step gracefully and resume the installation from a known\r
+               state. See <xref linkend="backingup"/> for further information.</para>\r
+               <para>Of course, after you successfully complete and test the entire Evergreen installation you should\r
+               take a final snapshot backup of your system(s). This can be the first in the series of regularly\r
+               scheduled system backups that you should probably also begin.</para>\r
+               <section xml:id="serversideinstallation-opensrf">\r
+                       <indexterm>\r
+                               <primary>OpenSRF</primary>\r
+                               <secondary>installation</secondary>\r
+                       </indexterm>\r
+                       <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or\r
+                               <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
+                       <para>This section describes the installation of the latest version of the Open Service Request\r
+                       Framework (OpenSRF), a major component of the Evergreen server-side software, on \r
+                       <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>\r
+                       systems. Evergreen software is integrated with and depends on the OpenSRF software\r
+                       system.</para>\r
+                       <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is\r
+                       properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>\r
+                       continue with any further Evergreen installation steps\r
+                       until you have verified that OpenSRF has been successfully installed and tested.</para>\r
+                       <note>\r
+                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)\r
+                               platforms. OpenSRF 1.4.0 has been tested on <systemitem class="osname">Debian Etch\r
+                               (4.0)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem> and\r
+                               <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>.</para>\r
+                               <para>In the following instructions, you are asked to perform certain steps as either\r
+                               the <systemitem class="username">root</systemitem> user, the \r
+                               <systemitem class="username">opensrf</systemitem> user, or the \r
+                               <systemitem class="username">postgres</systemitem> user.</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Debian</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>su -</command> and enter the password of the\r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>sudo su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
+                               different user, issue the command <command>su - USERNAME</command>. For example, to\r
+                               switch from the <systemitem class="username">root</systemitem> user to the \r
+                               <systemitem class="username">opensrf</systemitem> user, issue the command \r
+                               <command>su - opensrf</command>. Once you have become a non-root user, to become \r
+                               the <systemitem class="username">root</systemitem> user again, simply issue the command\r
+                               <command>exit</command>.</para>\r
+                       </note>\r
+                       <procedure>\r
+                               <step>\r
+                                       <title>Add the OpenSRF User</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, add the\r
+                                       opensrf user to the system. The default shell for the new user is automatically\r
+                                       set to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
+                                       <screen>\r
+                                               <userinput>useradd -m -s /bin/bash opensrf</userinput>\r
+                                               <userinput>passwd opensrf</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Download and Unpack Latest OpenSRF Version</title>\r
+                                       <indexterm>\r
+                                               <primary>OpenSRF</primary>\r
+                                               <secondary>download</secondary>\r
+                                       </indexterm>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, change to\r
+                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
+                                       and extract the latest version of OpenSRF. The latest version can be found here:\r
+                                       <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                               <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>\r
+                                               <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>\r
+                                       </screen>\r
+                                       <para>The new directory\r
+                                       <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Install Prerequisites to Build OpenSRF</title>\r
+                                       <para>In this section you will install and configure a set of prerequisites that will be\r
+                                       used to build OpenSRF. In a following step you will actually build the OpenSRF software \r
+                                       using the <command>make</command> utility.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
+                                       below to build the prerequisites from the software distribution that you just downloaded\r
+                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
+                                       example with the keyword corresponding to the name of one of the\r
+                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following\r
+                                       distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> . \r
+                                       For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would\r
+                                       enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                               <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
+                                       <table xml:id="serversideinstallation-keywords-opensrf">\r
+                                               <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>\r
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
+                                                       <colspec colnum="1" colwidth="1.0*"/>\r
+                                                       <colspec colnum="2" colwidth="3.0*"/>\r
+                                                       <thead>\r
+                                                               <row>\r
+                                                                       <entry>Keyword</entry>\r
+                                                                       <entry>Linux Version</entry>\r
+                                                               </row>\r
+                                                       </thead>\r
+                                                       <tbody>\r
+                                                               <row>\r
+                                                                       <entry>debian-etch</entry>\r
+                                                                       <entry>Debian "Etch" (4.0)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>debian-lenny</entry>\r
+                                                                       <entry>Debian "Lenny" (5.0)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-hardy</entry>\r
+                                                                       <entry>Ubuntu "Hardy Heron" (8.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-karmic</entry>\r
+                                                                       <entry>Ubuntu "Karmic Koala" (9.10)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-lucid</entry>\r
+                                                                       <entry>Ubuntu "Lucid Lynx" (10.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>fedora13</entry>\r
+                                                                       <entry>Fedora "Goddard" (13)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>centos</entry>\r
+                                                                       <entry>Centos</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>rhel</entry>\r
+                                                                       <entry>RHEL</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>gentoo</entry>\r
+                                                                       <entry>Gentoo</entry>\r
+                                                               </row>\r
+                                                       </tbody>\r
+                                               </tgroup>\r
+                                       </table>\r
+                                       <para>This will install a number of packages on the system that are required by OpenSRF,\r
+                                       including some Perl modules from CPAN. You can say <literal>No</literal> to the initial\r
+                                       CPAN configuration prompt to allow it to automatically configure itself to download and\r
+                                       install Perl modules from CPAN. The CPAN installer will ask you a number of times whether\r
+                                       it should install prerequisite modules - say <literal>Yes</literal>.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Build OpenSRF</title>\r
+                                       <para>In this section you will configure, build and install the OpenSRF\r
+                                       components that support other Evergreen services.</para>\r
+                                       <substeps>\r
+                                               <step>\r
+                                                       <title>Configure OpenSRF</title>\r
+                                                       <indexterm>\r
+                                                               <primary>OpenSRF</primary>\r
+                                                               <secondary>configure</secondary>\r
+                                                       </indexterm>\r
+                                                       <para>As the <systemitem class="username">opensrf</systemitem>\r
+                                                       user, return to the OpenSRF build directory and use the\r
+                                                       <command>configure</command> utility to prepare for the next\r
+                                                       step of compiling and linking the software. If you wish to\r
+                                                       include support for Python and Java, add the configuration\r
+                                                       options <option>--enable-python</option> and\r
+                                                       <option>--enable-java</option>, respectively:</para>\r
+                                                       <screen>\r
+                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                                               <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>\r
+                                                               <userinput>make</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Compile, Link and Install OpenSRF</title>\r
+                                                       <para>As the <systemitem class="username">root</systemitem>\r
+                                                       user, return to the OpenSRF build directory and use the\r
+                                                       <command>make</command> utility to compile, link and install\r
+                                                       OpenSRF:</para>\r
+                                                       <screen>\r
+                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                                               <userinput>make install</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Update the System Dynamic Library Path</title>\r
+                                                       <para>You must update the system dynamic library path to force\r
+                                                       your system to recognize the newly installed libraries. As the\r
+                                                       <systemitem class="username">root</systemitem> user, do this by\r
+                                                       creating the new file\r
+                                                       <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a\r
+                                                       new library path, then run the command\r
+                                                       <command>ldconfig</command> to automatically read the file and\r
+                                                       modify the system dynamic library path:</para>\r
+                                                       <screen>\r
+                                                               <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>\r
+                                                               <userinput>ldconfig</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step xml:id="serversideinstallation-definedomains">\r
+                                                       <title>Define Public and Private OpenSRF Domains</title>\r
+                                                       <para>For security purposes, OpenSRF uses Jabber domains to separate services\r
+                                                       into public and private realms. On a single-server system the easiest way to\r
+                                                       define public and private OpenSRF domains is to define separate host names by \r
+                                                       adding entries to the file <filename>/etc/hosts</filename>.</para>\r
+                                                       <para>In the following steps we will use the example domains\r
+                                                       <systemitem class="domainname">public.localhost</systemitem> for the public\r
+                                                       domain and <systemitem class="domainname">private.localhost</systemitem> \r
+                                                       for the private domain. In an upcoming step, you will configure two special\r
+                                                       <systemitem class="service">ejabberd</systemitem> users\r
+                                                       to handle communications for these two domains.</para>\r
+                                                       <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                                       <filename>/etc/hosts</filename> and add the following example domains:</para>\r
+                                                       <indexterm>\r
+                                                               <primary>Jabber</primary>\r
+                                                       </indexterm>\r
+                                                       <screen>\r
+                                                               <userinput>127.0.1.2  public.localhost   public</userinput>\r
+                                                               <userinput>127.0.1.3  private.localhost  private</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Change File Ownerships</title>\r
+                                                       <para>Finally, as the <systemitem class="username">root</systemitem>\r
+                                                       user, change the ownership of all files installed in the\r
+                                                       directory <filename class="directory">/openils</filename> to the\r
+                                                       user <systemitem class="username">opensrf</systemitem>:</para>\r
+                                                       <screen>\r
+                                                               <userinput>chown -R opensrf:opensrf /openils</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                       </substeps>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
+                                       <indexterm>\r
+                                               <primary>ejabberd</primary>\r
+                                       </indexterm>\r
+                                       <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>\r
+                                       you must stop that service. As the <systemitem class="username">root</systemitem> user,\r
+                                       execute the following command to stop the service:</para>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd stop</userinput>\r
+                                       </screen>\r
+                                       <para>If <systemitem class="service">ejabberd</systemitem> reports that it \r
+                                       is already stopped, there may have been a problem when it started back\r
+                                       in the installation step. If there are any remaining daemon processes such as\r
+                                       <systemitem class="daemon">beam</systemitem> or\r
+                                       <systemitem class="daemon">epmd</systemitem> \r
+                                       you may need to perform the following commands to kill them:</para>\r
+                                       <screen>\r
+                                               <userinput>epmd -kill</userinput>\r
+                                               <userinput>killall beam; killall beam.smp</userinput>\r
+                                               <userinput>rm /var/lib/ejabberd/*</userinput>\r
+                                               <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
+                                       <para>You must make several configuration changes for the\r
+                                       <systemitem class="service">ejabberd</systemitem> service before\r
+                                       it is started again.\r
+                                       As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                       <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>Change the line:\r
+                                                       <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>\r
+                                                       to:\r
+                                                       <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Change the line:\r
+                                                       <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to:\r
+                                                       <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>\r
+                                                       <para>If the line looks something like this:\r
+                                                       <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>\r
+                                                       then change it to:\r
+                                                       <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Change all three occurrences of: <literal>max_stanza_size</literal>\r
+                                                       to: <literal>2000000</literal>.</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Change both occurrences of: <literal>maxrate</literal> to:\r
+                                                       <literal>500000</literal>.</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Comment out the line <literal>{mod_offline, []}</literal> \r
+                                                       by placing two <literal>%</literal> comment signs in front.</para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-continued">\r
+                                       <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, restart the\r
+                                       <systemitem class="service">ejabberd</systemitem> service to test the\r
+                                       configuration changes and to register your users:</para>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd start</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Register <systemitem class="username">router</systemitem> and\r
+                                               <systemitem class="username">ejabberd</systemitem> users</title>\r
+                                       <para>The two <systemitem class="service">ejabberd</systemitem> users \r
+                                       <systemitem class="username">router</systemitem> and \r
+                                       <systemitem class="username">opensrf</systemitem> must be registered \r
+                                       and configured to manage OpenSRF router service and communications \r
+                                       for the two domains <literal>public.localhost</literal> and\r
+                                       <literal>private.localhost</literal> that you added to the file\r
+                                       <filename>/etc/hosts</filename> in a previous step\r
+                                       (see <xref linkend="serversideinstallation-definedomains"/>).\r
+                                       The users include:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>the <systemitem class="username">router</systemitem> user,\r
+                                                       to whom all requests to connect to an OpenSRF service will be\r
+                                                       routed;</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       which clients use to connect to OpenSRF services (you may name\r
+                                                       the user anything you like, but we use\r
+                                                       <literal>opensrf</literal> in these examples)</para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, execute the\r
+                                       <command>ejabberdctl</command> utility as shown below to register and create passwords\r
+                                       for the users <systemitem class="username">router</systemitem> and\r
+                                       <systemitem class="username">opensrf</systemitem> on each domain:</para>\r
+                                       <screen>\r
+                                               <prompt># The syntax for registering a user with ejabberdctl is:</prompt>\r
+                                               <prompt>#    ejabberdctl register USER DOMAIN PASSWORD</prompt>\r
+                                               <userinput>ejabberdctl register router  private.localhost NEWPASSWORD</userinput>\r
+                                               <userinput>ejabberdctl register router  public.localhost  NEWPASSWORD</userinput>\r
+                                               <userinput>ejabberdctl register opensrf private.localhost NEWPASSWORD</userinput>\r
+                                               <userinput>ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>\r
+                                       </screen>\r
+                                       <para>Note that the users <systemitem class="username">router</systemitem> and\r
+                                       <systemitem class="username">opensrf</systemitem> and their respective passwords \r
+                                       will be used again in the file <filename>/openils/conf/opensrf_core.xml</filename>\r
+                                       in the next steps.</para>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-createconfig">\r
+                                       <title>Create OpenSRF configuration files</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, \r
+                                       execute the following commands to create the new configuration files\r
+                                       <filename>/openils/conf/opensrf_core.xml</filename> and\r
+                                       <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>\r
+                                       <screen>\r
+                                               <userinput>cd /openils/conf</userinput>\r
+                                               <userinput>cp opensrf.xml.example      opensrf.xml</userinput>\r
+                                               <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Update usernames and passwords in the OpenSRF configuration file</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
+                                       OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>\r
+                                       and update the usernames and passwords to match the values shown in the\r
+                                       following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>\r
+                                       shows common XPath syntax to indicate the approximate position within the XML\r
+                                       file that needs changes. The right-hand side of the table shows the replacement\r
+                                       values:</para>\r
+                                       <table xml:id="serversideinstallation-xpath-table-1">\r
+                                               <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
+                                                       <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>\r
+                                                       <colspec colname="Value" colnum="2" colwidth="2.0*"/>\r
+                                                       <thead>\r
+                                                               <row>\r
+                                                                       <entry>XPath location</entry>\r
+                                                                       <entry>Value</entry>\r
+                                                               </row>\r
+                                                       </thead>\r
+                                                       <tbody>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/passwd </entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/passwd</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username, \r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                       </tbody>\r
+                                               </tgroup>\r
+                                       </table>\r
+                                       <para>You may also need to modify the file to specify the domains from which \r
+                                       <systemitem class="service">OpenSRF</systemitem> will accept connections,\r
+                                       and to which it will make connections.\r
+                                       If you are installing <application>OpenSRF</application> on a single server\r
+                                       and using the <systemitem class="domainname">private.localhost</systemitem> and\r
+                                       <systemitem class="domainname">public.localhost</systemitem> domains, \r
+                                       these will already be set to the correct values. Otherwise, search and replace\r
+                                       to match values for your own systems.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Set location of the persistent database</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
+                                       file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the \r
+                                       element <literal>dbfile</literal> (near the end of the file) to set the \r
+                                       location of the persistent database:</para>\r
+                                       <programlisting language="xml"><![CDATA[\r
+<!-- Example of an app-specific setting override -->\r
+<opensrf.persist>\r
+  <app_settings>\r
+    <dbfile>/tmp/persist.db</dbfile>\r
+  </app_settings>\r
+</opensrf.persist>\r
+]]></programlisting>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-srfsh">\r
+                                       <title>Create configuration files for users needing <command>srfsh</command></title>\r
+                                       <para>In this section you will set up a special configuration file for each user\r
+                                       who will need to run the <command>srfsh</command> (pronounced <emphasis>surf\r
+                                       shell</emphasis>) utility.</para>\r
+                                       <indexterm>\r
+                                               <primary>srfsh</primary>\r
+                                       </indexterm>\r
+                                       <para>The software installation will automatically create a utility named\r
+                                       <command>srfsh</command> (surf shell). This is a command line diagnostic tool for testing \r
+                                       and interacting with <application>OpenSRF</application>. It will be used in a future\r
+                                       step to complete and test the Evergreen installation. \r
+                                       See  <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, copy the short\r
+                                       sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>\r
+                                       to <filename>~/.srfsh.xml</filename> (note the leading dot!), the home\r
+                                       directory of each user who will use <command>srfsh</command>. Finally, edit each\r
+                                       file <filename>~/.srfsh.xml</filename> and make the following changes; when you\r
+                                       finish, remember to change the owner of the file to match the owner of the home\r
+                                       directory:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>domain</literal> to be the router hostname\r
+                                                       (following our domain examples,\r
+                                                       <systemitem class="domainname">private.localhost</systemitem> will give\r
+                                                       <command>srfsh</command> access to all OpenSRF services, while\r
+                                                       <systemitem class="domainname">public.localhost</systemitem>\r
+                                                       will only allow access to those OpenSRF services that are\r
+                                                       publicly exposed).</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>username</literal> and\r
+                                                       <literal>password</literal> to match the\r
+                                                       <literal>opensrf</literal> Jabber user for the chosen\r
+                                                       domain</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>logfile</literal> to be the full path for\r
+                                                       a log file to which the user has write access</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>loglevel</literal> as needed for testing</para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                                       <programlisting language="xml"><![CDATA[\r
+<?xml version="1.0"?>\r
+<!-- This file follows the standard bootstrap config file layout -->\r
+<!-- found in opensrf_core.xml -->\r
+<srfsh>\r
+<router_name>router</router_name>\r
+<domain>private.localhost</domain>\r
+<username>opensrf</username>\r
+<passwd>SOMEPASSWORD</passwd>\r
+<port>5222</port>\r
+<logfile>/tmp/srfsh.log</logfile>\r
+<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->\r
+<loglevel>4</loglevel>\r
+</srfsh>\r
+]]></programlisting>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Modify the environmental variable <envar>PATH</envar> for the\r
+                                               <systemitem class="username">opensrf</systemitem> user</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, modify the\r
+                                       environmental variable <envar>PATH</envar> by adding a new file path to the\r
+                                       <systemitem class="username">opensrf</systemitem> user's shell configuration\r
+                                       file <filename>~/.bashrc</filename>:</para>\r
+                                       <screen>\r
+                                               <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Start OpenSRF</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, start the\r
+                                       <systemitem class="service">ejabberd</systemitem> and \r
+                                       <systemitem class="service">memcached</systemitem> services:</para>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd start</userinput>\r
+                                               <userinput>/etc/init.d/memcached start</userinput>\r
+                                       </screen>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                       start OpenSRF as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>osrf_ctl.sh -l -a start_all</userinput>\r
+                                       </screen>\r
+                                       <para>The flag <option>-l</option> forces Evergreen to use \r
+                                       <systemitem class="domainname">localhost</systemitem> (your current system) \r
+                                       as the hostname. The flag <option>-a start_all</option>  starts the other \r
+                                       OpenSRF <systemitem class="service">router</systemitem> , \r
+                                       <systemitem class="service">Perl</systemitem> , and\r
+                                       <systemitem class="service">C</systemitem> services.</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>You can also start Evergreen without the\r
+                                                       <option>-l</option> flag, but the <command>osrf_ctl.sh</command>\r
+                                                       utility must know the fully qualified domain name for the system\r
+                                                       on which it will execute. That hostname was probably specified\r
+                                                       in the configuration file <filename>opensrf.xml</filename> which\r
+                                                       you configured in a previous step.</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>If you receive an error message similar to\r
+                                                       <emphasis>osrf_ctl.sh: command not found</emphasis>, then your\r
+                                                       environment variable <envar>PATH</envar> does not include the\r
+                                                       directory <filename class="directory">/openils/bin</filename>.\r
+                                                       As the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       edit the configuration file <filename>~/.bashrc</filename> and\r
+                                                       add the following line: \r
+                                                       <literal>export PATH=$PATH:/openils/bin</literal></para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Test connections to OpenSRF</title>\r
+                                       <para>Once you have installed and started OpenSRF, as the \r
+                                       <systemitem class="username">root</systemitem> user, test your connection to \r
+                                       <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command> \r
+                                       utility and trying to call the <command>add</command> method on the OpenSRF \r
+                                       <systemitem class="service">math</systemitem> service:</para>\r
+                                       <screen>\r
+                                               <userinput>/openils/bin/srfsh</userinput>\r
+                                               <computeroutput>srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput> \r
+                                               <computeroutput>Received Data: 4</computeroutput>\r
+                                               <computeroutput>------------------------------------</computeroutput>\r
+                                               <computeroutput>Request Completed Successfully</computeroutput>\r
+                                               <computeroutput>Request Time in seconds: 0.007519</computeroutput>\r
+                                               <computeroutput>------------------------------------</computeroutput>\r
+                                       </screen>\r
+                                       <para>For other <command>srfsh</command> commands, type in\r
+                                       <userinput>help</userinput> at the prompt.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Stop OpenSRF</title>\r
+                                       <para>After OpenSRF has started, you can stop it at any time by using the\r
+                                       <command>osrf_ctl.sh</command> again. As the \r
+                                       <systemitem class="username">opensrf</systemitem> \r
+                                       user, stop OpenSRF as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>osrf_ctl.sh -l -a stop_all</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                       </procedure>\r
+               </section>\r
+               <section xml:id="serversideinstallation-ubuntudebian">\r
+                       <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or\r
+                               <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
+                       <para>This section outlines the installation process for the latest stable version of\r
+                       Evergreen.</para>\r
+                       <para>In this section you will download, unpack, install, configure and test the Evergreen\r
+                       system, including the Evergreen server and the PostgreSQL database system. You will make several\r
+                       configuration changes and adjustments to the software, including updates to configure the system\r
+                       for your own locale, and some updates needed to work around a few known issues.</para>\r
+                       <note>\r
+                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)\r
+                               architectures. There may be differences between the Desktop and Server editions of\r
+                               <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server\r
+                               edition.</para>\r
+                               <para>In the following instructions, you are asked to perform certain steps as \r
+                               either the <systemitem class="username">root</systemitem> user, the \r
+                               <systemitem class="username">opensrf</systemitem> user, or the \r
+                               <systemitem class="username">postgres</systemitem> user.</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Debian</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>sudo su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
+                               different user, issue the command <command>su - USERNAME</command>. For example, to\r
+                               switch from the <systemitem class="username">root</systemitem> user to the \r
+                               <systemitem class="username">opensrf</systemitem> user, issue the command \r
+                               <command>su - opensrf</command>. Once you have become a non-root user, to become the\r
+                               <systemitem class="username">root</systemitem> user again, simply issue the command\r
+                               <command>exit</command>.</para>\r
+                       </note>\r
+                       <procedure>\r
+                               <step>\r
+                                       <title>Install OpenSRF</title>\r
+                                       <para>Evergreen software is integrated with and depends on the Open Service\r
+                                       Request Framework (OpenSRF) software system. For further information on\r
+                                       installing, configuring and testing OpenSRF, see \r
+                                       <xref linkend="serversideinstallation-opensrf"/>.</para>\r
+                                       <para>Follow the steps outlined in that section and run the specified tests to\r
+                                       ensure that OpenSRF is properly installed and configured. Do \r
+                                       <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with\r
+                                       any further Evergreen installation steps until you have verified that OpenSRF\r
+                                       has been successfully installed and tested.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Download and Unpack Latest Evergreen Version</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, download\r
+                                       and extract the latest version of Evergreen. The latest version can be found here:\r
+                                       <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>\r
+                                       <screen>\r
+                                               <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
+                                               <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
+                                       </screen>\r
+                                       <para>The new directory\r
+                                       <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>\r
+                                       will be created.</para>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-installprereq">\r
+                                       <title>Install Prerequisites to Build Evergreen</title>\r
+                                       <para>In this section you will install and configure a set of prerequisites that\r
+                                       will be used to build Evergreen. In a following step you will actually build the\r
+                                       Evergreen software using the <command>make</command> utility.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
+                                       below to build the prerequisites from the software distribution that you just downloaded\r
+                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
+                                       example with the keyword corresponding to the name of one of the \r
+                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following distribution\r
+                                       keywords table <xref linkend="serversideinstallation-keywords-evergreen"/> . For example,\r
+                                       to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would enter this\r
+                                       command: <command>make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic</command>.</para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
+                                       <table xml:id="serversideinstallation-keywords-evergreen">\r
+                                               <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>\r
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
+                                                       <colspec colnum="1" colwidth="1.0*"/>\r
+                                                       <colspec colnum="2" colwidth="3.0*"/>\r
+                                                       <thead>\r
+                                                               <row>\r
+                                                                       <entry>Keyword</entry>\r
+                                                                       <entry>Linux Version</entry>\r
+                                                               </row>\r
+                                                       </thead>\r
+                                                       <tbody>\r
+                                                               <row>\r
+                                                                       <entry>debian-etch</entry>\r
+                                                                       <entry>Debian "Etch" (4.0)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>debian-lenny</entry>\r
+                                                                       <entry>Debian "Lenny" (5.0)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-hardy</entry>\r
+                                                                       <entry>Ubuntu "Hardy Heron" (8.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-intrepid</entry>\r
+                                                                       <entry>Ubuntu "Intrepid Ibex" (8.10)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-karmic</entry>\r
+                                                                       <entry>Ubuntu "Karmic Koala" (9.10)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-karmic</entry>\r
+                                                                       <entry>Ubuntu "Lucid Lynx" (10.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>centos</entry>\r
+                                                                       <entry>Centos</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>rhel</entry>\r
+                                                                       <entry>RHEL</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>gentoo</entry>\r
+                                                                       <entry>Gentoo</entry>\r
+                                                               </row>\r
+                                                       </tbody>\r
+                                               </tgroup>\r
+                                       </table>\r
+                               </step>\r
+                               <step performance="optional" xml:id="serversideinstallation-postgresql-default">\r
+                                       <title>(OPTIONAL) Install the PostgreSQL Server</title>\r
+                                       <indexterm>\r
+                                               <primary>databases</primary>\r
+                                               <secondary>PostgreSQL</secondary>\r
+                                       </indexterm>\r
+                                       <para>Since the PostgreSQL server is usually a standalone server in multi-server\r
+                                       production systems, the prerequisite installer Makefile in the previous section\r
+                                       (see <xref linkend="serversideinstallation-installprereq"/>)\r
+                                       does not automatically install PostgreSQL. You must install the PostgreSQL server\r
+                                       yourself, either on the same system as Evergreen itself or on another system.\r
+                                       If your PostgreSQL server is on a different system, just skip this step.</para>\r
+                                       <para>For further information on manually installing PostgreSQL, visit the official\r
+                                       <link xl:href="http://www.postgresql.org/">PostgreSQL Site</link>.</para>\r
+                                       <para>If your PostgreSQL server will be on the same system as your Evergreen\r
+                                       software, then as the <systemitem class="username">root</systemitem> user\r
+                                       install the required PostgreSQL server packages:</para>\r
+                                       <para>For <systemitem class="osname">Debian Lenny</systemitem> and \r
+                                       <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>\r
+                                       <screen>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>\r
+                                       </screen>\r
+                                       <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and\r
+                                       <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>\r
+                                       <screen>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>\r
+                                       </screen>\r
+                                       <note>\r
+                   &nb