review section "Installing OpenSRF", make simple tweaks;
authorSteve Sheppard <sheppards.email@gmail.com>
Tue, 31 Aug 2010 15:20:56 +0000 (11:20 -0400)
committerSteve Sheppard <sheppards.email@gmail.com>
Tue, 31 Aug 2010 15:20:56 +0000 (11:20 -0400)
1.6/admin/ServersideInstallation.xml

index ea8202a..1d3a9a0 100644 (file)
@@ -8,18 +8,18 @@
        </info>
        <section xml:id="serversideinstallation-overview">
                <title>Overview</title>
-               <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current stable software release. See the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-ubuntudebian"> "Installing Evergreen On Ubuntu or Debian" </link></emphasis></emphasis> for instructions tailored to installing on some particular distributions of the Linux operating system. Earlier software distributions are described in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-previousversions"> "Installing Previous Versions of Evergreen" </link></emphasis></emphasis>.</para>
-               <para>Current versions of the Evergreen server-side software run as native applications on any of several well-known Linux distributions (e.g., <emphasis>Ubuntu</emphasis> and <emphasis>Debian</emphasis>). It does not currently run as a native application on the Windows operating system (e.g., WindowsXP, WindowsXP Professional, Windows7), but the software can still be installed and run on Windows via a so-called <emphasis>virtualized</emphasis> Unix-guest Operating System (using, for example, VirtualBox, or VMware, or VirtualPC to emulate a Linux environment). It can also be installed and run on other Linux systems via virtualized environments (using, for example, VirtualBox or VMware). More information on virtualized environments can be found in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-virtual">"Installing Evergreen in Virtualized Unix Environments"</link></emphasis></emphasis>.</para>
+               <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current stable software release. See the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-all">"Installation of Server-Side Software"</link></emphasis></emphasis> for instructions tailored to installing on some particular distributions of the Linux operating system. Earlier software distributions are described in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-previousversions"> "Installing Previous Versions of Evergreen" </link></emphasis></emphasis>.</para>
+               <para>The current version of the Evergreen server-side software runs as a native application on any of several well-known Linux distributions (e.g., <emphasis>Ubuntu</emphasis> and <emphasis>Debian</emphasis>). It does not currently run as a native application on the Windows operating system (e.g., WindowsXP, WindowsXP Professional, Windows7), but the software can still be installed and run on Windows via a so-called <emphasis>virtualized</emphasis> Unix-guest Operating System (using, for example, VirtualBox, or VMware, or VirtualPC to emulate a Linux environment). It can also be installed to run on other Linux systems via virtualized environments (using, for example, VirtualBox or VMware). More information on virtualized environments can be found in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-virtual">"Installing Evergreen in Virtualized Unix Environments"</link></emphasis></emphasis>.</para>
                <para>Installation of some sub-components of the Evergreen server-side software is mentioned only in abbreviated form in this section. More detailed information is available in the accompanying sections:
-<emphasis><emphasis role="bold"><link linkend="serversideinstallation-opensrf"> "Installing OpenSRF On Ubuntu or Debian" </link></emphasis></emphasis>, 
 <emphasis><emphasis role="bold"><link linkend="serversideinstallation-postgresql"> "Installing PostgreSQL" </link></emphasis></emphasis>, 
 <emphasis><emphasis role="bold"><link linkend="serversideinstallation-apache"> "Apache" </link></emphasis></emphasis> and
 <emphasis><emphasis role="bold"><link linkend="serversideinstallation-memcached"> "memcached Servers" </link></emphasis></emphasis>.
-               </para>
+</para>
+               <para>[[ FURTHER REFINEMENT NEEDED HERE ]]</para>
                <para>Finally, installation of the Evergreen Staff Client software is reviewed in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-staffclient"> "Running the Evergreen Staff Client" </link></emphasis></emphasis>. </para>
                <section>
                        <title>Evergreen Software Dependencies</title>
-                       <para>The Evergreen server-side software is keyed to certain major software sub-components in the Evergreen environment. Successful installation of Evergreen software requires that software versions agree with those listed here:</para>
+                       <para>The Evergreen server-side software has dependencies on particular versions of certain major software sub-components. Successful installation of Evergreen software requires that software versions agree with those listed here:</para>
                        <figure>
                                <title>Evergreen software dependencies</title>
                                <informaltable>
@@ -64,7 +64,7 @@
                        <title>Current Stable Software Release</title>
                        <para>The current stable release of Evergreen is version <emphasis><emphasis role="bold">1.6.0.7</emphasis></emphasis>. Instructions for installing, configuring and testing that version on the <emphasis>Ubuntu</emphasis> or <emphasis>Debian</emphasis> Linux systems are found in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-ubuntudebian"> "Installing Evergreen on Ubuntu or Debian" </link></emphasis></emphasis> .
                        </para>
-                       <para>This release of Evergreen software is dependent on the Open Service Request Framework (OpenSRF) software framework. The current stable release of OpenSRF is version <emphasis><emphasis role="bold">1.2.2</emphasis></emphasis>. Instructions for installing, configuring and testing that version are found in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-opensrf"> "Installing OpenSRF" </link></emphasis></emphasis> .</para>
+                       <para>This release of Evergreen software is dependent on the Open Service Request Framework (OpenSRF). The current stable release of OpenSRF is version <emphasis><emphasis role="bold">1.2.2</emphasis></emphasis>. Instructions for installing, configuring and testing that version are found in the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-opensrf"> "Installing OpenSRF On Ubuntu or Debian" </link></emphasis></emphasis> .</para>
                </section>
                <section>
                        <title>Previous Software Releases</title>
                <section>
                        <title>Example System Architectures</title>
                        <para>This sections describes examples of some working Evergreen system architectures, including both server-side software and Staff Client software.</para>
