+++ /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 and Maintenance</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 \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
- <indexterm><primary>databases</primary><secondary>backing up</secondary></indexterm>\r
- \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
- <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 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
- <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 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