<title>Stop Evergreen and back up data.</title>\r
<procedure>\r
<step>\r
- <para>As <
emphasis>root</emphasis>, stop the <application>Apache</application>
\r+ <para>As <
systemitem class="username">root</systemitem>, stop the <application>Apache</application>
\r web server<indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm>.</para>\r
</step>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, stop all \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, stop all \r
<application>Evergreen</application>\r
and <application>OpenSRF</application> services:</para>\r
- <screen>osrf_ctl.sh -l -a stop_all</screen>\r
+ <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
</step>\r
<step>\r
<para>Back up of the <filename class='directory'>/openils</filename> \r
directory.</para>\r
</step>\r
<step>\r
- <para><link linkend="back
upevergreendatabase">Back up the <application>evergreen
\r+ <para><link linkend="back
ingup">Back up the <application>evergreen
\r </application> database</link>.</para>\r
</step>\r
</procedure>\r
<title>Upgrade OpenSRF<indexterm><primary>OpenSRF</primary><secondary>1.2</secondary></indexterm> to 1.2</title>\r
<procedure>\r
<step>\r
- <para>As the opensrf user, download and extract the source files for OpenSRF \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the source files for <application>OpenSRF</application> \r
1.2:</para>\r
- <screen>wget http://open-ils.org/downloads/OpenSRF-1.2.2.tar.gz</screen>\r
- <screen>tar xzf OpenSRF-1.2.2.tar.gz</screen>\r
+ <screen><userinput>wget http://open-ils.org/downloads/OpenSRF-1.2.2.tar.gz</userinput></screen>\r
+ <screen><userinput>tar xzf OpenSRF-1.2.2.tar.gz</userinput></screen>\r
<para>A new directory OpenSRF-1.2.2 will be created</para>\r
<note><para>For the latest edition of OpenSRF, check the Evergreen download page at \r
<ulink url="http://www.open-ils.org/downloads.php" />.\r
</para></note>\r
</step>\r
<step> \r
- <para>As the root user, install the software prerequisites using the automatic \r
+ <para>As the <systemitem class="username">root</systemitem> user, install the software prerequisites using the automatic \r
prerequisite installer.</para> \r
- <screen>aptitude install make</screen>\r
- <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
+ <screen><userinput>aptitude install make</userinput></screen>\r
+ <screen><userinput>cd /home/opensrf/OpenSRF-1.2.2</userinput></screen>\r
\r
- <para>Replace <emphasis>[distribution]</emphasis> below with the following value \r
+ <para>Replace <option>[distribution]</option> below with the following value \r
for your distribution:</para>\r
<itemizedlist>\r
<listitem>\r
- <para><
emphasis>debian-etch</emphasis> for Debian Etch (4.0)<indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>
\r+ <para><
option>debian-etch</option> for <systemitem class="osname">Debian Etch (4.0)</systemitem><indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>
\r </listitem>\r
<listitem>\r
- <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>\r
+ <para><option>debian-lenny</option> for <systemitem class="osname">Debian Lenny (5.0)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><
emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron (8.04)<indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>
\r+ <para><
option>ubuntu-hardy</option> for <systemitem class="osname">Ubuntu Hardy Heron (8.04)</systemitem><indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm></para>
\r </listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex \r
- (8.10)</para>\r
+ <para><option>ubuntu-intrepid</option> for <systemitem class="osname">Ubuntu Intrepid Ibex \r
+ (8.10)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope \r
- (9.04)</para>\r
+ <para><option>ubuntu-jaunty</option> for <systemitem class="osname">Ubuntu Jaunty Jackalope \r
+ (9.04)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala \r
- (9.10)</para>\r
+ <para><option>ubuntu-karmic</option> for <systemitem class="osname">Ubuntu Karmic Koala \r
+ (9.10)</systemitem></para>\r
</listitem>\r
</itemizedlist>\r
- <screen>make -f src/extras/Makefile.install <emphasis>[distribution]</emphasis></screen>\r
+ <screen><userinput>make -f src/extras/Makefile.install <option>[distribution]</option></userinput></screen>\r
<para>This will install a number of packages required by OpenSRF on your system, \r
- including some Perl modules from CPAN<indexterm><primary>programming language</primary><secondary>Perl</secondary>\r
- <tertiary>CPAN</tertiary>\r
- </indexterm>. You can say <quote>no</quote> to the initial CPAN \r
+ including some Perl modules from <systemitem class="resource">CPAN</systemitem><indexterm><primary>Perl</primary><secondary>CPAN</secondary>\r
+ </indexterm>. You can type <userinput>no</userinput> to the initial <systemitem class="resource">CPAN</systemitem> \r
configuration prompt to allow it to automatically configure itself to download \r
- and install Perl modules from CPAN. The CPAN installer will ask you a number of \r
- times whether it should install prerequisite modules - say <quote>yes</quote>.</para>\r
+ and install Perl modules from <systemitem class="resource">CPAN</systemitem>. The <systemitem class="resource">CPAN</systemitem> installer will ask you a number of \r
+ times whether it should install prerequisite modules - type <userinput>yes</userinput>.</para>\r
</step>\r
<step> \r
<para>As the opensrf user, configure and compile OpenSRF:</para> \r
- <note>You can include the –enable-python and –enable-java configure options if \r
- you want to include support for Python<indexterm><primary>programming language</primary><secondary>Python</secondary>\r
- </indexterm> and Java<indexterm><primary>programming language</primary><secondary>Java</secondary>\r
- </indexterm>, respectively.</note>\r
- <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
- <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>\r
- <screen>make</screen>\r
+ <note>You can include the <option>–enable-python</option> and <option>–enable-java</option> configure options if \r
+ you want to include support for Python<indexterm><primary>Python</primary></indexterm> and Java\r
+ <indexterm><primary>Java</primary></indexterm>, respectively.</note>\r
+ <screen><userinput>cd /home/opensrf/OpenSRF-1.2.2</userinput></screen>\r
+ <screen><userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput></screen>\r
+ <screen><userinput>make</userinput></screen>\r
\r
</step>\r
<step> \r
- <para>As the root user, return to your OpenSRF build directory and install \r
+ <para>As the <systemitem class="username">root</systemitem> user, return to your OpenSRF build directory and install \r
OpenSRF:</para>\r
- <screen>cd /home/opensrf/OpenSRF-1.2.2</screen>\r
- <screen>make install</screen>\r
+ <screen><userinput>cd /home/opensrf/OpenSRF-1.2.2</userinput></screen>\r
+ <screen><userinput>make install</userinput></screen>\r
</step>\r
<step>\r
<para>As the root user, change the ownership of the installed files to the opensrf \r
user:</para>\r
- <screen>chown -R opensrf:opensrf /openils</screen>\r
+ <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>\r
</step>\r
<step>\r
<para>Restart and Test OpenSRF</para>\r
- <screen>osrf_ctl.sh -l -a start_all</screen>\r
- <screen>/openils/bin/srfsh</screen>\r
- <screen>srfsh# request opensrf.math add 2 2</screen>\r
+ <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>\r
+ <screen><userinput>/openils/bin/srfsh</userinput></screen>\r
+ <screen><userinput>srfsh# request opensrf.math add 2 2</userinput></screen>\r
<para>You should see output like:</para>\r
- <screen>Received Data: 4</screen>\r
- <screen></screen>\r
- <screen>------------------------------------</screen>\r
- <screen>Request Completed Successfully</screen>\r
- <screen>Request Time in seconds: 0.007519</screen>\r
- <screen>------------------------------------</screen>\r
- <screen></screen>\r
- <screen>srfsh#</screen> \r
- <para>If test <emphasis>Completed Successfully</emphasis> move onto next section. \r
- If not, refer to <link linkend="troubleshooting">troubleshooting</link> section \r
+ <screen>\r
+ Received Data: 4\r
+ \r
+ ------------------------------------\r
+ Request Completed Successfully\r
+ Request Time in seconds: 0.007519\r
+ ------------------------------------\r
+ \r
+ srfsh#\r
+ </screen> \r
+ <para>If test completed successfully move onto next section. \r
+ Otherwise, refer to the <link linkend="troubleshooting">troubleshooting</link> chapter \r
of this documentation.</para> \r
</step> \r
</procedure> \r
<title>Upgrade <application>Evergreen</application> to 1.6</title>\r
<procedure>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, download and extract Evergreen 1.6\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, download and extract <application>Evergreen 1.6</application>\r
</para>\r
- <screen>wget http://open-ils.org/downloads/Evergreen-ILS-1.6.0.8.tar.gz</screen>\r
- <screen>tar xzf Evergreen-ILS-1.6.0.8.tar.gz</screen>\r
+ <screen><userinput>wget http://open-ils.org/downloads/Evergreen-ILS-1.6.0.8.tar.gz</userinput></screen>\r
+ <screen><userinput>tar xzf Evergreen-ILS-1.6.0.8.tar.gz</userinput></screen>\r
<note><para>For the latest edition of Evergreen check the Evergreen download page at\r
<ulink url="http://www.open-ils.org/downloads.php" /> and adjust upgrading instructions accordingly.</para></note>\r
</step>\r
<step>\r
- <para>As the <emphasis>root</emphasis> user, install the prerequisites:</para> \r
- <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen> \r
- <para>On the next command, replace <emphasis>[distribution]</emphasis> with one of \r
+ <para>As the <systemitem class="username">root</systemitem> user, install the prerequisites:</para> \r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-1.6.0.8</userinput></screen> \r
+ <para>On the next command, replace <option>[distribution]</option> with one of \r
these values for your distribution of Debian or Ubuntu:</para>\r
<itemizedlist>\r
<listitem>\r
- <para><emphasis>debian-etch</emphasis> for Debian Etch (4.0)</para>\r
+ <para><option>debian-etch</option> for <systemitem class="osname">Debian Etch (4.0)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>debian-lenny</emphasis> for Debian Lenny (5.0)</para>\r
+ <para><option>debian-lenny</option> for <systemitem class="osname">Debian Lenny (5.0)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-hardy</emphasis> for Ubuntu Hardy Heron \r
- (8.04)</para>\r
+ <para><option>ubuntu-hardy</option> for <systemitem class="osname">Ubuntu Hardy Heron \r
+ (8.04)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-intrepid</emphasis> for Ubuntu Intrepid Ibex \r
- (8.10)</para>\r
+ <para><option>ubuntu-intrepid</option> for <systemitem class="osname">Ubuntu Intrepid Ibex \r
+ (8.10)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-jaunty</emphasis> for Ubuntu Jaunty Jackalope \r
- (9.04)</para>\r
+ <para><option>ubuntu-jaunty</option> for <systemitem class="osname">Ubuntu Jaunty Jackalope \r
+ (9.04)</systemitem></para>\r
</listitem>\r
<listitem>\r
- <para><emphasis>ubuntu-karmic</emphasis> for Ubuntu Karmic Koala \r
- (9.10)</para>\r
+ <para><option>ubuntu-karmic</option> for <systemitem class="osname">Ubuntu Karmic Koala \r
+ (9.10)</systemitem></para>\r
</listitem>\r
</itemizedlist>\r
- <screen>make -f Open-ILS/src/extras/Makefile.install <emphasis>[distribution]</emphasis></screen>\r
+ <screen><userinput>make -f Open-ILS/src/extras/Makefile.install <option>[distribution]</option></userinput></screen>\r
</step>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, configure and compile \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, configure and compile \r
<application>Evergreen</application>:</para>\r
- <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen>\r
- <screen>./configure --prefix=/openils --sysconfdir=/openils/conf</screen>\r
- <screen>make</screen>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-1.6.0.8</userinput></screen>\r
+ <screen><userinput>./configure --prefix=/openils --sysconfdir=/openils/conf</userinput></screen>\r
+ <screen><userinput>make</userinput></screen>\r
</step>\r
<step>\r
- <para>As the <emphasis>root</emphasis> user, install \r
+ <para>As the <systemitem class="username">root</systemitem> user, install \r
<application>Evergreen</application>:</para>\r
- <screen>make STAFF_CLIENT_BUILD_ID=rel_1_6_0_8 install</screen>\r
+ <screen><userinput>make STAFF_CLIENT_BUILD_ID=rel_1_6_0_8 install</userinput></screen>\r
</step>\r
<step>\r
<para>Change to the <application>Evergreen</application> installation \r
directory:</para>\r
- <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-1.6.0.8</userinput></screen>\r
</step>\r
<step>\r
<para>As the <emphasis>root</emphasis> user, change all files to be owned by the \r
<emphasis>opensrf</emphasis> user and group:</para>\r
- <screen>chown -R opensrf:opensrf /openils</screen>\r
+ <screen><userinput>chown -R opensrf:opensrf /openils</userinput></screen>\r
</step> \r
<step>\r
- <para>As the <emphasis>root</emphasis> user, build live-db-setup.pl for the cgi-bin \r
- bootstrapping scripts and offline-config.pl for the offline staff client data \r
- uploader:</para>\r
- <screen>cd /home/opensrf/Evergreen-ILS-1.6.0.8</screen> \r
- <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl --create-bootstrap --create-offline --user evergreen \</screen>\r
- <screen>--password evergreen --hostname localhost --port 5432 --database evergreen</screen>\r
+ <para>As the <systemitem class="username">root</systemitem> user, build <filename>live-db-setup.pl</filename> for the cgi-bin \r
+ bootstrapping scripts and <filename>offline-config.pl</filename> for the offline staff client data uploader:</para>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS-1.6.0.8</userinput></screen> \r
+ <screen>\r
+ <userinput>\r
+ perl Open-ILS/src/support-scripts/eg_db_config.pl --create-bootstrap --create-offline --user evergreen \\r
+ --password evergreen --hostname localhost --port 5432 --database evergreen\r
+ </userinput>\r
+ </screen>\r
</step>\r
<step>\r
- <para>As the opensrf user, update server symlink in <filename class="directory">/openils/var/web/xul/</filename>:</para>\r
- <screen>cd /openils/var/web/xul/</screen>\r
- <screen>rm server</screen>\r
- <screen>ln -s rel_1_6_0_8/server</screen>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, update server symlink in <filename class="directory">/openils/var/web/xul/</filename>:</para>\r
+ <screen><userinput>cd /openils/var/web/xul/</userinput></screen>\r
+ <screen><userinput>rm server</userinput></screen>\r
+ <screen><userinput>ln -s rel_1_6_0_8/server</userinput></screen>\r
</step>\r
\r
<step>\r
<para>Update the Evergreen database:</para>\r
<note><para>it is recommended that you <link linkend="backingup">back up your Evergreen database</link> in order to restore your data if anything goes wrong.</para></note>\r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.4.0.5-1.6.0.0-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.0-1.6.0.1-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.1-1.6.0.2-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.2-1.6.0.3-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.3-1.6.0.4-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.4-1.6.0.5-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.5-1.6.0.6-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.6-1.6.0.7-upgrade-db.sql evergreen</screen> \r
- <screen>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.7-1.6.0.8-upgrade-db.sql evergreen</screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.4.0.5-1.6.0.0-upgrade-db.sql evergreen</userinput></screen>\r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.0-1.6.0.1-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.1-1.6.0.2-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.2-1.6.0.3-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.3-1.6.0.4-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.4-1.6.0.5-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.5-1.6.0.6-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.6-1.6.0.7-upgrade-db.sql evergreen</userinput></screen> \r
+ <screen><userinput>psql -U evergreen -h localhost -f Open-ILS/src/sql/Pg/1.6.0.7-1.6.0.8-upgrade-db.sql evergreen</userinput></screen> \r
<para>Download and run the the billing view hot-fix script</para> \r
- <screen>wget http://www.open-ils.org/downloads/1.6.0-mmbxs-cleanup.sql</screen>\r
- <screen>psql -U evergreen -h localhost -f 1.6.0-mmbxs-cleanup.sql</screen> \r
+ <screen><userinput>wget http://www.open-ils.org/downloads/1.6.0-mmbxs-cleanup.sql</userinput></screen>\r
+ <screen><userinput>psql -U evergreen -h localhost -f 1.6.0-mmbxs-cleanup.sql</userinput></screen> \r
</step>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, \r
- copy /openils/conf/oils_web.xml.example to /openils/conf/oils_web.xml \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, \r
+ copy <filename>/openils/conf/oils_web.xml.example</filename> to <filename>/openils/conf/oils_web.xml</filename>\r
+ <indexterm><primary>configuration files</primary><secondary>oils_web.xml</secondary></indexterm>\r
(needed for acquisitions templates).</para>\r
- <screen>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</screen>\r
+ <screen><userinput>cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</userinput></screen>\r
</step>\r
<step>\r
- <para>Update opensrf_core.xml and opensrf.xml by copying the new example files (/\r
- openils/conf/opensrf_core.xml.example and /openils/conf/opensrf.xml).</para>\r
- <screen>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</screen>\r
- <screen>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</screen>\r
+ <para>Update <filename>opensrf_core.xml</filename> and <filename>opensrf.xml</filename> by copying the new example files \r
+ (<filename>/openils/conf/opensrf_core.xml.example</filename> and <filename>/openils/conf/opensrf.xml</filename>).</para>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>\r
+ <screen><userinput>cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml</userinput></screen>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>\r
+ <screen><userinput>cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</userinput></screen>\r
</step>\r
<step>\r
- <para>Update opensrf.xml with the database connection info:</para>\r
- <screen>perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config --service all --user evergreen \</screen>\r
- <screen>--password evergreen --hostname localhost --port 5432 --database evergreen</screen>\r
+ <para>Update <filename>opensrf.xml</filename> with the database connection info:</para>\r
+ <screen>\r
+ <userinput>\r
+ perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config --service all --user evergreen \\r
+ --password evergreen --hostname localhost --port 5432 --database evergreen\r
+ </userinput>\r
+ </screen>\r
</step>\r
<step>\r
<para>Update /etc/apache2/startup.pl by copying the example from \r
- Open-ILS/examples/apache/startup.pl.</para>\r
+ Open-ILS/examples/apache/startup.pl.</para><indexterm><primary>configuration files</primary><secondary>startup.pl</secondary></indexterm>\r
</step>\r
<step>\r
<para>Update /etc/apache2/eg_vhost.conf by copying the example from \r
- Open-ILS/examples/apache/eg_vhost.conf.</para>\r
+ Open-ILS/examples/apache/eg_vhost.conf.</para><indexterm><primary>configuration files</primary><secondary>eg_vhost.conf</secondary></indexterm>\r
</step>\r
<step>\r
<para>Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/\r
- examples/apache/eg.conf.</para>\r
+ examples/apache/eg.conf.</para><indexterm><primary>configuration files</primary><secondary>eg.conf</secondary></indexterm>\r
</step>\r
<step>\r
<para>Recover customizations you have made to the <application>Apache</application><indexterm><primary>Apache</primary></indexterm> \r
- configuration files. For example, if you purchased an SSL certificate<indexterm><primary>SSL certificate</primary></indexterm>, you \r
- will need to edit eg.conf to point to the appropriate SSL certificate files.</para>\r
+ configuration files. For example, if you purchased an SSL certificate, you \r
+ will need to edit <filename>eg.conf</filename> to point to the appropriate SSL certificate files.</para>\r
+ <indexterm><primary>SSL</primary><secondary>certificates</secondary></indexterm>\r
</step> \r
</procedure> \r
</simplesect>\r
<title>Restart Evergreen and Test</title>\r
<procedure>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, start all \r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, start all \r
<application>Evergreen</application> and <application>OpenSRF</application> \r
services:</para>\r
- <screen>osrf_ctl.sh -l -a start_all</screen>\r
+ <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>\r
</step>\r
<step>\r
- <para>As the <emphasis>opensrf</emphasis> user, run autogen to refresh the static \r
- organizational data files:</para>\r
- <screen>cd /openils/bin</screen>\r
- <screen>./autogen.sh -c /openils/conf/opensrf_core.xml -u</screen>\r
+ <para>As the <systemitem class="username">opensrf</systemitem> user, run <command>autogen</command> to refresh the static \r
+ organizational data files:</para><indexterm><primary>autogen</primary></indexterm>\r
+ <screen><userinput>cd /openils/bin</userinput></screen>\r
+ <screen><userinput>./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput></screen>\r
\r
</step>\r
<step>\r
- <para>Start
srfsh and try logging in using your <application>Evergreen</application>
\r+ <para>Start
<command>srfsh</command> and try logging in using your <application>Evergreen</application>
\r username and password:</para>\r
- <screen>/openils/bin/srfsh</screen> \r
- <screen>srfsh% login <emphasis>username password</emphasis></screen> \r
+ <screen><userinput>/openils/bin/srfsh</userinput></screen> \r
+ <screen><prompt>srfsh%</prompt> <userinput>login <option>username</option> <option>password</option></userinput></screen> \r
</step> \r
<step>\r
<para>Start the <application>Apache</application> web server.</para>\r
</step>\r
</procedure>\r
+ <note>\r
+ <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting \r
+ section</link> of this documentation for tips \r
+ on finding solutions and seeking further assistance from the Evergreen community.</para> \r
+ </note>\r
</simplesect>\r
- <note>\r
- <para>If you encounter errors, refer to the <link linkend="troubleshooting">troubleshooting \r
- section</link> of this documentation for tips \r
- on finding solutions and seeking further assistance from the Evergreen community.</para> \r
- </note>\r
-<simplesect>\r
+ <simplesect>\r
<title>Upgrading PostgreSQL from 8.2 to 8.3</title>\r
<para>Evergreen 1.6 supports PostgreSQL version 8.3 and it is recommended that you upgrade PostgreSQL when you upgrade Evergreen to 1.6.</para>\r
- <note><para>The Order of the following steps is very important.</para></note>\r
+ <note><para>The order of the following steps is very important.</para></note><indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<procedure>\r
<step>\r
- <para>As opensrf, stop the evergreen and opensrf services:</para>\r
- <screen>osrf_ctl.sh -l -a stop_all</screen>\r
+ <para>As <systemitem class="username">opensrf</systemitem>, stop the evergreen and opensrf services:</para>\r
+ <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
</step> \r
<step>\r
- <para><link linkend="backupevergreendatabase">Backup the Evergreen database data</link></para>\r
+ <para><link linkend="backingup">Backup the Evergreen database data</link></para>\r
</step>\r
<step> \r
<para>Create an empty Evergreen database in postgresql 8.3 by issuing the following commands as the postgres user:</para>\r
- <screen>createdb -E UNICODE evergreen</screen>\r
- <screen>createlang plperl evergreen</screen>\r
- <screen>createlang plperlu evergreen</screen>\r
- <screen>createlang plpgsql evergreen</screen>\r
- <screen>psql -f /usr/share/postgresql/8.3/contrib/tablefunc.sql evergreen</screen>\r
- <screen>psql -f /usr/share/postgresql/8.3/contrib/tsearch2.sql evergreen</screen>\r
- <screen>psql -f /usr/share/postgresql/8.3/contrib/pgxml.sql evergreen</screen> \r
- </step>\r
- <step>\r
- <para>As the postgres user on the PostgreSQL server, create a PostgreSQL user named evergreen for the database cluster:</para>\r
- <screen>createuser -P -s evergreen</screen>\r
- <para>Enter the password for the new PostgreSQL superuser (<quote>evergreen</quote>)</para> \r
+ <screen><userinput>createdb -E UNICODE evergreen</userinput></screen>\r
+ <screen><userinput>createlang plperl evergreen</userinput></screen>\r
+ <screen><userinput>createlang plperlu evergreen</userinput></screen>\r
+ <screen><userinput>createlang plpgsql evergreen</userinput></screen>\r
+ <screen><userinput>psql -f /usr/share/postgresql/8.3/contrib/tablefunc.sql evergreen</userinput></screen>\r
+ <screen><userinput>psql -f /usr/share/postgresql/8.3/contrib/tsearch2.sql evergreen</userinput></screen>\r
+ <screen><userinput>psql -f /usr/share/postgresql/8.3/contrib/pgxml.sql evergreen</userinput></screen> \r
+ </step>\r
+ <step>\r
+ <para>As the postgres user on the PostgreSQL server, create a PostgreSQL user named <systemitem class="username">evergreen</systemitem> for the database cluster:</para>\r
+ <screen><userinput>createuser -P -s evergreen</userinput></screen>\r
+ <para>Enter the password for the new PostgreSQL superuser (<systemitem class="username">evergreen</systemitem>)</para> \r
</step> \r
<step>\r
<para>Restore data from backup created in step 1.</para>\r
<step>\r
<para>To point tsearch2 to proper function names in 8.3, run the SQL script \r
<filename>/home/opensrf/Evergreen-ILS*/Open-ILS/src/sql/Pg/000.english.pg83.fts-config.sql</filename> using the <command>psql</command> command.</para>\r
+ <screen><userinput>cd /home/opensrf/Evergreen-ILS*</userinput></screen>\r
+ <screen><userinput>psql -f /Open-ILS/src/sql/Pg/000.english.pg83.fts-config.sql evergreen</userinput></screen>\r
</step>\r
<step>\r
<para><link linkend="upgraderestart">Restart Evergreen and OpenSRF services</link></para>\r
<info>\r
<title>SIP Server</title>\r
</info>\r
- <para>SIP, standing for Standard Interchange Protocol, was developed by the 3M corporation to be a common protocol for data transfer between ILS' \r
- (referred to in SIP as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>) and a third party device. Originally, the protocol was developed for \r
+ <para><systemitem class="protocol">SIP</systemitem>, standing for <systemitem class="protocol">Standard Interchange Protocol</systemitem>, was developed by the \r
+ <orgname class="corporation">3M</orgname>corporation to be a common protocol for data transfer between ILS' \r
+ (referred to in <systemitem class="protocol">SIP</systemitem> as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>)\r
+ <indexterm><primary>Automated Circulation System</primary></indexterm> and a \r
+ third party device. Originally, the protocol was developed for \r
use with 3M SelfCheck (often abbreviated SC, not to be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common to find \r
- SIP in use in several other vendors' SelfCheck systems, as well as other non-SelfCheck devices. Some examples include:</para>\r
+ <systemitem class="protocol">SIP</systemitem> in use in several other vendors' SelfCheck systems<indexterm><primary>SelfCheck</primary></indexterm>, as well as other non-SelfCheck devices. \r
+ Some examples include:</para>\r
<itemizedlist>\r
<listitem>Patron Authentication (computer access, subscription databases)</listitem>\r
- <listitem>Automated Material Handling (AMH) - The automated sorting of items, often to bins or book carts, based on shelving location or other programmable criteria</listitem>\r
+ <listitem>Automated Material Handling (AMH) <indexterm><primary>Automated Material Handling (AMH)</primary></indexterm>- The automated sorting of items, often to bins or \r
+ book carts, based on shelving location or other programmable criteria</listitem>\r
</itemizedlist>\r
\r
<section xml:id="Installing_SIP_Server">\r
<info>\r
- <title>Installing the SIP Server</title>\r
+ <title>Installing the <systemitem class="protocol">SIP</systemitem> Server</title>\r
</info>\r
- <para>This is a rough intro to installing the SIP server for Evergreen.</para>\r
+ <para>This is a rough intro to installing the <systemitem class="protocol">SIP</systemitem> server for Evergreen.</para>\r
<simplesect xml:id="Gettingthecode">\r
<title>Getting the code</title>\r
- <para>Current SIP code lives at github:</para>\r
+ <para>Current <systemitem class="protocol">SIP</systemitem> code lives at github:</para>\r
<screen>cd /opt</screen>\r
<screen>git clone git://github.com/atz/SIPServer.git SIPServer</screen>\r
<para>Or use the old style:</para>\r
<screen>$ cp oils_sip.xml.example oils_sip.xml</screen>\r
</step>\r
<step>\r
- <para>Edit oils_sip.xml. Change the commented out <server-params> section to this:</para>\r
+ <para>Edit <filename>oils_sip.xml</filename><indexterm><primary>configuration files</primary><primary>oils_sip.xml</primary></indexterm>. \r
+ Change the commented out <server-params> section to this:</para>\r
<screen><server-params</screen>\r
<screen>min_servers='1'</screen>\r
<screen>min_spare_servers='0'</screen>\r
<screen>/></screen>\r
</step>\r
<step>\r
- <para> max_servers will directly correspond to the number of allowed SIP clients. Set the number accordingly, but bear in mind that too many connections can \r
- exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), I would recommend not exceeding 100 SIP client connections, \r
+ <para> max_servers will directly correspond to the number of allowed <systemitem class="protocol">SIP</systemitem> clients. Set the number accordingly, but \r
+ bear in mind that too many connections can \r
+ exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), I would recommend not exceeding 100 \r
+ <systemitem class="protocol">SIP</systemitem> client connections, \r
give or take.</para> \r
</step>\r
</procedure> \r
</simplesect>\r
<simplesect xml:id="Adding_SIP_users">\r
- <title>Adding SIP Users</title>\r
+ <title>Adding <systemitem class="protocol">SIP</systemitem> Users</title>\r
<procedure>\r
<step>\r
<para>Type the following commands from the command prompt:</para>\r
<screen>$ cp oils_sip.xml.example oils_sip.xml</screen>\r
</step>\r
<step>\r
- <para> in the <accounts> section, add SIP client login information. Make sure that all <logins> use the same institution attribute, and make \r
- sure the institution is listed in <institutions>. All attributes in the <login> section will be used by the SIP client.</para>\r
+ <para> in the <accounts> section, add <systemitem class="protocol">SIP</systemitem> client login information. Make sure that all <logins> use the \r
+ same institution attribute, and make \r
+ sure the institution is listed in <institutions>. All attributes in the <login> section will be used by the <systemitem class="protocol">SIP</systemitem> client.</para>\r
\r
</step>\r
<step>\r
- <para> In Evergreen, create a new profile group called SIP. This group should be a sub-group of Users (not Staff or Patrons). \r
+ <para> In Evergreen, create a new profile group called <systemitem class="protocol">SIP</systemitem>. This group should be a sub-group of Users \r
+ (not Staff or Patrons). \r
Set Editing Permission as <emphasis>group_application.user.sip_client</emphasis> and give the group the following permissions:</para>\r
<literallayout>\r
COPY_CHECKIN\r
</step>\r
<step>\r
<para>For each account created in the <login> section of oils_sip.xml, create a user (via the staff client user editor) that has the same username \r
- and password and put that user into the SIP group.</para>\r
- <note><para>The expiration date will affect the SIP users' connection, you might want to make a note of \r
+ and password and put that user into the <systemitem class="protocol">SIP</systemitem> group.</para>\r
+ <note><para>The expiration date will affect the <systemitem class="protocol">SIP</systemitem> users' connection, you might want to make a note of \r
this somewhere. </para></note> \r
</step>\r
</procedure> \r
</simplesect>\r
<simplesect xml:id="Running_SIP_server">\r
<title>Running the server</title>\r
- <para>To start the SIP server type the following commands from the command prompt:</para>\r
+ <para>To start the <systemitem class="protocol">SIP</systemitem> server type the following commands from the command prompt:</para>\r
<screen>$ sudo su opensrf</screen>\r
<screen>$ oils_ctl.sh -d /openils/var/run -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip</screen> \r
</simplesect>\r
<title>Logging-SIP</title>\r
<simplesect>\r
<title>Syslog</title>\r
- <para>It is useful to log SIP requests to a separate file especially during initial setup by modifying your syslog config file.</para>\r
+ <para>It is useful to log <systemitem class="protocol">SIP</systemitem> requests to a separate file especially during initial setup by modifying your syslog config file.</para>\r
<procedure>\r
<step>\r
<para>Edit syslog.conf.</para>\r
</simplesect>\r
</simplesect> \r
<simplesect xml:id="Testing_SIP_Connection">\r
- <title>Testing Your SIP Connection</title>\r
+ <title>Testing Your <systemitem class="protocol">SIP</systemitem> Connection</title>\r
<itemizedlist>\r
<listitem>\r
<para>In the top level CVS checkout of the SIPServer code.</para>\r
<title>More Testing</title>\r
<procedure>\r
<step>\r
- <para>Once you have opened up either the SIP OR SIP2 ports to be accessible from outside you can do some testing via telnet. You can try this with localhost \r
- if you so wish, but we want to prove that SIP2 works from non-localhost. Replace $instid, $server, $barcode, $username, and $password variables below as \r
+ <para>Once you have opened up either the <systemitem class="protocol">SIP</systemitem> OR <systemitem class="protocol">SIP2</systemitem> ports to be accessible from outside you can do some testing via telnet. You can try this with localhost \r
+ if you so wish, but we want to prove that <systemitem class="protocol">SIP2</systemitem> works from non-localhost. Replace $instid, $server, $barcode, $username, and $password variables below as \r
necessary.</para>\r
- <note><para>We are using 6001 here which is associated with SIP2 as per our configuration.</para></note>\r
+ <note><para>We are using 6001 here which is associated with <systemitem class="protocol">SIP2</systemitem> as per our configuration.</para></note>\r
<screen>$ telnet $server 6001</screen>\r
<screen>Connected to $server.</screen>\r
<screen>Escape character is '^]'.</screen>\r
</section>\r
<section xml:id="SIP_Communication">\r
<info>\r
- <title>SIP Communication</title>\r
+ <title><systemitem class="protocol">SIP</systemitem> Communication</title>\r
</info>\r
- <para>SIP generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, \r
+ <para><systemitem class="protocol">SIP</systemitem> generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, \r
the most common deployment is a RAW socket connection on port 6001.</para>\r
<para>SIP communication consists of strings of messages, each message request and response begin with a 2-digit <quote>command</quote> - Requests usually being an odd \r
number and responses usually increased by 1 to be an even number. The combination numbers for the request command and response is often referred to as a \r
<entry>93/94</entry>\r
<entry>Login</entry>\r
<entry>Yes</entry>\r
- <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or SIP will terminate</entry>\r
+ <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or <systemitem class="protocol">SIP</systemitem> will terminate</entry>\r
</row>\r
<row>\r
<entry>97/96</entry>\r
<para>The request looks like:</para>\r
<screen>17<xact_date>[fields: AO,AB,AC]</screen>\r
<para>The request is very terse. AC is optional.</para>\r
- <para>The following response structure is for SIP2. (Version 1 of the protocol had only 6 total fields.)</para>\r
+ <para>The following response structure is for <systemitem class="protocol">SIP2</systemitem>. (Version 1 of the protocol had only 6 total fields.)</para>\r
<screen>18<circulation_status><security_marker><fee_type><xact_date>[fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]</screen>\r
<para>Example:</para>\r
<screen>1720060110 215612AOBR1|ABno_such_barcode|</screen>\r
<screen>2300120060101 084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
<screen>24 Y 00120100507 022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
<orderedlist>\r
- <listitem>The <emphasis>BL</emphasis> field (SIP2, optional) is <emphasis>valid patron</emphasis>, so the <emphasis>N</emphasis> value means \r
+ <listitem>The <emphasis>BL</emphasis> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid patron</emphasis>, so the <emphasis>N</emphasis> value means \r
<emphasis>bad_barcode</emphasis> doesn't match a patron, the <emphasis>Y</emphasis> value means 999999 does.</listitem>\r
- <listitem>The <emphasis>CQ</emphasis> field (SIP2, optional) is <emphasis>valid password</emphasis>, so the <emphasis>N</emphasis> \r
+ <listitem>The <emphasis>CQ</emphasis> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid password</emphasis>, so the <emphasis>N</emphasis> \r
value means <emphasis>bad_password</emphasis> doesn't match 999999's password, the <emphasis>Y</emphasis> means <emphasis>userpassword</emphasis> \r
does.</listitem>\r
</orderedlist>\r
- <para>So if you were building the most basic SIP2 authentication client, you would check for <emphasis>|CQY|</emphasis> in the response to know the user's barcode and password \r
+ <para>So if you were building the most basic <systemitem class="protocol">SIP2</systemitem> authentication client, you would check for <emphasis>|CQY|</emphasis> in the response to know the user's barcode and password \r
are correct (<emphasis>|CQY|</emphasis> implies <emphasis>|BLY|</emphasis>, since you cannot check the password unless the barcode exists). However, in practice, \r
depending on the application, there are other factors to consider in authentication, like whether the user is blocked from checkout, owes excessive fines, reported their \r
card lost, etc. These limitations are reflected in the 14-character <emphasis>patron status</emphasis> string immediately following the <emphasis>24</emphasis> code. \r
<para>Example:</para>\r
<screen>9910302.00</screen>\r
<screen>98YYYYNN60000320100510 1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|</screen>\r
- <para>The Supported Messages field <emphasis>(BX)</emphasis> appears only in SIP2, and specifies whether 16 different SIP commands are supported by the ACS or not.</para>\r
+ <para>The Supported Messages field <emphasis>(BX)</emphasis> appears only in <systemitem class="protocol">SIP2</systemitem>, and specifies whether 16 different \r
+ <systemitem class="protocol">SIP</systemitem> commands are supported by the ACS or not.</para>\r
</simplesect>\r
<simplesect xml:id="SIP_Fields">\r
<title>Fields</title>\r
<?xml version="1.0" encoding="utf-8"?>\r
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="troubleshooting">\r
- <title>Troubleshooting System Errors</title>\r
- <para>If you have Evergreen installed and are encountering systematic errors, here is the steps to find the \r
- cause and solution to most problems. These instructions assume standard locations and file names for Evergreen\r
- installations, and may also include commands for specific Linux distributions.</para>\r
- <procedure>\r
- <title>Systematic Evergreen Restart to Isolate Errors</title>\r
- <step>\r
- <para>Stop Apache:</para>\r
- <screen>/etc/init.d/apache2 stop</screen>\r
- <para>or</para>\r
- <screen>apache2ctl stop</screen>\r
- </step>\r
- <step>\r
- <para>Stop OpenSRF:</para>\r
- <screen>osrf_ctl.sh -l -a stop_all</screen>\r
- <para>You should get either output simlar to this:</para>\r
- <screen>Stopping OpenSRF C process 12515...</screen>\r
- <screen>Stopping OpenSRF C process 12520...</screen>\r
- <screen>Stopping OpenSRF C process 12526...</screen>\r
- <screen>Stopping OpenSRF Perl process 12471...</screen>\r
- <screen>Stopping OpenSRF Router process 12466...</screen>\r
- <para>Or, if services have already been stopped, output may look like this:</para>\r
- <screen>OpenSRF C not running</screen>\r
- <screen>OpenSRF Perl not running</screen>\r
- <screen>OpenSRF Router not running</screen>\r
- <para>Occasionally osrf_ctl.sh fails to kill OpenSRF processes, so we should check to make \r
- sure that none are still running with the command:</para>\r
- <screen>ps -aef | grep OpenSRF</screen>\r
- <para>You should manually kill any OpenSRF processes.</para>\r
- <para>If you were unable to stop OpenSRF with the above methods, you could also try this \r
- command:</para>\r
- <screen>rm –R /openils/var/run/*.pid</screen>\r
- <para>This will remove the temporary OpenSRF process files from the run directory which may \r
- have been left over from a previous system boot cycle.</para>\r
- </step>\r
- <step>\r
- <para>Restart Ejabberd and Memcached with the following commands:</para>\r
- <screen>sudo /etc/init.d/ejabberd restart</screen>\r
- <screen>sudo /etc/init.d/memcached restart</screen>\r
- </step>\r
- <step> \r
- <para>Start the OpenSRF router and check for errors</para>\r
- <screen>/openils/bin/osrf_ctl.sh -l -a start_router</screen>\r
- <para>If the router started correctly, output will be:</para>\r
- <screen>Starting OpenSRF Router</screen>\r
- <para>If router does not start correctly, you should check the router error log files \r
- for error information.</para>\r
- <para>Evergreen 1.6 uses two routers, a public one and a private one, with two different \r
- logfiles:</para>\r
- <para><filename >/openils/var/log/private.router.log</filename></para>\r
- <para><filename >/openils/var/log/public.router.log</filename></para>\r
- <para>A quick way to find error information in the logs is with the grep command.</para>\r
- <screen>grep ERR /openils/var/log/*router.log</screen>\r
- <para>As a final sanity check, look for router processes using the process status \r
- command:</para>\r
- <screen>ps -aef | grep Router</screen>\r
- </step>\r
- <step>\r
- <para>Start the OpenSRF perl services and check for errors</para>\r
- <screen>/openils/bin/osrf_ctl.sh -l -a start_perl</screen>\r
- <para>You should see the output similar to the following:</para>\r
- <screen>Starting OpenSRF Perl</screen>\r
- <screen>* starting all services for ...</screen>\r
- <screen>* starting service pid=7484 opensrf.settings</screen>\r
- <screen>* starting service pid=7493 open-ils.cat</screen>\r
- <screen>* starting service pid=7495 open-ils.supercat</screen>\r
- <screen>* starting service pid=7497 open-ils.search</screen>\r
- <screen>* starting service pid=7499 open-ils.circ</screen>\r
- <screen>* starting service pid=7501 open-ils.actor</screen>\r
- <screen>* starting service pid=7502 open-ils.storage</screen>\r
- <screen>...</screen>\r
- \r
- <para>If the perl services do not start correctly or you receive errors, search for errors \r
- in the following log files:</para>\r
- <screen>/openils/var/log/router.log</screen>\r
- <screen>/openils/var/log/osrfsys.log</screen>\r
- <para>At this point you can use the <command>grep</command> command to find errors in \r
- any of the Evergreen log files:</para>\r
- <screen>grep ERR /openils/var/log/*.log</screen>\r
- <para>As a final sanity check, look for OpenSRF processes:</para>\r
- <screen>ps -aef | grep -i opensrf</screen>\r
- </step>\r
- <step>\r
- <para>Start the OpenSRF C services and check for errors:</para>\r
- <screen>/openils/bin/osrf_ctl.sh -l -a start_c</screen>\r
- <para>And output should be:</para>\r
- <para>Starting OpenSRF C (host=localhost)</para>\r
- <para>If the <emphasis>c</emphasis> service does not start, check for errors by grepping \r
- the log files for errors:</para>\r
- <screen>grep ERR /openils/var/log/*.log</screen>\r
- <para>Check for OpenSRF processes:</para>\r
- <screen>ps -aef | grep -i opensrf</screen>\r
- </step>\r
- <step>\r
- <para>Smoke test with autogen.sh<indexterm><primary>autogen</primary></indexterm></para>\r
- <para>The Autogen tool will take some dynamic information from the database and generate \r
- static JavaScript files for use by the OPAC and staff client. It is also able to refresh \r
- the proximity map between libraries for the purpose of efficiently routing hold \r
- requests.</para>\r
- <para>As user opensrf, you invoke Autogen with the command:</para>\r
- <screen>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</screen>\r
- <para>If Autogen completes successfully, the output will be:</para>\r
- <screen>Updating fieldmapper</screen>\r
- <screen>Updating web_fieldmapper</screen>\r
- <screen>Updating OrgTree</screen>\r
- <screen>removing OrgTree from the cache...</screen>\r
- <screen>Updating OrgTree HTML</screen>\r
- <screen>Updating locales selection HTML</screen>\r
- <screen>Updating Search Groups</screen>\r
- <screen>Refreshing proximity of org units</screen>\r
- <screen>Successfully updated the organization proximity</screen>\r
- <screen>Done</screen>\r
- <para>If Autogen does not complete its task and you receive errors, use \r
- <command>grep</command> to find errors in the log files:</para> \r
- <screen>grep ERR /openils/var/log/*.log</screen>\r
- </step>\r
- <step>\r
- <para>Connect to Evergreen using the srfsh command-line OpenSRF client<indexterm><primary>srfsh (command-line OpenSRF client)</primary></indexterm></para>\r
- <screen>/openils/bin/srfsh</screen>\r
- <note>\r
- <para>In order for you to connect using <command>srfsh</command>, you will need to \r
- have set up the .srfsh.xml configuration file in your home directory as as \r
- described in the installation chapter.</para>\r
- </note> \r
- <para>You will then see the <emphasis>srfsh</emphasis> prompt:</para>\r
- <screen>srfsh#</screen>\r
- <para>At the srfsh prompt, enter this command:</para>\r
- <screen>login admin open-ils</screen>\r
- <para>You should the request verification:</para>\r
- <screen>Received Data: "6f63ff5542da1fead4431c6c280efc75"</screen>\r
- <screen>------------------------------------</screen>\r
- <screen>Request Completed Successfully</screen>\r
- <screen>Request Time in seconds: 0.018414</screen>\r
- <screen>------------------------------------</screen>\r
- <screen></screen>\r
- <screen>Received Data: {</screen>\r
- <screen>"ilsevent":0,</screen>\r
- <screen>"textcode":"SUCCESS",</screen>\r
- <screen>"desc":" ",</screen>\r
- <screen>"pid":7793,</screen>\r
- <screen>"stacktrace":"oils_auth.c:312",</screen>\r
- <screen>"payload":{</screen>\r
- <screen>"authtoken":"28804ebf99508496e2a4d2593aaa930e",</screen>\r
- <screen> "authtime":420.000000</screen>\r
- <screen>}</screen>\r
- <screen>}</screen>\r
- <screen></screen>\r
- <screen>------------------------------------</screen>\r
- <screen>Request Completed Successfully</screen>\r
- <screen> Request Time in seconds: 0.552430</screen>\r
- <screen>------------------------------------</screen>\r
- <screen> Login Session: 28804. Session timeout: 420.000</screen>\r
- <screen>srfsh#</screen> \r
- <para>If you encounter errors or if you are unable to connect, you should consult the \r
- <filename>srfsh.log</filename> file. The location of this file is configured in your \r
- <filename>.srfsh.xml</filename> configuration file and is \r
- <filename>/openils/var/log/srfsh.log</filename> by default.</para>\r
- <para>Pressing \r
- <keycombo>\r
- <keycap>Ctrl</keycap>\r
- <keycap>D</keycap>\r
- </keycombo>\r
- or entering <quote>exit</quote> will terminate srfsh.</para>\r
- </step>\r
- <step>\r
- <para>Start <application>Apache</application> and check for errors:</para>\r
- <screen>/etc/init.d/apache2 start</screen>\r
- <para>or</para>\r
- <screen>apache2ctl start</screen>\r
- <para>You should see output:</para>\r
- <screen>* Starting web server apache2</screen>\r
- <screen>...done.</screen>\r
- <para>the Apache OpenSRF modules write to the \r
- <filename>/openils/var/log/gateway.log</filename></para>\r
- <para>However, you should check all of the log files for errors:</para>\r
- <screen>grep ERR /openils/var/log/*.log</screen>\r
- <para>Another place to check for errors is the <application>Apache</application> error logs\r
- generally located in in the <filename class="directory">/var/log/Apache2</filename> \r
- directory</para>\r
- <para>If you encounter errors with Apache, a common source of potential problems are the \r
- Evergreen site configuration files <filename>/etc/apache2/eg_vhost.conf</filename> and \r
- <filename>/etc/apache2/sites-available/eg.conf</filename></para>\r
- </step>\r
- <step>\r
- <para>Try to login from the <link linkend="staffclient-login">staff client</link></para>\r
- </step>\r
- <step>\r
- <para>Try to access the catalog from the OPAC</para>\r
- </step> \r
- </procedure> \r
+ <title>Troubleshooting System Errors</title>\r
+ <para>If you have Evergreen installed and are encountering systematic errors, here is the steps to find the \r
+ cause and solution to most problems. These instructions assume standard locations and file names for Evergreen\r
+ installations, and may also include commands for specific Linux distributions.</para>\r
+ <procedure>\r
+ <title>Systematic Evergreen Restart to Isolate Errors</title>\r
+ <step>\r
+ <para>Stop Apache:</para><indexterm><primary>web server</primary><secondary>Apache</secondary><tertiery>stopping</tertiery></indexterm>\r
+ <screen><userinput>/etc/init.d/apache2 stop</userinput></screen>\r
+ <para>or</para>\r
+ <screen><userinput>apache2ctl stop</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Stop OpenSRF:</para><indexterm><primary>OpenSRF</primary></indexterm>\r
+ <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
+ <para>You should get either output simlar to this:</para>\r
+ <screen>Stopping OpenSRF C process 12515...</screen>\r
+ <screen>Stopping OpenSRF C process 12520...</screen>\r
+ <screen>Stopping OpenSRF C process 12526...</screen>\r
+ <screen>Stopping OpenSRF Perl process 12471...</screen>\r
+ <screen>Stopping OpenSRF Router process 12466...</screen>\r
+ <para>Or, if services have already been stopped, output may look like this:</para>\r
+ <screen>OpenSRF C not running</screen>\r
+ <screen>OpenSRF Perl not running</screen>\r
+ <screen>OpenSRF Router not running</screen>\r
+ <para>Occasionally osrf_ctl.sh fails to kill OpenSRF processes, so we should check to make \r
+ sure that none are still running with the command:</para>\r
+ <screen><userinput>ps -aef | grep OpenSRF</userinput></screen>\r
+ <para>You should manually kill any OpenSRF processes.</para>\r
+ <para>If you were unable to stop OpenSRF with the above methods, you could also try this \r
+ command:</para>\r
+ <screen><userinput>rm –R /openils/var/run/*.pid</userinput></screen>\r
+ <para>This will remove the temporary OpenSRF process files from the run directory which may \r
+ have been left over from a previous system boot cycle.</para>\r
+ </step>\r
+ <step>\r
+ <para>Restart <systemitem class="service">Ejabberd</systemitem> and \r
+ <systemitem class="service">Memcached</systemitem> with the following commands:</para><indexterm><primary>Ejabberd</primary></indexterm>\r
+ <screen><userinput>sudo /etc/init.d/ejabberd restart</userinput></screen>\r
+ <screen><userinput>sudo /etc/init.d/memcached restart</userinput></screen><indexterm><primary>memcached</primary></indexterm>\r
+ </step>\r
+ <step> \r
+ <para>Start the OpenSRF <systemitem class="service">router</systemitem> and check for errors</para>\r
+ <indexterm><primary>OpenSRF</primary><secondary>services</secondary><tertiery>router</tertiery></indexterm>\r
+ <screen><userinput>/openils/bin/osrf_ctl.sh -l -a start_router</userinput></screen>\r
+ <para>If the <systemitem class="service">router</systemitem> started correctly, output will be:</para>\r
+ <screen>Starting OpenSRF Router</screen>\r
+ <para>If <systemitem class="service">router</systemitem> does not start correctly, you should check the <systemitem class="service">router</systemitem> error log files \r
+ for error information.</para>\r
+ <para>Evergreen 1.6 uses two routers, a public one and a private one, with two different \r
+ logfiles:</para>\r
+ <para><filename >/openils/var/log/private.router.log</filename></para><indexterm><primary>logs</primary><secondary>router</secondary></indexterm>\r
+ <para><filename >/openils/var/log/public.router.log</filename></para>\r
+ <para>A quick way to find error information in the logs is with the grep command.</para>\r
+ <screen>grep ERR /openils/var/log/*router.log</screen>\r
+ <para>As a final sanity check, look for router processes using the process status \r
+ command:</para>\r
+ <screen><userinput>ps -aef | grep Router</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Start the OpenSRF <systemitem class="service">perl</systemitem> services and check for errors</para>\r
+ <indexterm><primary>OpenSRF</primary><secondary>services</secondary><tertiery>perl</tertiery></indexterm>\r
+ <screen><userinput>/openils/bin/osrf_ctl.sh -l -a start_perl</userinput></screen>\r
+ <para>You should see the output similar to the following:</para>\r
+ <screen>\r
+ Starting OpenSRF Perl\r
+ * starting all services for ...\r
+ * starting service pid=7484 opensrf.settings\r
+ * starting service pid=7493 open-ils.cat\r
+ * starting service pid=7495 open-ils.supercat\r
+ * starting service pid=7497 open-ils.search\r
+ * starting service pid=7499 open-ils.circ\r
+ * starting service pid=7501 open-ils.actor\r
+ * starting service pid=7502 open-ils.storage\r
+ ...\r
+ </screen>\r
+ <para>If the <systemitem class="service">perl</systemitem> services do not start correctly or you receive errors, search for errors \r
+ in the following log files:</para>\r
+ <itemizedlist> \r
+ <listitem>/openils/var/log/router.log</listitem>\r
+ <listitem>/openils/var/log/osrfsys.log</listitem><indexterm><primary>logs</primary><secondary>osrfsys.log</secondary></indexterm>\r
+ </itemizedlist>\r
+ <para>At this point you can use the <command>grep</command> command to find errors in \r
+ any of the Evergreen log files:</para>\r
+ <screen><userinput>grep ERR /openils/var/log/*.log</userinput></screen>\r
+ <para>As a final sanity check, look for OpenSRF processes:</para>\r
+ <screen><userinput>ps -aef | grep -i opensrf</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Start the OpenSRF <systemitem class="service">c</systemitem> services and check for errors:</para>]\r
+ <indexterm><primary>OpenSRF</primary><secondary>services</secondary><tertiery>C</tertiery></indexterm>\r
+ <screen>/openils/bin/osrf_ctl.sh -l -a start_c</screen>\r
+ <para>And output should be:</para>\r
+ <screen>Starting OpenSRF C (host=localhost)</screen>\r
+ <para>If the <systemitem class="service">c</systemitem> service does not start, check for errors by grepping \r
+ the log files for errors:</para>\r
+ <screen><userinput>grep ERR /openils/var/log/*.log</userinput></screen>\r
+ <para>Check for <application>OpenSRF</application> processes:</para>\r
+ <screen><userinput>ps -aef | grep -i opensrf</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Smoke test with <filename>autogen.sh</filename><indexterm><primary>autogen</primary></indexterm></para>\r
+ <para>The <command>autogen</command> tool will take some dynamic information from the database and generate \r
+ static JavaScript <indexterm><primary>JavaScript</primary></indexterm> files for use by the OPAC and staff client. It is also able to refresh \r
+ the proximity map<indexterm><primary>proximity map</primary></indexterm> between libraries for the purpose of efficiently routing hold \r
+ requests.</para>\r
+ <para>As user <systemitem class="username">opensrf</systemitem>, you invoke <command>autogen</command> with the command:</para>\r
+ <screen><userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput></screen>\r
+ <para>If Autogen completes successfully, the output will be:</para>\r
+ <screen>\r
+ Updating fieldmapper\r
+ Updating web_fieldmapper\r
+ Updating OrgTree\r
+ removing OrgTree from the cache...\r
+ Updating OrgTree HTML\r
+ Updating locales selection HTML\r
+ Updating Search Groups\r
+ Refreshing proximity of org units\r
+ Successfully updated the organization proximity\r
+ Done\r
+ </screen>\r
+ <para>If Autogen does not complete its task and you receive errors, use \r
+ <command>grep</command> to find errors in the log files:</para> \r
+ <screen><userinput>grep ERR /openils/var/log/*.log</userinput></screen>\r
+ </step>\r
+ <step>\r
+ <para>Connect to Evergreen using the <command>srfsh</command> command-line OpenSRF client<indexterm><primary>srfsh (command-line OpenSRF client)</primary></indexterm></para>\r
+ <screen><userinput>/openils/bin/srfsh</userinput></screen>\r
+ <note>\r
+ <para>In order for you to connect using <command>srfsh</command>, you will need to \r
+ have set up the .srfsh.xml configuration file in your home directory as as \r
+ described in the installation chapter.</para>\r
+ </note> \r
+ <para>You will then see the <emphasis>srfsh</emphasis> prompt:</para>\r
+ <screen><prompt>srfsh#</prompt></screen>\r
+ <para>At the srfsh prompt, enter this command:</para>\r
+ <screen><userinput>login admin open-ils</userinput></screen>\r
+ <para>You should the request verification:</para>\r
+ <screen>\r
+ Received Data: "6f63ff5542da1fead4431c6c280efc75"\r
+ ------------------------------------\r
+ Request Completed Successfully\r
+ Request Time in seconds: 0.018414\r
+ ------------------------------------\r
+ \r
+ Received Data: {\r
+ "ilsevent":0,\r
+ "textcode":"SUCCESS",\r
+ "desc":" ",\r
+ "pid":7793,\r
+ "stacktrace":"oils_auth.c:312",\r
+ "payload":{\r
+ "authtoken":"28804ebf99508496e2a4d2593aaa930e",\r
+ "authtime":420.000000\r
+ }\r
+ }\r
+ \r
+ ------------------------------------\r
+ Request Completed Successfully\r
+ Request Time in seconds: 0.552430\r
+ ------------------------------------\r
+ Login Session: 28804. Session timeout: 420.000\r
+ srfsh#</screen> \r
+ <para>If you encounter errors or if you are unable to connect, you should consult the \r
+ <filename>srfsh.log</filename> file. The location of this file is configured in your <indexterm><primary>logs</primary><secondary>srfsh.log</secondary></indexterm>\r
+ <filename>.srfsh.xml</filename> configuration file and is \r
+ <filename>/openils/var/log/srfsh.log</filename> by default.</para>\r
+ <para>Pressing \r
+ <keycombo>\r
+ <keycap>Ctrl</keycap>\r
+ <keycap>D</keycap>\r
+ </keycombo>\r
+ or entering <quote>exit</quote> will terminate srfsh.</para>\r
+ </step>\r
+ <step>\r
+ <para>Start <application>Apache</application> and check for errors:</para>\r
+ <indexterm><primary>web server</primary><secondary>Apache</secondary><tertiery>starting</tertiery></indexterm>\r
+ <screen>/etc/init.d/apache2 start</screen>\r
+ <para>or</para>\r
+ <screen>apache2ctl start</screen>\r
+ <para>You should see output:</para>\r
+ <screen>\r
+ * Starting web server apache2\r
+ ...done.\r
+ </screen>\r
+ <para>the Apache OpenSRF modules write to the \r
+ <filename>/openils/var/log/gateway.log</filename></para><indexterm><primary>logs</primary><secondary>gateway.log</secondary></indexterm>\r
+ <para>However, you should check all of the log files for errors:</para>\r
+ <screen>grep ERR /openils/var/log/*.log</screen>\r
+ <para>Another place to check for errors is the <application>Apache</application> error logs\r
+ generally located in in the <filename class="directory">/var/log/Apache2</filename> <indexterm><primary>logs</primary><secondary>Apache</secondary></indexterm>\r
+ <indexterm><primary>Apache</primary><secondary>logs</secondary></indexterm>\r
+ directory</para>\r
+ <para>If you encounter errors with Apache, a common source of potential problems are the \r
+ Evergreen site configuration files <filename>/etc/apache2/eg_vhost.conf</filename> and \r
+ <filename>/etc/apache2/sites-available/eg.conf</filename></para>\r
+ <indexterm><primary>configuration files</primary><secondary>Apache</secondary><tertiery>eg.conf</tertiery></indexterm>\r
+ <indexterm><primary>configuration files</primary><secondary>Apache</secondary><tertiery>eg_vhost.conf</tertiery></indexterm>\r
+ </step>\r
+ <step>\r
+ <para>Try to login from the <link linkend="staffclient-login">staff client</link></para>\r
+ </step>\r
+ <step>\r
+ <para>Try to search the catalog from the OPAC</para>\r
+ </step> \r
+ </procedure> \r
</chapter>\r
projects / contrib / Conifer.git / commitdiff