-                       <para>A bare-minimum system Evergreen system requires only a single Server and a single Staff Client, both residing on a single server machine. In fact, that is a reasonable architecture for simple experiments or as a proof of concept in a conference-room pilot. But typical real-world systems will probably consist of at least one or two Evergreen servers plus multiple Staff Clients.</para>
-                       <para>Another simple system may require only that you install one or more instances of the Staff Client software. For instance, if your consortium already provides the Evergreen server software or if you are using the hosted version provided by Equinox, you do not need to install the Evergreen server-side software at all.</para>
+                       <para>A bare-minimum system requires only a single Evergreen Server and a single Evergreen Staff Client, both residing on a single server machine. In fact, that is a reasonable architecture for simple experiments or as a proof of concept in a conference-room pilot. But typical real-world systems will probably consist of at least one or two Evergreen Servers plus multiple Staff Clients.</para>
+                       <para>Another simple system may require only that you install one or more instances of the Staff Client software. For instance, if your consortium already provides the Evergreen server software or if you are using the hosted version provided by Equinox, you do not need to install the Evergreen server-side software at all; you need only the Staff Client.</para>
                        <section xml:id="serversideinstallation-example-pines">
                                <title>PINES</title>
                                <para>In order to provide load balancing and high-availability at the OPAC and Staff Client level, PINES has implemented a Linux Virtual Server environment with five independent mini-clusters. This allows live updates of the entire system with no perceived downtime or interruption in service.</para>
        </section>
        <section xml:id="serversideinstallation-all">
                <title>Installation of Server-Side Software</title>
-               <para>This section describes the installation of the major components of Evergreen server-side software, including the Open Service Request Framework (OpenSRF), and Evergreen itself.</para>
-               <para>As far as possible, perform the following steps in the exact order they are given since the success of many steps relies on the successful completion of earlier steps. You should make backup copies of files and environments when you are instructed to do so. In the event of installation problems those copies can allow you to back out of a step gracefully and resume the installation from a known state. See the section on <emphasis><emphasis role="bold"><link linkend="adminmisc-backingup"> "Backing Up" </link></emphasis></emphasis>  for further information.</para>
+               <para>This section describes the installation of the major components of Evergreen server-side software.</para>
+               <para>As far as possible, you should perform the following steps in the exact order given since the success of many steps relies on the successful completion of earlier steps. You should make backup copies of files and environments when you are instructed to do so. In the event of installation problems those copies can allow you to back out of a step gracefully and resume the installation from a known state. See the section on <emphasis><emphasis role="bold"><link linkend="adminmisc-backingup"> "Backing Up" </link></emphasis></emphasis>  for further information.</para>
                <para>Of course, after you successfully complete and test the entire Evergreen installation you should take a final snapshot backup of your system(s). This can be the first in the series of regularly scheduled system backups that you should probably also begin.</para>
                <section xml:id="serversideinstallation-opensrf">
                        <title>Installing OpenSRF On Ubuntu or Debian</title>
                                <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) platforms. OpenSRF 1.2.0 has been tested on Debian Etch (4.0), Debian Lenny, Ubuntu Hardy Heron (8.04), and Ubuntu Intrepid Ibex (8.10).</para>
                                <para>In the following instructions, you are asked to perform certain steps as either the <emphasis role="bold">root</emphasis> user, the <emphasis role="bold">opensrf</emphasis> user, or the <emphasis role="bold">postgres</emphasis> user.</para>
                                <itemizedlist>
-                                       <listitem><emphasis role="bold">Debian</emphasis> To become the <emphasis>root</emphasis> user, issue the command <emphasis role="bold">su -</emphasis> and enter the password of the root user.</listitem>
-                                       <listitem><emphasis role="bold">Ubuntu</emphasis> To become the <emphasis>root</emphasis>  user, issue the command <emphasis role="bold">sudo su -</emphasis> and enter the password of your current user.</listitem>
+                                       <listitem><emphasis role="bold">Debian</emphasis> -- To become the <emphasis>root</emphasis> user, issue the command <emphasis role="bold">"su -"</emphasis> and enter the password of the root user.</listitem>
+                                       <listitem><emphasis role="bold">Ubuntu</emphasis> -- To become the <emphasis>root</emphasis>  user, issue the command <emphasis role="bold">"sudo su -"</emphasis> and enter the password of your current user.</listitem>
                                </itemizedlist>
-                               <para>To switch from the <emphasis role="bold">root</emphasis> user to a different user, issue the command <emphasis role="bold">su - USERNAME</emphasis>. For example, to switch from the <emphasis role="bold">root</emphasis> user to the <emphasis role="bold">opensrf</emphasis> user, issue the command <emphasis role="bold">su - opensrf</emphasis>. Once you have become a non-root user, to become the <emphasis role="bold">root</emphasis> user again, simply issue the command <emphasis role="bold">exit</emphasis>.</para>
+                               <para>To switch from the <emphasis role="bold">root</emphasis> user to a different user, issue the command <emphasis role="bold">"su - USERNAME"</emphasis>. For example, to switch from the <emphasis role="bold">root</emphasis> user to the <emphasis role="bold">opensrf</emphasis> user, issue the command <emphasis role="bold">"su - opensrf"</emphasis>. Once you have become a non-root user, to become the <emphasis role="bold">root</emphasis> user again, simply issue the command <emphasis role="bold">"exit"</emphasis>.</para>
                        </note>
                        <section>
                                <title>Add the OpenSRF User</title>
                                <para>As the <emphasis role="bold">root</emphasis> user, add the opensrf user to the system. The default shell for the new user is automatically set to <emphasis role="bold">/bin/bash</emphasis> to inherit a reasonable environment:</para>
                                <figure>
-                                       <title>Add the user "opensrf"</title>
+                                       <title>Adding the user "opensrf"</title>
                                        <screen>
                                        $ su - opensrf
                                        $ useradd -m -s /bin/bash opensrf
                                        $ passwd opensrf
