Move PostgreSQL ifnormation from ServersideInstallation to Admin misc.
[working/Evergreen.git] / 1.6 / admin / AdminMisc.xml
1 <?xml version='1.0' encoding='UTF-8'?>\r
2 <chapter xmlns="" xmlns:xi=""\r
3             xmlns:xl="" version="5.0" xml:id="adminmisc">\r
4         <info>\r
5                 \r
6         <title>Server Operations and Maintenance</title>\r
7                 <abstract>\r
8                         <para>This chapter deals with basic server operations such as starting and stopping <application>Evergreen</application> as well wall \r
9                         security, backing up and troubleshooting <application>Evergreen</application>.</para>\r
10                 </abstract>\r
11         </info>    \r
12         <section xml:id="startingopensrf">\r
13                 <title>Starting, Stopping and Restarting</title>\r
14                 <para>Occasionally, you may need to restart <application>Evergreen</application>. It is imperative that you understand the basic \r
15                 commands to stop and start the <application>Evergreen</application> server. You can start and stop <application>Evergreen</application> from the command line of \r
16                 the server using the <command></command> script located in the \r
17                 <filename class="directory">openils/bin</filename> directory.</para>   \r
18                 <note><para><command>The</command> command must be run as the <systemitem class="username">opensrf</systemitem> user.</para></note>\r
19                 <para>To view help on <command></command> and get all of its options, run:</para>\r
20                 <screen><userinput> -h</userinput></screen>\r
21                 <para>To start Evergreen, run:</para>\r
22                 <screen><userinput> -l -a start_all</userinput></screen>\r
23                 <para>The <option>-l</option> flag is used to indicate that Evergreen is configured to use <systemitem class="domainname">localhost</systemitem> as \r
24                 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
25                 option is required and indicates the <emphasis>action</emphasis> of the command. In this case \r
26                 <option>start_all</option>.    \r
27                 </para> \r
28                 <note>\r
29                         <para>If you receive the error message: <errortext> command not found</errortext>, then your environment variable \r
30                         <varname>PATH</varname><indexterm><primary>environment variable</primary><secondary>PATH</secondary></indexterm> does not include the \r
31                         <filename class="directory">/openils/bin</filename> directory. You can set it using the following command:</para>\r
32                         <screen><userinput>export <varname>PATH</varname>=$PATH:<filename class="directory">/openils/bin</filename></userinput></screen>\r
33                         <para>If you receive the error message <errortext>Can't locate OpenSRF/ in @INC … BEGIN \r
34                         failed–compilation aborted</errortext>, then your environment variable <varname>PERL5LIB</varname><indexterm><primary>environment \r
35                         variable</primary><secondary>PERL5LIB</secondary></indexterm> does not \r
36                         include the <filename class="directory">/openils/lib/perl5</filename> directory.  You can set it \r
37                         using the following command:</para>\r
38                         <screen><userinput>export <varname>PERL5LIB</varname>=$PERL5LIB:<filename class="directory">/openils/lib/perl5</filename></userinput></screen>\r
39                 </note>         \r
40                 <para>It is also possible to start a specific service. For example:</para>\r
41                 <screen><userinput> -l -a start_router</userinput></screen>\r
42                 <para>will only start the <systemitem class="service">router</systemitem> service.</para>\r
43                 <caution>\r
44                         <para>If you decide to start each service individually, you need to start them in a specific order \r
45                         for Evergreen to start correctly. Run the commands in this exact order:</para>\r
46                         <screen><userinput> -l -a start_router</userinput></screen>\r
47                         <screen><userinput> -l -a start_perl</userinput></screen>\r
48                         <screen><userinput> -l -a start_c</userinput></screen>\r
49                 </caution>      \r
50                 <para>After starting or restarting Evergreen, it is also necessary to restart the <systemitem class="service">Apache web server</systemitem>\r
51                 <indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm> for the OPAC to work correctly.</para>  \r
52                 <para>To stop <application>Evergreen</application>, run:</para>\r
53                 <screen><userinput> -l -a stop_all</userinput></screen>\r
54                 <para>As with starting, you can choose to stop services individually.</para>\r
55                 <para>To restart <application>Evergreen</application>, run:</para>\r
56                 <screen><userinput> -l -a restart_all</userinput></screen>\r
57         </section>\r
58         <section xml:id="backingup">\r
59                 <title>Backing Up</title>\r
60                 <para>Backing up your system files and data is a critical task for server and database administrators. \r
61                 Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and\r
62                 a complete catastrophe.</para>   \r
63                 <simplesect>\r
64                         <title>Backing up the <application>Evergreen</application> Database</title><indexterm><primary>databases</primary></indexterm>\r
65                         <para>Most of the critical data for an <application>Evergreen</application> system – patrons, bibliographic records, holdings, \r
66                         transactions, bills – is stored in the <application>PostgreSQL</application><indexterm><primary>databases</primary>\r
67                         <secondary>PostgreSQL</secondary></indexterm>  database. You can therefore use normal \r
68                         <application>PostgreSQL</application> backup procedures to backup this data. For example, the simplest method of backing up the Evergreen\r
69                         database is to use the <command>pg_dump</command> command to create a live backup of the database without having to \r
70                         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
71                         <screen><userinput>pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen</userinput></screen>\r
72                         <para>To restore the backed up database into a new database, create a new database using the \r
73                         template0 database template and the UTF8 encoding, and run the <command>psql</command> command, specifying the new \r
74                         database as your target:</para>\r
75                         <screen><userinput>createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen</userinput></screen>\r
76                         <screen><userinput>psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen</userinput></screen>\r
77                         <note>\r
78                                 <para>This method of backup is only suitable for small Evergreen instances. Larger sites \r
79                                 should consider implementing continuous archiving (also known as <quote>log shipping</quote>) to provide \r
80                                 more granular backups with lower system overhead. More information on backing up <application>PostgreSQL</application> \r
81                                 databases can be found in the official <link xl:href=""><application>PostgreSQL</application> documentation</link>.</para>\r
82                         </note>\r
83                 </simplesect>\r
84                 <simplesect>\r
85                         <title>Backing up Evergreen Files</title>\r
86                         <para>When you deploy Evergreen, you will probably customize many aspects of your system including \r
87                         the system configuration files, <application>Apache</application> configuration files, OPAC and Staff Client. In order to \r
88                         protect your investment of time, you should carefully consider the best approach to backing up \r
89                         files.</para>\r
90                         <para>There are a number of ways of tackling this problem. You could create a script that regularly \r
91                         creates a time-stamped tarball of all of these files and copies it to a remote server - but that \r
92                         would build up over time to hundreds of files. You could use <link xl:href=""><application>rsync</application></link>\r
93                         <indexterm><primary>rsync</primary></indexterm> to ensure that the files of \r
94                         interest are regularly updated on a remote server - but then you would lose track of the changes to \r
95                         the files, should you make a change that introduces a problem down the road.</para>\r
96                         <para>Perhaps one of the best options is to use a version control system like <link xl:href="">\r
97                         <application>Bazaar</application></link><indexterm><primary>Version Control System</primary><secondary>Subversion</secondary></indexterm>, \r
98                         <link xl:href=""><application>git</application></link><indexterm><primary>Version Control System</primary><secondary>git</secondary></indexterm> \r
99                         or <link xl:href=""><application>Subversion</application></link><indexterm><primary>Version Control System</primary>\r
100                         <secondary>Subversion</secondary></indexterm> to regularly push updates of the files you care about to a repository on a \r
101                         remote server. This gives you the advantage of quickly being able to run through the history of the \r
102                         changes you made, with a commenting system that reminds you why each change was made, combined with \r
103                         remote storage of the pertinent files in case of disaster on site. In addition, your team can create \r
104                         local copies of the repository and test their own changes in isolation from the production \r
105                         system. Using a version control system also helps to recover system customizations after an \r
106                         upgrade.</para>\r
107                 </simplesect>\r
108                 <simplesect>\r
109                         <title>Full System Backup</title>\r
110                         <para>A full system backup archives every file on the file system. Some basic methods require you \r
111                         to shut down most system processes; other methods can use mirrored RAID<indexterm><primary>RAID</primary></indexterm> setups or \r
112                         SAN<indexterm><primary>SAN</primary></indexterm> storage to \r
113                         take <quote>snapshot</quote> backups of your full system while the system continues to run. The subject of how \r
114                         to implement full system backups is beyond the scope of this documentation.</para>\r
115                 </simplesect>\r
116         </section>\r
117         <section xml:id="security">\r
118                 <title>Security</title>\r
119                 <para>As with an ILS and resource accessible from the world wide web careful consideration needs to be \r
120                 given to the security of your <application>Evergreen</application> servers and database. While it is impossible to cover all aspects \r
121                 of security, it is important to take several precautions when setting up production <application>Evergreen</application> site.</para>\r
122                 <orderedlist>\r
123                         <listitem>\r
124                                 <para>Change the Evergreen <systemitem class="username">admin</systemitem> password and keep it secure. The \r
125                                 default admin password is known by anyone who has installed <application>Evergreen</application>. It is not a secret \r
126                                 and needs to be changed by the Administrator. It should also only be shared by those who \r
127                                 need the highest level of access to your system.</para>\r
128                         </listitem>\r
129                         <listitem>\r
130                                 <para>Create strong passwords using a combination of numerical and alphabetical characters \r
131                                 for all of the Administrative passwords including the <systemitem class="username">postgres</systemitem> and \r
132                                 <systemitem class="username">opensrf</systemitem> users</para>     \r
133                         </listitem>\r
134                         <listitem>\r
135                                 <para>Open ports in the firewall<indexterm><primary>firewall</primary></indexterm>  with caution - It is necessary to open some ports to the \r
136                                 server such as port 80 for <systemitem class="protocal">http</systemitem> <indexterm><primary>HTTP</primary></indexterm> and  443 \r
137                                 for <systemitem class="protocal">ssl</systemitem><indexterm><primary>SSL</primary></indexterm> , and it can be helpful to open ports for \r
138                                 remote access to the database or staff client. It is also critical for administrators to \r
139                                 understand the concepts of network security and take precautions to minimize vulnerabilities. \r
140                                 </para>\r
141                         </listitem>\r
142                         <listitem>\r
143                                 <para>Use permissions <indexterm><primary>permissions</primary></indexterm> and permission groups wisely - it is important to understand the \r
144                                 purpose of the permissions and to only give users the level of access that they require.\r
145                                 </para> \r
146                         </listitem>\r
147                                         </orderedlist>  \r
148         </section>\r
149         <section xml:id="logfiles">\r
150                 <title>Managing Log Files</title>\r
151                 <para><application>Evergreen</application> comes with a sophisticated logging system, but it is important to manage the <application>OpenSRF</application> \r
152                 and <application>Evergreen</application> logs. This section will provide a couple of log management techniques and tools.</para>        \r
153                 <simplesect>\r
154                         <title>Using the Log Rotate<indexterm><primary>logrotate</primary></indexterm> Utility to Manage Log Size</title> \r
155                          <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
156                         On <systemitem class="osname">Debian</systemitem> and <systemitem class="osname">Ubuntu</systemitem>, for example, \r
157                         the <systemitem class="service">logrotate</systemitem> utility controls when old log files are compressed and a new log file is started. \r
158                         <systemitem class="service">logrotate</systemitem> runs once a day and checks all log files that it knows about to see if a \r
159                         threshold of time or size has been reached and rotates the log files if a threshold condition has been met.</para>\r
160                         <para>To teach <systemitem class="service">logrotate</systemitem> to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, \r
161                         create a new file <filename>/etc/logrotate.d/evergreen</filename> with the following contents: </para>\r
162 <programlisting>\r
163 compress\r
164 /openils/var/log/*.log {\r
165 # keep the last 4 archived log files along with the current log file\r
166  # log log.1.gz log.2.gz log.3.gz log.4.gz\r
167  # and delete the oldest log file (what would have been log.5.gz)\r
168 rotate 5\r
169 # if the log file is > 50MB in size, rotate it immediately\r
170 size 50M\r
171  # for those logs that don't grow fast, rotate them weekly anyway\r
172   weekly\r
173 }\r
174 </programlisting>\r
175                 </simplesect>\r
176                 <simplesect>\r
177                         <title>Changing Logging Level for <application>Evergreen</application></title>\r
178                         <para>Change the Log Levels in your config files. Changing the level of logging will help \r
179                         narrow down errors.</para> \r
180                         <tip>\r
181                                 <para>A high logging level is not wise to do in a production environment since  it \r
182                                 will produce vastly larger log files and thus reduce server performance.</para>\r
183                         </tip>\r
184                         <para>Change logging levels by editing the configuration file \r
185                         <filename>/openils/conf/opensrf_core.xml</filename><indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm></para>\r
186                         <para>you will want to search for lines containing &lt;loglevel&gt;.</para>\r
187                         <para> the default setting for loglevel is 3 which will log <emphasis>errors</emphasis>, \r
188                         <emphasis>warnings</emphasis> and <emphasis>information</emphasis>.</para>\r
189                         <para>The next level is 4 which is for debugging and provides additional information \r
190                         helpful for the debugging process.</para>\r
191                         <para>Thus, lines with:</para>\r
192                         <programlisting>&lt;loglevel&gt;3&lt;/loglevel&gt;</programlisting>\r
193                         <para>Should be changed to:</para>\r
194                         <programlisting>&lt;loglevel&gt;4&lt;/loglevel&gt;</programlisting>\r
195                         <para>to allow debugging level logging</para>\r
196                         <para>Other logging levels include <emphasis>0</emphasis> for no logging, \r
197                         <emphasis>1</emphasis> for logging errors and <emphasis>2</emphasis> for logging warnings \r
198                         and errors.</para>\r
199                 </simplesect>\r
200         </section>\r
201         <section xml:id="InstallingPostgreSQL">\r
202                 <title>Installing PostgreSQL from Source</title>\r
203                 <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
204                 version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
205                 to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
206 \r
207                 <note>\r
208                         <para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
209                 version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
210                 to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
211                 </note>\r
212                 \r
213                 <procedure>\r
214                         <step>\r
215                                 <para>Install the application <application>stow</application> on your system if it is not already installed. Issue the following command as \r
216                                 the <systemitem class="username">root</systemitem> user:</para>\r
217                                 \r
218                                         <title>Installing <application>stow</application></title>\r
219                                         <screen>\r
220                                         $ apt-get install stow\r
221                                         ...\r
222                                         </screen>\r
223                         </step>\r
224                         <step>\r
225                                 <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
226                                 As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
227                                 <figure>\r
228                                         <title>Installing PostgreSQL</title>\r
229                                         <screen>\r
230                                         $ wget\r
231                                         $ tar xzf postgresql-8.2.17.tar.gz\r
232                                         $ cd postgresql-8.2.17\r
233                                         $ ./configure --with-perl --enable-integer-datetimes --with-openssl --prefix=/usr/local/stow/pgsql\r
234                                         ...\r
235                                         $ make\r
236                                         ...\r
237                                         $ make install\r
238                                         ...\r
239                                         $ cd contrib\r
240                                         $ make\r
241                                         ...\r
242                                         $ make install\r
243                                         $ cd xml2\r
244                                         $ make\r
245                                         ...\r
246                                         $ make install\r
247                                         $ cd /usr/local/stow\r
248                                         $ stow pgsql\r
249                                         </screen>\r
250                                 </figure>\r
251                         </step>\r
252                         <step>\r
253                                 <para>Create the new user <systemitem class="username">postgres</systemitem> to run the PostgreSQL processes. \r
254                                 As the <systemitem class="username">root</systemitem> user, execute this command:</para>\r
255                                 <figure>\r
256                                         <title>Adding <systemitem class="username">postgres</systemitem></title>\r
257                                         <screen>\r
258                                         $ adduser postgres\r
259                                         </screen>\r
260                                 </figure>\r
261                         </step>\r
262                         <step>\r
263                                 <para>Initialize the database directory and start up PostgreSQL. As the <systemitem class="username">root</systemitem> user, follow these steps:</para>\r
264                                 <figure>\r
265                                         <title>Adding <systemitem class="username">postgres</systemitem></title>\r
266                                         <screen>\r
267                                         $ mkdir -p /usr/local/pgsql/data\r
268                                         $ chown postgres /usr/local/pgsql/data\r
269                                         $ su - postgres\r
270                                         $ initdb -D /usr/local/pgsql/data -E UNICODE --locale=C\r
271                                         $ pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start\r
272                                         </screen>\r
273                                 </figure>\r
274                                 <note>\r
275                                         <para>If an error occurs during the final step above, review the path of the home directory for the \r
276                                         <systemitem class="username">postgres</systemitem> user. It may be <literal>/var/lib/postresql</literal> instead of <literal>/home/postres</literal>.</para>\r
277                                 </note>\r
278                         </step>\r
279                 </procedure>\r
280         </section>\r
281         <section xml:id="configuringPostgreSQL">\r
282                 <title>Configuring PostgreSQL</title>\r
283                 <para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values \r
284                 and some suggested updates for several useful parameters:</para>\r
285                 <table>\r
286                         <title>Suggested configuration values</title>\r
287                         <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
288                                 <colspec colnum="1" colwidth="1.0*"/>\r
289                                 <colspec colnum="2" colwidth="1.0*"/>\r
290                                 <colspec colnum="3" colwidth="1.0*"/>\r
291                                 <thead>\r
292                                         <row>\r
293                                                 <entry>Parameter</entry>\r
294                                                 <entry>Default</entry>\r
295                                                 <entry>Suggested</entry>\r
296                                         </row>\r
297                                 </thead>\r
298                                 <tbody>\r
299                                         <row>\r
300                                                 <entry>default_statistics_target</entry>\r
301                                                 <entry>10</entry>\r
302                                                 <entry>100</entry>\r
303                                         </row>\r
304                                         <row>\r
305                                                 <entry>work_mem</entry>\r
306                                                 <entry>4Mb</entry>\r
307                                                 <entry>128Mb</entry>\r
308                                         </row>\r
309                                         <row>\r
310                                                 <entry>shared_buffers</entry>\r
311                                                 <entry>8Mb</entry>\r
312                                                 <entry>512Mb</entry>\r
313                                         </row>\r
314                                         <row>\r
315                                                 <entry>effective_cache_size</entry>\r
316                                                 <entry>128Mb</entry>\r
317                                                 <entry>4Gb</entry>\r
318                                         </row>\r
319                                 </tbody>\r
320                         </tgroup>\r
321                 </table>\r
322         </section>\r
323 </chapter>\r