1.6/admin/AdminMisc.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3             xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="adminmisc">\r
   4         <info>\r
   5                 \r
   6         <title>Server Operations</title>\r
   7         <indexterm><primary>receipt template editor</primary></indexterm>\r
   8                 <abstract>\r
   9                         <para>This chapter deals with basic server operations such as starting and stopping <application>Evergreen</application> as well wall \r
  10                         security, backing up and troubleshooting <application>Evergreen</application>.</para>\r
  11                 </abstract>\r
  12         </info>    \r
  13         <section xml:id="startingopensrf">\r
  14                 <title>Starting, Stopping and Restarting</title>\r
  15                 <para>Occasionally, you may need to restart <application>Evergreen</application>. It is imperative that you understand the basic \r
  16                 commands to stop and start the <application>Evergreen</application> server. You can start and stop <application>Evergreen</application> from the command line of \r
  17                 the server using the <command>osrf_ctl.sh</command> script located in the \r
  18                 <filename class="directory">openils/bin</filename> directory.</para>   \r
  19                 <note><para><command>The osrf_ctl.sh</command> command must be run as the <systemitem class="username">opensrf</systemitem> user.</para></note>\r
  20                 <para>To view help on <command>osrf_ctl.sh</command> and get all of its options, run:</para>\r
  21                 <screen><userinput>osrf_ctl.sh -h</userinput></screen>\r
  22                 <para>To start Evergreen, run:</para>\r
  23                 <screen><userinput>osrf_ctl.sh -l -a start_all</userinput></screen>\r
  24                 <para>The <option>-l</option> flag is used to indicate that Evergreen is configured to use <systemitem class="domainname">localhost</systemitem> as \r
  25                 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
  26                 option is required and indicates the <emphasis>action</emphasis> of the command. In this case \r
  27                 <option>start_all</option>.    \r
  28                 </para> \r
  29                 <note>\r
  30                         <para>If you receive the error message: <errortext>osrf_ctl.sh: command not found</errortext>, then your environment variable \r
  31                         <varname>PATH</varname><indexterm><primary>environment variable</primary><secondary>PATH</secondary></indexterm> does not include the \r
  32                         <filename class="directory">/openils/bin</filename> directory. You can set it using the following command:</para>\r
  33                         <screen><userinput>export <varname>PATH</varname>=$PATH:<filename class="directory">/openils/bin</filename></userinput></screen>\r
  34                         <para>If you receive the error message <errortext>Can't locate OpenSRF/System.pm in @INC … BEGIN \r
  35                         failed–compilation aborted</errortext>, then your environment variable <varname>PERL5LIB</varname><indexterm><primary>environment \r
  36                         variable</primary><secondary>PERL5LIB</secondary></indexterm> does not \r
  37                         include the <filename class="directory">/openils/lib/perl5</filename> directory.  You can set it \r
  38                         using the following command:</para>\r
  39                         <screen><userinput>export <varname>PERL5LIB</varname>=$PERL5LIB:<filename class="directory">/openils/lib/perl5</filename></userinput></screen>\r
  40                 </note>         \r
  41                 <para>It is also possible to start a specific service. For example:</para>\r
  42                 <screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
  43                 <para>will only start the <systemitem class="service">router</systemitem> service.</para>\r
  44                 <caution>\r
  45                         <para>If you decide to start each service individually, you need to start them in a specific order \r
  46                         for Evergreen to start correctly. Run the commands in this exact order:</para>\r
  47 <screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
  48 <screen><userinput>osrf_ctl.sh -l -a start_perl</userinput></screen>\r
  49 <screen><userinput>osrf_ctl.sh -l -a start_c</userinput></screen>\r
  50                 </caution>      \r
  51                 <para>After starting or restarting Evergreen, it is also necessary to restart the <systemitem class="service">Apache web server</systemitem>\r
  52                 <indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm> for the OPAC to work correctly.</para>  \r
  53                 <para>To stop <application>Evergreen</application>, run:</para>\r
  54                 <screen><userinput>osrf_ctl.sh -l -a stop_all</userinput></screen>\r
  55                 <para>As with starting, you can choose to stop services individually.</para>\r
  56                 <para>To restart <application>Evergreen</application>, run:</para>\r
  57                 <screen><userinput>osrf_ctl.sh -l -a restart_all</userinput></screen>\r
  58                 <simplesect>\r
  59                         <title>Starting Specific Perl Services</title>\r
  60                         <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
  61 <screen><userinput>opensrf-perl.pl --service <systemitem class="service">&lt;service-name&gt;</systemitem> -a start -p <filename class="directory">&lt;PID-directory&gt;</filename> </userinput></screen>\r
  62 <para>Example (starting the booking module):</para>\r
  63 <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
  64 \r
  65 <para>This is the syntax for stopping a perl service with this command:</para>\r
  66 <screen><userinput>opensrf-perl.pl --service <systemitem class="service">&lt;service-name&gt;</systemitem> -a stop -p <filename class="directory">&lt;PID-directory&gt;</filename> </userinput></screen>\r
  67 <para>Example (stopping the booking module):</para>\r
  68 <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
  69                         <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
  70                         \r
  71                         <note>\r
  72                         <para>The default for the PID-directory: <filename class="directory">/openils/var/run/opensrf</filename></para>\r
  73                         <para>For a clustered server instance of Evergreen, you must store the PIDs on a directory \r
  74                         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
  75                         <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
  76                         instead of the fully qualified domain name for the machine.</para>\r
  77                         <para>To see other options run the command with the <option>-h</option> option:</para>\r
  78 <screen><userinput>opensrf-perl.pl  -h</userinput></screen>\r
  79                         </note>\r
  80 <para>For a list of Evergreen/OpenSRF perl services see: <xref linkend="_evergreen_specific_opensrf_services"/>.</para>\r
  81                 </simplesect>\r
  82         </section>\r
  83         <section xml:id="evergreen_startup_script">\r
  84                 <title>Automating Evergreen Startup and Shutdown</title>\r
  85                 <para>Once you understand starting and stopping Evergreen, you will want to create a start up script for two purposes:</para>\r
  86                 <itemizedlist>\r
  87                         <listitem>Allow you to start, restart and stop Evergreen, SIP, reporter and z39.50 services with one command.</listitem>\r
  88                         <listitem>Allow Evergreen to stop and start properly during a system restart.</listitem>\r
  89                 </itemizedlist>\r
  90                 <para>The following procedure is for Debian or Ubuntu distributions of Linux.</para>\r
  91                 <procedure>\r
  92                         <step>\r
  93                                 <para>Create a bash script for starting Evergreen and all associated services. Here is an example script:</para>  \r
  94 \r
  95 <programlisting><![CDATA[\r
  96 #!/bin/bash\r
  97 \r
  98 OPENILS_BASE="/openils"\r
  99 OPENILS_CORE="${OPENILS_BASE}/conf/opensrf_core.xml"\r
 100 SRU_LOG="${OPENILS_BASE}/var/log/sru.log"\r
 101 \r
 102 SIP_PID="${OPENILS_BASE}/var/run"\r
 103 SIP_CONF="${OPENILS_BASE}/conf/oils_sip.xml"\r
 104 \r
 105 REP_LOCK="${OPENILS_BASE}/var/lock/reporter-LOCK"\r
 106 REP_NAME="Clark Kent, waiting for trouble"\r
 107 \r
 108 sru_name='simple2zoom'\r
 109 \r
 110 if [ $(whoami) != 'opensrf' ]; then\r
 111  PERL5LIB='/openils/lib/perl5:$PERL5LIB';\r
 112 fi;\r
 113 \r
 114 start() {\r
 115         sleep 3\r
 116         echo "Starting Evergreen"\r
 117         sudo -u opensrf /bin/bash -c \ \r
 118         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh \\r
 119         -l -a start_all"\r
 120 }\r
 121 \r
 122 stop() {\r
 123         echo "Stopping Evergreen"\r
 124         sudo -u opensrf /bin/bash -c \\r
 125         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh \\r
 126         -l -a stop_all"\r
 127 }\r
 128 \r
 129 autogen() {\r
 130         echo "Running Autogen Update"\r
 131         sudo -u opensrf /bin/bash -c \ \r
 132         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin autogen.sh \\r
 133          -u -c ${OPENILS_CORE}"\r
 134 }\r
 135 \r
 136 sip_start() {\r
 137         sudo -u opensrf /bin/bash -c \\r
 138         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
 139         -d ${SIP_PID} \\r
 140         -s ${SIP_CONF} \\r
 141         -a start_sip"\r
 142 }\r
 143 \r
 144 sip_stop() {\r
 145         sudo -u opensrf /bin/bash -c \ \r
 146         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
 147         -d ${SIP_PID} \\r
 148         -s ${SIP_CONF} \\r
 149         -a stop_sip"\r
 150 }\r
 151 \r
 152 sip_restart() {\r
 153         sudo -u opensrf /bin/bash -c \\r
 154         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin oils_ctl.sh \\r
 155         -d ${SIP_PID} \\r
 156          -s ${SIP_CONF} \\r
 157         -a restart_sip"\r
 158 }\r
 159 ]]></programlisting>\r
 160 <programlisting><![CDATA[\r
 161 \r
 162 start_rep() {\r
 163         pids="$(pidof "$REP_NAME")"\r
 164         if [ ! x"$pids" = x ] ; then\r
 165           echo FAILURE ; echo $"Starting Reporting: already running as $pids" \r
 166           return 1\r
 167         fi\r
 168         rm -f $REP_LOCK\r
 169         sudo -u opensrf bash -c \\r
 170         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin clark-kent.pl \\r
 171         --lockfile=${REP_LOCK} --boostrap=${OPENILS_CORE} --concurrency=1 --sleep=30 --daemon" ;\r
 172         pids="$(pidof "$REP_NAME")"\r
 173         if [ x"$pids" = x ] ; then\r
 174           echo FAILURE \r
 175         else \r
 176           echo OK\r
 177         fi\r
 178         echo "Starting Reporting: $pids" \r
 179         return $RETVAL\r
 180 }\r
 181 \r
 182 stop_rep() {\r
 183         pids="$(pidof "$REP_NAME")"\r
 184         if [ x"$pids" = x ] ; then\r
 185           echo FAILURE ; echo $"Stopping Reporting: not running" ; RETVAL=1\r
 186         else \r
 187           kill $pids ; RETVAL=$?\r
 188           if [ $RETVAL ] ; then\r
 189             echo OK ; echo $"Stopping Reporting: $pids"\r
 190           else\r
 191             echo FAILURE \r
 192           fi\r
 193         fi\r
 194         rm -f $REP_LOCK\r
 195         return $RETVAL\r
 196 }\r
 197 \r
 198 z39_50_start() {\r
 199         pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
 200         if [ ! x"$pids" = x ] ; then\r
 201           echo FAILURE ; echo $"Starting Z39.50/SRU: already running as $pids" \r
 202           return 1\r
 203         fi\r
 204         sudo -u opensrf bash -c "touch ${SRU_LOG}"\r
 205         sudo bash -c \ \r
 206         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 PATH=${PATH}:${OPENILS_BASE}/bin \\r
 207         z39_50.sh >> ${SRU_LOG} 2>&1" &\r
 208         sleep 1\r
 209         pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
 210         if [ x"$pids" = x ] ; then\r
 211           echo FAILURE \r
 212         else \r
 213           echo OK\r
 214         fi\r
 215         echo "Starting Z39.50/SRU: $pids" \r
 216         return $RETVAL\r
 217 }\r
 218 \r
 219 z39_50_stop() {\r
 220         pids=`ps -eo pid,args | grep $sru_name | grep -v grep | cut -c1-6`\r
 221         if [ x"$pids" = x ] ; then\r
 222           echo FAILURE ; echo $"Stopping Z39.50/SRU: not running" ; RETVAL=1\r
 223         else \r
 224           kill $pids ; RETVAL=$?\r
 225           if [ $RETVAL ] ; then\r
 226             echo OK ; echo $"Stopping Z39.50/SRU: $pids"\r
 227           else\r
 228             echo FAILURE \r
 229           fi\r
 230         fi\r
 231         return $RETVAL\r
 232 }\r
 233 ]]></programlisting>\r
 234 <programlisting><![CDATA[\r
 235 case "$1" in\r
 236     start)\r
 237         start\r
 238         start_rep\r
 239         z39_50_start\r
 240         sip_start\r
 241     ;;\r
 242     stop)\r
 243         sip_stop\r
 244         z39_50_stop\r
 245         stop_rep\r
 246         stop\r
 247     ;;\r
 248     restart)\r
 249         echo "Restarting Evergreen, Reporter and Z39.50 Processes"\r
 250         sip_stop\r
 251         z39_50_stop\r
 252         stop_rep\r
 253         stop\r
 254         start\r
 255         start_rep\r
 256         z39_50_start\r
 257         sip_start\r
 258     ;;\r
 259     autogen)\r
 260         autogen\r
 261     ;;\r
 262     sip_start)\r
 263         sip_start\r
 264     ;;\r
 265     sip_stop)\r
 266         sip_stop\r
 267     ;;\r
 268     sip_restart)\r
 269         sip_restart\r
 270     ;;\r
 271     start_reporter)\r
 272         start_rep\r
 273     ;;\r
 274     stop_reporter)\r
 275         stop_rep\r
 276     ;;\r
 277     restart_reporter)\r
 278         stop_rep\r
 279         start_rep\r
 280     ;;\r
 281     z39_50_start)\r
 282         z39_50_start\r
 283     ;;\r
 284     z39_50_stop)\r
 285         z39_50_stop\r
 286     ;;\r
 287     z39_50_restart)\r
 288         z39_50_stop\r
 289         z39_50_start\r
 290     ;;\r
 291     start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl| \\r
 292     start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf|stop_all|start_all|restart_all)\r
 293         sudo -u opensrf /bin/bash -c \\r
 294         "PERL5LIB=${PERL5LIB}:${OPENILS_BASE}/lib/perl5 \ \r
 295         PATH=${PATH}:${OPENILS_BASE}/bin osrf_ctl.sh -l -a $1"\r
 296     ;;\r
 297     *)\r
 298         echo " * Usage: /etc/init.d/evergreen {start|stop|restart|autogen"\r
 299         echo "  |sip_start|sip_stop|sip_restart"\r
 300         echo "  |z39_50_start|z39_50_stop|z39_50_restart"\r
 301         echo "  |start_reporter|stop_reporter|restart_reporter"\r
 302         echo "  |start_router|stop_router|restart_router|start_perl|stop_perl|restart_perl"\r
 303         echo "  |start_c|stop_c|restart_c|start_osrf|stop_osrf|restart_osrf \r
 304                 |stop_all|start_all|restart_all}"\r
 305         exit 1\r
 306     ;;\r
 307 esac;\r
 308 ]]></programlisting>\r
 309                         </step>\r
 310                         <step>\r
 311                                 <para>Save file in <filename class="directory">/etc/bin</filename> folder as <filename>evergreenstart</filename> \r
 312                                 if you would like this as a manual script for starting Evergreen services.</para> \r
 313                                 \r
 314                                 <para>Save file in <filename class="directory">/etc/init.d</filename> folder as <filename>evergreenstart</filename> \r
 315                                 if you would like to run this script automatically during your server's boot process as explained in later steps.</para> \r
 316                         </step>\r
 317                         <step>\r
 318                         <para>Ensure that the script is executable.</para>\r
 319 <screen><userinput>sudo chmod 755 evergreenstart </userinput></screen>\r
 320                         </step> \r
 321                         <step>\r
 322                                 <para>Test the script by running it from the command line as the <systemitem class="username">root</systemitem> user.</para>\r
 323 <screen><userinput>/etc/init.d/evergreenstart restart</userinput></screen>\r
 324                                 <para>You will also need to restart apache as the <systemitem class="username">root</systemitem> user.</para>\r
 325 <screen><userinput>/etc/init.d/apache2 restart</userinput></screen>\r
 326                         </step> \r
 327                         <step>\r
 328                                 <note>\r
 329                                         <para>The next steps are optional if you want to automate Evergreen so it starts during your server's boot process.</para>\r
 330                                 </note>\r
 331                                 <para>Update runlevel defaults of the new evergreenstart service as the <systemitem class="username">root</systemitem>  user:</para>\r
 332 <screen><userinput>update-rc.d evergreenstart defaults 80 20</userinput></screen>\r
 333                                 <note>\r
 334                                         <para>For Evergreen to start properly during a reboot, you will want to ensure that the first number \r
 335                                         (<option>80</option>) is lower than the assigned \r
 336                                         starting priority for Apache, so it starts before Apache. It should also have a larger stopping priority number \r
 337                                         (<option>20</option>) than Apache so it stops \r
 338                                         after Apache during a boot cycle.</para>\r
 339                                 </note>\r
 340                         </step> \r
 341                         <step>\r
 342                         <para>Test the startup script by rebooting the Evergreen Server and checking to ensure that all Evergreen sercices started properly.</para>\r
 343                         </step> \r
 344                 </procedure>\r
 345                 <caution><para>This has not yet been tested in a Evergreen multi-server, <quote>brick</quote> configuration.</para></caution> \r
 346                 <para>For more information on update-rc.d you should review the documentation on this topic for \r
 347                 <link xl:href="http://www.debuntu.org/how-to-manage-services-with-update-rc.d">\r
 348                 Debian</link> or <link xl:href="http://manpages.ubuntu.com/manpages/hardy/man8/update-rc.d.8.html">Ubuntu</link> \r
 349                 depending on your distribution of Linux.</para>         \r
 350         </section>\r
 351         <section xml:id="backingup">\r
 352                 <title>Backing Up</title>\r
 353                 <indexterm><primary>databases</primary><secondary>backing up</secondary></indexterm>\r
 354                 <para>Backing up your system files and data is a critical task for server and database administrators. \r
 355                 Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and\r
 356                 a complete catastrophe.</para>   \r
 357                 <simplesect>\r
 358                         <title>Backing up the <application>Evergreen</application> Database</title><indexterm><primary>databases</primary></indexterm>\r
 359                         <para>Most of the critical data for an <application>Evergreen</application> system – patrons, bibliographic records, holdings, \r
 360                         transactions, bills – is stored in the <application>PostgreSQL</application><indexterm><primary>databases</primary>\r
 361                         <secondary>PostgreSQL</secondary></indexterm>  database. You can therefore use normal \r
 362                         <application>PostgreSQL</application> backup procedures to backup this data. For example, the simplest method of backing up the Evergreen\r
 363                         database is to use the <command>pg_dump</command> command to create a live backup of the database without having to \r
 364                         interrupt any Evergreen services. Here is an example pg_dump command which will dump a local Evergreen database into a the file \r
 365                         <filename>evergreen_db.backup</filename>:</para>\r
 366                         <screen><userinput>pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen</userinput></screen>\r
 367                         <para>To restore the backed up database into a new database, create a new database using the \r
 368                         template0 database template and the UTF8 encoding, and run the <command>psql</command> command, specifying the new \r
 369                         database as your target:</para>\r
 370                         <screen><userinput>createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen</userinput></screen>\r
 371                         <screen><userinput>psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen</userinput></screen>\r
 372                         <note>\r
 373                                 <para>This method of backup is only suitable for small Evergreen instances. Larger sites \r
 374                                 should consider implementing continuous archiving (also known as <quote>log shipping</quote>) to provide \r
 375                                 more granular backups with lower system overhead. More information on backing up <application>PostgreSQL</application> \r
 376                                 databases can be found in the official <link xl:href="http://www.postgresql.org/docs/"><application>PostgreSQL</application> \r
 377                                 documentation</link>.</para>\r
 378                         </note>\r
 379                 </simplesect>\r
 380                 <simplesect>\r
 381                         <title>Backing up Evergreen Files</title>\r
 382                         <indexterm><primary>directories</primary><secondary>backing up</secondary></indexterm>\r
 383                         <para>When you deploy Evergreen, you will probably customize many aspects of your system including \r
 384                         the system configuration files, <application>Apache</application> configuration files, OPAC and Staff Client. In order to \r
 385                         protect your investment of time, you should carefully consider the best approach to backing up \r
 386                         files.</para>\r
 387                         <para>There are a number of ways of tackling this problem. You could create a script that regularly \r
 388                         creates a time-stamped tarball of all of these files and copies it to a remote server - but that \r
 389                         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
 390                         <indexterm><primary>rsync</primary></indexterm> to ensure that the files of \r
 391                         interest are regularly updated on a remote server - but then you would lose track of the changes to \r
 392                         the files, should you make a change that introduces a problem down the road.</para>\r
 393                         <para>Perhaps one of the best options is to use a version control system like <link xl:href="http://bazaar.canonical.com">\r
 394                         <application>Bazaar</application></link><indexterm><primary>Version Control System</primary><secondary>Subversion</secondary></indexterm>, \r
 395                         <link xl:href="http://git-scm.com/"><application>git</application></link><indexterm><primary>Version Control System</primary><secondary>git</secondary></indexterm> \r
 396                         or <link xl:href="http://subversion.apache.org/"><application>Subversion</application></link><indexterm><primary>Version Control System</primary>\r
 397                         <secondary>Subversion</secondary></indexterm> to regularly push updates of the files you care about to a repository on a \r
 398                         remote server. This gives you the advantage of quickly being able to run through the history of the \r
 399                         changes you made, with a commenting system that reminds you why each change was made, combined with \r
 400                         remote storage of the pertinent files in case of disaster on site. In addition, your team can create \r
 401                         local copies of the repository and test their own changes in isolation from the production \r
 402                         system. Using a version control system also helps to recover system customizations after an \r
 403                         upgrade.</para>\r
 404                 </simplesect>\r
 405                 <simplesect>\r
 406                         <title>Full System Backup</title>\r
 407                         <para>A full system backup archives every file on the file system. Some basic methods require you \r
 408                         to shut down most system processes; other methods can use mirrored RAID<indexterm><primary>RAID</primary></indexterm> setups or \r
 409                         SAN<indexterm><primary>SAN</primary></indexterm> storage to \r
 410                         take <quote>snapshot</quote> backups of your full system while the system continues to run. The subject of how \r
 411                         to implement full system backups is beyond the scope of this documentation.</para>\r
 412                 </simplesect>\r
 413         </section>\r
 414         <section xml:id="security">\r
 415                 <title>Security</title>\r
 416                 <indexterm><primary>security</primary></indexterm>\r
 417                 <para>As with an ILS and resource accessible from the world wide web careful consideration needs to be \r
 418                 given to the security of your <application>Evergreen</application> servers and database. While it is impossible to cover all aspects \r
 419                 of security, it is important to take several precautions when setting up production <application>Evergreen</application> site.</para>\r
 420                 <orderedlist>\r
 421                         <listitem>\r
 422                                 <para>Change the Evergreen <systemitem class="username">admin</systemitem> password and keep it secure. The \r
 423                                 default admin password is known by anyone who has installed <application>Evergreen</application>. It is not a secret \r
 424                                 and needs to be changed by the Administrator. It should also only be shared by those who \r
 425                                 need the highest level of access to your system.</para>\r
 426                         </listitem>\r
 427                         <listitem>\r
 428                                 <para>Create strong passwords using a combination of numerical and alphabetical characters \r
 429                                 for all of the Administrative passwords including the <systemitem class="username">postgres</systemitem> and \r
 430                                 <systemitem class="username">opensrf</systemitem> users</para>     \r
 431                         </listitem>\r
 432                         <listitem>\r
 433                                 <para>Open ports in the firewall<indexterm><primary>firewall</primary></indexterm> with caution - It is only necessary to open ports \r
 434                                 <systemitem class="protocol">80</systemitem> and <systemitem class="protocol">443</systemitem>\r
 435                                 for <systemitem class="protocol">TCP</systemitem> connections to the Evergreen server from the OPAC and the staff client.  It is \r
 436                                 critical for administrators to understand the concepts of network security and take precautions to minimize vulnerabilities. \r
 437                                 </para>\r
 438                         </listitem>\r
 439                         <listitem>\r
 440                                 <para>Use permissions <indexterm><primary>permissions</primary></indexterm> and permission groups wisely - it is important to understand the \r
 441                                 purpose of the permissions and to only give users the level of access that they require.\r
 442                                 </para> \r
 443                         </listitem>\r
 444                                         </orderedlist>  \r
 445         </section>\r
 446         <section xml:id="logfiles">\r
 447                 <title>Managing Log Files</title>\r
 448                 <indexterm><primary>logs</primary><secondary>managing</secondary></indexterm>\r
 449                 <para><application>Evergreen</application> comes with a sophisticated logging system, but it is important to manage the <application>OpenSRF</application> \r
 450                 and <application>Evergreen</application> logs. This section will provide a couple of log management techniques and tools.</para>        \r
 451                 <simplesect>\r
 452                         <title>Using the <systemitem class="service">logrotate</systemitem> Utility to Manage Log Size</title> \r
 453                         <indexterm><primary>logs</primary><secondary>Log Rotate</secondary></indexterm>\r
 454                          <para>Fortunately, this is not a new problem for <systemitem class="osname">Unix</systemitem> administrators, and \r
 455                         there are a number of ways of keeping your logs under control. \r
 456                         On <systemitem class="osname">Debian</systemitem> and <systemitem class="osname">Ubuntu</systemitem>, for example, \r
 457                         the <systemitem class="service">logrotate</systemitem> utility controls when old log files are compressed and a new log file is started. \r
 458                         <systemitem class="service">logrotate</systemitem> runs once a day and checks all log files that it knows about to see if a \r
 459                         threshold of time or size has been reached and rotates the log files if a threshold condition has been met.</para>\r
 460                         <para>To teach <systemitem class="service">logrotate</systemitem> to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, \r
 461                         create a new file <filename>/etc/logrotate.d/evergreen</filename> with the following contents: </para>\r
 462 <programlisting>\r
 463 compress\r
 464 /openils/var/log/*.log {\r
 465 # keep the last 4 archived log files along with the current log file\r
 466  # log log.1.gz log.2.gz log.3.gz log.4.gz\r
 467  # and delete the oldest log file (what would have been log.5.gz)\r
 468 rotate 5\r
 469 # if the log file is > 50MB in size, rotate it immediately\r
 470 size 50M\r
 471  # for those logs that don't grow fast, rotate them weekly anyway\r
 472   weekly\r
 473 }\r
 474 </programlisting>\r
 475                 </simplesect>\r
 476                 <simplesect>\r
 477                         <title>Changing Logging Level for <application>Evergreen</application></title>\r
 478                         <indexterm><primary>logs</primary><secondary>logging levels</secondary></indexterm>\r
 479                         <para>Change the Log Levels in your config files. Changing the level of logging will help \r
 480                         narrow down errors.</para> \r
 481                         <tip>\r
 482                                 <para>A high logging level is not wise to do in a production environment since  it \r
 483                                 will produce vastly larger log files and thus reduce server performance.</para>\r
 484                         </tip>\r
 485                         <para>Change logging levels by editing the configuration file \r
 486                         <filename>/openils/conf/opensrf_core.xml</filename><indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm></para>\r
 487                         <para>you will want to search for lines containing &lt;loglevel&gt;.</para>\r
 488                         <para> the default setting for loglevel is 3 which will log <emphasis>errors</emphasis>, \r
 489                         <emphasis>warnings</emphasis> and <emphasis>information</emphasis>.</para>\r
 490                         <para>The next level is 4 which is for debugging and provides additional information \r
 491                         helpful for the debugging process.</para>\r
 492                         <para>Thus, lines with:</para>\r
 493                         <programlisting>&lt;loglevel&gt;3&lt;/loglevel&gt;</programlisting>\r
 494                         <para>Should be changed to:</para>\r
 495                         <programlisting>&lt;loglevel&gt;4&lt;/loglevel&gt;</programlisting>\r
 496                         <para>to allow debugging level logging</para>\r
 497                         <para>Other logging levels include <emphasis>0</emphasis> for no logging, \r
 498                         <emphasis>1</emphasis> for logging errors and <emphasis>2</emphasis> for logging warnings \r
 499                         and errors.</para>\r
 500                 </simplesect>\r
 501         </section>\r
 502         <section xml:id="InstallingPostgreSQL">\r
 503                 <title>Installing PostgreSQL from Source</title>\r
 504                 <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
 505                 <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
 506                 version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
 507                 to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
 508 \r
 509                 <note>\r
 510                         <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
 511                 version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
 512                 to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
 513                 </note>\r
 514                 \r
 515                 <procedure>\r
 516                         <step>\r
 517                                 <para>Install the application <application>stow</application> on your system if it is not already installed. Issue the following command as \r
 518                                 the <systemitem class="username">root</systemitem> user:</para>\r
 519 <screen>\r
 520 <userinput>apt-get install stow</userinput>\r
 521 </screen>\r
 522                         </step>\r
 523                         <step>\r
 524                                 <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
 525                                 As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
 526                                 \r
 527 <screen>\r
 528 <userinput>\r
 529 wget http://wwwmaster.postgresql.org/redir/198/h/source/v8.2.17/postgresql-8.2.17.tar.bz2\r
 530 tar xzf postgresql-8.2.17.tar.gz\r
 531 cd postgresql-8.2.17\r
 532 ./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
 533 make\r
 534 make install\r
 535 cd contrib\r
 536 make\r
 537 make install\r
 538 cd xml2\r
 539 make\r
 540 make install\r
 541 cd /usr/local/stow\r
 542 stow pgsql\r
 543 </userinput>\r
 544 </screen>\r
 545                                 \r
 546                         </step>\r
 547                         <step>\r
 548                                 <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. \r
 549                                 As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
 550                                 <screen><userinput>adduser postgres</userinput></screen>\r
 551                         </step>\r
 552                         <step>\r
 553                                 <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
 554                                 \r
 555 <screen>\r
 556 <userinput>\r
 557 mkdir -p /usr/local/pgsql/data\r
 558 chown postgres /usr/local/pgsql/data\r
 559 su - postgres\r
 560 initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
 561 pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
 562 </userinput>\r
 563 </screen>\r
 564                                 <note>\r
 565                                         <para>If an error occurs during the final step above, review the path of the home directory for the \r
 566                                         <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
 567                                 </note>\r
 568                         </step>\r
 569                 </procedure>\r
 570         </section>\r
 571         <section xml:id="configuringPostgreSQL">\r
 572                 <title>Configuring PostgreSQL</title>\r
 573                 <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
 574                 <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values \r
 575                 and some suggested updates for several useful parameters:</para>\r
 576                 <table>\r
 577                         <title>Suggested configuration values</title>\r
 578                         <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
 579                                 <colspec colnum="1" colwidth="1.0*"/>\r
 580                                 <colspec colnum="2" colwidth="1.0*"/>\r
 581                                 <colspec colnum="3" colwidth="1.0*"/>\r
 582                                 <thead>\r
 583                                         <row>\r
 584                                                 <entry>Parameter</entry>\r
 585                                                 <entry>Default</entry>\r
 586                                                 <entry>Suggested</entry>\r
 587                                         </row>\r
 588                                 </thead>\r
 589                                 <tbody>\r
 590                                         <row>\r
 591                                                 <entry>default_statistics_target</entry>\r
 592                                                 <entry>10</entry>\r
 593                                                 <entry>100</entry>\r
 594                                         </row>\r
 595                                         <row>\r
 596                                                 <entry>work_mem</entry>\r
 597                                                 <entry>4Mb</entry>\r
 598                                                 <entry>128Mb</entry>\r
 599                                         </row>\r
 600                                         <row>\r
 601                                                 <entry>shared_buffers</entry>\r
 602                                                 <entry>8Mb</entry>\r
 603                                                 <entry>512Mb</entry>\r
 604                                         </row>\r
 605                                         <row>\r
 606                                                 <entry>effective_cache_size</entry>\r
 607                                                 <entry>128Mb</entry>\r
 608                                                 <entry>4Gb</entry>\r
 609                                         </row>\r
 610                                 </tbody>\r
 611                         </tgroup>\r
 612                 </table>\r
 613         </section>\r
 614 </chapter>\r