+                                       Enter new UNIX password: ******
+                                       Retype new UNIX password: ******
+                                       passwd: password updated successfully
+                                       $
                                        </screen>
                                </figure>
                        </section>
                        <section>
                                <title>Download and Unpack Latest OpenSRF Version</title>
                                <para>As the <emphasis role="bold">opensrf</emphasis> user, download and extract the latest version of OpenSRF. The latest version can be found here: <emphasis><emphasis role="bold"><ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.2.2.tar.gz"></ulink></emphasis></emphasis></para>
-                               <para>[[ VERIFY LOCATION OF LATEST VERSION OF OPENSRF ]]</para>
                                <figure>
-                                       <title>Commands to download/extract OpenSRF</title>
+                                       <title>Commands to download and unpack OpenSRF</title>
                                        <screen>
                                        $ su - opensrf
                                        $ wget http://evergreen-ils.org/downloads/OpenSRF-1.2.2.tar.gz
                        </section>
                        <section>
                                <title>Install Prerequisites to Build OpenSRF</title>
-                               <para>In this step you will install and configure a set of prerequisites used to build OpenSRF. In a following step you will actually build the software using the <emphasis>make</emphasis> utility.</para>
-                               <para>As the <emphasis role="bold">root</emphasis> user, enter the commands show below in <emphasis>Figure 1.5</emphasis> to build the prerequisites from the software distribution that you just downloaded and unpacked. Remember to replace <emphasis>[distribution]</emphasis> in the example with the keyword corresponding to the actual Linux distribution listed here:</para>
-                               <para>[[ ADD INFO FOR OTHER LINUX DISTRIBUTIONS ]]</para>
+                               <para>In this section you will install and configure a set of prerequisites that will be used to build OpenSRF. In a following step you will actually build the software using the <emphasis>make</emphasis> utility.</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, enter the commands show below to build the prerequisites from the software distribution that you just downloaded and unpacked. Remember to replace <emphasis>[distribution]</emphasis> in the example with the keyword corresponding to the actual Linux distribution listed in <emphasis>Figure 1.5</emphasis>.</para>
+                               <figure>
+                                       <title>Commands to install prerequisites for OpenSRF</title>
+                                       <screen>
+                                       $ su - root
+                                       $ cd /home/opensrf/OpenSRF-1.2.2
+                                       $ make -f src/extras/Makefile.install [distribution]
+                                       </screen>
+                               </figure>
                                <figure>
                                        <title>Keywords used with "make"</title>
                                        <informaltable>
                                                        <tbody>
                                                                <row>
                                                                        <entry>debian-lenny</entry>
-                                                                       <entry>for Debian Lenny (5.0), the most recent version</entry>
+                                                                       <entry>for Debian Lenny (5.0)</entry>
                                                                </row>
                                                        </tbody>
                                                        <tbody>
                                                        </tbody>
                                                        <tbody>
                                                                <row>
-                                                                       <entry>ubuntu-intrepid</entry>
-                                                                       <entry>for Ubuntu Jaunty (9.04)</entry>
+                                                                       <entry>ubuntu-karmic</entry>
+                                                                       <entry>for Ubuntu Karmic (9.10)</entry>
                                                                </row>
                                                        </tbody>
                                                        <tbody>
                                                                <row>
                                                                        <entry>ubuntu-intrepid</entry>
-                                                                       <entry>for Ubuntu Intrepid (8.10)</entry>
+                                                                       <entry>for Ubuntu Jaunty (9.04) or Intrepid (8.10)</entry>
                                                                </row>
                                                        </tbody>
                                                        <tbody>
                                                </tgroup>
                                        </informaltable>
                                </figure>
-                               <figure>
-                                       <title>Commands to install prerequisites for OpenSRF</title>
-                                       <screen>
-                                       $ su - root
-                                       $ cd /home/opensrf/OpenSRF-1.2.2
-                                       $ make -f src/extras/Makefile.install [distribution]
-                                       </screen>
-                               </figure>
+                               <para>[[ ADD INFO FOR OTHER LINUX DISTRIBUTIONS ]]</para>
                                <para>This will install a number of packages required by OpenSRF on your system, including some Perl modules from CPAN. You can say "no" to the initial CPAN configuration prompt to allow it to automatically configure itself to download and install Perl modules from CPAN. The CPAN installer will ask you a number of times whether it should install prerequisite modules - say "yes".</para>
                        </section>
                        <section>
                                <title>Configure OpenSRF</title>
-                               <para>As the <emphasis role="bold">opensrf</emphasis> user, configure OpenSRF by preparing a "make" file to be used in the next step to compile and link OpenSRF. You can include the <emphasis>--enable-python</emphasis>  and <emphasis>--enable-java</emphasis> configure options if you want to include support for Python and Java, respectively:</para>
+                               <para>As the <emphasis role="bold">opensrf</emphasis> user, return to your build directory and configure OpenSRF by using the utility "configure" to prepare for the next step of compiling and linking the software. You can include the <emphasis>--enable-python</emphasis>  and <emphasis>--enable-java</emphasis> configuration options if you want to include support for Python and Java, respectively:</para>
                                <figure>
-                                       <title>Commands to prepare make file for OpenSRF</title>
+                                       <title>Commands to configure OpenSRF</title>
                                        <screen>
                                        $ su - opensrf
                                        $ cd /home/opensrf/OpenSRF-1.2.2
                                </figure>
                        </section>
                        <section>
-                               <title>Compile and link OpenSRF</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, return to your OpenSRF build directory and compile, link and install OpenSRF:</para>
+                               <title>Compile, Link and Install OpenSRF</title>
+                               <para>As the <emphasis role="bold">root</emphasis> user, return to your build directory and compile, link and install OpenSRF:</para>
                                <figure>
-                                       <title>Commands to build OpenSRF</title>
+                                       <title>Commands to build, link and install OpenSRF</title>
                                        <screen>
                                        $ su - opensrf
                                        $ cd /home/opensrf/OpenSRF-1.2.2
                                </figure>
                        </section>
                        <section>
