+++ /dev/null
-<?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><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>\r
-Stopping OpenSRF C process 12515...\r
-Stopping OpenSRF C process 12520...\r
-Stopping OpenSRF C process 12526...\r
-Stopping OpenSRF Perl process 12471...\r
-Stopping OpenSRF Router process 12466...\r
-</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
-\r
- <step>\r
- <title>Testing with <command>settings-tester.pl</command></title>\r
- <para>As the <systemitem class="username">opensrf</systemitem> user, run the script <command>settings-tester.pl</command> to see if it finds any \r
- system configuration problems.</para>\r
-<screen> \r
-<userinput>cd /home/opensrf/Evergreen-ILS-1.6.0.0</userinput>\r
-<userinput>perl Open-ILS/src/support-scripts/settings-tester.pl</userinput>\r
-</screen>\r
- <para>Here is example output from running <command>settings-tester.pl</command>:</para>\r
-<screen>\r
-LWP::UserAgent version 5.810\r
-XML::LibXML version 1.70\r
-XML::LibXML::XPathContext version 1.70\r
-XML::LibXSLT version 1.70\r
-Net::Server::PreFork version 0.97\r
-Cache::Memcached version 1.24\r
-Class::DBI version 0.96\r
-Class::DBI::AbstractSearch version 0.07\r
-Template version 2.19\r
-DBD::Pg version 2.8.2\r
-Net::Z3950::ZOOM version 1.24\r
-MARC::Record version 2.0.0\r
-MARC::Charset version 1.1\r
-MARC::File::XML version 0.92\r
-Text::Aspell version 0.04\r
-CGI version 3.29\r
-DateTime::TimeZone version 0.7701\r
-DateTime version 0.42\r
-DateTime::Format::ISO8601 version 0.06\r
-DateTime::Format::Mail version 0.3001\r
-Unix::Syslog version 1.1\r
-GD::Graph3d version 0.63\r
-JavaScript::SpiderMonkey version 0.19\r
-Log::Log4perl version 1.16\r
-Email::Send version 2.192\r
-Text::CSV version 1.06\r
-Text::CSV_XS version 0.52\r
-Spreadsheet::WriteExcel::Big version 2.20\r
-Tie::IxHash version 1.21\r
-Parse::RecDescent version 1.95.1\r
-SRU version 0.99\r
-JSON::XS version 2.27\r
-</screen>\r
-<screen>\r
-Checking Jabber connection for user opensrf, domain private.localhost\r
-* Jabber successfully connected\r
-\r
-Checking Jabber connection for user opensrf, domain public.localhost\r
-* Jabber successfully connected\r
-\r
-Checking Jabber connection for user router, domain public.localhost\r
-* Jabber successfully connected\r
-\r
-Checking Jabber connection for user router, domain private.localhost\r
-* Jabber successfully connected\r
-\r
-Checking database connections\r
-* /opensrf/default/reporter/setup :: Successfully connected to database...\r
- * Database has the expected server encoding UTF8.\r
-* /opensrf/default/apps/open-ils.storage/app_settings/databases :: Successfully...\r
-* /opensrf/default/apps/open-ils.cstore/app_settings :: Successfully...\r
- * Database has the expected server encoding UTF8.\r
-* /opensrf/default/apps/open-ils.pcrud/app_settings :: Successfully ...\r
- * Database has the expected server encoding UTF8.\r
-* /opensrf/default/apps/open-ils.reporter-store/app_settings :: Successfully...\r
- * Database has the expected server encoding UTF8.\r
-\r
-Checking database drivers to ensure <driver> matches <language>\r
-* OK: Pg language is undefined for reporter base configuration\r
-* OK: Pg language is undefined for reporter base configuration\r
-* OK: Pg language is perl in /opensrf/default/apps/open-ils.storage/language\r
-* OK: pgsql language is C in /opensrf/default/apps/open-ils.cstore/language\r
-* OK: pgsql language is C in /opensrf/default/apps/open-ils.pcrud/language\r
-* OK: pgsql language is C in /opensrf/default/apps/open-ils.reporter-store/language\r
-\r
-Checking libdbi and libdbi-drivers\r
- * OK - found locally installed libdbi.so and libdbdpgsql.so in shared library path\r
-\r
-Checking hostname\r
- * OK: found hostname 'localhost' in <hosts> section of opensrf.xml\r
-$\r
-</screen>\r
- <para>If the output from the script does not help you find the problem, please do not make any further significant changes to your configuration. \r
- Follow the steps in the troubleshooting guide in <xref linkend="troubleshooting"/>.</para>\r
- </step>\r
- <step>\r
- <para>Try to login from the <link linkend="staffclient-login">staff client</link></para><indexterm><primary>staff client</primary><secondary>testing</secondary></indexterm>\r
- </step>\r
- <step xml:id="testing-opac">\r
- <title>Testing the Catalog</title>\r
- <indexterm><primary>OPAC</primary><secondary>testing</secondary></indexterm>\r
- <para>By default, the OPAC will live at the URL <uri>http://my.domain.com/opac/</uri>.</para>\r
- <para>Navigate to this URL and the front page of the OPAC should load. There is a basic text entry field with some extra search options. If you have any \r
- problems loading this page, check the Apache error logs. If the page loads but does not function correctly, then check for possible javascript errors. We \r
- highly recommend testing with the <application>Firefox</application> browser because of the helpful javascript debugging tools.</para>\r
- <para>Assuming that the OPAC is functioning and there is data in your database, you can now perform other simple functional tests \r
- (e.g., searching the catalog).</para>\r
- </step> \r
- </procedure> \r
-</chapter>\r
projects / Evergreen-DocBook.git / blobdiff