Docbook cleanup to address many errors during DocBook processing including fop overfl...
[working/Evergreen.git] / 1.6 / admin / serversideinstallation.xml
index 1ba1848..c5b5fd4 100644 (file)
@@ -32,6 +32,9 @@
        listed here:</para>\r
        <table xml:id="serversideinstall-software-dependencies">\r
                <title>Evergreen Software Dependencies</title>\r
+               <indexterm>\r
+                       <primary>Evergreen software dependencies</primary>\r
+               </indexterm>\r
                <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
                        <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>\r
                        <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>\r
                take a final snapshot backup of your system(s). This can be the first in the series of regularly\r
                scheduled system backups that you should probably also begin.</para>\r
                <section xml:id="serversideinstallation-opensrf">\r
+                       <indexterm>\r
+                               <primary>OpenSRF</primary>\r
+                               <secondary>installation</secondary>\r
+                       </indexterm>\r
                        <title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or\r
                                <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
                        <para>This section describes the installation of the latest version of the Open Service Request\r
                        Framework (OpenSRF), a major component of the Evergreen server-side software, on \r
                        <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>\r
                                        <para>As the <systemitem class="username">root</systemitem> user, add the\r
                                        opensrf user to the system. The default shell for the new user is automatically\r
                                        set to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
-<screen>\r
-<userinput>useradd -m -s /bin/bash opensrf</userinput>\r
-<userinput>passwd opensrf</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>useradd -m -s /bin/bash opensrf</userinput>\r
+                                               <userinput>passwd opensrf</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Download and Unpack Latest OpenSRF Version</title>\r
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, download\r
+                                       <indexterm>\r
+                                               <primary>OpenSRF</primary>\r
+                                               <secondary>download</secondary>\r
+                                       </indexterm>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, change to\r
+                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
                                        and extract the latest version of OpenSRF. The latest version can be found here:\r
                                        <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>\r
-<screen>\r
-<userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>\r
-<userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                               <userinput>wget http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz</userinput>\r
+                                               <userinput>tar zxf OpenSRF-1.4.0.tar.gz</userinput>\r
+                                       </screen>\r
                                        <para>The new directory\r
                                        <filename class="directory">/home/opensrf/OpenSRF-1.4.0</filename> will be created.</para>\r
                                </step>\r
                                        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 example with\r
-                                       the keyword corresponding to the name of the <systemitem class="osname">Linux</systemitem>\r
-                                       distribution listed in the distribution keywords table\r
-                                       <xref linkend="serversideinstallation-keywords-opensrf"/>. </para>\r
-<screen>\r
-<userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
-<userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
+                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
+                                       example with the keyword corresponding to the name of one of the\r
+                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following\r
+                                       distribution keywords table <xref linkend="serversideinstallation-keywords-opensrf"/> . \r
+                                       For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would\r
+                                       enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                               <userinput>make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
                                        <table xml:id="serversideinstallation-keywords-opensrf">\r
                                                <title>Keyword Targets for OpenSRF <application>"make"</application> Command</title>\r
                                                <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
                                                        <tbody>\r
                                                                <row>\r
                                                                        <entry>debian-etch</entry>\r