-                               <title>Update the system dynamic library path</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating a new file named <emphasis role="bold">/etc/ld.so.conf.d/eg.conf</emphasis> containing two new library paths, then run the command <emphasis role="bold">ldconfig</emphasis> to automatically read the file and modify the dynamic library path:</para>
+                               <title>Update the System Dynamic Library Path</title>
+                               <para>As the <emphasis role="bold">root</emphasis> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating a new file named <emphasis role="bold">/etc/ld.so.conf.d/osrf.conf</emphasis> containing a new library path, then run the command <emphasis role="bold">ldconfig</emphasis> to automatically read the file and modify the system dynamic library path:</para>
                                <figure>
                                        <title>Commands to modify system dynamic library path</title>
                                        <screen>
                                        $ su - root
-                                       $ cat > /etc/ld.so.conf.d/eg.conf &lt;&lt; ENDOFFILE
-                                       /usr/local/lib
-                                       /usr/local/lib/dbd
-                                       ENDOFFILE
+                                       $ echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf
                                        $ ldconfig
                                        </screen>
                                </figure>
                        </section>
                        <section>
-                               <title>Define public and private OpenSRF domains</title>
-                               <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <emphasis>public.localhost</emphasis>  for the public domain and <emphasis>private.localhost</emphasis> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the file <emphasis>/etc/hosts</emphasis>. Here are the entries to add to a stock file <emphasis>/etc/hosts</emphasis> for our example domains:</para>
+                               <title>Define Public and Private OpenSRF Domains</title>
+                               <para>Define your public and private OpenSRF domains. For security purposes, OpenSRF uses Jabber domains to separate services into public and private realms. Throughout these instructions, we will use the example domains <emphasis>public.localhost</emphasis>  for the public domain and <emphasis>private.localhost</emphasis> for the private domain. On a single-server system, the easiest way to define public and private domains is to define separate hostnames by adding entries to the file <emphasis>/etc/hosts</emphasis>.</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, edit the file <emphasis>/etc/hosts</emphasis> and add the following entries for our example domains:</para>
                                <figure>
-                                       <title>Entries to add to /etc/hosts</title>
+                                       <title>Adding public and private domains to /etc/hosts</title>
                                        <screen>
+                                       127.0.1.2       public.localhost        public
                                        127.0.1.3       private.localhost       private
                                        </screen>
                                </figure>
                        </section>
                        <section>
                                <title>Change file ownerships</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, change the ownership of the installed files to the opensrf user:</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, change the ownership of files installed in the directory <emphasis>/openils</emphasis> to the user "opensrf":</para>
                                <figure>
-                                       <title>Entries to add to /etc/hosts</title>
+                                       <title>Changing file ownerships in /openils</title>
                                        <screen>
-                                       chown -R opensrf:opensrf /openils
+                                       chown -R opensrf:opensrf /openils
                                        </screen>
                                </figure>
                        </section>
                                <title>Stop the "ejabberd" service</title>
                                <para>As the <emphasis role="bold">root</emphasis> user, stop the "ejabberd" service:</para>
                                <figure>
-                                       <title>Stop the "ejabberd" service</title>
+                                       <title>Stopping the "ejabberd" service</title>
                                        <screen>
                                        $ /etc/init.d/ejabberd stop
                                        </screen>
                                </figure>
                                <para>If "ejabberd" reports that it is already stopped, it may have run into a problem starting back at the installation stage. One possible fix is to kill any remaining <emphasis>beam</emphasis> and <emphasis>epmd</emphasis> processes, then edit the <emphasis>ejabberd</emphasis> configuration file to hardcode a domain:</para>
                                <figure>
-                                       <title>Stop the "ejabberd" service</title>
+                                       <title>Recovering from "ejabberd" error</title>
                                        <screen>
                                        $ su - root
                                        $ epmd -kill
                        </section>
                        <section>
                                <title>Edit the "ejabberd" configuration</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, edit <emphasis>/etc/ejabberd/ejabberd.cfg</emphasis> :</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, edit the file <emphasis>/etc/ejabberd/ejabberd.cfg</emphasis> and make the following changes:</para>
                                <itemizedlist>
-                                       <listitem>Change <screen>{hosts, ["localhost"]}.</screen> to <screen>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</screen></listitem>
+                                       <listitem>Change <emphasis role="bold">{hosts, ["localhost"]}.</emphasis>  to <emphasis role="bold">{hosts, ["localhost", "private.localhost", "public.localhost"]}.</emphasis></listitem>
                                        <listitem>Change <emphasis role="bold">{max_user_sessions, 10}.</emphasis> to <emphasis role="bold">{max_user_sessions, 10000}.</emphasis>  If you see something like this instead: <emphasis role="bold">{access, max_user_sessions, [{10, all}]}.</emphasis>, then change it to <emphasis role="bold">{access, max_user_sessions, [{10000, all}]}.</emphasis></listitem>
                                        <listitem>Change all three occurrences of <emphasis role="bold">max_stanza_size</emphasis> to <emphasis role="bold">2000000</emphasis>.</listitem>
                                        <listitem>Change both occurrences of <emphasis role="bold">maxrate</emphasis> to <emphasis role="bold">500000</emphasis>.       </listitem>
