--- /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 / commitdiff