1.6/admin/AdminMisc.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
   3             xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="adminmisc">
   4         <info>
   5
   6         <title>Server Operations and Maintenance</title>
   7                 <abstract>
   8                         <para>This chapter deals with basic server operations such as starting and stopping Evergreen as well wall security, backing up and troubleshooting Evergreen.</para>
   9                 </abstract>
  10         </info>
  11         <section xml:id="startingopensrf">
  12                 <title>Starting, Stopping and Restarting</title>
  13                 <para>Occasionally, you may need to restart Evergreen. It is imperative that you understand the basic
  14                 commands to stop and start the Evergreen server. You can start and stop Evergreen from the command line of
  15                 the server using the <filename >osrf_ctl.sh</filename> script located in the
  16                 <filename class="directory">openils/bin</filename> directory.</para>
  17                 <note><para>The osrf_ctl.sh script must be run as the <emphasis>opensrf</emphasis> user.</para></note>
  18                 <para>To view help on <filename>osrf_ctl.sh</filename> and get all of its options,
  19                 run:</para>
  20                 <screen>osrf_ctl.sh -h</screen>
  21                 <para>To start Evergreen, run:</para>
  22                 <screen>osrf_ctl.sh -l -a start_all</screen>
  23                 <para>The -l flag is used to indicate that Evergreen is configured to use <emphasis>localhost</emphasis> as
  24                 the host. If you have configured opensrf.xml to use your real hostname, do not use the -l flag. The -a
  25                 option is required and indicates the <emphasis>action</emphasis> of the command. In this case
  26                 <emphasis>start_all</emphasis>.
  27                 </para>
  28                 <note>
  29                         <para>If you receive the error message bash: osrf_ctl.sh:
  30                         command not found, then your environment variable PATH does not include the
  31                         <filename class="directory">/openils/bin</filename> directory.
  32                         You can set it using the following command:</para>
  33                         <screen>export PATH=$PATH:/openils/bin</screen>
  34                         <para>If you receive the error message Can't locate OpenSRF/System.pm in @INC … BEGIN
  35                         failed–compilation aborted, then your environment variable <emphasis>PERL5LIB</emphasis> does not
  36                         include the <filename class="directory">/openils/lib/perl5</filename> directory.  You can set it
  37                         using the following command:</para>
  38                         <screen>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</screen>
  39                 </note>
  40                 <para>It is also possible to start a specific service. For example:</para>
  41                 <screen>osrf_ctl.sh -l -a start_router</screen>
  42                 <para>will only start the router service.</para>
  43                 <caution>
  44                         <para>If you decide to start each service individually, you need to start them in a specific order
  45                         for Evergreen to start correctly. Run the commands in this exact order:</para>
  46                         <screen>osrf_ctl.sh -l -a start_router</screen>
  47                         <screen>osrf_ctl.sh -l -a start_perl</screen>
  48                         <screen>osrf_ctl.sh -l -a start_c</screen>
  49                 </caution>
  50                 <para>After starting or restarting Evergreen, it is also necessary to restart the Apache web server for the
  51                 OPAC to work correctly.</para>
  52                 <para>To stop Evergreen, run:</para>
  53                 <screen>osrf_ctl.sh -l -a stop_all</screen>
  54                 <para>As with starting, you can choose to stop one service</para>
  55                 <para>To restart Evergreen, run:</para>
  56                 <screen>osrf_ctl.sh -l -a restart_all</screen>
  57         </section>
  58         <section xml:id="backingup">
  59                 <title>Backing Up</title>
  60                 <para>Backing up your system files and data is a critical task for server and database adminstrators.
  61                 Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and
  62                 a a complete catastrophy.</para>
  63                 <simplesect>
  64                         <title>Backing up the Evergreen Database</title>
  65                         <para>Most of the critical data for an Evergreen system – patrons, bibliographic records, holdings,
  66                         transactions, bills – is stored in the PostgreSQL database. You can therefore use normal PostgreSQL
  67                         backup procedures to backup this data. For example, the simplest method of backing up the Evergreen
  68                         database is to use the pg_dump command to create a live backup of the database without having to
  69                         interrupt any Evergreen services as follows:</para>
  70                         <screen># pg_dump -U [username] -h [hostname] -f [output-file] [database-name]</screen>
  71                         <screen>pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen</screen>
  72                         <para>To restore the backed up database into a new database, create a new database using the
  73                         template0 database template and the UTF8 encoding, and run the psql command, specifying the new
  74                         database as your target:</para>
  75                         <screen>createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen</screen>
  76                         <screen>psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen</screen>
  77                         <note>
  78                                 <para>This method of backup is only suitable for small Evergreen instances. Larger sites
  79                                 should consider implementing continuous archiving (also known as “log shipping”) to provide
  80                                 more granular backups with lower system overhead. More information on backing up PostgreSQL
  81                                 databases can be found in the official PostgreSQL documentation.</para>
  82                         </note>
  83                 </simplesect>
  84                 <simplesect>
  85                         <title>Backing up Evergreen Files</title>
  86                         <para>When you deploy Evergreen, you will probably customize many aspects of your system includung
  87                         the system configuration files, Apache configuration files, OPAC and Staff Client. In order to
  88                         protect your investment of time, you should carefully consider the best approach to backing up
  89                         files.</para>
  90                         <para>There are a number of ways of tackling this problem. You could create a script that regularly
  91                         creates a time-stamped tarball of all of these files and copies it to a remote server - but that
  92                         would build up over time to hundreds of files. You could use rsync to ensure that the files of
  93                         interest are regularly updated on a remote server - but then you would lose track of the changes to
  94                         the files, should you make a change that introduces a problem down the road.</para>
  95                         <para>Perhaps one of the best options is to use a version control system like Bazaar, git,
  96                         Subversion, or CVS to regularly push updates of the files you care about to a repository on a
  97                         remote server. This gives you the advantage of quickly being able to run through the history of the
  98                         changes you made, with a commenting system that reminds you why each change was made, combined with
  99                         remote storage of the pertinent files in case of disaster on site. In addition, your team can create
 100                         local copies of the repository and test their own changes in isolation from the production
 101                         system. Using a version control system also helps to recover system customizations after an
 102                         upgrade.</para>
 103                 </simplesect>
 104                 <simplesect>
 105                         <title>Full System Backup</title>
 106                         <para>A full system backup archives every file on the file system. Some basic methods require you
 107                         to shut down most system processes; other methods can use mirrored RAID setups or SAN storage to
 108                         take “snapshot” backups of your full system while the system continues to run. The subject of how
 109                         to implement full system backups is beyond the scope of this documentation.</para>
 110                 </simplesect>
 111         </section>
 112         <section xml:id="security">
 113                 <title>Security</title>
 114                 <para>As with an ILS and resource accessible from the world wilde web careful consideration needs to be
 115                 given to the security of your Evergreen servers and database. While it is impossible to cover all aspects
 116                 of security, it is important to take several percautions when setting up production Evergreen site.</para>
 117                 <orderedlist>
 118                         <listitem>
 119                                 <para>Change the Evergreen <emphasis>Admin</emphasis> password and keep it secure. The
 120                                 default Admin password is known by anyone who has installed Evergreen. It is not a secret
 121                                 and needs to be changed by the Administrator. It should also only be shared by those who
 122                                 need the highest level access to Evergreen.</para>
 123                         </listitem>
 124                         <listitem>
 125                                 <para>Create strong passwords using a combination of numerican and alphatbetical characters
 126                                 for all of the Administrative passwords used by Evergreen including the Evergreen
 127                                 postgresql user, opensrf linux account, and Admin evergreen users, and of course, any
 128                                 superusers on your server.</para>
 129                         </listitem>
 130                         <listitem>
 131                                 <para>Open ports in the firewall with Caution - It is necessary to open some ports to the
 132                                 server such as port 80 for http and  443 for ssl, and it can be helpful to open ports for
 133                                 remote access to the database or staff client. It is also critical for an administrator to
 134                                 understand the concepts of network security and take precautions to not allow the server to
 135                                 be vulnerable to the outside world.
 136                                 </para>
 137                         </listitem>
 138                         <listitem>
 139                                 <para>Use permissions and permission groups wisely - it is important to understand the
 140                                 purpose of the permissions and to only give users the level of access that they require.
 141                                 </para>
 142                         </listitem>
 143                                         </orderedlist>
 144         </section>
 145         <section xml:id="logfiles">
 146                 <title>Managing Log Files</title>
 147                 <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
 148                 and tools.</para>
 149                 <simplesect>
 150                         <title>Using the Log Rotate Utility to Manage Log Size</title>
 151                          <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,
 152                         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
 153                         threshold of time or size has been reached and rotates the log files if a threshold condition has been met.</para>
 154                         <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
 155                         following contents: </para>
 156                         <screen>compress</screen>
 157                         <screen>/openils/var/log/*.log {</screen>
 158                         <screen> # keep the last 4 archived log files along with the current log file</screen>
 159                         <screen> # log log.1.gz log.2.gz log.3.gz log.4.gz</screen>
 160                         <screen> # and delete the oldest log file (what would have been log.5.gz)</screen>
 161                         <screen>rotate 5</screen>
 162                         <screen># if the log file is > 50MB in size, rotate it immediately</screen>
 163                         <screen> size 50M</screen>
 164                         <screen> # for those logs that don't grow fast, rotate them weekly anyway</screen>
 165                         <screen>  weekly</screen>
 166                         <screen>}</screen>
 167                 </simplesect>
 168                 <simplesect>
 169                         <title>Chaning Logging Level for Evergreen</title>
 170                         <para>Change the Log Levels in your config files. Changing the level of logging will help
 171                         narrow down errors.</para>
 172                         <tip>
 173                                 <para>A high logging level is not wise to do in a production environment since  it
 174                                 will produce vastly larger log files and thus reduce server performance.</para>
 175                         </tip>
 176                         <para>Change logging levels by editing the configuration file
 177                         <filename>/openils/conf/opensrf_core.xml</filename></para>
 178                         <para>you will want to search for lines containing &lt;loglevel&gt;.</para>
 179                         <para> the default setting for loglevel is 3 which will log <emphasis>errors</emphasis>,
 180                         <emphasis>warnings</emphasis> and <emphasis>information</emphasis>.</para>
 181                         <para>The next level is 4 which is for debugging and provides additional information
 182                         helpful for the debugging process.</para>
 183                         <para>Thus, lines with:</para>
 184                         <screen>&lt;loglevel&gt;3&lt;/loglevel&gt;</screen>
 185                         <para>Should be changed to:</para>
 186                         <screen>&lt;loglevel&gt;4&lt;/loglevel&gt;</screen>
 187                         <para>to allow debugging level logging</para>
 188                         <para>Other logging levels inclide <emphasis>0</emphasis> for no logging,
 189                         <emphasis>1</emphasis> for logging errors and <emphasis>2</emphasis> for logging warnings
 190                         and errors.</para>
 191                 </simplesect>
 192         </section>
 193 </chapter>