-                                       <listitem>Comment out the <emphasis role="bold">{mod_offline</emphasis> line by placing two <emphasis role="bold">%</emphasis> signs in front.</listitem>
+                                       <listitem>Comment out the line <emphasis role="bold">{mod_offline, []}</emphasis>  by placing two <emphasis role="bold">%</emphasis> comment signs in front.</listitem>
                                </itemizedlist>
                        </section>
                        <section>
                                        <listitem>a "router" user, to whom all requests to connect to an OpenSRF service will be routed; this "ejabberd" user must be named "router"</listitem>
                                        <listitem>an "opensrf" user, which clients use to connect to OpenSRF services; this user can be named anything you like, but we will use "opensrf" in our examples</listitem>
                                </itemizedlist>
-                               <para>As the <emphasis role="bold">root</emphasis> user, register your ejabber users <emphasis>router</emphasis> and <emphasis>opensrf</emphasis> for the OpenSRF router service on each domain. The users should have different passwords on each domain. These users will correspond to your configuration in <emphasis>opensrf_core.xml</emphasis>:</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, use the utility "ejabberdctl" to register your ejabber users <emphasis>router</emphasis> and <emphasis>opensrf</emphasis> for the OpenSRF router service on each domain. The users should have different passwords on each domain. These users will correspond to those configured in the file <emphasis>/openils/conf/opensrf_core.xml</emphasis>:</para>
                                <figure>
-                                       <title>Register "router" and "ejabberd" users</title>
+                                       <title>Registering "router" and "ejabberd" users</title>
                                        <screen>
                                        # Syntax for registering a user with ejabberdctl:
                                        #    ejabberdctl register &lt;user> &lt;domain> &lt;password>
                        </section>
                        <section>
                                <title>Create configuration files</title>
-                               <para>As the <emphasis role="bold">opensrf</emphasis> user, create the configuration files <emphasis> /openils/conf/opensrf_core.xml</emphasis> and <emphasis>/openils/conf/opensrf.xml</emphasis> from the example templates:</para>
+                               <para>As the <emphasis role="bold">opensrf</emphasis> user, use the example templates to create the configuration files <emphasis>/openils/conf/opensrf_core.xml</emphasis> and <emphasis>/openils/conf/opensrf.xml</emphasis>:</para>
                                <figure>
-                                       <title>Commands to copy OpenSRF configuration files</title>
+                                       <title>Creating configuration files</title>
                                        <screen>
                                        $ su - root
-                                       $ cp /openils/conf/opensrf.xml.example      /openils/conf/opensrf.xml
-                                       $ cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
+                                       $ cd /openils/conf
+                                       $ cp opensrf.xml.example      opensrf.xml
+                                       $ cp opensrf_core.xml.example opensrf_core.xml
                                        </screen>
                                </figure>
                        </section>
                                <figure>
                                        <title>Updates needed to the file "/openils/conf/opensrf_core.xml"</title>
                                        <screen>
-                                       /config/opensrf/username  = opensrf
+                                       /config/opensrf/username = opensrf
 
-                                       /config/opensrf/passwd    = password for "private.localhost" opensrf user
+                                       /config/opensrf/passwd = password for "private.localhost" opensrf user
 
-                                       /config/gateway/username  = opensrf
+                                       /config/gateway/username = opensrf
 
-                                       /config/gateway/passwd    = password for "public.localhost" opensrf user
+                                       /config/gateway/passwd = password for "public.localhost" opensrf user
 
                                        # first entry, where "transport/server" == "public.localhost" :
                                        /config/routers/router/transport 
                                            password = password for "private.localhost" router user
                                        </screen>
                                </figure>
-                               <para>You also need to specify the domains from which Evergreen will accept and to which Evergreen will make connections. If you are installing OpenSRF on a single server and using the "private.localhost" / "public.localhost" domains, these will already be set to the correct values. Otherwise, search and replace to match your values.</para>
+                               <para>You also need to specify the domains from which OpenSRF will accept and to which OpenSRF will make connections. If you are installing OpenSRF on a single server and using the "private.localhost" / "public.localhost" domains, these will already be set to the correct values. Otherwise, search and replace to match your values.</para>
                        </section>
                        <section>
-                               <title>Edit opensrf.xml</title>
-                               <para>Edit the file <emphasis>/openils/conf/opensrf.xml</emphasis> to set the location of the persistent database in the <emphasis role="bold">&lt;dbfile></emphasis> element near the end of the file:</para>
+                               <title>Modify the file "opensrf.xml"</title>
+                               <para>Modify the file <emphasis>/openils/conf/opensrf.xml</emphasis>.</para>
+                               <para>As the <emphasis role="bold">opensrf</emphasis> user, edit the file to set the location of the persistent database in the <emphasis role="bold">&lt;dbfile></emphasis> element near the end of the file:</para>
                                <figure>
-                                       <title>example of file "opensrf.xml"</title>
+                                       <title>Modify the file "opensrf.xml"</title>
                                        <screen>
                                        &lt;!-- Example of an app-specific setting override -->
                                        &lt;opensrf.persist>
                                </figure>
                        </section>
                        <section>
-                               <title>Copy srfsh.xml.example</title>
-                               <para>In this step you will set up a special configuration file for each user who will need to run the utility. Copy the short sample configuration file <emphasis>/openils/conf/srfsh.xml.example</emphasis> to the file <emphasis>.srfsh.xml</emphasis> (note the leading dot!) in the home directory of each user who will use <emphasis role="bold">srfsh</emphasis>. Finally, edit each file <emphasis>.srfsh.xml</emphasis> and make the following changes:</para>
+                               <title>Create Configuration Files for Users Needing srfsh</title>
+                               <para>In this section you will set up a special configuration file for each user who will need to run the <emphasis>srfsh</emphasis> (surf shell) utility.</para>
+                               <para>The software installation will automatically create <emphasis>srfsh</emphasis>. This is a command line diagnostic tool for testing and interacting with the OpenSRF network software. It will be used in a future step to complete and test the Evergreen installation. See the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-testing"> "Testing the Installation" </link></emphasis></emphasis> for further information.</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, copy the short sample configuration file <emphasis>/openils/conf/srfsh.xml.example</emphasis> to the file <emphasis>.srfsh.xml</emphasis> (note the leading dot!) in the home directory of each user who will use <emphasis role="bold">srfsh</emphasis>. Finally, edit each file <emphasis>.srfsh.xml</emphasis> and make the following changes. When you finish, remember to change the owner of the file to match the owner of the home directory.</para>
                                <itemizedlist>
-                                       <listitem>Modify <emphasis role="bold">domain</emphasis> to be the router hostname (following our domain examples, <emphasis role="bold">private.localhost</emphasis> will give <emphasis role="bold">srfsh</emphasis> access to all OpenSRF services, while <emphasis role="bold">public.localhost</emphasis> will only allow access to those OpenSRF services that are publicly exposed).</listitem>
+                                       <listitem>Modify <emphasis role="bold">domain</emphasis> to be the router hostname (following our domain examples, <emphasis role="bold">private.localhost</emphasis> will give <emphasis>srfsh</emphasis> access to all OpenSRF services, while <emphasis role="bold">public.localhost</emphasis> will only allow access to those OpenSRF services that are publicly exposed).</listitem>
                                        <listitem>Modify <emphasis role="bold">username</emphasis> and <emphasis role="bold">password</emphasis> to match the <emphasis role="bold">opensrf</emphasis> Jabber user for the chosen domain</listitem>
                                        <listitem>Modify <emphasis role="bold">logfile</emphasis> to be the full path for a log file to which the user has write access</listitem>
                                        <listitem>Modify <emphasis role="bold">loglevel</emphasis> as needed for testing</listitem>
                                <title>Modify environmental variable PATH for "opensrf" user</title>
                                <para>As the <emphasis role="bold">opensrf</emphasis> user, modify the environmental variable PATH by adding a new file path to the <emphasis>opensrf</emphasis> user's shell configuration file <emphasis>.bashrc</emphasis>:</para>
                                <figure>
-                                       <title>Add path to ".bashrc" configuration file</title>
+                                       <title>Adding path to ".bashrc" configuration file</title>
                                        <screen>
+                                       $ su - opensrf
                                        $ echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc
-                                       $ exit
                                        </screen>
                                </figure>
                        </section>
                        <section>
                                <title>Starting OpenSRF</title>
-                               <para>Before starting OpenSRF, ensure that the "ejabberd" and "memcached" daemons are running.</para>
                                <para>As the <emphasis role="bold">root</emphasis> user, start the "ejabberd" and "memcached" services:</para>
                                <figure>
-                                       <title>Start some services</title>
+                                       <title>Starting some services</title>
                                        <screen>
                                        $ su - root
                                        $ /etc/init.d/ejabberd start
                                        $ /etc/init.d/memcached start
                                        </screen>
                                </figure>
-                               <para>As the <emphasis role="bold">root</emphasis> user, OpenSRF:</para>
+                               <para/>
+                               <para>Finally, as the <emphasis role="bold">opensrf</emphasis> user, start OpenSRF:</para>
                                <figure>
-                                       <title>Start OpenSRF</title>
+                                       <title>Starting OpenSRF</title>
                                        <screen>
                                        $ su - opensrf
 
                                </figure>
                                <note>
                                        <para>
-                                               <emphasis> You can also start Evergreen <emphasis role="bold">without</emphasis> the <emphasis>-l</emphasis> flag, but <emphasis>osrf_ctl.sh</emphasis> must know the fully qualified domain name for the system on which it will execute. That hostname may have been specified in the configuration file <emphasis>opensrf.xml</emphasis>, which you configured in a previous step.</emphasis>
+                                               <emphasis>You can also start Evergreen <emphasis role="bold">without</emphasis> the <emphasis>-l</emphasis> flag, but <emphasis>osrf_ctl.sh</emphasis> must know the fully qualified domain name for the system on which it will execute. That hostname may have been specified in the configuration file <emphasis>opensrf.xml</emphasis>, which you configured in a previous step.</emphasis>
                                        </para>
                                </note>
                        </section>
                        <section>
                                <title>Testing connections to OpenSRF</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, test your connection to OpenSRF by executing the utility <emphasis>srfsh</emphasis> and trying to call the <emphasis>add</emphasis> method on the OpenSRF "math" service:</para>
+                               <para>Once you have installed and started OpenSRF, as the <emphasis role="bold">root</emphasis> user, test your connection to OpenSRF using the utility <emphasis>srfsh</emphasis> and trying to call the <emphasis>add</emphasis> method on the OpenSRF "math" service:</para>
                                <figure>
-                                       <title>Testing OpenSRF with the "math" method</title>
+                                       <title>Testing OpenSRF with "srfsh"</title>
                                        <screen>
                                        $ su - opensrf
                                        $ /openils/bin/srfsh
                                        srfsh#
                                        </screen>
                                </figure>
+                               <para>[[ VERIFY THIS TEST ]]</para>
                                <para>For other srfsh commands, type 'help' in at the prompt.</para>
                        </section>
                        <section>
                                <title>Stopping OpenSRF</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, stop OpenSRF:</para>
+                               <para>As the <emphasis role="bold">opensrf</emphasis> user, stop OpenSRF:</para>
                                <figure>
-                                       <title>Testing OpenSRF with the "math" method</title>
+                                       <title>Stopping OpenSRF</title>
                                        <screen>
                                        $ su - opensrf
                                        $ osrf_ctl.sh -l -a stop_all
                                <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit) architectures. There may be differences between the Desktop and Server editions of Ubuntu. These instructions assume the Server edition.</para>
                                <para>In the following instructions, you are asked to perform certain steps as either the <emphasis role="bold">root</emphasis> user, the <emphasis role="bold">opensrf</emphasis> user, or the <emphasis role="bold">postgres</emphasis> user.</para>
                                <itemizedlist>