-                                                                       <entry>for Debian Etch (4.0)</entry>\r
+                                                                       <entry>for Debian "Etch" (4.0)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>debian-lenny</entry>\r
-                                                                       <entry>for Debian Lenny (5.0)</entry>\r
+                                                                       <entry>for Debian "Lenny" (5.0)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-hardy</entry>\r
-                                                                       <entry>for Ubuntu Hardy Heron (8.04)</entry>\r
+                                                                       <entry>for Ubuntu "Hardy Heron" (8.04)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-karmic</entry>\r
-                                                                       <entry>for Ubuntu Karmic Koala (9.10)</entry>\r
+                                                                       <entry>for Ubuntu "Karmic Koala" (9.10)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-lucid</entry>\r
-                                                                       <entry>for Ubuntu Lucid Lynx (10.04)</entry>\r
+                                                                       <entry>for Ubuntu "Lucid Lynx" (10.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>fedora13</entry>\r
+                                                                       <entry>for Fedora "Goddard" (13)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>centos</entry>\r
+                                                                       <entry>for Centos</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>rhel</entry>\r
+                                                                       <entry>for RHEL</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>gentoo</entry>\r
+                                                                       <entry>for Gentoo</entry>\r
                                                                </row>\r
                                                        </tbody>\r
                                                </tgroup>\r
                                </step>\r
                                <step>\r
                                        <title>Build OpenSRF</title>\r
+                                       <para>In this section you will configure and build the OpenSRF\r
+                                       components that support other Evergreen services.</para>\r
                                        <substeps>\r
                                                <step>\r
                                                        <title>Configure OpenSRF</title>\r
+                                                       <indexterm>\r
+                                                               <primary>OpenSRF</primary>\r
+                                                               <secondary>configure</secondary>\r
+                                                       </indexterm>\r
                                                        <para>As the <systemitem class="username">opensrf</systemitem>\r
                                                        user, return to the OpenSRF build directory and use the\r
                                                        <command>configure</command> utility to prepare for the next\r
                                                        include support for Python and Java, add the configuration\r
                                                        options <option>--enable-python</option> and\r
                                                        <option>--enable-java</option>, respectively:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
-<userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>\r
-<userinput>make</userinput>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                                               <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>\r
+                                                               <userinput>make</userinput>\r
+                                                       </screen>\r
                                                </step>\r
                                                <step>\r
                                                        <title>Compile, Link and Install OpenSRF</title>\r
                                                        user, return to the OpenSRF build directory and use the\r
                                                        <command>make</command> utility to compile, link and install\r
                                                        OpenSRF:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
-<userinput>make install</userinput>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>cd /home/opensrf/OpenSRF-1.4.0</userinput>\r
+                                                               <userinput>make install</userinput>\r
+                                                       </screen>\r
                                                </step>\r
                                                <step>\r
                                                        <title>Update the System Dynamic Library Path</title>\r
                                                        new library path, then run the command\r
                                                        <command>ldconfig</command> to automatically read the file and\r
                                                        modify the system dynamic library path:</para>\r
-<screen>\r
-<userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>\r
-<userinput>ldconfig</userinput>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf</userinput>\r
+                                                               <userinput>ldconfig</userinput>\r
+                                                       </screen>\r
                                                </step>\r
-                                               <step><title>Define Public and Private OpenSRF Domains</title><para>You must define your public and private OpenSRF\r
-                                                       domains. For security purposes, OpenSRF uses Jabber domains to\r
-                                                       separate services into public and private realms. Throughout\r
-                                                       these instructions, we will use the example domains <systemitem class="domainname">public.localhost</systemitem> for the public\r
-                                                       domain and <systemitem class="domainname">private.localhost</systemitem> for the\r
-                                                       private domain. On a single-server system, the easiest way to\r
-                                                       define public and private domains is to define separate host\r
-                                                       names by adding entries to the file\r
-                                                       <filename>/etc/hosts</filename>.</para> <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
-                                                       <filename>/etc/hosts</filename> and add the following entries\r
-                                                       for our example domains:</para>\r
-<screen>\r
-<userinput>127.0.1.2   public.localhost        public</userinput>\r
-<userinput>127.0.1.3   private.localhost       private</userinput>\r
-</screen>\r
+                                               <step>\r
+                                                       <title>Define Public and Private OpenSRF Domains</title>\r
+                                                       <para>For security purposes, OpenSRF uses Jabber domains to separate services\r
+                                                       into public and private realms. On a single-server system the easiest way to\r
+                                                       define public and private OpenSRF domains is to define separate host names by \r
+                                                       adding entries to the file <filename>/etc/hosts</filename>.</para>\r
+                                                       <para>In the following steps we will use the example domains\r
+                                                       <systemitem class="domainname">public.localhost</systemitem> for the public\r
+                                                       domain and <systemitem class="domainname">private.localhost</systemitem> \r
+                                                       for the private domain. In an upcoming step, you will configure two special\r
+                                                       <systemitem class="service">ejabberd</systemitem> users\r
+                                                       to handle communications for these two domains.</para>\r
+                                                       <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                                       <filename>/etc/hosts</filename> and add the following example domains:</para>\r
+                                                       <indexterm>\r
+                                                               <primary>Jabber</primary>\r
+                                                       </indexterm>\r
+                                                       <screen>\r
+                                                               <userinput>127.0.1.2    public.localhost        public</userinput>\r
+                                                               <userinput>127.0.1.3    private.localhost       private</userinput>\r
+                                                       </screen>\r
                                                </step>\r
                                                <step>\r
                                                        <title>Change File Ownerships</title>\r
-                                                       <para>As the <systemitem class="username">root</systemitem>\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
                                </step>\r
                                <step>\r
                                        <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, stop the\r
-                                       <systemitem class="service">ejabberd</systemitem> service:</para>\r
-<screen>\r
-<userinput>/etc/init.d/ejabberd stop</userinput>\r
-</screen>\r
-                                       <para>If <systemitem class="service">ejabberd</systemitem> reports that it is\r
-                                       already stopped, it may have run into a problem starting back at the\r
-                                       installation stage. One possible fix is to kill any remaining\r
-                                       <systemitem class="daemon">beam</systemitem> and \r
-                                       <systemitem class="daemon">epmd</systemitem> processes, then edit the\r
-                                       configuration file <filename>/etc/ejabberd/ejabberd.cfg</filename> \r
-                                       to hardcode a domain:</para>\r
-<screen>\r
-<userinput>epmd -kill</userinput>\r
-<userinput>killall beam; killall beam.smp</userinput>\r
-<userinput>rm /var/lib/ejabberd/*</userinput>\r
-<userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>\r
-</screen>\r
+                                       <indexterm>\r
+                                               <primary>ejabberd</primary>\r
+                                       </indexterm>\r
+                                       <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>\r
+                                       you must stop that service. As the <systemitem class="username">root</systemitem> user,\r
+                                       execute the following command to stop the service:</para>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd stop</userinput>\r
+                                       </screen>\r
+                                       <para>If <systemitem class="service">ejabberd</systemitem> reports that it \r
+                                       is already stopped, there may have been a problem when it started back\r
+                                       in the installation step. If there are any remaining daemon processes such as\r
+                                       <systemitem class="daemon">beam</systemitem> or\r
+                                       <systemitem class="daemon">epmd</systemitem> \r
+                                       you may need to perform the following commands to kill them:</para>\r
+                                       <screen>\r
+                                               <userinput>epmd -kill</userinput>\r
+                                               <userinput>killall beam; killall beam.smp</userinput>\r
+                                               <userinput>rm /var/lib/ejabberd/*</userinput>\r
+                                               <userinput>echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
-                                       <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following\r
-                                       changes:</para>\r
+                                       <para>You must make several configuration changes for the\r
+                                       <systemitem class="service">ejabberd</systemitem> service before\r
+                                       it is started again.\r
+                                       As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                       <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
                                        <itemizedlist>\r
                                                <listitem>\r
-                                                       <para>Change\r
+                                                       <para>Change the line:\r
                                                        <screen><userinput>{hosts, ["localhost"]}.</userinput></screen>\r
                                                        to:\r
                                                        <screen><userinput>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</userinput></screen></para>\r
                                                </listitem>\r
                                                <listitem>\r
-                                                       <para>Change\r
-                                                       <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to\r
+                                                       <para>Change the line:\r
+                                                       <screen><userinput>{max_user_sessions, 10}.</userinput></screen> to:\r
                                                        <screen><userinput>{max_user_sessions, 10000}.</userinput></screen></para>\r
-                                                       <para>If you see something like this instead:\r
+                                                       <para>If the line looks something like this:\r
                                                        <screen><userinput>{access, max_user_sessions, [{10, all}]}.</userinput></screen>\r
                                                        then change it to:\r
                                                        <screen><userinput>{access, max_user_sessions, [{10000, all}]}</userinput></screen></para>\r
                                                </listitem>\r
                                                <listitem>\r
-                                                       <para>Change all three occurrences of <literal>max_stanza_size</literal>\r
-                                                       to<literal>2000000</literal>.</para>\r
+                                                       <para>Change all three occurrences of: <literal>max_stanza_size</literal>\r
+                                                       to<literal>2000000</literal>.</para>\r
                                                </listitem>\r
                                                <listitem>\r
-                                                       <para>Change both occurrences of <literal>maxrate</literal> to\r
+                                                       <para>Change both occurrences of: <literal>maxrate</literal> to:\r
                                                        <literal>500000</literal>.</para>\r
                                                </listitem>\r
                                                <listitem>\r
                                        <para>As the <systemitem class="username">root</systemitem> user, restart the\r
                                        <systemitem class="service">ejabberd</systemitem> service to test the\r
                                        configuration changes and to register your users:</para>\r
-<screen>\r
-<userinput>/etc/init.d/ejabberd start</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd start</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Register <systemitem class="username">router</systemitem> and\r
                                                <systemitem class="username">ejabberd</systemitem> users</title>\r
-                                       <para>On each domain, you need two \r
-                                       <systemitem class="service">ejabberd</systemitem> users to manage \r
-                                       the OpenSRF communications:</para>\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>\r
+                                       that you added to the file <filename>/etc/hosts</filename>\r
+                                       in a previous step:</para>\r
                                        <itemizedlist>\r
                                                <listitem>\r
-                                                       <para>a <systemitem class="username">router</systemitem> user,\r
+                                                       <para>the <systemitem class="username">router</systemitem> user,\r
                                                        to whom all requests to connect to an OpenSRF service will be\r
-                                                       routed; this <systemitem class="service">ejabberd</systemitem>\r
-                                                       user must be named <systemitem class="username">router</systemitem></para>\r
+                                                       routed;</para>\r
                                                </listitem>\r
                                                <listitem>\r
-                                                       <para>an <systemitem class="username">opensrf</systemitem> user,\r
-                                                       which clients use to connect to OpenSRF services; this user can\r
-                                                       be named anything you like, but we will use\r
-                                                       <literal>opensrf</literal> in our examples</para>\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, use the\r
-                                       <command>ejabberdctl</command> utility to register your ejabber users\r
-                                       <systemitem class="username">router</systemitem> and\r
-                                       <systemitem class="username">opensrf</systemitem> for the OpenSRF router service\r
-                                       on each domain. The users should have different passwords on each domain.\r
-                                       These users will correspond to those configured in the file\r
-                                       <filename>/openils/conf/opensrf_core.xml</filename>:</para>\r
-<programlisting language="xml">\r
-<![CDATA[\r
-# The syntax for registering a user with ejabberdctl is\r
-# ejabberdctl register <user> <domain> <password>\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 two users on each domain. Note that the users correspond to those configured\r
+                                       in the file <filename>/openils/conf/opensrf_core.xml</filename>  in the next steps.</para>\r
+                                       <programlisting language="xml"><![CDATA[\r
+# The syntax for registering a user with ejabberdctl is:\r
+#    ejabberdctl register <user> <domain> <password>\r
 #\r
-ejabberdctl register router private.localhost  <password>\r
-ejabberdctl register opensrf private.localhost <password>\r
-ejabberdctl register router public.localhost   <password>\r
-ejabberdctl register opensrf public.localhost  <password>\r
-]]>\r
-</programlisting>\r
+ejabberdctl register router  private.localhost <password #1>\r
+ejabberdctl register router  public.localhost  <password #1>\r
+ejabberdctl register opensrf private.localhost <password #2>\r
+ejabberdctl register opensrf public.localhost  <password #2>\r
+]]></programlisting>\r
                                </step>\r
                                <step>\r
                                        <title>Create configuration files</title>\r
-                                       <para>As the <systemitem class="username">opensrf</systemitem> user, use the\r
-                                       example templates to create the configuration files\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, execute\r
+                                       the following commands to create the new configuration files\r
                                        <filename>/openils/conf/opensrf_core.xml</filename> and\r
                                        <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>\r
-<screen>\r
-<userinput>cd /openils/conf</userinput>\r
-<userinput>cp opensrf.xml.example      opensrf.xml</userinput>\r
-<userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>cd /openils/conf</userinput>\r
+                                               <userinput>cp opensrf.xml.example      opensrf.xml</userinput>\r
+                                               <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Change Jabber usernames and passwords</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 to match the values shown in the\r
+                                       and update the Jabber 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
+                                       values:</para>\r
                                        <table xml:id="serversideinstallation-xpath-table-1">\r
                                                <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
                                                <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
@@ -467,37 +522,38 @@ ejabberdctl register opensrf public.localhost  <password>
                                                        </tbody>\r
                                                </tgroup>\r
                                        </table>\r
-                                       <para>You also need to specify the domains from which \r
-                                       <systemitem class="service">OpenSRF</systemitem> will accept and to which \r
-                                       <systemitem class="service">OpenSRF</systemitem> will make connections. \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> / \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 your values.</para>\r
+                                       to match values for your own systems.</para>\r
                                </step>\r
                                <step>\r
                                        <title>Set location of persistent database</title>\r
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
-                                       file <filename>/openils/conf/opensrf.xml</filename> to set the location of the\r
-                                       persistent database in the <literal>dbfile</literal> element near the end of the\r
-                                       file:</para>\r
-<programlisting language="xml">\r
-<![CDATA[\r
+                                       file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the \r
+                                       element <literal>dbfile</literal> (near the end of the file) to set the \r
+                                       location of the persistent database:</para>\r
+                                       <programlisting language="xml"><![CDATA[\r
 <!-- Example of an app-specific setting override -->\r
 <opensrf.persist>\r
   <app_settings>\r
     <dbfile>/tmp/persist.db</dbfile>\r
   </app_settings>\r
 </opensrf.persist>\r
-]]>\r
-</programlisting>\r
+]]></programlisting>\r
                                </step>\r
                                <step>\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\r
                                        <command>srfsh</command>. This is a command line diagnostic tool for testing and\r
                                        interacting with <application>OpenSRF</application>. It will be used in a future\r
@@ -525,8 +581,7 @@ ejabberdctl register opensrf public.localhost  <password>
                                                log file to which the user has write access</listitem>\r
                                                <listitem>Modify <literal>loglevel</literal> as needed for testing</listitem>\r
                                        </itemizedlist>\r
-<programlisting language="xml">\r
-<![CDATA[\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
@@ -540,8 +595,7 @@ ejabberdctl register opensrf public.localhost  <password>
 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->\r
 <loglevel>4</loglevel>\r
 </srfsh>\r
-]]>\r
-</programlisting>\r
+]]></programlisting>\r
                                </step>\r
                                <step>\r
                                        <title>Modify Environmental Variable PATH for\r
@@ -550,9 +604,9 @@ ejabberdctl register opensrf public.localhost  <password>
                                        environmental variable <envar>PATH</envar> by adding a new file path to the\r
                                        <systemitem class="username">opensrf</systemitem> user's shell configuration\r
                                        file <filename>.bashrc</filename>:</para>\r
-<screen>\r
-<userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Start OpenSRF</title>\r
@@ -565,9 +619,9 @@ ejabberdctl register opensrf public.localhost  <password>
                                        </screen>\r
                                        <para>Finally, as the <systemitem class="username">opensrf</systemitem> user,\r
                                        start OpenSRF. Use "-l" to force hostname to be "localhost":</para>\r
-<screen>\r
-<userinput>osrf_ctl.sh -l -a start_all</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>osrf_ctl.sh -l -a start_all</userinput>\r
+                                       </screen>\r
                                        <note>\r
                                                <para>If you receive the error message <errortext>bash: osrf_ctl.sh:\r
                                                command not found</errortext>, then your environment variable\r
@@ -576,9 +630,9 @@ ejabberdctl register opensrf public.localhost  <password>
                                                 this should have been set by <filename>.bashrc</filename> when you \r
                                                logged in as the <systemitem class="username">opensrf</systemitem> user, \r
                                                but you can manually set it using the following command:</para>\r
-<screen>\r
-<userinput>export PATH=$PATH:/openils/bin</userinput>\r
-</screen>\r
+                                               <screen>\r
+                                                       <userinput>export PATH=$PATH:/openils/bin</userinput>\r
+                                               </screen>\r
                                        </note>\r
                                        <para>You can also start Evergreen <emphasis role="bold">without</emphasis> the\r
                                        <option>-l</option> flag, but <command>osrf_ctl.sh</command> must know the fully\r
@@ -593,9 +647,9 @@ ejabberdctl register opensrf public.localhost  <password>
                                        <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command> \r
                                        utility and trying to call the <command>add</command> method on the OpenSRF \r
                                        <systemitem class="service">math</systemitem> service:</para>\r
-<screen>\r
-<userinput>/openils/bin/srfsh</userinput>\r
-<computeroutput>\r
+                                       <screen>\r
+                                               <userinput>/openils/bin/srfsh</userinput>\r
+                                               <computeroutput>\r
 srfsh#\r
 request opensrf.math add 2 2\r
 Received Data: 4\r
@@ -606,22 +660,30 @@ Request Time in seconds: 0.007519
 \r
 srfsh#\r
 </computeroutput>\r
-</screen>\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>Stopping OpenSRF</title>\r
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, stop OpenSRF:</para>\r
-<screen>\r
-<userinput>osrf_ctl.sh -l -a stop_all</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>osrf_ctl.sh -l -a stop_all</userinput>\r
+                                       </screen>\r
                                </step>\r
                        </procedure>\r
                </section>\r
                <section xml:id="serversideinstallation-ubuntudebian">\r
                        <title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or\r
                                <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
                        <para>This section outlines the installation process for the latest stable version of\r
                        Evergreen.</para>\r
                        <para>In this section you will download, unpack, install, configure and test the Evergreen\r
@@ -676,10 +738,10 @@ srfsh#
                                        <para>As the <systemitem class="username">opensrf</systemitem> user, download\r
                                        and extract the latest version of Evergreen. The latest version can be found here:\r
                                        <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz"></ulink></para>\r
-<screen>\r
-<userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
-<userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
+                                               <userinput>tar zxf Evergreen-ILS-1.6.1.2.tar.gz</userinput>\r
+                                       </screen>\r
                                        <para>The new directory\r
                                        <filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2</filename>\r
                                        will be created.</para>\r
@@ -692,14 +754,16 @@ srfsh#
                                        <para>As the <systemitem class="username">root</systemitem> user, enter the\r
                                        commands show below to build the prerequisites from the software distribution\r
                                        that you just downloaded and unpacked. Remember to replace\r
-                                       <emphasis>[DISTRIBUTION]</emphasis> in the example with the keyword\r
-                                       corresponding to the name of the <systemitem class="osname">Linux</systemitem>\r
-                                       distribution listed in the distribution keywords table \r
-                                       <xref linkend="serversideinstallation-keywords-evergreen"/> .</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
-<userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
-</screen>\r
+                                       <emphasis>[DISTRIBUTION]</emphasis> in the following example with the keyword\r
+                                       corresponding to the name of one of the <systemitem class="osname">Linux</systemitem>\r
+                                       distributions listed in the following distribution keywords table \r
+                                       <xref linkend="serversideinstallation-keywords-evergreen"/> .\r
+                                       For example, to install the prerequisites for Ubuntu version 9.10 (Karmic Koala) you would\r
+                                       enter this command: <command>make -f Open-ILS/src/extras/Makefile.install ubuntu-karmic</command> .</para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
                                        <table xml:id="serversideinstallation-keywords-evergreen">\r
                                                <title>Keyword Targets for Evergreen <application>"make"</application> Command</title>\r
                                                <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
@@ -714,30 +778,50 @@ srfsh#
                                                        <tbody>\r
                                                                <row>\r
                                                                        <entry>debian-etch</entry>\r
-                                                                       <entry>for Debian Etch (4.0)</entry>\r
+                                                                       <entry>for Debian "Etch" (4.0)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>debian-lenny</entry>\r
-                                                                       <entry>for Debian Lenny (5.0)</entry>\r
+                                                                       <entry>for Debian "Lenny" (5.0)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-hardy</entry>\r
-                                                                       <entry>for Ubuntu Hardy Heron (8.04)</entry>\r
+                                                                       <entry>for Ubuntu "Hardy Heron" (8.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>ubuntu-intrepid</entry>\r
+                                                                       <entry>for Ubuntu "Intrepid Ibex" (8.10)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-karmic</entry>\r
-                                                                       <entry>for Ubuntu Karmic Koala (9.10)</entry>\r
+                                                                       <entry>for Ubuntu "Karmic Koala" (9.10)</entry>\r
                                                                </row>\r
                                                                <row>\r
                                                                        <entry>ubuntu-karmic</entry>\r
-                                                                       <entry>for Ubuntu Lucid Lynx (10.04)</entry>\r
+                                                                       <entry>for Ubuntu "Lucid Lynx" (10.04)</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>centos</entry>\r
+                                                                       <entry>for Centos</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>rhel</entry>\r
+                                                                       <entry>for RHEL</entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>gentoo</entry>\r
+                                                                       <entry>for Gentoo</entry>\r
                                                                </row>\r
                                                        </tbody>\r
                                                </tgroup>\r
                                        </table>\r
                                </step>\r
-                               <step xml:id="serversideinstallation-postgresql-default">\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 step\r
                                        does not automatically install PostgreSQL. You must install the PostgreSQL server\r
@@ -750,14 +834,14 @@ srfsh#
                                        install the required PostgreSQL server packages:</para>\r
                                        <para>For <systemitem class="osname">Debian Lenny</systemitem> and \r
                                        <systemitem class="osname">Ubuntu Hardy (8.04)</systemitem>:</para>\r
-<screen>\r
-<userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_83</userinput>\r
+                                       </screen>\r
                                        <para>For <systemitem class="osname">Ubuntu Karmic (9.10)</systemitem> and\r
                                        <systemitem class="osname">Ubuntu Lucid (10.04)</systemitem>:</para>\r
-<screen>\r
-<userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_84</userinput>\r
+                                       </screen>\r
                                        <note>\r
                                                <para>PostgreSQL versions 8.3 or 8.4 are the recommended versions to work \r
                                                with Evergreen 1.6. If you have an older version of PostgreSQL, you should\r
@@ -776,47 +860,53 @@ srfsh#
                                        <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
-<screen>\r
-<userinput># first, ensure the gcc compiler is installed:</userinput>\r
-<userinput>apt-get install gcc</userinput>\r
-<userinput># then install the Perl modules:</userinput>\r
-<userinput>perl -MCPAN -e shell</userinput>\r
-<prompt>cpan></prompt>\r
-<userinput>install JSON::XS</userinput>\r
-<prompt>cpan></prompt>\r
-<userinput>install MARC::Record</userinput>\r
-<prompt>cpan></prompt>\r
-<userinput>install MARC::File::XML</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput># first, ensure the gcc compiler is installed:</userinput>\r
+                                               <userinput>apt-get install gcc</userinput>\r
+                                               <userinput># then install the Perl modules:</userinput>\r
+                                               <userinput>perl -MCPAN -e shell</userinput>\r
+                                               <prompt>cpan></prompt>\r
+                                               <userinput>install JSON::XS</userinput>\r
+                                               <prompt>cpan></prompt>\r
+                                               <userinput>install MARC::Record</userinput>\r
+                                               <prompt>cpan></prompt>\r
+                                               <userinput>install MARC::File::XML</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\r
-                                       recognize the newly installed libraries. As the <systemitem class="username">root</systemitem> user, create a file named\r
-                                       /etc/ld.so.conf.d/eg.conf containing the new library paths:</para>\r
-<programlisting>\r
+                                       recognize the newly installed libraries. As the <systemitem class="username">root</systemitem>\r
+                                       user, create a file named <filename>/etc/ld.so.conf.d/eg.conf</filename>\r
+                                       containing these new library paths:</para>\r
+                                       <programlisting>\r
 /usr/local/lib\r
 /usr/local/lib/dbd\r
 </programlisting>\r
                                        <para>Then run the command <command>ldconfig</command> to automatically read the\r
                                        file and modify the system dynamic library path:</para>\r
-<screen>\r
-<userinput>ldconfig</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>ldconfig</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step performance="optional">\r
-                                       <title>(OPTIONAL) Restart the PostgreSQL Server</title>\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. As the <systemitem class="username">opensrf</systemitem> user, execute the following command, where\r
+                                       running on another system, you may skip this step. As the <systemitem class="username">opensrf</systemitem>\r
+                                       user, execute the following command, where\r
                                        <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL version\r
                                        (e.g. <literal>8.3</literal>):</para>\r
-<screen>\r
-<userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/postgresql-[PGSQL_VERSION] restart</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step xml:id="serversideinstallation-configure">\r
                                        <title>Configure Evergreen</title>\r
@@ -824,60 +914,72 @@ srfsh#
                                        the Evergreen build directory and use the <command>configure</command> and\r
                                        <command>make</command> utilities to configure Evergreen so it can be compiled\r
                                        and linked in the next step:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
-<userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>\r
-<userinput>make</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
+                                               <userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput>\r
+                                               <userinput>make</userinput>\r
+                                       </screen>\r
                                </step>\r
-                               <step xml:id="serversideinstallation-compilingevergreen">\r
+                               <step>\r
                                        <title>Compile, Link and Install Evergreen</title>\r
-                                       <para>In this step you will actually compile, link and install Evergreen and the\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\r
-                                       below. 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\r
-                                       the Staff Client you will use to connect to the Evergreen server.</para>\r
-                                       <para>For further information on manually building the Staff Client, see \r
+                                       Evergreen build directory and use the <command>make</command> utility as shown below:</para>\r
+                                       <screen>\r
+                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
+                                               <userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 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 Staff\r
+                                       Client you will use to connect to the Evergreen server. For further information on manually\r
+                                       building the Staff Client, see \r
                                        <xref linkend="staffclientinstallation-building-staffclient"/>.</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
-<userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_1_2 install</userinput>\r
-</screen>\r
-                                       <para>The above commands will create a new subdirectory <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename> containing the\r
-                                       Staff Client.</para>\r
-                                       <para>To complete the Staff Client installation, as the <systemitem class="username">root</systemitem> user create a symbolic link named\r
-                                       <emphasis>server</emphasis> in the head of the Staff Client directory <filename class="directory">/openils/var/web/xul</filename> that points to the\r
+                                       <para>The above commands will create a new subdirectory\r
+                                       <filename class="directory">/openils/var/web/xul/rel_1_6_1_2</filename> \r
+                                       containing the Staff Client.</para>\r
+                                       <para>To complete the Staff Client installation, \r
+                                       as the <systemitem class="username">root</systemitem> user create a symbolic link \r
+                                       named <emphasis>server</emphasis> in the head of the Staff Client directory \r
+                                       <filename class="directory">/openils/var/web/xul</filename> that points to the\r
                                        subdirectory <filename class="directory">/server</filename> of the new Staff\r
                                        Client build:</para>\r
-<screen>\r
-<userinput>cd /openils/var/web/xul</userinput>\r
-<userinput>ln -sf rel_1_6_1_2/server server</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>cd /openils/var/web/xul</userinput>\r
+                                               <userinput>ln -sf rel_1_6_1_2/server server</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <title>Copy the OpenSRF Configuration Files</title>\r
-                                       <para>As the <systemitem class="username">root</systemitem> user, copy the\r
-                                       example OpenSRF configuration files into place. This replaces the configuration\r
-                                       files that you set up in a previous step when you installed and tested\r
-                                       OpenSRF. You should also create backup copies of the old files for\r
-                                       troubleshooting purposes. Finally, change the ownership on the installed files\r
-                                       to the <systemitem class="username">opensrf</systemitem> user:</para>\r
-<screen>\r
-<userinput>cp /openils/conf/opensrf.xml.example      /openils/conf/opensrf.xml</userinput>\r
-<userinput>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</userinput>\r
-<userinput>cp /openils/conf/oils_web.xml.example     /openils/conf/oils_web.xml</userinput>\r
-<userinput>chown -R opensrf:opensrf /openils/</userinput>\r
-</screen>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, execute the\r
+                                       following commands to copy the example OpenSRF configuration files into place\r
+                                       after first creating backup copies of the old files for troubleshooting purposes.\r
+                                       These files replace the configuration files that you set up in a previous step\r
+                                       when you installed and tested OpenSRF. Finally, change the ownership on\r
+                                       the installed files to the <systemitem class="username">opensrf</systemitem> user:</para>\r
+                                       <screen>\r
+                                               <userinput>cd /openils/conf</userinput>\r
+                                               <userinput>cp opensrf.xml      opensrf.xml.BAK</userinput>\r
+                                               <userinput>cp opensrf_core.xml opensrf_core.xml.BAK</userinput>\r
+                                               <userinput>cp opensrf.xml.example      opensrf.xml</userinput>\r
+                                               <userinput>cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
+                                               <userinput>cp oils_web.xml.example     oils_web.xml</userinput>\r
+                                               <userinput>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> repository to match your PostgreSQL server\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>; if you\r
-                                       installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>, the path would be \r
+                                       installed the PostgreSQL 8.3 server packages on <systemitem class="osname">Ubuntu 8.04</systemitem>,\r
+                                       the path would be \r
                                        <systemitem class="directory">/usr/share/postgresql/8.3/contrib/</systemitem>.</para>\r
                                        <substeps>\r
                                                <step>\r
@@ -887,21 +989,21 @@ srfsh#
                                                        <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
-                                                       <para>Create the database:</para>\r
-<screen>\r
-<userinput>createdb -E UNICODE evergreen</userinput>\r
-<userinput>createlang plperl   evergreen</userinput>\r
-<userinput>createlang plperlu  evergreen</userinput>\r
-<userinput>createlang plpgsql  evergreen</userinput>\r
-</screen>\r
-                                                       <para>Adjust the paths as shown, where\r
+                                                       <screen>\r
+                                                               <userinput>createdb evergreen -E UTF8 -T template0</userinput>\r
+                                                               <userinput>createlang plperl   evergreen</userinput>\r
+                                                               <userinput>createlang plperlu  evergreen</userinput>\r
+                                                               <userinput>createlang plpgsql  evergreen</userinput>\r
+                                                       </screen>\r
+                                                       <para>Continue as user <systemitem class="username">postgres</systemitem>\r
+                                                       and execute the SQL scripts as shown below, adjusting the paths as needed, where\r
                                                        <literal>[PGSQL_VERSION]</literal> is your installed PostgreSQL\r
                                                        version (e.g. <literal>8.3</literal>).</para>\r
-<screen>\r
-<userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>\r
-<userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql  evergreen</userinput>\r
-<userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql     evergreen</userinput>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tablefunc.sql evergreen</userinput>\r
+                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/tsearch2.sql  evergreen</userinput>\r
+                                                               <userinput>psql -f /usr/share/postgresql/[PGSQL_VERSION]/contrib/pgxml.sql     evergreen</userinput>\r
+                                                       </screen>\r
                                                </step>\r
                                                <step>\r
                                                        <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>\r
@@ -909,11 +1011,11 @@ srfsh#
                                                        user on the PostgreSQL system, create a new PostgreSQL user\r
                                                        named <systemitem class="username">evergreen</systemitem> and\r
                                                        assign a password:</para>\r
-<screen>\r
-<userinput>createuser -P -s evergreen</userinput>\r
-<prompt>Enter password for new role: MYNEWPASSWORD</prompt>\r
-<prompt>Enter it again: MYNEWPASSWORD</prompt>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>createuser -P -s evergreen</userinput>\r
+                                                               <prompt>Enter password for new role: <userinput>MYNEWPASSWORD</userinput></prompt>\r
+                                                               <prompt>Enter it again: <userinput>MYNEWPASSWORD</userinput></prompt>\r
+                                                       </screen>\r
                                                </step>\r
                                                <step>\r
                                                        <title>Create Database Schema</title>\r
@@ -926,18 +1028,24 @@ srfsh#
                                                        <emphasis>HOSTNAME, PORT, PASSWORD</emphasis> and\r
                                                        <emphasis>DATABASENAME</emphasis> with appropriate\r
                                                        values:</para>\r
-<screen>\r
-<userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
-<userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>\r
-<userinput>  --service all --create-schema --create-bootstrap --create-offline \</userinput>\r
-<userinput>  --hostname HOSTNAME --port PORT \</userinput>\r
-<userinput>  --user evergreen --password PASSWORD --database DATABASENAME</userinput>\r
-</screen>\r
+                                                       <screen>\r
+                                                               <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
+                                                               <userinput>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \</userinput>\r
+                                                               <userinput>  --service all --create-schema --create-bootstrap --create-offline \</userinput>\r
+                                                               <userinput>  --hostname HOSTNAME --port PORT \</userinput>\r
+                                                               <userinput>  --user evergreen --password PASSWORD --database DATABASENAME</userinput>\r
+                                                       </screen>\r
                                                        <para>On most systems, <emphasis>HOSTNAME</emphasis> will be\r
                                                        <emphasis role="bold">localhost</emphasis>,\r
-                                                       <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>,\r
-                                                       and <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> \r
-                                                       will be <emphasis role="bold">evergreen</emphasis>.</para>\r
+                                                       <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.\r
+                                                       Values for <emphasis>PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> \r
+                                                       will match the values you used in the previous step when you created the\r
+                                                       database and and set a password for the\r
+                                                       <systemitem class="username">evergreen</systemitem> user.\r
+                                                       Adjust the values to match your own systems.</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>\r
                                                                <para>If you are entering the above command on a single\r
                                                                line, do not include the <literal>\</literal>\r
@@ -949,6 +1057,10 @@ srfsh#
                                                </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\r
                                                        support Evergreen software.</para>\r
                                                        <para>First, you must enable some built-in Apache modules and install\r
@@ -967,13 +1079,16 @@ srfsh#
                                                                                <userinput>a2enmod rewrite # enable mod_rewrite</userinput>\r
                                                                                <userinput>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 safely ignore them.</para>\r
                                                                </step>\r
                                                                <step>\r
                                                                        <title>Copy Apache configuration files</title>\r
                                                                        <para>You must copy the Apache configuration\r
-                                                                       files from the Evergreen installation dierectory\r
-                                                                       to the Apache directory. As the <systemitem class="username">root</systemitem> user, perform\r
-                                                                       the following commands:</para>\r
+                                                                       files from the Evergreen installation directory\r
+                                                                       to the Apache directory. As the \r
+                                                                       <systemitem class="username">root</systemitem> \r
+                                                                       user, perform the following commands:</para>\r
                                                                        <screen>\r
                                                                                <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2</userinput>\r
                                                                                <userinput>cp Open-ILS/examples/apache/eg.conf  /etc/apache2/sites-available/</userinput>\r
@@ -992,11 +1107,11 @@ srfsh#
                                                                        development. As the\r
                                                                        <systemitem class="username">root</systemitem> user, \r
                                                                        perform the following commands:</para>\r
-<screen>\r
-<userinput>mkdir /etc/apache2/ssl</userinput>\r
-<userinput>cd /etc/apache2/ssl</userinput>\r
-<userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>\r
-</screen>\r
+                                                                       <screen>\r
+                                                                               <userinput>mkdir /etc/apache2/ssl</userinput>\r
+                                                                               <userinput>cd /etc/apache2/ssl</userinput>\r
+                                                                               <userinput>openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>\r
+                                                                       </screen>\r
                                                                        <note>\r
                                                                                <para>This step generates a self-signed SSL\r
                                                                                certificate. You must install a proper SSL\r
@@ -1004,9 +1119,6 @@ srfsh#
                                                                                avoid warning messages when users login to their\r
                                                                                account through the OPAC or when staff login\r
                                                                                through the staff client.</para>\r
-                                                                               <para>For further information on getting a proper\r
-                                                                               SSL certificate, see\r
-                                                                               <xref linkend="serversideinstallation-ssl"/>.</para>\r
                                                                        </note>\r
                                                                </step>\r
                                                                <step xml:id="serversideinstallation-modify-apache">\r
@@ -1020,25 +1132,16 @@ srfsh#
                                                                                <listitem>\r
                                                                                        <para>Comment out the line <literal>Allow\r
                                                                                        from 10.0.0.0/8</literal> and uncomment\r
-                                                                                       the line <literal>Allow from\r
-                                                                                       all</literal>.</para>\r
-                                                                                       <para>This change allows access to your\r
-                                                                                       configuration CGI scripts from \r
-                                                                                       <emphasis role="bold">any</emphasis> workstation on\r
-                                                                                       <emphasis role="bold">any</emphasis>\r
-                                                                                       network. This is only a temporary change\r
-                                                                                       to expedite testing and should be removed\r
-                                                                                       after you have finished and successfully\r
-                                                                                       tested the Evergreen installation.</para>\r
-                                                                                       <warning>\r
-                                                                                               <para>\r
-                                                                                                       <emphasis>You must remove these changes\r
-                                                                                               after testing is completed. See \r
-                                                                                               <xref linkend="serversideinstallation-postinstallation"/>\r
-                                                                                               for further details on removing this change \r
-                                                                                               after the Evergreen installation is\r
-                                                                                               complete.</emphasis>\r
-                                                                                               </para>\r
+                                                                                       the line <literal>Allow from all</literal>.</para>\r
+                                                                                       <warning>This change allows access to your\r
+                                                                                       configuration CGI scripts from any workstation on\r
+                                                                                       any network. This is only a temporary change to\r
+                                                                                       expedite testing and should be removed after you\r
+                                                                                       have finished and successfully tested the Evergreen\r
+                                                                                       installation. See \r
+                                                                                       <xref linkend="serversideinstallation-postinstallation"/>\r
+                                                                                       for further details on removing this change after\r
+                                                                                       the Evergreen installation is complete.\r
                                                                                        </warning>\r
                                                                                </listitem>\r
                                                                                <listitem>\r
@@ -1080,32 +1183,6 @@ srfsh#
                                                                                </listitem>\r
                                                                        </itemizedlist>\r
                                                                </step>\r
-                                                               <step performance="optional">\r
-                                                                       <title>(OPTIONAL) Apache Performance Modifications</title>\r
-                                                                       <para>Some 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 <systemitem class="username">root</systemitem> \r
-                                                                       user, edit the Apache configuration file\r
-                                                                       <filename>/etc/apache2/apache2.conf</filename> and add the\r
-                                                                       lines <literal>KeepAliveTimeout 1</literal> and\r
-                                                                       <literal>MaxKeepAliveRequests 100</literal>, or modify any\r
-                                                                       existing lines. Then locate the section related to\r
-                                                                       <emphasis>prefork configuration</emphasis> and modify it\r
-                                                                       to suit the load on your system:</para>\r
-<programlisting language="xml">\r
-<![CDATA[\r
-<IfModule mpm_prefork_module>\r
-   StartServers                  20\r
-   MinSpareServers        5\r
-   MaxSpareServers       15\r
-   MaxClients           150\r
-   MaxRequestsPerChild 10000\r
-</IfModule>\r
-]]>\r
-</programlisting>\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
@@ -1113,10 +1190,10 @@ srfsh#
                                                                        the following Apache configuration commands to disable the default\r
                                                                        <emphasis>It Works</emphasis> web page and enable the\r
                                                                        Evergreen web site:</para>\r
-<screen>\r
-<userinput>a2dissite default</userinput>\r
-<userinput>a2ensite eg.conf</userinput>\r
-</screen>\r
+                                                                       <screen>\r
+                                                                               <userinput>a2dissite default</userinput>\r
+                                                                               <userinput>a2ensite eg.conf</userinput>\r
+                                                                       </screen>\r
                                                                </step>\r
                                                        </substeps>\r
                                                </step>\r
@@ -1248,8 +1325,7 @@ srfsh#
                                                        for testing.</para>\r
                                                </step>\r
                                        </substeps>\r
-<programlisting language="xml">\r
-<![CDATA[\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
@@ -1263,8 +1339,7 @@ srfsh#
 <!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->\r
 <loglevel>4</loglevel>\r
 </srfsh>\r
-]]>\r
-</programlisting>\r
+]]></programlisting>\r
                                </step>\r
                                <step xml:id="serversideinstallation-opensrf-env">\r
                                        <title>Modify the OpenSRF Environment</title>\r
@@ -1282,16 +1357,16 @@ srfsh#
                                                        environment.</emphasis>\r
                                                </para>\r
                                        </note>\r
-<screen>\r
-<userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>\r
-<userinput>. ~/.bashrc</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc</userinput>\r
+                                               <userinput>. ~/.bashrc</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\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 <xref linkend="localization"/>.</para>\r
+                                       the OPAC and staff client. For further information, see <xref linkend="enabling_and_disabling_localization"/>.</para>\r
                                </step>\r
                        </procedure>\r
                </section>\r
@@ -1303,10 +1378,10 @@ srfsh#
                                        user, start the <systemitem class="service">ejabberd</systemitem> and \r
                                        <systemitem class="service">memcached</systemitem> services\r
                                         (if they are not already running):</para>\r
-<screen>\r
-<userinput>/etc/init.d/ejabberd start</userinput>\r
-<userinput>/etc/init.d/memcached start</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/ejabberd start</userinput>\r
+                                               <userinput>/etc/init.d/memcached start</userinput>\r
+                                       </screen>\r
                                </step>\r
                                <step>\r
                                        <para>As the <systemitem class="username">opensrf</systemitem>\r
@@ -1318,9 +1393,9 @@ srfsh#
                                        <systemitem class="service">router</systemitem> , \r
                                        <systemitem class="service">Perl</systemitem> , and\r
                                        <systemitem class="service">C</systemitem> services:</para>\r
-<screen>\r
-<userinput>$ osrf_ctl.sh -l -a start_all</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>osrf_ctl.sh -l -a start_all</userinput>\r
+                                       </screen>\r
                                        <note>\r
                                                <para>\r
                                                        <emphasis>You can also start Evergreen \r
@@ -1374,23 +1449,23 @@ srfsh#
                                        catalog, and calculate the proximity of locations in the\r
                                        Organizational Unit tree (which allows\r
                                        <emphasis>Holds</emphasis> to work properly):</para>\r
-<screen>\r
-<userinput>cd /openils/bin</userinput>\r
-<userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
-<computeroutput>\r
+                                       <screen>\r
+                                               <userinput>cd /openils/bin</userinput>\r
+                                               <userinput>./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
 </computeroutput>\r
-</screen>\r
+                                       </screen>\r
                                        <para>You must do this the first time you start Evergreen, and\r
                                        after making any changes to the library hierarchy.</para>\r
                                </step>\r
                                <step>\r
                                        <para>As the <systemitem class="username">root</systemitem>\r
                                        user, restart the Apache Web server:</para>\r
-<screen>\r
-<userinput>/etc/init.d/apache2 restart</userinput>\r
-</screen>\r
+                                       <screen>\r
+                                               <userinput>/etc/init.d/apache2 restart</userinput>\r
+                                       </screen>\r
                                        <note>\r
                                                <para>If the Apache Web server was running when you\r
                                                started the OpenSRF services, you might not be able to\r
@@ -1457,8 +1532,101 @@ Updating fieldmapper
                                </itemizedlist>\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 CGI \r
+                               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>\r
+                               <title>Configure a permanent SSL key</title>\r
+                               <para>In a previous step, you used the command <command>openssl</command> to temporarily\r
+                               create a new SSL key for the Apache server. This self-signed certificate was adequate\r
+                               during testing and development, but will continue to generate warnings in the Staff Client \r
+                               and browser. For a public production server you should configure or purchase a signed SSL\r
+                               certificate.</para>\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>Set Up Support For Reports</title>\r
+                               <para>Evergreen reports are extremely powerful but require some simple configuration.\r
+                               This section describes starting and stopping the Reporter daemon processes.</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para>Starting the Reporter Daemon</para>\r
+                                               <para>Once the <systemitem class="daemon">open-ils.reporter</systemitem>\r
+                                               process is running and enabled on the gateway, you can start the\r
+                                               Reporter daemon. That process periodically checks for requests for new\r
+                                               or scheduled reports, then starts them as required.</para>\r
+                                               <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                               start the Reporter daemon using the following command:</para>\r
+                                               <screen>\r
+                                                       <userinput>cd /home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/reporter</userinput>\r
+                                                       <userinput>./clark-kent.pl --daemon</userinput>\r
+                                               </screen>\r
+                                               <para>You can control how the <command>clark-kent.pl</command> utility behaves\r
+                                               by specifying any of several command-line options:</para>\r
+                                               <itemizedlist>\r
+                                                       <listitem><option>--sleep=interval</option> : number of seconds\r
+                                                       to sleep between checks for new reports to run; defaults to\r
+                                                       <literal>10</literal></listitem>\r
+                                                       <listitem><option>--lockfile=filename</option> : where to place\r
+                                                       the lockfile for the process; defaults to\r
+                                                       <filename>/tmp/reporter-LOCK</filename></listitem>\r
+                                                       <listitem><option>--concurrency=integer</option> : number of\r
+                                                       Reporter daemon processes to run; defaults to\r
+                                                       <literal>1</literal></listitem>\r
+                                                       <listitem><option>--bootstrap=filename</option> : OpenSRF\r
+                                                       bootstrap configuration file; defaults to\r
+                                                       <filename>/openils/conf/opensrf_core.xml</filename></listitem>\r
+                                               </itemizedlist>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para>Stopping the Reporter Daemon</para>\r
+                                               <para>To stop the Reporter daemon, you must kill the process and remove\r
+                                               the lockfile. The daemon may have just a single associated process or\r
+                                               there may be several processes if the daemon was started with the optional\r
+                                               <literal>--concurrency</literal> switch. It will also have a lockfile\r
+                                               in the default location.</para>\r
+                                               <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                               execute the following shell commands:</para>\r
+                                               <screen>\r
+                                                       <userinput># find and kill the process ID number(s)</userinput>\r
+                                                       <userinput>kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`</userinput>\r
+                                                       <userinput># remove the lock file</userinput>\r
+                                                       <userinput>rm /tmp/reporter-LOCK</userinput>\r
+                                               </screen>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                       </section>\r
+               </section>\r
                <section xml:id="serversideinstallation-virtual">\r
-                       <title>(OPTIONAL) Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>\r
+                       <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>\r
                        <para>This section describes the installation of Evergreen software in so-called "virtualized"\r
                        software environments. Evergreen software runs as a native application on any of several\r
                        well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>\r
@@ -1496,14 +1664,22 @@ Updating fieldmapper
                                        <application>"VirtualBox"</application> application on \r
                                        <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. \r
                                        Download the latest edition of <application>VirtualBox</application> from their official website: \r
-                                       <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link> and follow the on screen instructions to install the software.</para>\r
+                                       <link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link>\r
+                                       and follow the on screen instructions to install the software.</para>\r
                                </simplesect>\r
                                <simplesect>\r
-                                       <title>Installing <application>"VMware"</application> Virtualization Software</title>\r
+                                       <title>Installing VMware Virtualization Software</title>\r
+                                       <indexterm>\r
+                                               <primary>virtualization software</primary>\r
+                                               <secondary>VMware</secondary>\r
+                                       </indexterm>\r
                                        <para>This section reviews installation of the\r
-                                       <application>"VMware"</application> application on <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. Find and Download the free virtual \r
-                                       machine software of from the VMware official website: <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink> and follow the on \r
-                                       screen instructions.</para>\r
+                                       <application>"VMware"</application> application on\r
+                                       <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. \r
+                                       Find and Download the free virtual machine software of from the VMware\r
+                                       official website:\r
+                                       <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink> \r
+                                       and follow the on-screen instructions.</para>\r
                                </simplesect>\r
                        </simplesect>\r
                        <simplesect xml:id="serversideinstallation-virtual-install-linux-ev">\r
@@ -1521,8 +1697,7 @@ Updating fieldmapper
                                        </listitem>\r
                                        <listitem>\r
                                                <para>Manually install a <systemitem class="osname">Linux</systemitem>\r
-                                               guest system, then manually install Evergreen on it (see \r
-                                               <xref linkend="serversideinstall-virtual-manual"/> for details)</para>\r
+                                               guest system, then manually install Evergreen on it.</para>\r
                                        </listitem>\r
                                </orderedlist>\r
                                <para>We review each method in the following sections.</para>\r
@@ -1578,9 +1753,12 @@ Updating fieldmapper
                                                        </tbody>\r
                                                </tgroup>\r
                                        </table>\r
-                       \r
                                        <procedure>\r
                                                <title>VirtualBox Example</title>\r
+                                               <indexterm>\r
+                                                       <primary>virtualization software</primary>\r
+                                                       <secondary>VirtualBox</secondary>\r
+                                               </indexterm>\r
                                                <step>\r
                                                        <para>Start VirtualBox for the first time and select\r
                                                        <menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media\r
@@ -1611,7 +1789,8 @@ Updating fieldmapper
                                                </step>\r
                                                <step>\r
                                                        <para>Edit the Virtual Hard Disk configuration settings; click\r
-                                                       the radio boxes <guilabel>Boot Hard Disk</guilabel> and <guilabel>Use existing hard disk</guilabel>\r
+                                                       the radio boxes <guilabel>Boot Hard Disk</guilabel> and\r
+                                                       <guilabel>Use existing hard disk</guilabel>\r
                                                        and ensure that the disk name <guilabel>Evergreen1601_DebianLenny.vmdk</guilabel>\r
                                                        is selected. Click <guibutton>Finish</guibutton> to finish the\r
                                                        setup.</para>\r
@@ -1626,11 +1805,15 @@ Updating fieldmapper
                                                        created. Click <guibutton>Start</guibutton> to boot the new VM.</para>\r
                                                </step>\r
                                                <step>\r
-                                                       <para>See the start of the <systemitem class="osname">Linux</systemitem> boot sequence. Choose <guimenuitem>Debian\r
-                                                       Gnu/Linux, kernel 2.6.26-2-686</guimenuitem> from the startup menu and click\r
-                                                       <guibutton>Enter</guibutton> to start <systemitem class="osname">Linux</systemitem> and Evergreen. After\r
-                                                       some delay you should see the command line prompt <prompt>debian-lenny login:</prompt>. Log in with username\r
-                                                       <userinput>root</userinput> and password <userinput>evergreen</userinput> to continue.</para>\r
+                                                       <para>See the start of the <systemitem class="osname">Linux</systemitem>\r
+                                                       boot sequence. Choose <guimenuitem>Debian Gnu/Linux, kernel\r
+                                                       2.6.26-2-686</guimenuitem> from the startup menu and click\r
+                                                       <guibutton>Enter</guibutton> to start \r
+                                                       <systemitem class="osname">Linux</systemitem> and Evergreen. \r
+                                                       After some delay you should see the command line prompt \r
+                                                       <prompt>debian-lenny login:</prompt>. Log in with username\r
+                                                       <userinput>root</userinput> and password <userinput>evergreen</userinput>\r
+                                                       to continue.</para>\r
                                                </step>\r
                                        </procedure>\r
                                </simplesect>\r