+++ /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="adminmisc">\r
- <info>\r
- \r
- <title>Server Operations</title>\r
- <indexterm><primary>receipt template editor</primary></indexterm>\r
- <abstract>\r
- <para>This chapter deals with basic server operations such as starting and stopping <application>Evergreen</application> as well wall \r
- security, backing up and troubleshooting <application>Evergreen</application>.</para>\r
- </abstract>\r
- </info> \r
- <section xml:id="startingopensrf">\r
- <title>Starting, Stopping and Restarting</title>\r
- <para>Occasionally, you may need to restart <application>Evergreen</application>. It is imperative that you understand the basic \r
- commands to stop and start the <application>Evergreen</application> server. You can start and stop <application>Evergreen</application> from the command line of \r
- the server using the <command>osrf_ctl.sh</command> script located in the \r
- <filename class="directory">openils/bin</filename> directory.</para> \r
- <note><para><command>The osrf_ctl.sh</command> command must be run as the <systemitem class="username">opensrf</systemitem> user.</para></note>\r
- <para>To view help on <command>osrf_ctl.sh</command> and get all of its options, run:</para>\r
- <screen><userinput>osrf_ctl.sh -h</userinput></screen>\r
- <para>To start Evergreen, run:</para>\r
- <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>\r
- <para>The <option>-l</option> flag is used to indicate that Evergreen is configured to use <systemitem class="domainname">localhost</systemitem> as \r
- the host. If you have configured <filename>opensrf.xml</filename> to use your real hostname, do not use the <option>-l</option> flag. The <option>-a</option> \r
- option is required and indicates the <emphasis>action</emphasis> of the command. In this case \r
- <option>start_all</option>. \r
- </para> \r
- <note>\r
- <para>If you receive the error message: <errortext>osrf_ctl.sh: command not found</errortext>, then your environment variable \r
- <varname>PATH</varname><indexterm><primary>environment variable</primary><secondary>PATH</secondary></indexterm> does not include the \r
- <filename class="directory">/openils/bin</filename> directory. You can set it using the following command:</para>\r
- <screen><userinput>export <varname>PATH</varname>=$PATH:<filename class="directory">/openils/bin</filename></userinput></screen>\r
- <para>If you receive the error message <errortext>Can't locate OpenSRF/System.pm in @INC … BEGIN \r
- failed–compilation aborted</errortext>, then your environment variable <varname>PERL5LIB</varname><indexterm><primary>environment \r
- variable</primary><secondary>PERL5LIB</secondary></indexterm> does not \r
- include the <filename class="directory">/openils/lib/perl5</filename> directory. You can set it \r
- using the following command:</para>\r
- <screen><userinput>export <varname>PERL5LIB</varname>=$PERL5LIB:<filename class="directory">/openils/lib/perl5</filename></userinput></screen>\r
- </note> \r
- <para>It is also possible to start a specific service. For example:</para>\r
- <screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
- <para>will only start the <systemitem class="service">router</systemitem> service.</para>\r
- <caution>\r
- <para>If you decide to start each service individually, you need to start them in a specific order:</para>\r
-<screen>\r
-<userinput>osrf_ctl.sh -l -a start_router</userinput>\r
-<userinput>osrf_ctl.sh -l -a start_perl</userinput>\r
-<userinput>osrf_ctl.sh -l -a start_c</userinput>\r
-</screen>\r
- </caution> \r
- <para>After starting or restarting Evergreen, it is also necessary to restart the <systemitem class="service">Apache web server</systemitem>\r
- <indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm> for the OPAC to work correctly.</para> \r
- <para>To stop <application>Evergreen</application>, run:</para>\r
- <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
- <para>As with starting, you can choose to stop services individually.</para>\r
- <para>To restart <application>Evergreen</application>, run:</para>\r
- <screen><userinput>osrf_ctl.sh -l -a restart_all</userinput></screen>\r
- <simplesect>\r
- <title>Starting Specific Perl Services</title>\r
- <para>It is also possible to start and stop a specific perl service using <filename>opensrf-perl.pl</filename>. Here is the syntax for starting a perl service with this command:</para>\r
-<screen><userinput>opensrf-perl.pl --service <systemitem class="service"><service-name></systemitem> -a start -p <filename class="directory"><PID-directory></filename> </userinput></screen>\r
-<para>Example (starting the booking module):</para>\r
-<screen><userinput>opensrf-perl.pl --service <systemitem class="service">open-ils.booking</systemitem> -a start -p <filename class="directory">/openils/var/run/opensrf</filename></userinput></screen>\r
-\r
-<para>This is the syntax for stopping a perl service with this command:</para>\r
-<screen><userinput>opensrf-perl.pl --service <systemitem class="service"><service-name></systemitem> -a stop -p <filename class="directory"><PID-directory></filename> </userinput></screen>\r
-<para>Example (stopping the booking module):</para>\r
-<screen><userinput>opensrf-perl.pl --service <systemitem class="service">open-ils.booking</systemitem> -a stop -p <filename class="directory">/openils/var/run/opensrf</filename></userinput></screen>\r
- <para>These commands can be very useful when you edit Perl modules and only need to restart the specific service for changes to take effect.</para>\r
- \r
- <note>\r
- <para>The default for the PID-directory: <filename class="directory">/openils/var/run/opensrf</filename></para>\r
- <para>For a clustered server instance of Evergreen, you must store the PIDs on a directory \r
- that is local to each server, or else one of your cluster servers may try killing processes on itself that actually have PIDs on other servers.</para>\r
- <para>For services running on the local server use the <option>--localhost</option> to force the hostname to be <systemitem class="domainname">localhost</systemitem>, \r
- instead of the fully qualified domain name for the machine.</para>\r
- <para>To see other options run the command with the <option>-h</option> option:</para>\r
-<screen><userinput>opensrf-perl.pl -h</userinput></screen>\r
- </note>\r
-<para>For a list of Evergreen/OpenSRF perl services see: <xref linkend="_evergreen_specific_opensrf_services"/>.</para>\r
- </simplesect>\r
- </section>\r
- <section xml:id="evergreen_startup_script">\r
- <title>Automating Evergreen Startup and Shutdown</title>\r
- <para>Once you understand starting and stopping Evergreen, you will want to create a start up script for two purposes:</para>\r
- <itemizedlist>\r
- <listitem>Allow you to start, restart and stop Evergreen, SIP, reporter and z39.50 services with one command.</listitem>\r
- <listitem>Allow Evergreen to stop and start properly during a system restart.</listitem>\r
- </itemizedlist>\r
- <para>The following procedure is for Debian or Ubuntu distributions of Linux.</para>\r
- <procedure>\r
- <step>\r
- <para>Create a bash script for starting Evergreen and all associated services. Here is an example script:</para> \r
-\r
-<programlisting><![CDATA[\r
-#!/bin/bash\r
-\r
-OPENILS_BASE="/openils"\r
-OPENILS_CORE="${OPENILS_BASE}/conf/opensrf_core.xml"\r
-SRU_LOG="${OPENILS_BASE}/var/log/sru.log"\r
-\r
-SIP_PID="${OPENILS_BASE}/var/run"\r
-SIP_CONF="${OPENILS_BASE}/conf/oils_sip.xml"\r
-\r
-REP_LOCK="${OPENILS_BASE}/var/lock/reporter-LOCK"\r
-REP_NAME="Clark Kent, waiting for trouble"\r
-\r
-sru_name='simple2zoom'\r
-\r
-if [ $(whoami) != 'opensrf' ]; then\r
- PERL5LIB='/openils/lib/perl5:$PERL5LIB';\r
-fi;\r
-\r
-start() {\r
- sleep 3\r
- echo "Starting Evergreen"\r
- sudo -u opensrf /bin/bash -c \ \r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh \\r
- -l -a start_all"\r
-}\r
-\r
-stop() {\r
- echo "Stopping Evergreen"\r
- sudo -u opensrf /bin/bash -c \\r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh \\r
- -l -a stop_all"\r
-}\r
-\r
-autogen() {\r
- echo "Running Autogen Update"\r
- sudo -u opensrf /bin/bash -c \ \r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin autogen.sh \\r
- -u -c ${OPENILS_CORE}"\r
-}\r
-\r
-sip_start() {\r
- sudo -u opensrf /bin/bash -c \\r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
- -d ${SIP_PID} \\r
- -s ${SIP_CONF} \\r
- -a start_sip"\r
-}\r
-\r
-sip_stop() {\r
- sudo -u opensrf /bin/bash -c \ \r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
- -d ${SIP_PID} \\r
- -s ${SIP_CONF} \\r
- -a stop_sip"\r
-}\r
-\r
-sip_restart() {\r
- sudo -u opensrf /bin/bash -c \\r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
- -d ${SIP_PID} \\r
- -s ${SIP_CONF} \\r
- -a restart_sip"\r
-}\r
-]]></programlisting>\r
-<programlisting><![CDATA[\r
-\r
-start_rep() {\r
- pids="$(pidof "$REP_NAME")"\r
- if [ ! x"$pids" = x ] ; then\r
- echo FAILURE ; echo $"Starting Reporting: already running as $pids" \r
- return 1\r
- fi\r
- rm -f $REP_LOCK\r
- sudo -u opensrf bash -c \\r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin clark-kent.pl \\r
- --lockfile=${REP_LOCK} --boostrap=${OPENILS_CORE} --concurrency=1 --sleep=30 --daemon" ;\r
- pids="$(pidof "$REP_NAME")"\r
- if [ x"$pids" = x ] ; then\r
- echo FAILURE \r
- else \r
- echo OK\r
- fi\r
- echo "Starting Reporting: $pids" \r
- return $RETVAL\r
-}\r
-\r
-stop_rep() {\r
- pids="$(pidof "$REP_NAME")"\r
- if [ x"$pids" = x ] ; then\r
- echo FAILURE ; echo $"Stopping Reporting: not running" ; RETVAL=1\r
- else \r
- kill $pids ; RETVAL=$?\r
- if [ $RETVAL ] ; then\r
- echo OK ; echo $"Stopping Reporting: $pids"\r
- else\r
- echo FAILURE \r
- fi\r
- fi\r
- rm -f $REP_LOCK\r
- return $RETVAL\r
-}\r
-\r
-z39_50_start() {\r
- pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
- if [ ! x"$pids" = x ] ; then\r
- echo FAILURE ; echo $"Starting Z39.50/SRU: already running as $pids" \r
- return 1\r
- fi\r
- sudo -u opensrf bash -c "touch ${SRU_LOG}"\r
- sudo bash -c \ \r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin \\r
- z39_50.sh >> ${SRU_LOG} 2>&1" &\r
- sleep 1\r
- pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
- if [ x"$pids" = x ] ; then\r
- echo FAILURE \r
- else \r
- echo OK\r
- fi\r
- echo "Starting Z39.50/SRU: $pids" \r
- return $RETVAL\r
-}\r
-\r
-z39_50_stop() {\r
- pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
- if [ x"$pids" = x ] ; then\r
- echo FAILURE ; echo $"Stopping Z39.50/SRU: not running" ; RETVAL=1\r
- else \r
- kill $pids ; RETVAL=$?\r
- if [ $RETVAL ] ; then\r
- echo OK ; echo $"Stopping Z39.50/SRU: $pids"\r
- else\r
- echo FAILURE \r
- fi\r
- fi\r
- return $RETVAL\r
-}\r
-]]></programlisting>\r
-<programlisting><![CDATA[\r
-case "$1" in\r
- start)\r
- start\r
- start_rep\r
- z39_50_start\r
- sip_start\r
- ;;\r
- stop)\r
- sip_stop\r
- z39_50_stop\r
- stop_rep\r
- stop\r
- ;;\r
- restart)\r
- echo "Restarting Evergreen, Reporter and Z39.50 Processes"\r
- sip_stop\r
- z39_50_stop\r
- stop_rep\r
- stop\r
- start\r
- start_rep\r
- z39_50_start\r
- sip_start\r
- ;;\r
- autogen)\r
- autogen\r
- ;;\r
- sip_start)\r
- sip_start\r
- ;;\r
- sip_stop)\r
- sip_stop\r
- ;;\r
- sip_restart)\r
- sip_restart\r
- ;;\r
- start_reporter)\r
- start_rep\r
- ;;\r
- stop_reporter)\r
- stop_rep\r
- ;;\r
- restart_reporter)\r
- stop_rep\r
- start_rep\r
- ;;\r
- z39_50_start)\r
- z39_50_start\r
- ;;\r
- z39_50_stop)\r
- z39_50_stop\r
- ;;\r
- z39_50_restart)\r
- z39_50_stop\r
- z39_50_start\r
- ;;\r
- start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl| \\r
- start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf|stop_all|start_all|restart_all)\r
- sudo -u opensrf /bin/bash -c \\r
- "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 \ \r
- PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh -l -a $1"\r
- ;;\r
- *)\r
- echo " * Usage: /etc/init.d/evergreen {start|stop|restart|autogen"\r
- echo " |sip_start|sip_stop|sip_restart"\r
- echo " |z39_50_start|z39_50_stop|z39_50_restart"\r
- echo " |start_reporter|stop_reporter|restart_reporter"\r
- echo " |start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl"\r
- echo " |start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf \r
- |stop_all|start_all|restart_all}"\r
- exit 1\r
- ;;\r
-esac;\r
-]]></programlisting>\r
- </step>\r
- <step>\r
- <para>Save file in <filename class="directory">/etc/bin</filename> folder as <filename>evergreenstart</filename> \r
- if you would like this as a manual script for starting Evergreen services.</para> \r
- \r
- <para>Save file in <filename class="directory">/etc/init.d</filename> folder as <filename>evergreenstart</filename> \r
- if you would like to run this script automatically during your server's boot process as explained in later steps.</para> \r
- </step>\r
- <step>\r
- <para>Ensure that the script is executable.</para>\r
-<screen><userinput>sudo chmod 755 evergreenstart </userinput></screen>\r
- </step> \r
- <step>\r
- <para>Test the script by running it from the command line as the <systemitem class="username">root</systemitem> user.</para>\r
-<screen><userinput>/etc/init.d/evergreenstart restart</userinput></screen>\r
- <para>You will also need to restart apache as the <systemitem class="username">root</systemitem> user.</para>\r
-<screen><userinput>/etc/init.d/apache2 restart</userinput></screen>\r
- </step> \r
- <step>\r
- <note>\r
- <para>The next steps are optional if you want to automate Evergreen so it starts during your server's boot process.</para>\r
- </note>\r
- <para>Update runlevel defaults of the new evergreenstart service as the <systemitem class="username">root</systemitem> user:</para>\r
-<screen><userinput>update-rc.d evergreenstart defaults 80 20</userinput></screen>\r
- <note>\r
- <para>For Evergreen to start properly during a reboot, you will want to ensure that the first number \r
- (<option>80</option>) is lower than the assigned \r
- starting priority for Apache, so it starts before Apache. It should also have a larger stopping priority number \r
- (<option>20</option>) than Apache so it stops \r
- after Apache during a boot cycle.</para>\r
- </note>\r
- </step> \r
- <step>\r
- <para>Test the startup script by rebooting the Evergreen Server and checking to ensure that all Evergreen sercices started properly.</para>\r
- </step> \r
- </procedure>\r
- <caution><para>This has not yet been tested in a Evergreen multi-server, <quote>brick</quote> configuration.</para></caution> \r
- <para>For more information on update-rc.d you should review the documentation on this topic for \r
- <link xl:href="http://www.debuntu.org/how-to-manage-services-with-update-rc.d">\r
- Debian</link> or <link xl:href="http://manpages.ubuntu.com/manpages/hardy/man8/update-rc.d.8.html">Ubuntu</link> \r
- depending on your distribution of Linux.</para> \r
- </section>\r
- <section xml:id="backingup">\r
- <title>Backing Up</title>\r
- <indexterm><primary>databases</primary><secondary>backing up</secondary></indexterm>\r
- <para>Backing up your system files and data is a critical task for server and database administrators. \r
- Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and\r
- a complete catastrophe.</para> \r
- <simplesect>\r
- <title>Backing up the <application>Evergreen</application> Database</title><indexterm><primary>databases</primary></indexterm>\r
- <para>Most of the critical data for an <application>Evergreen</application> system – patrons, bibliographic records, holdings, \r
- transactions, bills – is stored in the <application>PostgreSQL</application><indexterm><primary>databases</primary>\r
- <secondary>PostgreSQL</secondary></indexterm> database. You can therefore use normal \r
- <application>PostgreSQL</application> backup procedures to backup this data. For example, the simplest method of backing up the Evergreen\r
- database is to use the <command>pg_dump</command> command to create a live backup of the database without having to \r
- interrupt any Evergreen services. Here is an example pg_dump command which will dump a local Evergreen database into a the file \r
- <filename>evergreen_db.backup</filename>:</para>\r
- <screen><userinput>pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen</userinput></screen>\r
- <para>To restore the backed up database into a new database, create a new database using the \r
- template0 database template and the UTF8 encoding, and run the <command>psql</command> command, specifying the new \r
- database as your target:</para>\r
- <screen><userinput>createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen</userinput></screen>\r
- <screen><userinput>psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen</userinput></screen>\r
- <note>\r
- <para>This method of backup is only suitable for small Evergreen instances. Larger sites \r
- should consider implementing continuous archiving (also known as <quote>log shipping</quote>) to provide \r
- more granular backups with lower system overhead. More information on backing up <application>PostgreSQL</application> \r
- databases can be found in the official <link xl:href="http://www.postgresql.org/docs/"><application>PostgreSQL</application> \r
- documentation</link>.</para>\r
- </note>\r
- </simplesect>\r
- <simplesect>\r
- <title>Backing up Evergreen Files</title>\r
- <indexterm><primary>directories</primary><secondary>backing up</secondary></indexterm>\r
- <para>When you deploy Evergreen, you will probably customize many aspects of your system including \r
- the system configuration files, <application>Apache</application> configuration files, OPAC and Staff Client. In order to \r
- protect your investment of time, you should carefully consider the best approach to backing up \r
- files.</para>\r
- <para>There are a number of ways of tackling this problem. You could create a script that regularly \r
- creates a time-stamped tarball of all of these files and copies it to a remote server - but that \r
- would build up over time to hundreds of files. You could use <link xl:href="http://www.samba.org/rsync/"><application>rsync</application></link>\r
- <indexterm><primary>rsync</primary></indexterm> to ensure that the files of \r
- interest are regularly updated on a remote server - but then you would lose track of the changes to \r
- the files, should you make a change that introduces a problem down the road.</para>\r
- <para>Perhaps one of the best options is to use a version control system like <link xl:href="http://bazaar.canonical.com">\r
- <application>Bazaar</application></link><indexterm><primary>Version Control System</primary><secondary>Subversion</secondary></indexterm>, \r
- <link xl:href="http://git-scm.com/"><application>git</application></link><indexterm><primary>Version Control System</primary><secondary>git</secondary></indexterm> \r
- or <link xl:href="http://subversion.apache.org/"><application>Subversion</application></link><indexterm><primary>Version Control System</primary>\r
- <secondary>Subversion</secondary></indexterm> to regularly push updates of the files you care about to a repository on a \r
- remote server. This gives you the advantage of quickly being able to run through the history of the \r
- changes you made, with a commenting system that reminds you why each change was made, combined with \r
- remote storage of the pertinent files in case of disaster on site. In addition, your team can create \r
- local copies of the repository and test their own changes in isolation from the production \r
- system. Using a version control system also helps to recover system customizations after an \r
- upgrade.</para>\r
- </simplesect>\r
- <simplesect>\r
- <title>Full System Backup</title>\r
- <para>A full system backup archives every file on the file system. Some basic methods require you \r
- to shut down most system processes; other methods can use mirrored RAID<indexterm><primary>RAID</primary></indexterm> setups or \r
- SAN<indexterm><primary>SAN</primary></indexterm> storage to \r
- take <quote>snapshot</quote> backups of your full system while the system continues to run. The subject of how \r
- to implement full system backups is beyond the scope of this documentation.</para>\r
- </simplesect>\r
- </section>\r
- <section xml:id="security">\r
- <title>Security</title>\r
- <indexterm><primary>security</primary></indexterm>\r
- <para>As with an ILS and resource accessible from the world wide web careful consideration needs to be \r
- given to the security of your <application>Evergreen</application> servers and database. While it is impossible to cover all aspects \r
- of security, it is important to take several precautions when setting up production <application>Evergreen</application> site.</para>\r
- <orderedlist>\r
- <listitem>\r
- <para>Change the Evergreen <systemitem class="username">admin</systemitem> password and keep it secure. The \r
- default admin password is known by anyone who has installed <application>Evergreen</application>. It is not a secret \r
- and needs to be changed by the Administrator. It should also only be shared by those who \r
- need the highest level of access to your system.</para>\r
- </listitem>\r
- <listitem>\r
- <para>Create strong passwords using a combination of numerical and alphabetical characters \r
- for all of the Administrative passwords including the <systemitem class="username">postgres</systemitem> and \r
- <systemitem class="username">opensrf</systemitem> users</para> \r
- </listitem>\r
- <listitem>\r
- <para>Open ports in the firewall<indexterm><primary>firewall</primary></indexterm> with caution - It is only necessary to open ports \r
- <systemitem class="protocol">80</systemitem> and <systemitem class="protocol">443</systemitem>\r
- for <systemitem class="protocol">TCP</systemitem> connections to the Evergreen server from the OPAC and the staff client. It is \r
- critical for administrators to understand the concepts of network security and take precautions to minimize vulnerabilities. \r
- </para>\r
- </listitem>\r
- <listitem>\r
- <para>Use permissions <indexterm><primary>permissions</primary></indexterm> and permission groups wisely - it is important to understand the \r
- purpose of the permissions and to only give users the level of access that they require.\r
- </para> \r
- </listitem>\r
- </orderedlist> \r
- </section>\r
- <section xml:id="logfiles">\r
- <title>Managing Log Files</title>\r
- <indexterm><primary>logs</primary><secondary>managing</secondary></indexterm>\r
- <para><application>Evergreen</application> comes with a sophisticated logging system, but it is important to manage the <application>OpenSRF</application> \r
- and <application>Evergreen</application> logs. This section will provide a couple of log management techniques and tools.</para> \r
- <simplesect>\r
- <title>Using the <systemitem class="service">logrotate</systemitem> Utility to Manage Log Size</title> \r
- <indexterm><primary>logs</primary><secondary>Log Rotate</secondary></indexterm>\r
- <para>Fortunately, this is not a new problem for <systemitem class="osname">Unix</systemitem> administrators, and \r
- there are a number of ways of keeping your logs under control. \r
- On <systemitem class="osname">Debian</systemitem> and <systemitem class="osname">Ubuntu</systemitem>, for example, \r
- the <systemitem class="service">logrotate</systemitem> utility controls when old log files are compressed and a new log file is started. \r
- <systemitem class="service">logrotate</systemitem> runs once a day and checks all log files that it knows about to see if a \r
- threshold of time or size has been reached and rotates the log files if a threshold condition has been met.</para>\r
- <para>To teach <systemitem class="service">logrotate</systemitem> to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, \r
- create a new file <filename>/etc/logrotate.d/evergreen</filename> with the following contents: </para>\r
-<programlisting>\r
-compress\r
-/openils/var/log/*.log {\r
-# keep the last 4 archived log files along with the current log file\r
- # log log.1.gz log.2.gz log.3.gz log.4.gz\r
- # and delete the oldest log file (what would have been log.5.gz)\r
-rotate 5\r
-# if the log file is > 50MB in size, rotate it immediately\r
-size 50M\r
- # for those logs that don't grow fast, rotate them weekly anyway\r
- weekly\r
-}\r
-</programlisting>\r
- </simplesect>\r
- <simplesect>\r
- <title>Changing Logging Level for <application>Evergreen</application></title>\r
- <indexterm><primary>logs</primary><secondary>logging levels</secondary></indexterm>\r
- <para>Change the Log Levels in your config files. Changing the level of logging will help \r
- narrow down errors.</para> \r
- <tip>\r
- <para>A high logging level is not wise to do in a production environment since it \r
- will produce vastly larger log files and thus reduce server performance.</para>\r
- </tip>\r
- <para>Change logging levels by editing the configuration file \r
- <filename>/openils/conf/opensrf_core.xml</filename><indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm></para>\r
- <para>you will want to search for lines containing <loglevel>.</para>\r
- <para> the default setting for loglevel is 3 which will log <emphasis>errors</emphasis>, \r
- <emphasis>warnings</emphasis> and <emphasis>information</emphasis>.</para>\r
- <para>The next level is 4 which is for debugging and provides additional information \r
- helpful for the debugging process.</para>\r
- <para>Thus, lines with:</para>\r
- <programlisting><loglevel>3</loglevel></programlisting>\r
- <para>Should be changed to:</para>\r
- <programlisting><loglevel>4</loglevel></programlisting>\r
- <para>to allow debugging level logging</para>\r
- <para>Other logging levels include <emphasis>0</emphasis> for no logging, \r
- <emphasis>1</emphasis> for logging errors and <emphasis>2</emphasis> for logging warnings \r
- and errors.</para>\r
- </simplesect>\r
- </section>\r
- <section xml:id="InstallingPostgreSQL">\r
- <title>Installing PostgreSQL from Source</title>\r
- <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
- <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
- version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
- to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
-\r
- <note>\r
- <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
- version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
- to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
- </note>\r
- \r
- <procedure>\r
- <step>\r
- <para>Install the application <application>stow</application> on your system if it is not already installed. Issue the following command as \r
- the <systemitem class="username">root</systemitem> user:</para>\r
-<screen>\r
-<userinput>apt-get install stow</userinput>\r
-</screen>\r
- </step>\r
- <step>\r
- <para>Download, compile, and install the latest release for PostgreSQL 8.2 (which was version <literal>8.2.12</literal> at the time of this writing). \r
- As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- \r
-<screen>\r
-<userinput>\r
-wget http://wwwmaster.postgresql.org/redir/198/h/source/v8.2.17/postgresql-8.2.17.tar.bz2\r
-tar xzf postgresql-8.2.17.tar.gz\r
-cd postgresql-8.2.17\r
-./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
-make\r
-make install\r
-cd contrib\r
-make\r
-make install\r
-cd xml2\r
-make\r
-make install\r
-cd /usr/local/stow\r
-stow pgsql\r
-</userinput>\r
-</screen>\r
- \r
- </step>\r
- <step>\r
- <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. \r
- As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
- <screen><userinput>adduser postgres</userinput></screen>\r
- </step>\r
- <step>\r
- <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
- \r
-<screen>\r
-<userinput>\r
-mkdir -p /usr/local/pgsql/data\r
-chown postgres /usr/local/pgsql/data\r
-su - postgres\r
-initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
-pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
-</userinput>\r
-</screen>\r
- <note>\r
- <para>If an error occurs during the final step above, review the path of the home directory for the \r
- <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
- </note>\r
- </step>\r
- </procedure>\r
- </section>\r
- <section xml:id="configuringPostgreSQL">\r
- <title>Configuring PostgreSQL</title>\r
- <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
- <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values \r
- and some suggested updates for several useful parameters:</para>\r
- <table>\r
- <title>Suggested configuration values</title>\r
- <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
- <colspec colnum="1" colwidth="1.0*"/>\r
- <colspec colnum="2" colwidth="1.0*"/>\r
- <colspec colnum="3" colwidth="1.0*"/>\r
- <thead>\r
- <row>\r
- <entry>Parameter</entry>\r
- <entry>Default</entry>\r
- <entry>Suggested</entry>\r
- </row>\r
- </thead>\r
- <tbody>\r
- <row>\r
- <entry>default_statistics_target</entry>\r
- <entry>10</entry>\r
- <entry>100</entry>\r
- </row>\r
- <row>\r
- <entry>work_mem</entry>\r
- <entry>4Mb</entry>\r
- <entry>128Mb</entry>\r
- </row>\r
- <row>\r
- <entry>shared_buffers</entry>\r
- <entry>8Mb</entry>\r
- <entry>512Mb</entry>\r
- </row>\r
- <row>\r
- <entry>effective_cache_size</entry>\r
- <entry>128Mb</entry>\r
- <entry>4Gb</entry>\r
- </row>\r
- </tbody>\r
- </tgroup>\r
- </table>\r
- </section>\r
-</chapter>\r
projects / Evergreen-DocBook.git / blobdiff