-                                       <listitem><emphasis role="bold">Debian</emphasis> To become the <emphasis>root</emphasis> user, issue the command <emphasis role="bold">su -</emphasis> and enter the password of the root user.</listitem>
-                                       <listitem><emphasis role="bold">Ubuntu</emphasis> To become the <emphasis>root</emphasis>  user, issue the command <emphasis role="bold">sudo su -</emphasis> and enter the password of your current user.</listitem>
+                                       <listitem><emphasis role="bold">Debian</emphasis> -- To become the <emphasis>root</emphasis> user, issue the command <emphasis role="bold">"su -"</emphasis> and enter the password of the root user.</listitem>
+                                       <listitem><emphasis role="bold">Ubuntu</emphasis> -- To become the <emphasis>root</emphasis>  user, issue the command <emphasis role="bold">"sudo su -"</emphasis> and enter the password of your current user.</listitem>
                                </itemizedlist>
-                               <para>To switch from the <emphasis role="bold">root</emphasis> user to a different user, issue the command <emphasis role="bold">su - USERNAME</emphasis>. For example, to switch from the <emphasis role="bold">root</emphasis> user to the <emphasis role="bold">opensrf</emphasis> user, issue the command <emphasis role="bold">su - opensrf</emphasis>. Once you have become a non-root user, to become the <emphasis role="bold">root</emphasis> user again, simply issue the command <emphasis role="bold">exit</emphasis>.</para>
+                               <para>To switch from the <emphasis role="bold">root</emphasis> user to a different user, issue the command <emphasis role="bold">"su - USERNAME"</emphasis>. For example, to switch from the <emphasis role="bold">root</emphasis> user to the <emphasis role="bold">opensrf</emphasis> user, issue the command <emphasis role="bold">"su - opensrf"</emphasis>. Once you have become a non-root user, to become the <emphasis role="bold">root</emphasis> user again, simply issue the command <emphasis role="bold">"exit"</emphasis>.</para>
                        </note>
                        <section xml:id="serversideinstallation-opensrf-overview">
                                <title>Installing OpenSRF</title>
                        <section>
                                <title>Download and Unpack Latest Evergreen Version</title>
                                <para>As the <emphasis role="bold">opensrf</emphasis> user, download and extract the latest version of Evergreen. The latest version can be found here: <emphasis><emphasis role="bold"><ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.0.7.tar.gz"></ulink></emphasis></emphasis></para>
