updates to section 'Installing Evergreen 2.x On Fedora';
authorSteve Sheppard <ssheps@gmail.com>
Sun, 17 Apr 2011 17:47:57 +0000 (13:47 -0400)
committerSteve Sheppard <ssheps@gmail.com>
Sun, 17 Apr 2011 17:47:57 +0000 (13:47 -0400)
2.0/admin/serversideinstallation_2.0.xml

index 7b1b1bd..c768d91 100644 (file)
-<?xml version="1.0" encoding="UTF-8"?>\r
-<chapter version="5.0" xml:id="serversideinstallation" xml:lang="EN" 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>\r
-       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
-               <?dbfo keep-together="always" ?>\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>2.0</entry>\r
-                                       <entry>1.6.3</entry>\r
-                                       <entry>8.4</entry>\r
-                               </row>\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.6.3 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) architecture of\r
-                               <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,\r
-                               <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on\r
-                               <systemitem class="osname">Fedora 13</systemitem> and\r
-                               <systemitem class="osname">Fedora 14</systemitem>.</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 \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 New <systemitem class="username">opensrf</systemitem> User</title>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, add the\r
-                                       <systemitem class="username">opensrf</systemitem> user to the system.\r
-                                       In the following example, the default shell for the \r
-                                       <systemitem class="username">opensrf</systemitem> user is automatically set\r
-                                       to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       useradd -m -s /bin/bash opensrf\r
-       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>The latest version of OpenSRF can be found here:\r
-                                       <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz"></ulink> .\r
-                                       As the <systemitem class="username">opensrf</systemitem> user, change to\r
-                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
-                                       and extract OpenSRF. The new subdirectory\r
-                                       <filename class="directory">/home/opensrf/OpenSRF-1.6.3</filename> will be created:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       cd /home/opensrf\r
-       wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz\r
-       tar zxf OpenSRF-1.6.3.tar.gz</userinput>\r
-</screen>\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\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>\r
-       # as the root user:\r
-       cd /home/opensrf/OpenSRF-1.6.3\r
-       make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
-                                       <table xml:id="serversideinstallation-keywords-opensrf">\r
-                                               <?dbfo keep-together="always" ?>\r
-                                               <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>\r
-                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
-                                                       <colspec colname="keyword" colnum="1" colwidth="1.0*"/>\r
-                                                       <colspec colname="linux_version" 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-squeeze</entry>\r
-                                                                       <entry>Debian "Squeeze" (6.0)</entry>\r
-                                                               </row>\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>fedora13</entry>\r
-                                                                       <entry>Fedora "Laughlin" (14)</entry>\r
-                                                               </row>\r
-                                                               <row>\r
-                                                                       <entry>centos</entry>\r
-                                                                       <entry>CentOS 5</entry>\r
-                                                               </row>\r
-                                                               <row>\r
-                                                                       <entry>rhel</entry>\r
-                                                                       <entry>Red Hat Enterprise Linux 5</entry>\r
-                                                               </row>\r
-                                                               <row>\r
-                                                                       <entry>gentoo</entry>\r
-                                                                       <entry>Gentoo</entry>\r
-                                                               </row>\r
-                                                       </tbody>\r
-                                               </tgroup>\r
-                                       </table>\r
-                                       <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
-                                       <indexterm><primary>Linux</primary><secondary>Fedora</secondary></indexterm>\r
-                                       <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
-                                       <indexterm><primary>Linux</primary><secondary>CentOS</secondary></indexterm>\r
-                                       <indexterm><primary>Linux</primary><secondary>Red Hat</secondary></indexterm>\r
-                                       <indexterm><primary>Linux</primary><secondary>Gentoo</secondary></indexterm>\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 new 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>\r
-       # as the opensrf user:\r
-       cd /home/opensrf/OpenSRF-1.6.3\r
-       ./configure --prefix=/openils --sysconfdir=/openils/conf\r
-       make</userinput>\r
-</screen>\r
-                                                       <para>This step will take several minutes to complete.</para>\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 new OpenSRF build directory and use the\r
-                                                       <command>make</command> utility to compile, link and install\r
-                                                       OpenSRF:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /home/opensrf/OpenSRF-1.6.3\r
-       make install</userinput>\r
-</screen>\r
-                                                       <para>This step will take several minutes to complete.</para>\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 two\r
-                                                       new library paths, then execute the command\r
-                                                       <command>ldconfig</command> to automatically read the file and\r
-                                                       modify the system dynamic library path:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       echo "/openils/lib"   > /etc/ld.so.conf.d/osrf.conf\r
-       echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf\r
-       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>\r
-       # as the root user:\r
-       127.0.1.2  public.localhost   public\r
-       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>\r
-       # as the root user:\r
-       chown -R opensrf:opensrf /openils</userinput>\r
-</screen>\r
-                                               </step>\r
-                                       </substeps>\r
-                               </step>\r
-                               <step xml:id="stop-ejabberd-service">\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>\r
-       # as the root user:\r
-       /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>\r
-       # as the root user:\r
-       epmd -kill\r
-       killall beam; killall beam.smp\r
-       rm /var/lib/ejabberd/*\r
-       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
-                                       <substeps>\r
-                                               <step>\r
-                                                       <para>Change the line:</para>\r
-                                                       <literal>{hosts, ["localhost"]}.</literal>\r
-                                                       <para>to instead read:</para>\r
-                                                       <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>\r
-                                                       <para/>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <para>Change the line for older versions of <systemitem class="service">ejabberd</systemitem>:</para>\r
-                                                       <literal>{max_user_sessions, 10}</literal>\r
-                                                       <para>to instead read:</para>\r
-                                                       <literal>{max_user_sessions, 10000}</literal>\r
-                                                       <para/>\r
-                                                       <para>Change the line for newer versions of <systemitem class="service">ejabberd</systemitem>:</para>\r
-                                                       <literal>{access, max_user_sessions, [{10, all}]}</literal>\r
-                                                       <para>to instead read:</para>\r
-                                                       <literal>{access, max_user_sessions, [{10000, all}]}</literal>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <para>Change all three occurrences of:</para>\r
-                                                       <literal>max_stanza_size</literal>\r
-                                                       <para>to instead read:</para>\r
-                                                       <literal>2000000</literal>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <para>Change both occurrences of:</para>\r
-                                                       <literal>maxrate</literal>\r
-                                                       <para>to instead read:</para>\r
-                                                       <literal>500000</literal>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <para>Comment out the line:</para>\r
-                                                       <literal>{mod_offline, []}</literal>\r
-                                                       <para>by placing two <literal>%</literal> comment signs in front\r
-                                                       so it instead reads:</para>\r
-                                                       <literal>%%{mod_offline, []}</literal>\r
-                                               </step>\r
-                                       </substeps>\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>\r
-       # as the root user:\r
-       /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">opensrf</systemitem> as\r
-                                               <systemitem class="service">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 (remember to replace\r
-                                       <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       # Note: the syntax for registering a user with ejabberdctl is:\r
-       #    ejabberdctl register USER DOMAIN PASSWORD\r
-       ejabberdctl register router  private.localhost NEWPASSWORD\r
-       ejabberdctl register router  public.localhost  NEWPASSWORD\r
-       ejabberdctl register opensrf private.localhost NEWPASSWORD\r
-       ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>\r
-</screen>\r
-                                       <para>The users <systemitem class="username">router</systemitem> and\r
-                                       <systemitem class="username">opensrf</systemitem> and their respective passwords \r
-                                       will be used again in <xref linkend="serversideinstallation-passwords"/> when\r
-                                       we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para>\r
-                                       <note>\r
-                                               <para>\r
-                                               There appears to be a problem with <command>ejabberdctl</command> in\r
-                                               that it does not escape input correctly, so a password like\r
-                                               <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.\r
-                                               A bug against ejabberd has been filed. To register a password using\r
-                                               <command>ejabberdctl</command> with special shell characters until such\r
-                                               time as that bug is resolved, the workaround is to specify a\r
-                                               double-escaped character at the command line, for example,\r
-                                               <literal>'0P3N\\\\$RF'</literal> .</para>\r
-                                       </note>\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>\r
-       # as the opensrf user:\r
-       cd /openils/conf\r
-       cp opensrf.xml.example      opensrf.xml\r
-       cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step xml:id="serversideinstallation-passwords">\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
-                                               <?dbfo keep-together="always" ?>\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 the 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 verify that\r
-                                       the element <literal>dbfile</literal> (near the end of the file) is set to the \r
-                                       location of the persistent database. If necessary, change the default line:</para>\r
-                                       <literal>/openils/var/persist.db</literal>\r
-                                       <para>to instead read:</para>\r
-                                       <literal>/tmp/persist.db</literal>\r
-                                       <para>Following is a sample modification of that portion of the file:</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 the utility\r
-                                       <command>srfsh</command>, a command line diagnostic tool for testing and\r
-                                       interacting with <application>OpenSRF</application>. It will be used\r
-                                       in a future step to complete and test the Evergreen installation. See \r
-                                       <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, copy the\r
-                                       sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>\r
-                                       to the home directory of each user who will use <command>srfsh</command>. \r
-                                       For instance, do the following for the \r
-                                       <systemitem class="username">opensrf</systemitem> user:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cp /openils/conf/srfsh.xml.example  /home/opensrf/.srfsh.xml</userinput>\r
-</screen>\r
-                                       <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the\r
-                                       following changes:</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
-                                               <listitem>\r
-                                                       <para>Change the owner of the file to match the owner of the home directory</para>\r
-                                               </listitem>\r
-                                       </itemizedlist>\r
-                                       <para>Following is a sample of the file:</para>\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>\r
-       # as the opensrf user:\r
-       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>\r
-       # as the root user:\r
-       /etc/init.d/ejabberd start\r
-       /etc/init.d/memcached start</userinput>\r
-</screen>\r
-                                       <para>Then as the <systemitem class="username">opensrf</systemitem> user,\r
-                                       start OpenSRF as follows:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       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\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> with the <command>srfsh</command> \r
-                                       utility and try to call the <command>add</command> method on the OpenSRF \r
-                                       <systemitem class="service">math</systemitem> service:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       /openils/bin/srfsh</userinput>\r
-       <computeroutput>\r
-       srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>\r
-       <computeroutput>\r
-       Received Data: 4\r
-       ------------------------------------\r
-       Request Completed Successfully\r
-       Request Time in seconds: 0.007519\r
-       ------------------------------------</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>\r
-       # as the opensrf user:\r
-       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 2.0 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>The latest version of Evergreen can be found here:\r
-                                       <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .\r
-                                       As the <systemitem class="username">opensrf</systemitem> user, change to\r
-                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
-                                       and extract Evergreen. The new subdirectory\r
-                                       <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename> will be created:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       cd /home/opensrf\r
-       wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz\r
-       tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>\r
-</screen>\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 will be\r
-                                       used later in <xref linkend="serversideinstallation-configure"/> and \r
-                                       <xref linkend="serversideinstallation-compile"/> to build the Evergreen 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 list.\r
-                                       For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would\r
-                                       enter this command: <command>make -f Open-ILS/src/extras/Makefile.install\r
-                                       ubuntu-lucid</command>.</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /home/opensrf/Evergreen-ILS-2.0.4\r
-       make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
-                                       <itemizedlist>\r
-                                       \r
-                                       <listitem>\r
-                                               <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>\r
-                                       </listitem>\r
-                                       \r
-                                       <listitem>\r
-                                               <para><option>ubuntu-lucid</option> for  <systemitem class="osname">Ubuntu Lucid Lynx \r
-                                               (10.04)</systemitem></para>\r
-                                       </listitem>\r
-                               </itemizedlist>\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.\r
-                                       If your PostgreSQL server will be on the same system as your Evergreen\r
-                                       software, you can install the required PostgreSQL server packages as described\r
-                                       in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official \r
-                                       web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>\r
-                                       for more information.</para>\r
-                                       <note>\r
-                                               <para>PostgreSQL version 8.4 is the minimum supported version to work \r
-                                               with Evergreen 2.0. If you have an older version of PostgreSQL, \r
-                                               you should upgrade before installing Evergreen. To find your current version \r
-                                               of PostgreSQL, as the <systemitem class="username">postgres</systemitem> \r
-                                               user execute the command <command>psql</command>, then type \r
-                                               <userinput>SELECT version();</userinput> to get detailed information \r
-                                               about your version of PostgreSQL.</para>\r
-                                       </note>\r
-                               </step>\r
-                               <step performance="optional">\r
-                                       <title>Install Perl Modules on PostgreSQL Server</title>\r
-                                       <para>If PostgreSQL is running on the same system as your Evergreen software,\r
-                                       then the Perl modules will automatically be available. Just skip this step.\r
-                                       Otherwise, continue if your PostgreSQL server is running on another system.</para>\r
-                                       <para>You will need to install several Perl modules on the other system. As the\r
-                                       <systemitem class="username">root</systemitem> user install the following Perl\r
-                                       modules:</para>\r
-                                       <para>as the root user, ensure the gcc compiler is installed:</para>\r
-<screen>\r
-       <userinput>aptitude install gcc libxml-libxml-perl libxml-libxslt-perl</userinput>\r
-</screen>\r
-                                       <para>then install the Perl modules:</para>\r
-<screen>\r
-       <userinput>perl -MCPAN -e shell</userinput>\r
-       <prompt>cpan></prompt> <userinput>Business::ISBN</userinput>    \r
-       <prompt>cpan></prompt> <userinput>install JSON::XS</userinput>\r
-       <prompt>cpan></prompt> <userinput>Library::CallNumber::LC</userinput>\r
-       <prompt>cpan></prompt> <userinput>install MARC::Record</userinput>\r
-       <prompt>cpan></prompt> <userinput>install MARC::File::XML</userinput>\r
-       <prompt>cpan></prompt> <userinput>cpan UUID::Tiny</userinput>\r
-</screen>\r
-                                       <para>For more information on installing Perl Modules vist the official\r
-                                       <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>\r
-                                       <indexterm>\r
-                                               <primary>Perl</primary>\r
-                                               <secondary>CPAN</secondary>\r
-                                       </indexterm>\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 your system to recognize\r
-                                       the newly installed libraries. As the <systemitem class="username">root</systemitem> user,\r
-                                       do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>\r
-                                       containing a new library path, then run the command <command>ldconfig</command> to\r
-                                       automatically read the file and modify the system dynamic library path:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       echo "/usr/local/lib"     >> /etc/ld.so.conf.d/osrf.conf\r
-       echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf\r
-       ldconfig</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step performance="optional">\r
-                                       <title>Restart the PostgreSQL Server</title>\r
-                                       <para>If PostgreSQL is running on the same system as the rest of Evergreen, as\r
-                                       the <systemitem class="username">root</systemitem> user you must restart\r
-                                       PostgreSQL to re-read the new library paths just configured. If PostgreSQL is\r
-                                       running on another system, you may skip this step.\r
-                                       As the <systemitem class="username">opensrf</systemitem> user,\r
-                                       execute the following command (remember to replace\r
-                                       <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,\r
-                                       for example <literal>8.4</literal>):</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step xml:id="serversideinstallation-configure">\r
-                                       <title>Configure Evergreen</title>\r
-                                       <para>In this step you will use the <command>configure</command> and\r
-                                       <command>make</command> utilities to configure Evergreen so it can be compiled\r
-                                       and linked later in <xref linkend="serversideinstallation-compile"/>.</para>\r
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, return to\r
-                                       the Evergreen build directory and execute these commands:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       cd /home/opensrf/Evergreen-ILS-2.0.4\r
-       ./configure --prefix=/openils --sysconfdir=/openils/conf\r
-       make</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step xml:id="serversideinstallation-compile">\r
-                                       <title>Compile, Link and Install Evergreen</title>\r
-                                       <para>In this step you will actually compile, link and install Evergreen and the \r
-                                       default Evergreen Staff Client.</para>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, return to the\r
-                                       Evergreen build directory and use the <command>make</command> utility as shown below:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /home/opensrf/Evergreen-ILS-2.0.4\r
-       make STAFF_CLIENT_BUILD_ID=rel_2_0_4 install</userinput>\r
-</screen>\r
-                                       <para>The Staff Client will also be automatically built, but you must remember\r
-                                       to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the \r
-                                       Staff Client you will use to connect to the Evergreen server.</para>\r
-                                       <para>The above commands will create a new subdirectory\r
-                                       <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename> \r
-                                       containing the Staff Client.</para>\r
-                                       <para>To complete the Staff Client installation, as the\r
-                                       <systemitem class="username">root</systemitem> user execute the following commands to\r
-                                       create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client\r
-                                       directory <filename class="directory">/openils/var/web/xul</filename> that points to the\r
-                                       subdirectory <filename class="directory">/server</filename> of the new Staff Client\r
-                                       build:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /openils/var/web/xul\r
-       ln -sf rel_2_0_4/server server</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step>\r
-                                       <title>Copy the OpenSRF Configuration Files</title>\r
-                                       <para>In this step you will replace some OpenSRF configuration files that you set up in\r
-                                       <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and\r
-                                       tested OpenSRF.</para>\r
-                                       <para>You must copy several example OpenSRF configuration files into place after first\r
-                                       creating backup copies for troubleshooting purposes, then change all the file ownerships\r
-                                       to <systemitem class="username">opensrf</systemitem>.\r
-                                       As the <systemitem class="username">root</systemitem> user, execute the following\r
-                                       commands:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /openils/conf\r
-       cp opensrf.xml        opensrf.xml.BAK\r
-       cp opensrf_core.xml      opensrf_core.xml.BAK\r
-       cp opensrf.xml.example      opensrf.xml\r
-       cp opensrf_core.xml.example opensrf_core.xml\r
-       cp oils_web.xml.example     oils_web.xml\r
-       chown -R opensrf:opensrf /openils/</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step>\r
-                                       <title>Create and Configure PostgreSQL Database</title>\r
-                                       <indexterm>\r
-                                               <primary>databases</primary>\r
-                                               <secondary>PostgreSQL</secondary>\r
-                                       </indexterm>\r
-                                       <para>In this step you will create the Evergreen database. In the commands\r
-                                       below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>\r
-                                       repository to match your PostgreSQL server\r
-                                       layout. For example, if you built PostgreSQL from source the path would be\r
-                                       <filename class="directory">/usr/local/share/contrib</filename> , and if you\r
-                                       installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,\r
-                                       the path would be \r
-                                       <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>\r
-                                       <substeps>\r
-                                               <step>\r
-                                                       <para>\r
-                                                               <emphasis role="bold">Create and configure the database</emphasis>\r
-                                                       </para>\r
-                                                       <para>As the <systemitem class="username">postgres</systemitem>\r
-                                                       user on the PostgreSQL system create the PostgreSQL database,\r
-                                                       then set some internal paths:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the postgres user:\r
-       createdb evergreen -E UTF8 -T template0\r
-       createlang plperl   evergreen\r
-       createlang plperlu  evergreen\r
-       createlang plpgsql  evergreen</userinput>\r
-</screen>\r
-                                                       <para>Continue as the <systemitem class="username">postgres</systemitem> user\r
-                                                       and execute the SQL scripts as shown below (remember to adjust the paths as needed,\r
-                                                       where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL\r
-                                                       version, for example <literal>8.4</literal>).</para>\r
-<screen>\r
-       <userinput>\r
-       # as the postgres user:\r
-       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen\r
-       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen\r
-       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>\r
-</screen>\r
-                                               </step>\r
-                                               <step xml:id="serversideinstallation-postgresqlcreateuser">\r
-                                                       <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>\r
-                                                       <para>As the <systemitem class="username">postgres</systemitem>\r
-                                                       user on the PostgreSQL system, create a new PostgreSQL user\r
-                                                       named <systemitem class="username">evergreen</systemitem> and\r
-                                                       assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>\r
-                                                       with an appropriate new password):</para>\r
-<screen>\r
-       <userinput>\r
-       # as the postgres user:\r
-       createuser -P -s evergreen</userinput>\r
-       <computeroutput>\r
-       Enter password for new role: <userinput>NEWPASSWORD</userinput>\r
-       Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>\r
-</screen>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <title>Create database schema</title>\r
-                                                       <para>In this step you will create the database schema and configure your\r
-                                                       system with the corresponding database authentication details for the\r
-                                                       <emphasis>evergreen</emphasis> database user that you just created in\r
-                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>\r
-                                                       <para>As the <systemitem class="username">root</systemitem> user, enter\r
-                                                       the following commands and replace <emphasis>HOSTNAME, PORT,\r
-                                                       PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate\r
-                                                       values:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-2.0.4\r
-perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
---service all --create-schema --create-offline \\r
---hostname HOSTNAME --port PORT \\r
---user evergreen --password PASSWORD \\r
---database DATABASENAME --admin-user ADMIN-USER \ \r
---admin-pass ADMIN-PASSWORD </userinput>\r
-</screen>\r
-                                                       <para>On most systems, <emphasis>HOSTNAME</emphasis> will be\r
-                                                       <emphasis role="bold">localhost</emphasis> and\r
-                                                       <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.\r
-                                                       Of course, values for <emphasis>PASSWORD</emphasis> and\r
-                                                       <emphasis>DATABASENAME</emphasis> must match the values you used in \r
-                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>. The <option>admin-user</option> and <option>admin-pass</option> options will \r
-                                                       specify the Evergreen administrator account's username and password. This was \r
-                                                       changed for security reasons, it was previously admin/open-ils</para>\r
-                                                       <para>As the command executes, you may see warnings similar to:\r
-                                                       <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,\r
-                                                       you may see one warning per schema) but they can be safely ignored.</para>\r
-                                                       <note>If you are entering the above command on a single line, do not\r
-                                                       include the <literal>\</literal> (backslash) characters. If you are using\r
-                                                       the <command>bash</command> shell, these should only be used at the end of\r
-                                                       a line at a <command>bash</command> prompt to indicate that the command is\r
-                                                       continued on the next line.</note>\r
-                                               </step>\r
-                                       </substeps>\r
-                               </step>\r
-                               <step>\r
-                                       <title>Configure the Apache web server</title>\r
-                                       <indexterm>\r
-                                               <primary>web server</primary>\r
-                                               <secondary>Apache</secondary>\r
-                                       </indexterm>\r
-                                       <para>In this step you will configure the Apache web server to support Evergreen\r
-                                       software.</para>\r
-                                       <para>First, you must enable some built-in Apache modules and install some\r
-                                       additional Apache configuration files. Then you will create a new Security\r
-                                       Certificate. Finally, you must make several changes to the Apache configuration\r
-                                       file.</para>\r
-                                       <substeps>\r
-                                               <step>\r
-                                                       <title>Enable the required Apache Modules</title>\r
-                                                       <para>As the <systemitem class="username">root</systemitem>\r
-                                                       user, enable some modules in the Apache server, then copy the\r
-                                                       new configuration files to the Apache server directories:</para>\r
-                                                       <indexterm>\r
-                                                               <primary>Apache modules</primary>\r
-                                                       </indexterm>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       a2enmod ssl     # enable mod_ssl\r
-       a2enmod rewrite # enable mod_rewrite\r
-       a2enmod expires # enable mod_expires</userinput>\r
-</screen>\r
-                                                       <para>As the commands execute, you may see warnings similar to:\r
-                                                       <literal>Module SOMEMODULE already enabled</literal> but you can\r
-                                                       safely ignore them.</para>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <title>Copy Apache configuration files</title>\r
-                                                       <para>You must copy the Apache configuration files from the\r
-                                                       Evergreen installation directory to the Apache directory. As the\r
-                                                       <systemitem class="username">root</systemitem> user, perform the\r
-                                                       following commands:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       cd /home/opensrf/Evergreen-ILS-2.0.4\r
-       cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/\r
-       cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/\r
-       cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>\r
-</screen>\r
-                                               </step>\r
-                                               <step xml:id="serversideinstallation-createsslcertificate">\r
-                                                       <title>Create a Security Certificate</title>\r
-                                                       <para>In this step you will create a new Security Certificate (SSL Key)\r
-                                                       for the Apache server using the <command>openssl</command> command. For a\r
-                                                       public production server you must configure or purchase a signed SSL\r
-                                                       certificate, but for now you can just use a self-signed certificate and\r
-                                                       accept the warnings in the Staff Client and browser during testing and\r
-                                                       development. As the <systemitem class="username">root</systemitem> user,\r
-                                                       perform the following commands:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       mkdir /etc/apache2/ssl\r
-       cd /etc/apache2/ssl\r
-       openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>\r
-</screen>\r
-                                                       <para>You will be prompted for several items of information; enter\r
-                                                       the appropriate information for each item. The new files\r
-                                                       <filename>server.crt</filename> and <filename>server.key</filename> will\r
-                                                       be created in the directory \r
-                                                       <filename class="directory">/etc/apache2/ssl</filename> .</para>\r
-                                                       <note>This step generates a self-signed SSL certificate. You must install\r
-                                                       a proper SSL certificate for a public production system to avoid warning\r
-                                                       messages when users login to their account through the OPAC or when staff\r
-                                                       login through the Staff Client. For further information on\r
-                                                       installing a proper SSL certificate, see \r
-                                                       <xref linkend="serversideinstallation-ssl"/>.</note>\r
-                                               </step>\r
-                                               <step xml:id="serversideinstallation-modify-apache">\r
-                                                       <title>Update Apache configuration file</title>\r
-                                                       <para>You must make several changes to the new Apache\r
-                                                       configuration file\r
-                                                       <filename>/etc/apache2/sites-available/eg.conf</filename> . \r
-                                                       As the <systemitem class="username">root</systemitem> user,\r
-                                                       edit the file and make the following changes:</para>\r
-                                                       <itemizedlist>\r
-                                                               <listitem>\r
-                                                                       <para>In the section\r
-                                                                       <literal>&lt;Directory "/openils/var/cgi-bin"></literal>\r
-                                                                       replace the line:</para>\r
-                                                                       <literal>Allow from 10.0.0.0/8</literal>\r
-                                                                       <para>with the line:</para>\r
-                                                                       <literal>Allow from all</literal>\r
-                                                                       <warning>This change allows access to your configuration\r
-                                                                       CGI scripts from any workstation on any network. This is\r
-                                                                       only a temporary change to expedite testing and should be\r
-                                                                       removed after you have finished and successfully tested\r
-                                                                       the Evergreen installation. See \r
-                                                                       <xref linkend="serversideinstallation-postinstallation"/> \r
-                                                                       for further details on removing this change after the\r
-                                                                       Evergreen installation is complete.\r
-                                                                       </warning>\r
-                                                               </listitem>\r
-                                                               <listitem>\r
-                                                                       <para>Comment out the line:</para>\r
-                                                                       <literal>Listen 443</literal>\r
-                                                                       <para>since it conflicts with the same declaration in \r
-                                                                       the configuration file:</para>\r
-                                                                       <para><filename>/etc/apache2/ports.conf</filename>.</para>\r
-                                                               </listitem>\r
-                                                               <listitem>\r
-                                                                       <para>The following updates are needed to allow the logs\r
-                                                                       to function properly, but it may break other Apache\r
-                                                                       applications on your server:</para>\r
-                                                                       \r
-                                                                       <para>Edit the Apache configuration file and change the lines:</para>\r
-<screen>\r
-<userinput>export APACHE_RUN_USER=www-data</userinput>\r
-<userinput>export APACHE_RUN_GROUP=www-data</userinput>\r
-</screen>\r
-                                                                       <para>to instead read:</para>\r
-<screen>\r
-       <userinput>\r
-       export APACHE_RUN_USER=opensrf\r
-       export APACHE_RUN_GROUP=opensrf</userinput>\r
-</screen>\r
-                                                               </listitem>\r
-                                                               <listitem>\r
-                                                                       <para>As the \r
-                                                                       <systemitem class="username">root</systemitem> user,\r
-                                                                       edit the Apache configuration file\r
-                                                                       <filename>/etc/apache2/apache2.conf</filename> and\r
-                                                                       modify the value for <literal>KeepAliveTimeout</literal>\r
-                                                                       and <literal>MaxKeepAliveRequests</literal> to match\r
-                                                                       the following:</para>\r
-<screen>\r
-       <userinput>\r
-       KeepAliveTimeout       1\r
-       MaxKeepAliveRequests 100</userinput>\r
-</screen>\r
-                                                               </listitem>\r
-                                                               <listitem>\r
-                                                                       <para>Further configuration changes to Apache may be\r
-                                                                       necessary for busy systems. These changes increase the\r
-                                                                       number of Apache server processes that are started to\r
-                                                                       support additional browser connections.</para>\r
-                                                                       <para>As the \r
-                                                                       <systemitem class="username">root</systemitem> user, \r
-                                                                       edit the Apache configuration file\r
-                                                                       <filename>/etc/apache2/apache2.conf</filename>, locate \r
-                                                                       and modify the section related to <emphasis>prefork\r
-                                                                       configuration</emphasis> to suit the load on your\r
-                                                                       system:</para>\r
-                                                                       <programlisting language="xml"><![CDATA[\r
-<IfModule mpm_prefork_module>\r
-   StartServers           20\r
-   MinSpareServers      5\r
-   MaxSpareServers     15\r
-   MaxClients      150\r
-   MaxRequestsPerChild 10000\r
-</IfModule>\r
-]]></programlisting>\r
-                                                               </listitem>\r
-                                                       </itemizedlist>\r
-                                               </step>\r
-                                               <step>\r
-                                                       <title>Enable the Evergreen web site</title>\r
-                                                       <para>Finally, you must enable the Evergreen web site. As the\r
-                                                       <systemitem class="username">root</systemitem> user, execute the\r
-                                                       following Apache configuration commands to disable the default\r
-                                                       <emphasis>It Works</emphasis> web page and enable the Evergreen\r
-                                                       web site, and then restart the Apache server:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       # disable/enable web sites\r
-       a2dissite default\r
-       a2ensite eg.conf\r
-       # restart the server\r
-       /etc/init.d/apache2 reload</userinput>\r
-</screen>\r
-                                               </step>\r
-                                       </substeps>\r
-                               </step>\r
-                               <step xml:id="serversideinstallation-opensrf-config">\r
-                                       <title>Update 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
-                                       to update the Jabber usernames and passwords, and to specify the domain from\r
-                                       which we will accept and to which we will make connections.</para>\r
-                                       <para>If you are installing Evergreen on a single server and using the\r
-                                       <systemitem class="domainname">private.localhost</systemitem> / \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 your customized values.</para>\r
-                                       <para>The left-hand side of  <xref linkend="serversideinstallation-xpath-table-2"/>\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-2">\r
-                                               <?dbfo keep-together="always" ?>\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
-                               </step>\r
-                               <step performance="optional">\r
-                                       <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>\r
-                                       <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the\r
-                                       software installation automatically created a utility named <command>srfsh</command> (surf\r
-                                       shell). This is a command line diagnostic tool for testing and interacting with\r
-                                       OpenSRF. It will be used in a future step to complete and test the Evergreen installation.\r
-                                       Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration \r
-                                       file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.\r
-                                       See <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
-                               </step>\r
-                               <step xml:id="serversideinstallation-opensrf-env">\r
-                                       <title>Modify the OpenSRF Environment</title>\r
-                                       <para>In this step you will make some minor modifications to the OpenSRF environment:</para>\r
-                                       <itemizedlist>\r
-                                               <listitem>\r
-                                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
-                                                       modify the shell configuration file <filename>~/.bashrc</filename> for\r
-                                                       user <systemitem class="username">opensrf</systemitem> by adding a Perl\r
-                                                       environmental variable, then execute the shell configuration file to load\r
-                                                       the new variables into your current environment.</para>\r
-                                                       <note>In a multi-server environment, you must add any\r
-                                                       modifications to <filename>~/.bashrc</filename> to the top of the file\r
-                                                       <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &amp;&amp;\r
-                                                       return </literal>. This will allow headless (scripted) logins to load the\r
-                                                       correct environment.</note>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc\r
-       . ~/.bashrc</userinput>\r
-</screen>\r
-                                               </listitem>\r
-                                       </itemizedlist>\r
-                               </step>\r
-                               <step performance="optional">\r
-                                       <title>(OPTIONAL) Enable and Disable Language Localizations</title>\r
-                                       <para>You can load translations such as Armenian (hy-AM), Canadian French\r
-                                       (fr-CA), and others into the database to complete the translations available in\r
-                                       the OPAC and Staff Client. For further information, see\r
-                                       <xref linkend="languagesandlocalization"/>.</para>\r
-                               </step>\r
-                       </procedure>\r
-               </section>\r
-               <section xml:id="serversideinstallation-fedora">\r
-                       <title>Installing Evergreen 2.x On <systemitem class="osname">Fedora 13</systemitem> or\r
-                               <systemitem class="osname">Fedora 14</systemitem> </title>\r
-               </section>\r
-               <section xml:id="serversideinstallation-starting">\r
-                       <title>Starting Evergreen</title>\r
-                       <para>In this section you will learn how to start the Evergreen services. \r
-                       For completeness, instructions for stopping Evergreen can be found later in \r
-                       <xref linkend="serversideinstallation-stopping"/>.</para>\r
-                       <procedure>\r
-                               <step>\r
-                                       <para>As the <systemitem class="username">root</systemitem>\r
-                                       user, start the <systemitem class="service">ejabberd</systemitem> and \r
-                                       <systemitem class="service">memcached</systemitem> services as follows:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       /etc/init.d/ejabberd start\r
-       /etc/init.d/memcached start</userinput>\r
-</screen>\r
-                               </step>\r
-                               <step>\r
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
-                                       start the OpenSRF router service as follows:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       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 \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
-                                               <listitem>\r
-                                                       <para>If you receive an error message similar to <emphasis>Can't\r
-                                                       locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation\r
-                                                       aborted</emphasis>, then your environment variable \r
-                                                       <emphasis role="bold">PERL5LIB</emphasis> does not include the \r
-                                                       directory <filename class="directory">/openils/lib/perl5</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 PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>\r
-                                               </listitem>\r
-                                       </itemizedlist>\r
-                               </step>\r
-                               <step>\r
-                                       <para>In this step you will generate the Web files needed by the Staff Client\r
-                                       and catalog, and update the proximity of locations in the Organizational Unit\r
-                                       tree (which allows <emphasis>Holds</emphasis> to work properly).</para>\r
-                                       <para>You must do this the first time you start Evergreen and after making any\r
-                                       changes to the library hierarchy.</para>\r
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, execute the\r
-                                       following command and review the results:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       cd /openils/bin\r
-       ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
-       <computeroutput>\r
-       Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'\r
-       Updating fieldmapper\r
-       Updating web_fieldmapper\r
-       Updating OrgTree\r
-       removing OrgTree from the cache for locale hy-AM...\r
-       removing OrgTree from the cache for locale cs-CZ...\r
-       removing OrgTree from the cache for locale en-CA...\r
-       removing OrgTree from the cache for locale en-US...\r
-       removing OrgTree from the cache for locale fr-CA...\r
-       removing OrgTree from the cache for locale ru-RU...\r
-       Updating OrgTree HTML\r
-       Updating locales selection HTML\r
-       Updating Search Groups\r
-       Refreshing proximity of org units\r
-       Successfully updated the organization proximity\r
-       Done</computeroutput>\r
-</screen>\r
-                               </step>\r
-                               <step>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, restart the\r
-                                       Apache Web server:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       /etc/init.d/apache2 restart</userinput>\r
-</screen>\r
-                                       <note>If the Apache Web server was running when you started the OpenSRF\r
-                                       services, you might not be able to successfully log into the OPAC or Staff\r
-                                       Client until the Apache Web server has been restarted.</note>\r
-                               </step>\r
-                       </procedure>\r
-               </section>\r
-               <section xml:id="serversideinstallation-testing">\r
-                       <title>Testing Your Evergreen Installation</title>\r
-                       <para>This section describes several simple tests you can perform to verify that the Evergreen\r
-                       server-side software has been installed and configured properly and is running as\r
-                       expected.</para>\r
-                       <simplesect xml:id="serversideinstallation-testing-connections">\r
-                               <title>Testing Connections to Evergreen</title>\r
-                               <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the\r
-                               <command>srfsh</command> application and try logging onto the Evergreen server using the default\r
-                               administrator username and password. Following is sample output generated by executing\r
-                               <command>srfsh</command> after a successful Evergreen installation. For help with\r
-                               <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.\r
-                               As the <systemitem class="username">opensrf</systemitem> user,\r
-                               execute the following commands to test your Evergreen connection:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       /openils/bin/srfsh</userinput>\r
-       <computeroutput>\r
-       srfsh% <userinput>login admin open-ils</userinput>\r
-       Received Data: "250bf1518c7527a03249858687714376"\r
-       ------------------------------------\r
-       Request Completed Successfully\r
-       Request Time in seconds: 0.045286\r
-       ------------------------------------\r
-       Received Data: {\r
-          "ilsevent":0,\r
-          "textcode":"SUCCESS",\r
-          "desc":" ",\r
-          "pid":21616,\r
-          "stacktrace":"oils_auth.c:304",\r
-          "payload":{\r
-             "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",\r
-             "authtime":420\r
-          }\r
-       }\r
-       ------------------------------------\r
-       Request Completed Successfully\r
-       Request Time in seconds: 1.336568\r
-       ------------------------------------</computeroutput>\r
-</screen>\r
-                               <para>If this does not work, try the following:</para>\r
-                               <itemizedlist>\r
-                                       <listitem>\r
-                                               <para>As the <systemitem class="username">opensrf</systemitem> user, run the\r
-                                               <filename>settings-tester.pl</filename> utility to review your Evergreen\r
-                                               installation for any system configuration problems:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user:\r
-       cd /home/opensrf\r
-       ./Evergreen-ILS-2.0.4/Open-ILS/src/support-scripts/settings-tester.pl</userinput>\r
-</screen>\r
-                                               <para>If the output of <command>settings-tester.pl</command> does not help you\r
-                                               find the problem, please do not make any significant changes to your\r
-                                               configuration.</para>\r
-                                       </listitem>\r
-                                       <listitem>\r
-                                               <para>Follow the steps in the troubleshooting guide in \r
-                                               <xref linkend="troubleshooting"/>.</para>\r
-                                       </listitem>\r
-                                       <listitem>\r
-                                               <para>If you have followed the entire set of installation steps listed here\r
-                                               closely, you are probably extremely close to a working system. Gather your\r
-                                               configuration files and log files and contact the \r
-                                               <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>\r
-                                               list for assistance before making any drastic changes to your system\r
-                                               configuration.</para>\r
-                                       </listitem>\r
-                               </itemizedlist>\r
-                       </simplesect>\r
-                       <simplesect xml:id="serversideinstallation-running-staffclient">\r
-                               <title>Testing the Staff Client on Linux</title>\r
-                               <para>In this section you will confirm that a basic login on the Staff Client works\r
-                               properly.</para>\r
-                               <para>Run the Evergreen Staff Client on a Linux system by using the application\r
-                               <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox\r
-                               version 3.0 and later on Ubuntu and Debian distributions).</para>\r
-                               <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client\r
-                               as shown:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       xulrunner /home/opensrf/Evergreen-ILS-v/Open-ILS/xul/staff_client/build/application.ini</userinput>\r
-</screen>\r
-                               <para>A login screen for the Staff Client similar to this should appear:</para>\r
-                               <mediaobject>\r
-                                       <alt>Logging into the Staff Client</alt>\r
-                                       <imageobject>\r
-                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>\r
-                                       </imageobject>\r
-                               </mediaobject>\r
-                               <para>First, add the name of your Evergreen server to the field\r
-                               <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably\r
-                               want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test\r
-                               Server. You should now see the messages <literal>200:OK</literal> in the fields\r
-                               <literal>Status</literal> and <literal>Version</literal>.</para>\r
-                               <para>Because this is the initial run of the Staff Client, you will see a warning in the\r
-                               upper-right saying: <emphasis role="bold">Not yet configured for the specified\r
-                               server</emphasis>. To continue, you must assign a workstation name.</para>\r
-                               <para>Try to log into the Staff Client with the admin username and password you created during installation. If the login is successful, \r
-                               you will see the following screen:</para>\r
-                               <mediaobject>\r
-                                       <alt>Logging into the Staff Client</alt>\r
-                                       <imageobject>\r
-                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>\r
-                                       </imageobject>\r
-                               </mediaobject>\r
-                               <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the\r
-                               main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>\r
-                               <mediaobject>\r
-                                       <alt>Adding an SSL Exception in the Staff Client</alt>\r
-                                       <imageobject>\r
-                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>\r
-                                       </imageobject>\r
-                               </mediaobject>\r
-                               <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm\r
-                               Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the\r
-                               main window and try to log in again.</para>\r
-                       </simplesect>\r
-                       <simplesect xml:id="serversideinstallation-starting-apache-server">\r
-                               <title>Testing the Apache Web Server</title>\r
-                               <para>In this section you will test the Apache configuration file(s), then restart the\r
-                               Apache web server.</para>\r
-                               <para>As the <emphasis role="bold">root</emphasis> user, execute the following\r
-                               commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen\r
-                               modules to be reloaded even if the Apache server is already running. Any problems found\r
-                               with your configuration files should be displayed:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the root user:\r
-       apache2ctl configtest &amp;&amp; /etc/init.d/apache2 restart</userinput>\r
-</screen>\r
-                       </simplesect>\r
-                       <simplesect xml:id="serversideinstallation-stopping">\r
-                               <title>Stopping Evergreen</title>\r
-                               <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the\r
-                               Evergreen services. For completeness, following are instructions for stopping the\r
-                               Evergreen services.</para>\r
-                               <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen\r
-                               services by using the following command:</para>\r
-<screen>\r
-       <userinput>\r
-       # as the opensrf user\r
-       #   stop the server; use "-l" to force hostname to be "localhost"\r
-       osrf_ctl.sh -l -a stop_all</userinput>\r
-</screen>\r
-                               <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the\r
-                               <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the\r
-                               fully qualified domain name for the system on which it will execute. That hostname may\r
-                               have been specified in the configuration file <filename>opensrf.xml</filename>, which\r
-                               you configured in a previous step.</note>\r
-                       </simplesect>\r
-               </section>\r
-               <section xml:id="serversideinstallation-postinstallation">\r
-                       <title>Post-Installation Chores</title>\r
-                       <para>There are several additional steps you may need to complete after Evergreen has been\r
-                       successfully installed and tested. Some steps may not be needed (e.g., setting up support for\r
-                       Reports).</para>\r
-                       <section>\r
-                               <title>Remove temporary Apache configuration changes</title>\r
-                               <para>You modified the Apache configuration file\r
-                               <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a\r
-                               temporary measure to expedite testing (see \r
-                               <xref linkend="serversideinstallation-modify-apache"/> for further information).\r
-                               Those changes must now be reversed in order to deny unwanted access to your \r
-                               CGI scripts from users on other public networks.</para>\r
-                               <warning>\r
-                                       <para>\r
-                                               <emphasis>This temporary network update was done to expedite\r
-                                               testing. You <emphasis role="bold">must</emphasis> correct\r
-                                               this for a public production system.</emphasis>\r
-                                       </para>\r
-                               </warning>\r
-                               <para>As the <systemitem class="username">root</systemitem> user, edit the configuration\r
-                               file again and comment out the line <literal>Allow from all</literal> and uncomment the\r
-                               line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network\r
-                               address scheme.</para>\r
-                       </section>\r
-                       <section xml:id="serversideinstallation-ssl">\r
-                               <title>Configure a permanent SSL key</title>\r
-                               <para>You used the command <command>openssl</command> in an earlier step to\r
-                               temporarily create a new SSL key for the Apache server (see \r
-                               <xref linkend="serversideinstallation-createsslcertificate"/> for further\r
-                               information). This self-signed security certificate was adequate during\r
-                               testing and development, but will continue to generate warnings in the Staff\r
-                               Client and browser. For a public production server you should configure or\r
-                               purchase a signed SSL certificate.</para>\r
-                               <para>There are several open source software solutions that provide schemes to\r
-                               generate and maintain public key security certificates for your library\r
-                               system. Some popular projects are listed below; please review them for\r
-                               background information on why you need such a system and how you can provide\r
-                               it:</para>\r
-                               <itemizedlist>\r
-                                       <listitem>\r
-                                               <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>\r
-                                       </listitem>\r
-                                       <listitem>\r
-                                               <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>\r
-                                       </listitem>\r
-                                       <listitem>\r
-                                               <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>\r
-                                       </listitem>\r
-                               </itemizedlist>\r
-                               <warning>\r
-                                       <para>\r
-                                               <emphasis>The temporary SSL key was only created to expedite\r
-                                               testing. You should install a proper SSL certificate for a public\r
-                                               production system.</emphasis>\r
-                                       </para>\r
-                               </warning>\r
-                       </section>\r
-                       <section>\r
-                               <title>(OPTIONAL) IP-Redirection</title>\r
-                               <para>By default, Evergreen is configured so searching the OPAC always starts in the\r
-                               top-level (regional) library rather than in a second-level (branch) library. Instead,\r
-                               you can use "IP-Redirection" to change the default OPAC search location to use the IP\r
-                               address range assigned to the second-level library where the seach originates. You must\r
-                               configure these IP ranges by creating the configuration file\r
-                               <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script\r
-                               <filename>/etc/apache2/startup.pl</filename>.</para>\r
-                               <para>First, copy the sample file\r
-                               <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>\r
-                               to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single\r
-                               line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use\r
-                               the IP address ranges for your library system. Add new lines to represent the IP address\r
-                               range for each branch library. Replace the values for <literal>MY-LIB</literal> with the\r
-                               values for each branch library found in the table\r
-                               <literal>actor.org_unit</literal>.</para>\r
-                               <para>Finally, modify the Apache startup script\r
-                               <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then\r
-                               restarting the Apache server:</para>\r
-                               <programlisting language="xml"><![CDATA[\r
-# - Uncomment the following 2 lines to make use of the IP redirection code\r
-# - The IP file should contain a map with the following format:\r
-# - actor.org_unit.shortname <start_ip> <end_ip>\r
-# - e.g.  LIB123 10.0.0.1 10.0.0.254\r
-use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);\r
-OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');\r
-]]></programlisting>\r
-                       </section>\r
-                       <section>\r
-                               <title>(OPTIONAL) Set Up Support For Reports</title>\r
-                               <para>Evergreen reports are extremely powerful but require some simple configuration.\r
-                               See <xref linkend="report_starting_reporter_service"/> for information on starting and\r
-                               stopping the Reporter daemon processes.</para>\r
-                       </section>\r
-               </section>\r
-       </section>\r
-</chapter>\r
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="serversideinstallation" xml:lang="EN" 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>
+       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">
+               <?dbfo keep-together="always" ?>
+               <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>2.0</entry>
+                                       <entry>1.6.3</entry>
+                                       <entry>8.4</entry>
+                               </row>
+                               <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-1.6.3">
+                       <indexterm>
+                               <primary>OpenSRF</primary>
+                               <secondary>installation</secondary>
+                       </indexterm>
+                       <title>Installing OpenSRF 1.6.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) architecture of
+                               <systemitem class="osname">Debian Squeeze (6.0)</systemitem>,
+                               <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, and on
+                               <systemitem class="osname">Fedora 13</systemitem> and
+                               <systemitem class="osname">Fedora 14</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 New <systemitem class="username">opensrf</systemitem> User</title>
+                                       <para>As the <systemitem class="username">root</systemitem> user, add the
+                                       <systemitem class="username">opensrf</systemitem> user to the system.
+                                       In the following example, the default shell for the 
+                                       <systemitem class="username">opensrf</systemitem> user is automatically set
+                                       to <command>/bin/bash</command> to inherit a reasonable environment:</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       useradd -m -s /bin/bash opensrf
+       passwd opensrf</userinput>
+                                       </screen>
+                               </step>
+                               <step>
+                                       <title>Download and Unpack Latest OpenSRF Version</title>
+                                       <indexterm>
+                                               <primary>OpenSRF</primary>
+                                               <secondary>download</secondary>
+                                       </indexterm>
+                                       <para>The latest version of OpenSRF can be found here:
+                                       <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz"></ulink> .
+                                       As the <systemitem class="username">opensrf</systemitem> user, change to
+                                       the directory <filename class="directory">/home/opensrf</filename> then download
+                                       and extract OpenSRF. The new subdirectory
+                                       <filename class="directory">/home/opensrf/OpenSRF-1.6.3</filename> will be created:</para>
+                                       <screen>
+                                               <userinput>
+       # as the opensrf user:
+       cd /home/opensrf
+       wget http://evergreen-ils.org/downloads/OpenSRF-1.6.3.tar.gz
+       tar zxf OpenSRF-1.6.3.tar.gz</userinput>
+                                       </screen>
+                               </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
+                                       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>
+       # as the root user:
+       cd /home/opensrf/OpenSRF-1.6.3
+       make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>
+                                       </screen>
+                                       <table xml:id="serversideinstallation-keywords-opensrf">
+                                               <?dbfo keep-together="always" ?>
+                                               <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">
+                                                       <colspec colname="keyword" colnum="1" colwidth="1.0*"/>
+                                                       <colspec colname="linux_version" colnum="2" colwidth="3.0*"/>
+                                                       <thead>
+                                                               <row>
+                                                                       <entry>Keyword</entry>
+                                                                       <entry>Linux Version</entry>
+                                                               </row>
+                                                       </thead>
+                                                       <tbody>
+                                                               <row>
+                                                                       <entry>debian-squeeze</entry>
+                                                                       <entry>Debian "Squeeze" (6.0)</entry>
+                                                               </row>
+                                                               <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>fedora13</entry>
+                                                                       <entry>Fedora "Laughlin" (14)</entry>
+                                                               </row>
+                                                               <row>
+                                                                       <entry>centos</entry>
+                                                                       <entry>CentOS 5</entry>
+                                                               </row>
+                                                               <row>
+                                                                       <entry>rhel</entry>
+                                                                       <entry>Red Hat Enterprise Linux 5</entry>
+                                                               </row>
+                                                               <row>
+                                                                       <entry>gentoo</entry>
+                                                                       <entry>Gentoo</entry>
+                                                               </row>
+                                                       </tbody>
+                                               </tgroup>
+                                       </table>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>Debian</secondary>
+                                       </indexterm>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>Fedora</secondary>
+                                       </indexterm>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>Ubuntu</secondary>
+                                       </indexterm>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>CentOS</secondary>
+                                       </indexterm>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>Red Hat</secondary>
+                                       </indexterm>
+                                       <indexterm>
+                                               <primary>Linux</primary>
+                                               <secondary>Gentoo</secondary>
+                                       </indexterm>
+                                       <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 new 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>
+       # as the opensrf user:
+       cd /home/opensrf/OpenSRF-1.6.3
+       ./configure --prefix=/openils --sysconfdir=/openils/conf
+       make</userinput>
+                                                       </screen>
+                                                       <para>This step will take several minutes to complete.</para>
+                                               </step>
+                                               <step>
+                                                       <title>Compile, Link and Install OpenSRF</title>
+                                                       <para>As the <systemitem class="username">root</systemitem>
+                                                       user, return to the new OpenSRF build directory and use the
+                                                       <command>make</command> utility to compile, link and install
+                                                       OpenSRF:</para>
+                                                       <screen>
+                                                               <userinput>
+       # as the root user:
+       cd /home/opensrf/OpenSRF-1.6.3
+       make install</userinput>
+                                                       </screen>
+                                                       <para>This step will take several minutes to complete.</para>
+                                               </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 two
+                                                       new library paths, then execute the command
+                                                       <command>ldconfig</command> to automatically read the file and
+                                                       modify the system dynamic library path:</para>
+                                                       <screen>
+                                                               <userinput>
+       # as the root user:
+       echo "/openils/lib"   > /etc/ld.so.conf.d/osrf.conf
+       echo "/usr/local/lib >> /etc/ld.so.conf.d/osrf.conf
+       ldconfig</userinput>
+                                                       </screen>
+                                               </step>
+                                               <step xml:id="serversideinstallation-definedomains">
+                                                       <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>
+       # as the root user:
+       127.0.1.2  public.localhost   public
+       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>
+       # as the root user:
+       chown -R opensrf:opensrf /openils</userinput>
+                                                       </screen>
+                                               </step>
+                                       </substeps>
+                               </step>
+                               <step xml:id="stop-ejabberd-service">
+                                       <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>
+       # as the root user:
+       /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>
+       # as the root user:
+       epmd -kill
+       killall beam; killall beam.smp
+       rm /var/lib/ejabberd/*
+       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>
+                                       <substeps>
+                                               <step>
+                                                       <para>Change the line:</para>
+                                                       <literal>{hosts, ["localhost"]}.</literal>
+                                                       <para>to instead read:</para>
+                                                       <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>
+                                                       <para/>
+                                               </step>
+                                               <step>
+                                                       <para>Change the line for older versions of
+                                                       <systemitem class="service">ejabberd</systemitem>:</para>
+                                                       <literal>{max_user_sessions, 10}</literal>
+                                                       <para>to instead read:</para>
+                                                       <literal>{max_user_sessions, 10000}</literal>
+                                                       <para/>
+                                                       <para>Change the line for newer versions of
+                                                       <systemitem class="service">ejabberd</systemitem>:</para>
+                                                       <literal>{access, max_user_sessions, [{10, all}]}</literal>
+                                                       <para>to instead read:</para>
+                                                       <literal>{access, max_user_sessions, [{10000, all}]}</literal>
+                                               </step>
+                                               <step>
+                                                       <para>Change all three occurrences of:</para>
+                                                       <literal>max_stanza_size</literal>
+                                                       <para>to instead read:</para>
+                                                       <literal>2000000</literal>
+                                               </step>
+                                               <step>
+                                                       <para>Change both occurrences of:</para>
+                                                       <literal>maxrate</literal>
+                                                       <para>to instead read:</para>
+                                                       <literal>500000</literal>
+                                               </step>
+                                               <step>
+                                                       <para>Comment out the line:</para>
+                                                       <literal>{mod_offline, []}</literal>
+                                                       <para>by placing two <literal>%</literal> comment signs in front
+                                                       so it instead reads:</para>
+                                                       <literal>%%{mod_offline, []}</literal>
+                                               </step>
+                                       </substeps>
+                               </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>
+       # as the root user:
+       /etc/init.d/ejabberd start</userinput>
+                                       </screen>
+                               </step>
+                               <step>
+                                       <title>Register <systemitem class="username">router</systemitem> and
+                                               <systemitem class="username">opensrf</systemitem> as
+                                               <systemitem class="service">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
+                                       (see <xref linkend="serversideinstallation-definedomains"/>).
+                                       The users include:</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 (remember to replace
+                                       <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       # Note: the syntax for registering a user with ejabberdctl is:
+       #    ejabberdctl register USER DOMAIN PASSWORD
+       ejabberdctl register router  private.localhost NEWPASSWORD
+       ejabberdctl register router  public.localhost  NEWPASSWORD
+       ejabberdctl register opensrf private.localhost NEWPASSWORD
+       ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>
+                                       </screen>
+                                       <para>The users <systemitem class="username">router</systemitem> and
+                                       <systemitem class="username">opensrf</systemitem> and their respective passwords 
+                                       will be used again in <xref linkend="serversideinstallation-passwords"/> when
+                                       we modify the OpenSRF configuration file
+                                       <filename>/openils/conf/opensrf_core.xml</filename> .</para>
+                                       <note>
+                                               <para>
+                                               There appears to be a problem with <command>ejabberdctl</command> in
+                                               that it does not escape input correctly, so a password like
+                                               <literal>'0P3N$SRF'</literal> will be created as <literal>'0P3N'</literal>.
+                                               A bug against ejabberd has been filed. To register a password using
+                                               <command>ejabberdctl</command> with special shell characters until such
+                                               time as that bug is resolved, the workaround is to specify a
+                                               double-escaped character at the command line, for example,
+                                               <literal>'0P3N\\\\$RF'</literal> .</para>
+                                       </note>
+                               </step>
+                               <step xml:id="serversideinstallation-opensrf-createconfig">
+                                       <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>
+       # as the opensrf user:
+       cd /openils/conf
+       cp opensrf.xml.example      opensrf.xml
+       cp opensrf_core.xml.example opensrf_core.xml</userinput>
+                                       </screen>
+                               </step>
+                               <step xml:id="serversideinstallation-passwords">
+                                       <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">
+                                               <?dbfo keep-together="always" ?>
+                                               <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 the 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 verify that
+                                       the element <literal>dbfile</literal> (near the end of the file) is set to the 
+                                       location of the persistent database. If necessary, change the default line:</para>
+                                       <literal>/openils/var/persist.db</literal>
+                                       <para>to instead read:</para>
+                                       <literal>/tmp/persist.db</literal>
+                                       <para>Following is a sample modification of that portion of the file:</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 the utility
+                                       <command>srfsh</command>, 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
+                                       sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>
+                                       to the home directory of each user who will use <command>srfsh</command>. 
+                                       For instance, do the following for the 
+                                       <systemitem class="username">opensrf</systemitem> user:</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       cp /openils/conf/srfsh.xml.example  /home/opensrf/.srfsh.xml</userinput>
+                                       </screen>
+                                       <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the
+                                       following changes:</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>
+                                               <listitem>
+                                                       <para>Change the owner of the file to match the owner of the
+                                                       home directory</para>
+                                               </listitem>
+                                       </itemizedlist>
+                                       <para>Following is a sample of the file:</para>
+                                       <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>
+       # as the opensrf user:
+       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>
+       # as the root user:
+       /etc/init.d/ejabberd start
+       /etc/init.d/memcached start</userinput>
+                                       </screen>
+                                       <para>Then as the <systemitem class="username">opensrf</systemitem> user,
+                                       start OpenSRF as follows:</para>
+                                       <screen>
+                                               <userinput>
+       # as the opensrf user:
+       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
+                                       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> with the <command>srfsh</command> 
+                                       utility and try to call the <command>add</command> method on the OpenSRF 
+                                       <systemitem class="service">math</systemitem> service:</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       /openils/bin/srfsh</userinput>
+                                               <computeroutput>
+       srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>
+                                               <computeroutput>
+       Received Data: 4
+       ------------------------------------
+       Request Completed Successfully
+       Request Time in seconds: 0.007519
+       ------------------------------------</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>
+       # as the opensrf user:
+       osrf_ctl.sh -l -a stop_all</userinput>
+                                       </screen>
+                               </step>
+                       </procedure>
+               </section>
+               <section xml:id="serversideinstallation-ubuntudebian">
+                       <title>Installing Evergreen 2.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 on <systemitem class="osname">Ubuntu</systemitem> or 
+                       <systemitem class="osname">Debian</systemitem> systems.  See 
+                       <xref linkend="serversideinstallation-fedora"/> for description of a similar 
+                       installation on a <systemitem class="osname">Fedora 14</systemitem> system.</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-1.6.3"/>.</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>The latest version of Evergreen can be found here:
+                                       <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz"></ulink> .
+                                       As the <systemitem class="username">opensrf</systemitem> user, change to
+                                       the directory <filename class="directory">/home/opensrf</filename> then download
+                                       and extract Evergreen. The new subdirectory
+                                       <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.4</filename>
+                                       will be created:</para>
+                                       <screen>
+                                               <userinput>
+       # as the opensrf user:
+       cd /home/opensrf
+       wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.4.tar.gz
+       tar zxf Evergreen-ILS-2.0.4.tar.gz</userinput>
+                                       </screen>
+                               </step>
+                               <step xml:id="serversideinstallation-installprereq">
+                                       <title>Install Prerequisites to Build Evergreen</title>
+                                       <para>In this section you will install and configure a set of prerequisites that will be
+                                       used later in <xref linkend="serversideinstallation-configure"/> and 
+                                       <xref linkend="serversideinstallation-compile"/> to 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 list.
+                                       For example, to install the prerequisites for Ubuntu version 10.05 (Lucid Lynx) you would
+                                       enter this command: <command>make -f Open-ILS/src/extras/Makefile.install
+                                       ubuntu-lucid</command>.</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       cd /home/opensrf/Evergreen-ILS-2.0.4
+       make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>
+                                       </screen>
+                               </step>
+                               <step performance="optional">
+                                       <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 section
+                                       (see <xref linkend="serversideinstallation-installprereq"/>)
+                                       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.
+                                       If your PostgreSQL server will be on the same system as your Evergreen
+                                       software, you can install the required PostgreSQL server packages as described
+                                       in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official 
+                                       web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>
+                                       for more information.</para>
+                                       <note>
+                                               <para>PostgreSQL version 8.4 is the minimum supported version to work 
+                                               with Evergreen 2.0. If you have an older version of PostgreSQL, 
+                                               you should upgrade before installing Evergreen. To find your current version 
+                                               of PostgreSQL, as the <systemitem class="username">postgres</systemitem> 
+                                               user execute the command <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
+                                       and install several Perl modules there. As the 
+                                       <systemitem class="username">root</systemitem> user, ensure the gcc compiler
+                                       is installed, then install the following Perl modules:</para>
+                                       <screen>
+                                               <userinput>
+       aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
+       perl -MCPAN -e shell
+               <prompt>cpan></prompt> Business::ISBN
+               <prompt>cpan></prompt> install JSON::XS
+               <prompt>cpan></prompt> Library::CallNumber::LC
+               <prompt>cpan></prompt> install MARC::Record
+               <prompt>cpan></prompt> install MARC::File::XML
+               <prompt>cpan></prompt> cpan UUID::Tiny</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 two new library paths, then run the command <command>ldconfig</command> to
+                                       automatically read the file and modify the system dynamic library path:</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       echo "/usr/local/lib"      > /etc/ld.so.conf.d/osrf.conf
+       echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf
+       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 (remember to replace
+                                       <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,
+                                       for example <literal>8.4</literal>):</para>
+                                       <screen>
+                                               <userinput>
+       # as the opensrf user:
+       /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>
+                                       </screen>
+                               </step>
+                               <step xml:id="serversideinstallation-configure">
+                                       <title>Configure Evergreen</title>
+                                       <para>In this step you will use the <command>configure</command> and
+                                       <command>make</command> utilities to configure Evergreen so it can be compiled
+                                       and linked later in <xref linkend="serversideinstallation-compile"/>.</para>
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, return to
+                                       the Evergreen build directory and execute these commands:</para>
+                                       <screen>
+                                               <userinput>
+       # as the opensrf user:
+       cd /home/opensrf/Evergreen-ILS-2.0.4
+       ./configure --prefix=/openils --sysconfdir=/openils/conf
+       make</userinput>
+                                       </screen>
+                               </step>
+                               <step xml:id="serversideinstallation-compile">
+                                       <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>
+       # as the root user:
+       cd /home/opensrf/Evergreen-ILS-2.0.4
+       make STAFF_CLIENT_BUILD_ID=rel_2_0_4 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.</para>
+                                       <para>The above commands will create a new subdirectory
+                                       <filename class="directory">/openils/var/web/xul/rel_2_0_4</filename> 
+                                       containing the Staff Client.</para>
+                                       <para>To complete the Staff Client installation, as the
+                                       <systemitem class="username">root</systemitem> user execute the following commands to
+                                       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>
+       # as the root user:
+       cd /openils/var/web/xul
+       ln -sf rel_2_0_4/server server</userinput>
+                                       </screen>
+                               </step>
+                               <step>
+                                       <title>Copy the OpenSRF Configuration Files</title>
+                                       <para>In this step you will replace some OpenSRF configuration files that you set up in
+                                       <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and
+                                       tested OpenSRF.</para>
+                                       <para>You must copy several example OpenSRF configuration files into place after first
+                                       creating backup copies for troubleshooting purposes, then change all the file ownerships
+                                       to <systemitem class="username">opensrf</systemitem>.
+                                       As the <systemitem class="username">root</systemitem> user, execute the following
+                                       commands:</para>
+                                       <screen>
+                                               <userinput>
+       # as the root user:
+       cd /openils/conf
+       cp opensrf.xml        opensrf.xml.BAK
+       cp opensrf_core.xml      opensrf_core.xml.BAK
+       cp opensrf.xml.example      opensrf.xml
+       cp opensrf_core.xml.example opensrf_core.xml
+       cp oils_web.xml.example     oils_web.xml
+       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> , and if you
+                                       installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,
+                                       the path would be 
+                                       <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>
+                                       <substeps>
+                                               <step>
+                                                       <title>Create and configure the database</title>
+                                                       <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>
+       # as the postgres user:
+       createdb evergreen -E UTF8 -T template0
+       createlang plperl   evergreen
+       createlang plperlu  evergreen
+       createlang plpgsql  evergreen</userinput>
+                                                       </screen>
+                                                       <para>Continue as the <systemitem class="username">postgres</systemitem> 
+                                                       user and execute the SQL scripts as shown below (remember to adjust the
+                                                       paths as needed, where <emphasis>PGSQL_VERSION</emphasis> is
+                                                       your installed PostgreSQL version, for example
+                                                       <literal>"8.4"</literal>).</para>
+                                                       <screen>
+                                                               <userinput>
+       # as the postgres user:
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>
+                                                       </screen>
+                                               </step>
+                                               <step xml:id="serversideinstallation-postgresqlcreateuser">
+                                                       <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 (remember to replace <emphasis>NEWPASSWORD</emphasis>
+                                                       with an appropriate new password):</para>
+                                                       <screen>
+                                                               <userinput>
+       # as the postgres user:
+       createuser -P -s evergreen</userinput>
+                                                               <computeroutput>
+       Enter password for new role: <userinput>NEWPASSWORD</userinput>
+       Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>
+                                                       </screen>
+                                               </step>
+                                               <step>
+                                                       <title>Create database schema</title>
+                                                       <para>In this step you will create the database schema and configure your
+                                                       system with the corresponding database authentication details for the
+                                                       <emphasis>evergreen</emphasis> database user that you just created in
+                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>
+                                                       <para>As the <systemitem class="username">root</systemitem> user, enter
+                                                       the following commands and replace <emphasis>HOSTNAME, PORT,
+                                                       PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate
+                                                       values:</para>
+                                                       <screen>
+                                                               <userinput>
+       # as the root user:
+       cd /home/opensrf/Evergreen-ILS-2.0.4
+       perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
+       --service all --create-schema --create-offline \
+       --hostname HOSTNAME --port PORT \
+       --user evergreen --password PASSWORD \
+       --database DATABASENAME --admin-user ADMIN-USER \ 
+       --admin-pass ADMIN-PASSWORD </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 
+                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>.
+                                                       The <option>admin-user</option> and <option>admin-pass</option> options will 
+                                                       specify the Evergreen administrator account's username and password. This was 
+                                                       changed for security reasons, it was previously admin/open-ils</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>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 <command>bash</command> prompt to indicate that the command is
+                                                       continued on the next line.</note>
+                                               </step>
+                                       </substeps>
+                               </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>
+                                                       <indexterm>
+                                                               <primary>Apache modules</primary>
+                                                       </indexterm>
+                                                       <screen>
+                                                               <userinput>
+       # as the root user:
+       a2enmod ssl     # enable mod_ssl
+       a2enmod rewrite # enable mod_rewrite
+       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>
+       # as the root user:
+       cd /home/opensrf/Evergreen-ILS-2.0.4
+       cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/
+       cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/
+       cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>
+                                                       </screen>
+                                               </step>
+                                               <step xml:id="serversideinstallation-createsslcertificate">
+                                                       <title>Create a Security Certificate</title>
+                                                       <para>In this step you will 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>
+       # as the root user:
+       mkdir /etc/apache2/ssl
+       cd /etc/apache2/ssl
+       openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>
+                                                       </screen>
+                                                       <para>You will be prompted for several items of information; enter
+                                                       the appropriate information for each item. The new files
+                                                       <filename>server.crt</filename> and <filename>server.key</filename> will
+                                                       be created in the directory 
+                                                       <filename class="directory">/etc/apache2/ssl</filename> .</para>
+                                                       <note>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. For further information on
+                                                       installing a proper SSL certificate, see 
+                                                       <xref linkend="serversideinstallation-ssl"/>.</note>
+                                               </step>
+                                               <step xml:id="serversideinstallation-modify-apache">
+                                                       <title>Update Apache configuration files</title>
+                                                       <para>You must make several changes to an Apache configuration file.</para>
+                                                       <para>As the <systemitem class="username">root</systemitem> user
+                                                       edit the file <filename>/etc/apache2/sites-available/eg.conf</filename> 
+                                                       and make the following changes:</para>
+                                                       <itemizedlist>
+