Move PostgreSQL ifnormation from ServersideInstallation to Admin misc.
[working/Evergreen.git] / 1.6 / admin / AdminMisc.xml
index ce2b571..6430e72 100644 (file)
-<?xml version='1.0' encoding='UTF-8'?>
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
-           xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="adminmisc">
-       <info>
-               
-       <title>Server Operations and Maintenance</title>
-               <abstract>
-                       <para>This chapter deals with basic server operations such as starting and stopping Evergreen as well wall security, backing up and troubleshooting Evergreen.</para>
-               </abstract>
-       </info>    
-       <section xml:id="startingopensrf">
-               <title>Starting, Stopping and Restarting</title>
-               <para>Occasionally, you may need to restart Evergreen. It is imperative that you understand the basic 
-               commands to stop and start the Evergreen server. You can start and stop Evergreen from the command line of 
-               the server using the <filename >osrf_ctl.sh</filename> script located in the 
-               <filename class="directory">openils/bin</filename> directory.</para>   
-               <note><para>The osrf_ctl.sh script must be run as the <emphasis>opensrf</emphasis> user.</para></note>
-               <para>To view help on <filename>osrf_ctl.sh</filename> and get all of its options, 
-               run:</para>
-               <screen>osrf_ctl.sh -h</screen>
-               <para>To start Evergreen, run:</para>
-               <screen>osrf_ctl.sh -l -a start_all</screen>
-               <para>The -l flag is used to indicate that Evergreen is configured to use <emphasis>localhost</emphasis> as 
-               the host. If you have configured opensrf.xml to use your real hostname, do not use the -l flag. The -a 
-               option is required and indicates the <emphasis>action</emphasis> of the command. In this case 
-               <emphasis>start_all</emphasis>.    
-               </para> 
-               <note>
-                       <para>If you receive the error message bash: osrf_ctl.sh: 
-                       command not found, then your environment variable PATH does not include the 
-                       <filename class="directory">/openils/bin</filename> directory. 
-                       You can set it using the following command:</para>
-                       <screen>export PATH=$PATH:/openils/bin</screen>
-                       <para>If you receive the error message Can't locate OpenSRF/System.pm in @INC … BEGIN 
-                       failed–compilation aborted, then your environment variable <emphasis>PERL5LIB</emphasis> does not 
-                       include the <filename class="directory">/openils/lib/perl5</filename> directory.  You can set it 
-                       using the following command:</para>
-                       <screen>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</screen>
-               </note>         
-               <para>It is also possible to start a specific service. For example:</para>
-               <screen>osrf_ctl.sh -l -a start_router</screen>
-               <para>will only start the router service.</para>
-               <caution>
-                       <para>If you decide to start each service individually, you need to start them in a specific order 
-                       for Evergreen to start correctly. Run the commands in this exact order:</para>
-                       <screen>osrf_ctl.sh -l -a start_router</screen>
-                       <screen>osrf_ctl.sh -l -a start_perl</screen>
-                       <screen>osrf_ctl.sh -l -a start_c</screen>
-               </caution>      
-               <para>After starting or restarting Evergreen, it is also necessary to restart the Apache web server for the 
-               OPAC to work correctly.</para>  
-               <para>To stop Evergreen, run:</para>
-               <screen>osrf_ctl.sh -l -a stop_all</screen>
-               <para>As with starting, you can choose to stop one service</para>
-               <para>To restart Evergreen, run:</para>
-               <screen>osrf_ctl.sh -l -a restart_all</screen>
-       </section>
-       <section xml:id="backingup">
-               <title>Backing Up</title>
-               <para>Backing up your system files and data is a critical task for server and database adminstrators. 
-               Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and
-               a a complete catastrophy.</para>   
-               <simplesect>
-                       <title>Backing up the Evergreen Database</title>
-                       <para>Most of the critical data for an Evergreen system – patrons, bibliographic records, holdings, 
-                       transactions, bills – is stored in the PostgreSQL database. You can therefore use normal PostgreSQL 
-                       backup procedures to backup this data. For example, the simplest method of backing up the Evergreen
-                       database is to use the pg_dump command to create a live backup of the database without having to 
-                       interrupt any Evergreen services as follows:</para>
-                       <screen># pg_dump -U [username] -h [hostname] -f [output-file] [database-name]</screen> 
-                       <screen>pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen</screen>
-                       <para>To restore the backed up database into a new database, create a new database using the 
-                       template0 database template and the UTF8 encoding, and run the psql command, specifying the new 
-                       database as your target:</para>
-                       <screen>createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen</screen>
-                       <screen>psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen</screen>
-                       <note>
-                               <para>This method of backup is only suitable for small Evergreen instances. Larger sites 
-                               should consider implementing continuous archiving (also known as “log shipping”) to provide 
-                               more granular backups with lower system overhead. More information on backing up PostgreSQL 
-                               databases can be found in the official PostgreSQL documentation.</para>
-                       </note>
-               </simplesect>
-               <simplesect>
-                       <title>Backing up Evergreen Files</title>
-                       <para>When you deploy Evergreen, you will probably customize many aspects of your system includung 
-                       the system configuration files, Apache configuration files, OPAC and Staff Client. In order to 
-                       protect your investment of time, you should carefully consider the best approach to backing up 
-                       files.</para>
-                       <para>There are a number of ways of tackling this problem. You could create a script that regularly 
-                       creates a time-stamped tarball of all of these files and copies it to a remote server - but that 
-                       would build up over time to hundreds of files. You could use rsync to ensure that the files of 
-                       interest are regularly updated on a remote server - but then you would lose track of the changes to 
-                       the files, should you make a change that introduces a problem down the road.</para>
-                       <para>Perhaps one of the best options is to use a version control system like Bazaar, git, 
-                       Subversion, or CVS to regularly push updates of the files you care about to a repository on a 
-                       remote server. This gives you the advantage of quickly being able to run through the history of the 
-                       changes you made, with a commenting system that reminds you why each change was made, combined with 
-                       remote storage of the pertinent files in case of disaster on site. In addition, your team can create 
-                       local copies of the repository and test their own changes in isolation from the production 
-                       system. Using a version control system also helps to recover system customizations after an 
-                       upgrade.</para>
-               </simplesect>
-               <simplesect>
-                       <title>Full System Backup</title>
-                       <para>A full system backup archives every file on the file system. Some basic methods require you 
-                       to shut down most system processes; other methods can use mirrored RAID setups or SAN storage to 
-                       take “snapshot” backups of your full system while the system continues to run. The subject of how 
-                       to implement full system backups is beyond the scope of this documentation.</para>
-               </simplesect>
-       </section>
-       <section xml:id="security">
-               <title>Security</title>
-               <para>As with an ILS and resource accessible from the world wilde web careful consideration needs to be 
-               given to the security of your Evergreen servers and database. While it is impossible to cover all aspects 
-               of security, it is important to take several percautions when setting up production Evergreen site.</para>
-               <orderedlist>
-                       <listitem>
-                               <para>Change the Evergreen <emphasis>Admin</emphasis> password and keep it secure. The 
-                               default Admin password is known by anyone who has installed Evergreen. It is not a secret 
-                               and needs to be changed by the Administrator. It should also only be shared by those who 
-                               need the highest level access to Evergreen.</para>
-                       </listitem>
-                       <listitem>
-                               <para>Create strong passwords using a combination of numerican and alphatbetical characters 
-                               for all of the Administrative passwords used by Evergreen including the Evergreen 
-                               postgresql user, opensrf linux account, and Admin evergreen users, and of course, any
-                               superusers on your server.</para>     
-                       </listitem>
-                       <listitem>
-                               <para>Open ports in the firewall with Caution - It is necessary to open some ports to the 
-                               server such as port 80 for http and  443 for ssl, and it can be helpful to open ports for 
-                               remote access to the database or staff client. It is also critical for an administrator to 
-                               understand the concepts of network security and take precautions to not allow the server to 
-                               be vulnerable to the outside world. 
-                               </para>
-                       </listitem>
-                       <listitem>
-                               <para>Use permissions and permission groups wisely - it is important to understand the 
-                               purpose of the permissions and to only give users the level of access that they require.
-                               </para> 
-                       </listitem>
-                                       </orderedlist>  
-       </section>
-       <section xml:id="logfiles">
-               <title>Managing Log Files</title>
-               <para>Evergreen comes with a sophisticated logging system, but it is important to manage the OpenSRF and Evergreen logs. This section will provide a couple of log management techniques 
-               and tools.</para>       
-               <simplesect>
-                       <title>Using the Log Rotate Utility to Manage Log Size</title> 
-                        <para>Fortunately, this is not a new problem for Unix administrators, and there are a number of ways of keeping your logs under control. On Debian and Ubuntu, for example, 
-                       the logrotate utility controls when old log files are compressed and a new log file is started. logrotate runs once a day and checks all log files that it knows about to see if a 
-                       threshold of time or size has been reached and rotates the log files if a threshold condition has been met.</para>
-                       <para>To teach logrotate to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, create a new file <filename>/etc/logrotate.d/evergreen</filename> with the 
-                       following contents: </para>
-                       <screen>compress</screen>
-                       <screen>/openils/var/log/*.log {</screen>
-                       <screen> # keep the last 4 archived log files along with the current log file</screen>
-                       <screen> # log log.1.gz log.2.gz log.3.gz log.4.gz</screen>
-                       <screen> # and delete the oldest log file (what would have been log.5.gz)</screen>
-                       <screen>rotate 5</screen>
-                       <screen># if the log file is > 50MB in size, rotate it immediately</screen>
-                       <screen> size 50M</screen>
-                       <screen> # for those logs that don't grow fast, rotate them weekly anyway</screen>
-                       <screen>  weekly</screen>
-                       <screen>}</screen>
-               </simplesect>
-               <simplesect>
-                       <title>Chaning Logging Level for Evergreen</title>
-                       <para>Change the Log Levels in your config files. Changing the level of logging will help 
-                       narrow down errors.</para> 
-                       <tip>
-                               <para>A high logging level is not wise to do in a production environment since  it 
-                               will produce vastly larger log files and thus reduce server performance.</para>
-                       </tip>
-                       <para>Change logging levels by editing the configuration file 
-                       <filename>/openils/conf/opensrf_core.xml</filename></para>
-                       <para>you will want to search for lines containing &lt;loglevel&gt;.</para>
-                       <para> the default setting for loglevel is 3 which will log <emphasis>errors</emphasis>, 
-                       <emphasis>warnings</emphasis> and <emphasis>information</emphasis>.</para>
-                       <para>The next level is 4 which is for debugging and provides additional information 
-                       helpful for the debugging process.</para>
-                       <para>Thus, lines with:</para>
-                       <screen>&lt;loglevel&gt;3&lt;/loglevel&gt;</screen>
-                       <para>Should be changed to:</para>
-                       <screen>&lt;loglevel&gt;4&lt;/loglevel&gt;</screen>
-                       <para>to allow debugging level logging</para>
-                       <para>Other logging levels inclide <emphasis>0</emphasis> for no logging, 
-                       <emphasis>1</emphasis> for logging errors and <emphasis>2</emphasis> for logging warnings 
-                       and errors.</para>
-               </simplesect>
-       </section>
-</chapter>
+<?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 and Maintenance</title>\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 \r
+                       for Evergreen to start correctly. Run the commands in this exact order:</para>\r
+                       <screen><userinput>osrf_ctl.sh -l -a start_router</userinput></screen>\r
+                       <screen><userinput>osrf_ctl.sh -l -a start_perl</userinput></screen>\r
+                       <screen><userinput>osrf_ctl.sh -l -a start_c</userinput></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
+       </section>\r
+       <section xml:id="backingup">\r
+               <title>Backing Up</title>\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 <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> documentation</link>.</para>\r
+                       </note>\r
+               </simplesect>\r
+               <simplesect>\r
+                       <title>Backing up Evergreen Files</title>\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
+               <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 necessary to open some ports to the \r
+                               server such as port 80 for <systemitem class="protocal">http</systemitem> <indexterm><primary>HTTP</primary></indexterm> and  443 \r
+                               for <systemitem class="protocal">ssl</systemitem><indexterm><primary>SSL</primary></indexterm> , and it can be helpful to open ports for \r
+                               remote access to the database or staff client. It is also critical for administrators to \r
+                               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
+               <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 Log Rotate<indexterm><primary>logrotate</primary></indexterm> Utility to Manage Log Size</title> \r
+                        <para>Fortunately, this is not a new problem for <systemitem class="osname">Unix</systemitem> administrators, and 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
+                       <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 &lt;loglevel&gt;.</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>&lt;loglevel&gt;3&lt;/loglevel&gt;</programlisting>\r
+                       <para>Should be changed to:</para>\r
+                       <programlisting>&lt;loglevel&gt;4&lt;/loglevel&gt;</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
+               <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
+                               \r
+                                       <title>Installing <application>stow</application></title>\r
+                                       <screen>\r
+                                       $ apt-get install stow\r
+                                       ...\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
+                               <figure>\r
+                                       <title>Installing PostgreSQL</title>\r
+                                       <screen>\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
+                                       ...\r
+                                       $ make\r
+                                       ...\r
+                                       $ make install\r
+                                       ...\r
+                                       $ cd contrib\r
+                                       $ make\r
+                                       ...\r
+                                       $ make install\r
+                                       $ cd xml2\r
+                                       $ make\r
+                                       ...\r
+                                       $ make install\r
+                                       $ cd /usr/local/stow\r
+                                       $ stow pgsql\r
+                                       </screen>\r
+                               </figure>\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
+                               <figure>\r
+                                       <title>Adding <systemitem class="username">postgres</systemitem></title>\r
+                                       <screen>\r
+                                       $ adduser postgres\r
+                                       </screen>\r
+                               </figure>\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
+                               <figure>\r
+                                       <title>Adding <systemitem class="username">postgres</systemitem></title>\r
+                                       <screen>\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
+                                       </screen>\r
+                               </figure>\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
+               <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