-                               <para>[[ VERIFY LOCATION OF LATEST VERSION OF EVERGREEN ]]</para>
                                <figure>
-                                       <title>Commands to download/extract Evergreen</title>
+                                       <title>Commands to download and unpack Evergreen</title>
                                        <screen>
                                        $ su - opensrf
                                        $ wget http://evergreen-ils.org/downloads/Evergreen-ILS-1.6.0.7.tar.gz
                        </section>
                        <section>
                                <title>Install Prerequisites to Build Evergreen</title>
-                               <para>In this step you will install and configure a set of prerequisites used to build Evergreen. In a following step you will actually build the software using the <emphasis>make</emphasis> utility.</para>
-                               <para>As the <emphasis role="bold">root</emphasis> user, enter the commands show below in <emphasis> Figure 1.3</emphasis> to build the prerequisites from the software distribution that you just downloaded and unpacked. Remember to replace <emphasis>[distribution]</emphasis> in the example with the keyword corresponding to the actual Linux distribution listed here:</para>
-                               <para>[[ ADD INFO FOR OTHER LINUX DISTRIBUTIONS ]]</para>
+                               <para>In this section you will install and configure a set of prerequisites that will be used to build Evergreen. In a following step you will actually build the software using the <emphasis>make</emphasis> utility.</para>
+                               <para>As the <emphasis role="bold">root</emphasis> user, enter the commands show below to build the prerequisites from the software distribution that you just downloaded and unpacked. Remember to replace <emphasis>[distribution]</emphasis> in the example with the keyword corresponding to the actual Linux distribution listed in <emphasis> Figure 1.26</emphasis>.</para>
+                               <figure>
+                                       <title>Commands to install prerequisites for Evergreen</title>
+                                       <screen>
+                                       $ su - root
+                                       $ cd /home/opensrf/Evergreen-ILS-1.6.0.7
+                                       $ make -f Open-ILS/src/extras/Makefile.install [distribution]
+                                       </screen>
+                               </figure>
                                <figure>
                                        <title>Keywords used with "make"</title>
                                        <informaltable>
                                                </tgroup>
                                        </informaltable>
                                </figure>
-                               <figure>
-                                       <title>Commands to install prerequisites for Evergreen</title>
-                                       <screen>
-                                       $ su - root
-                                       $ cd /home/opensrf/Evergreen-ILS-1.6.0.7
-                                       $ make -f Open-ILS/src/extras/Makefile.install [distribution]
-                                       </screen>
-                               </figure>
+                               <para>[[ ADD INFO FOR OTHER LINUX DISTRIBUTIONS ]]</para>
                        </section>
                        <section>
                                <title>(OPTIONAL) Install the PostgreSQL Server</title>
                                <para>[[ ADD INFO ON HOW TO VERIFY THAT THE PERL MODULES ARE INSTALLED ]]</para>
                        </section>
                        <section>
-                               <title>Update the system dynamic library path</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating a new file named <emphasis role="bold">/etc/ld.so.conf.d/eg.conf</emphasis> containing two new library paths, then run the command <emphasis role="bold">ldconfig</emphasis> to automatically read the file and modify the dynamic library path:</para>
+                               <title>Update the System Dynamic Library Path</title>
+                               <para>As the <emphasis role="bold">root</emphasis> user, you must update the system dynamic library path to make your system recognize the newly installed libraries. Do this by creating a new file named <emphasis role="bold">/etc/ld.so.conf.d/eg.conf</emphasis> containing two new library paths, then run the command <emphasis role="bold">ldconfig</emphasis> to automatically read the file and modify the system dynamic library path:</para>
                                <figure>
                                        <title>Commands to modify system dynamic library path</title>
                                        <screen>
                                </figure>
                        </section>
                        <section>
-                               <title>Configure and Compile Evergreen Sources</title>
-                               <para>As the <emphasis role="bold">opensrf</emphasis> user, configure and compile the software from the prerequisites that were set up in previous steps:</para>
+                               <title>Configure and Evergreen</title>
+                               <para>As the <emphasis role="bold">opensrf</emphasis> user, return to your build directory and configure Evergreen by using the utility "configure" to prepare for the next step of compiling and linking the software:</para>
                                <figure>
-                                       <title>Commands to configure and compile Evergreen</title>
+                                       <title>Commands to configure Evergreen</title>
                                        <screen>
                                        $ su - opensrf
                                        $ cd /home/opensrf/Evergreen-ILS-1.6.0.7
                                </figure>
                        </section>
                        <section>
-                               <title>Link and Install Evergreen</title>
-                               <para>As the <emphasis role="bold">root</emphasis> user, link and install the compiled code. In the commands below, remember to set the variable <emphasis role="bold"> STAFF_CLIENT_BUILD_ID </emphasis> to match the version of the Staff Client you will use to connect to the Evergreen server. Finally, create a symbolic link named <emphasis role="bold">server</emphasis> in <emphasis role="bold">/openils/var/web/xul</emphasis> to the <emphasis role="bold">/server</emphasis> subdirectory of your Staff Client build:</para>
+                               <title>Compile, Link and Install Evergreen</title>
+                               <para>As the <emphasis role="bold">root</emphasis> user, return to your build directory and compile, link and install Evergreen.</para>
+                               <para>In the following commands, remember to set the variable <emphasis role="bold">STAFF_CLIENT_BUILD_ID</emphasis> to match the version of the Staff Client you will use to connect to the Evergreen server. Finally, create a symbolic link named <emphasis role="bold">server</emphasis> in the directory <emphasis role="bold">/openils/var/web/xul</emphasis> to the <emphasis role="bold">/server</emphasis> subdirectory of your Staff Client build:</para>
                                <figure>
-                                       <title>Commands to link and install Evergreen</title>
+                                       <title>Commands  to build, link and install Evergreen</title>
                                        <screen>
                                        $ su - root
                                        $ cd /home/opensrf/Evergreen-ILS-1.6.0.7
                        <section>
                                <title>Create Configuration Files for Users Needing srfsh</title>
                                <para>The software installation will automatically create a utility named <emphasis>srfsh</emphasis> (surf shell). This is a command line diagnostic tool for testing and interacting with the OpenSRF network software. It will be used in a future step to complete and test the Evergreen installation. See the section <emphasis><emphasis role="bold"><link linkend="serversideinstallation-testing"> "Testing the Installation" </link></emphasis></emphasis> for further information.</para>
-                               <para>In this step you will set up a special configuration file for each user who will need to run the utility. Copy the short sample configuration file <emphasis>/openils/conf/srfsh.xml.example</emphasis> to the file <emphasis>.srfsh.xml</emphasis> (note the leading dot!) in the home directory of each user who will use <emphasis role="bold">srfsh</emphasis>. Finally, edit each file <emphasis>.srfsh.xml</emphasis> and make the following changes:</para>
+                               <para>In this section you will set up a special configuration file for each user who will need to run the utility. Copy the short sample configuration file <emphasis>/openils/conf/srfsh.xml.example</emphasis> to the file <emphasis>.srfsh.xml</emphasis> (note the leading dot!) in the home directory of each user who will use <emphasis role="bold">srfsh</emphasis>. Finally, edit each file <emphasis>.srfsh.xml</emphasis> and make the following changes:</para>
                                <itemizedlist>
                                        <listitem>Modify <emphasis role="bold">domain</emphasis> to be the router hostname (following our domain examples, <emphasis role="bold">private.localhost</emphasis> will give <emphasis role="bold">srfsh</emphasis> access to all OpenSRF services, while <emphasis role="bold">public.localhost</emphasis> will only allow access to those OpenSRF services that are publicly exposed).</listitem>
                                        <listitem>Modify <emphasis role="bold">username</emphasis> and <emphasis role="bold">password</emphasis> to match the <emphasis role="bold">opensrf</emphasis> Jabber user for the chosen domain</listitem>
                        <title>Testing Connections to Evergreen</title>
                        <para>Once you have installed and started Evergreen, test your connection to Evergreen. As the <emphasis role="bold">opensrf</emphasis> user start the utility <emphasis>srfsh</emphasis> and try logging onto the Evergreen server using the default administrator username and password. Following is sample output generated by executing that script after a successful Evergreen installation:</para>
                        <figure>
-                               <title>Running the srfsh utility</title>
+                               <title>Testing Evergreen with "srfsh"</title>
                                <screen>
                                $ su - opensrf
                                $ /openils/bin/srfsh
                        <itemizedlist>
                                <listitem>
                                        <para>As the <emphasis role="bold">opensrf</emphasis> user, run the script <emphasis>settings-tester.pl</emphasis> to see if it finds any system configuration problems. Following is sample output generated by executing that script after a successful Evergreen installation:</para>
-                                       <para>[[ MAY NEED TO REWORK THIS DIAGRAM TO USE SAME IMAGE STANDARDS AS OTHER CHAPTERS ]]</para>
+                                       <para>[[ REWORK THIS DIAGRAM TO USE SAME IMAGE STANDARDS AS OTHER CHAPTERS ]]</para>
                                        <figure>
                                                <title>Executing the script <emphasis> settings-test.pl</emphasis></title>
                                                <mediaobject>
                        <listitem>
                                <para>As the <emphasis role="bold">root</emphasis> user, start the "ejabberd" and "memcached" services (if they aren't already running):</para>
                                <figure>
-                                       <title>Start some services</title>
+                                       <title>Starting some services</title>
                                        <screen>
                                        $ su - root
                                        $ /etc/init.d/ejabberd start
                                <para>As the <emphasis role="bold">opensrf</emphasis> user, start Evergreen.</para>
                                <para>Use the flag <emphasis>-l</emphasis> to force Evergreen to use <emphasis>localhost</emphasis> (your current system) as the hostname. Using the <emphasis>start_all</emphasis> option will start the OpenSRF router, Perl services, and C services:</para>
                                <figure>
-                                       <title>Start Evergreen</title>
+                                       <title>Starting Evergreen</title>
                                        <screen>
                                        $ su - opensrf
 
                <title>Stopping Evergreen</title>
                <para>As the <emphasis role="bold">opensrf</emphasis> user, stop all Evergreen services by using the following command:</para>
                <figure>
-                       <title>Stop all Evergreen services</title>
+                       <title>Stopping all Evergreen services</title>
                        <screen>
                        $ su - opensrf