Add files to 2.0.
authorRobert Soulliere <rsoulliere@libdog.mohawkcollege.ca>
Tue, 22 Feb 2011 17:11:46 +0000 (12:11 -0500)
committerRobert Soulliere <rsoulliere@libdog.mohawkcollege.ca>
Tue, 22 Feb 2011 17:11:46 +0000 (12:11 -0500)
43 files changed:
2.0/admin/AdminMisc.xml [new file with mode: 0644]
2.0/admin/actiontriggers.xml [new file with mode: 0644]
2.0/admin/admin-booking.xml [new file with mode: 0644]
2.0/admin/serversideinstallation_2.0.xml [new file with mode: 0644]
2.0/admin/sip.xml [new file with mode: 0644]
2.0/admin/troubleshooting.xml [new file with mode: 0644]
2.0/admin/z3950.xml [new file with mode: 0644]
2.0/appendices/glossary.xml
2.0/media/serversideinstallation-staffclient-running-1.png [new file with mode: 0755]
2.0/media/serversideinstallation-staffclient-running-2.png [new file with mode: 0755]
2.0/media/serversideinstallation-staffclient-running-3.png [new file with mode: 0755]
2.0/media/serversideinstallation-staffclient-running-4.png [new file with mode: 0755]
2.0/media/serversideinstallation-testing-1.png [new file with mode: 0755]
2.0/media/serversideinstallation-testing-2.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vbox-install-1.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vbox-install-2.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vbox-install-3.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vbox-install-4.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vbox-install-5.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-1.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-10.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-11.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-12.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-13.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-14.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-15.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-16.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-17.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-18.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-19.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-2.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-20.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-21.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-3.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-4.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-5.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-6.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-7.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-8.png [new file with mode: 0755]
2.0/media/serversideinstallation-virtual-vm-install-9.png [new file with mode: 0755]
2.0/pdf/temp.fo [new file with mode: 0644]
2.0/root.xml
2.0/stafftasks/booking.xml [new file with mode: 0644]

diff --git a/2.0/admin/AdminMisc.xml b/2.0/admin/AdminMisc.xml
new file mode 100644 (file)
index 0000000..ec6144e
--- /dev/null
@@ -0,0 +1,320 @@
+<?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 &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
+               <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
diff --git a/2.0/admin/actiontriggers.xml b/2.0/admin/actiontriggers.xml
new file mode 100644 (file)
index 0000000..7e7941c
--- /dev/null
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="actiontriggers" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+    <info>\r
+        <title>Action Triggers</title>\r
+       <indexterm><primary>action triggers</primary></indexterm>    \r
+       </info>\r
+       <para>Action Triggers were introduced to Evergreen in 1.6. They allow administrators the ability to set up actions for specific events. They are useful for notification events such as \r
+       hold notifications.</para>\r
+       \r
+                       \r
+       <para>To access the Action Triggers module, select\r
+               <menuchoice>\r
+                       <guimenu>Admin</guimenu>  \r
+                       <guisubmenu>Local Administration</guisubmenu>\r
+                       <guisubmenu>Notifications / Action triggers</guisubmenu>\r
+               </menuchoice>\r
+       </para>\r
+       <note><para>You must have Local Administrator permissions to access the Action Triggers module.</para></note>\r
+       <para>You will notice four tabs on this page: <guilabel><link linkend="eventdefinitions">Event Definitions</link></guilabel>, <guilabel><link linkend="Hooks">Hooks</link></guilabel>, \r
+       <guilabel><link linkend="Reactors">Reactors</link></guilabel> and <guilabel><link linkend="Validators">Validators</link></guilabel>.</para>\r
+               \r
+       <section xml:id="eventdefinitions">\r
+               <title>Event Definitions</title>\r
+               <indexterm><primary>action triggers</primary><secondary>event definitions</secondary></indexterm>   \r
+               <para><guilabel>Event Definitions</guilabel> is the main tab and contains the key fields when working with action triggers. These fields include:</para>\r
+                       <table xml:id="eventdefinitionstable">\r
+                               <title>Action Trigger Event Definitions</title>\r
+                               <tgroup cols="2">\r
+                                       <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
+                                       <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
+                                       <thead>\r
+                                               <row>\r
+                                                       <entry>Field</entry>\r
+                                                       <entry>Description</entry>\r
+                                               </row>\r
+                                       </thead>\r
+                                       <tbody>\r
+                                               <row>\r
+                                                       <entry><guilabel>Owning library</guilabel></entry>\r
+                                                       <entry>The shortname of the library for which the action / trigger / hook is defined.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Name</guilabel></entry>\r
+                                                       <entry>The name of the trigger event, that links to a trigger event environment containing a set of fields  \r
+                                                       that will be returned to the <link linkend="Validators">Validators</link> / <link linkend="Reactors">Reactors</link> for processing.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel><link linkend="Hooks">Hooks</link></guilabel></entry>\r
+                                                       <entry>The name of the trigger for the trigger event. The underlying action_trigger.hook table defines the Fieldmapper \r
+                                                       class in the core_type column off of which the rest of the field definitions <quote>hang</quote>. </entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Enabled</guilabel></entry>\r
+                                                       <entry>Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Processing Delay</guilabel></entry>\r
+                                                       <entry>Defines how long after a given trigger / hook event has occurred before the associated action (<quote>Reactor</quote>) \r
+                                                       will be taken.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Processing Delay Field</guilabel></entry>\r
+                                                       <entry>Defines the field associated with the event on which the processing delay is calculated. For example, the processing delay \r
+                                                       context field on the hold.capture hook (which has a core_type of ahr) is <emphasis>capture_time</emphasis>.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Processing Group Context Field</guilabel></entry>\r
+                                                       <entry>Used to batch actions based on its associated group.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel><link linkend="Validators">Validators</link></guilabel></entry>\r
+                                                       <entry>The subroutines receive the trigger environment as an argument (see the linked <emphasis>Name</emphasis> for \r
+                                                       the environment definition) and returns either <emphasis>1</emphasis> if the validator is <emphasis>true</emphasis> or <emphasis>0</emphasis> \r
+                                                       if the validator returns <emphasis>false</emphasis>.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel><link linkend="Reactors">Reactors</link></guilabel></entry>\r
+                                                       <entry>Links the action trigger to the Reactor.</entry>\r
+                                               </row>\r
+                                               <row>\r
+                                                       <entry><guilabel>Max Event Validity Delay</guilabel></entry>\r
+                                                       <entry>Define the threshold for how far back the action_trigger_runner.pl script should reach to generate \r
+                                                       a batch of events.</entry>\r
+                                               </row>\r
+                                       </tbody>        \r
+                               </tgroup>\r
+                       </table>\r
+               \r
+               <procedure>\r
+               <title>Creating Action Triggers</title>\r
+               <indexterm><primary>action triggers</primary><secondary>creating</secondary></indexterm>  \r
+                       <step>\r
+                               <para>From the top menu, select\r
+                                       <menuchoice>\r
+                                               <guimenu>Admin</guimenu>  \r
+                                               <guisubmenu>Local Administration</guisubmenu>\r
+                                               <guisubmenu>Notifications / Action triggers</guisubmenu>\r
+                                       </menuchoice>\r
+                               </para>\r
+                       </step>\r
+                       <step><para>Click on the <guibutton>New</guibutton> button.</para></step>\r
+                       <step><para>Select an <guilabel>Owning Library</guilabel>.</para></step>\r
+                       <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step>                                \r
+                       <step><para>Select the <guilabel>Hook</guilabel>.</para></step>\r
+                       <step><para>Check the <guilabel>Enabled</guilabel> check box.</para></step>\r
+               \r
+                       <step><para>Create a unique <guilabel>Name</guilabel> for your new action trigger.</para></step>\r
+                       <step><para>Set the <guilabel>Processing Delay</guilabel> in the appropriate format. Eg. <emphasis class="bold">7 days</emphasis> to run 7 days from the trigger event \r
+                       or <emphasis class="bold">00:01:00</emphasis> to run 1 hour after the <guilabel>Processing Delay Context Field</guilabel>.</para></step>\r
+                       <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step>  \r
+                       <step><para>Select the <guilabel>Validator</guilabel>, <guilabel>Reactor</guilabel>, <guilabel>Failure Cleanup</guilabel> and <guilabel>Success Cleanup</guilabel>.\r
+                       </para></step>  \r
+                       <step><para>Set the <guilabel>Processing Delay Context Field</guilabel> and <guilabel>Processing Group Context Field</guilabel>.</para></step>  \r
+                       <step preformance="optional"><para>Enter text in the <guilabel>Template</guilabel> text box if required. These are for email messages. Here is an sample \r
+                       template for sending 90 day overdue notices:</para>\r
+<programlisting><![CDATA[\r
+[%- USE date -%]\r
+[%- user = target.0.usr -%]\r
+To: robert.soulliere@mohawkcollege.ca\r
+From: robert.soulliere@mohawkcollege.ca\r
+Subject: Overdue Notification\r
+\r
+Dear [% user.family_name %], [% user.first_given_name %]\r
+Our records indicate the following items are overdue.\r
+\r
+[%- USE date -%]\r
+[%- user = target.0.usr -%]\r
+To: [%- params.recipient_email || user.email %]\r
+From: [%- params.sender_email || default_sender %]\r
+Subject: Overdue Items Marked Lost\r
+\r
+Dear [% user.family_name %], [% user.first_given_name %]\r
+The following items are 90 days overdue and have been marked LOST.\r
+[%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]\r
+[% FOR circ IN target %]\r
+    Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
+    Barcode: [% circ.target_copy.barcode %] \r
+    Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
+    Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
+    Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
+    Library: [% circ.circ_lib.name %]\r
+[% END %]\r
+\r
+\r
+[% FOR circ IN target %]\r
+    Title: [% circ.target_copy.call_number.record.simple_record.title %] \r
+    Barcode: [% circ.target_copy.barcode %] \r
+    Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]\r
+    Item Cost: [% helpers.get_copy_price(circ.target_copy) %]\r
+    Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]\r
+    Library: [% circ.circ_lib.name %]\r
+[% END %]\r
+]]>\r
+</programlisting>      \r
+                       </step> \r
+                       <step><para>Once you are satisfied with your new event trigger , click the <guibutton>Save</guibutton> button located at the bottom of the \r
+                       form</para></step>\r
+               </procedure>\r
+               <tip><para>A quick and easy way to create new action triggers is to clone an existing action trigger.</para></tip>\r
+               <procedure>\r
+                       <title>Cloning Existing Action Triggers</title>\r
+                       <step>\r
+                               <para>Check the check box next to the action trigger you wish to clone</para>\r
+                       </step>\r
+                       <step>\r
+                               <para>Click the <guibutton>Clone Selected</guibutton> on the top left of the page.</para>\r
+                       </step>\r
+                       <step>\r
+                               <para>An editing window with open. Notice that the fields will be populated with content from the cloned action trigger. Edit as necessary and \r
+                       give the new action trigger a unique <guilabel>Name</guilabel>.</para>\r
+                       </step>\r
+                       <step>\r
+                               <para>Click <guilabel>Save</guilabel>.</para>\r
+                       </step>\r
+               </procedure>\r
+               <procedure>\r
+                       <title>Editing Action Triggers</title>\r
+                       <step>\r
+                               <para>Check the check box next to the action trigger you wish to delete</para>\r
+                       </step>\r
+                       <step>\r
+                               <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
+                       </step>\r
+               </procedure>\r
+               \r
+               <note><para>Before deleting an action trigger, you should consider disabling it through the editing form. This way you can simply enable it if you decide that you would like to use \r
+               the action trigger in the future.</para></note>\r
+               <procedure>\r
+                       <title>Deleting Action Triggers</title>\r
+                       <step>\r
+                               <para>Check the check box next to the action trigger you wish to delete</para>\r
+                       </step>\r
+                       <step>\r
+                               <para>Click the <guibutton>Delete Selected</guibutton> on the top left of the page.</para>\r
+                       </step>\r
+               </procedure>\r
+       </section>\r
+       <section xml:id="Hooks">\r
+               <title>Hooks</title>\r
+               <indexterm><primary>action triggers</primary><secondary>hooks</secondary></indexterm>\r
+               <para><guilabel>Hooks</guilabel> define the Fieldmapper class in the core_type column off of which the rest of the field definitions <quote>hang</quote>.</para>\r
+               <table xml:id="Hookstable">\r
+                       <title>Hooks</title>\r
+                       <tgroup cols="2">\r
+                               <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
+                               <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
+                               <thead>\r
+                                       <row>\r
+                                               <entry>Field</entry>\r
+                                               <entry>Description</entry>\r
+                                       </row>\r
+                               </thead>\r
+                               <tbody>\r
+                                       <row>\r
+                                               <entry><guilabel>Hook Key</guilabel></entry>\r
+                                               <entry>A unique name given to the hook.</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry><guilabel>Core Type</guilabel></entry>\r
+                                               <entry>Used to link the action trigger to the IDL class in fm_IDL.xml</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry><guilabel>Description</guilabel></entry>\r
+                                               <entry>Text to describe the purpose of the hook. </entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry><guilabel>Passive</guilabel></entry>\r
+                                               <entry>Indicates whether or not an event is created by direct user action or is circumstantial.</entry>\r
+                                       </row>\r
+                               </tbody>        \r
+                       </tgroup>\r
+               </table>\r
+               <para>You may also create, edit and delete Hooks but the <guilabel>Core Type</guilabel> must refer to an IDL class in the fm_IDL.xml file.</para>\r
+       </section>      \r
+       <section xml:id="Reactors">\r
+               <title>Reactors</title>\r
+               <indexterm><primary>action triggers</primary><secondary>reactors</secondary></indexterm>\r
+               <para><guilabel>Reactors</guilabel> link the trigger definition to the action to be carried out.</para>\r
+               <table xml:id="Reactorstable">\r
+                       <title>Action Trigger Reactors</title>\r
+                       <tgroup cols="2">\r
+                               <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
+                               <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
+                               <thead>\r
+                                       <row>\r
+                                               <entry>Field</entry>\r
+                                               <entry>Description</entry>\r
+                                       </row>\r
+                               </thead>\r
+                               <tbody>\r
+                                       <row>\r
+                                               <entry><guilabel>Module Name</guilabel></entry>\r
+                                               <entry>The name of the Module to run if the action trigger is validated. It must be defined as a subroutine in \r
+                                               <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> or as a module\r
+                                                in <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm</filename>.</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry><guilabel>Description</guilabel></entry>\r
+                                               <entry>Description of the Action to be carried out.</entry>\r
+                                       </row>\r
+                               </tbody>        \r
+                       </tgroup>\r
+               </table>\r
+               <para>You may also create, edit and delete Reactors. Just remember that their must be an associated subroutine or module in the Reactor Perl module.</para>\r
+       </section>      \r
+       <section xml:id="Validators">\r
+               <title>Validators</title>\r
+               <indexterm><primary>action triggers</primary><secondary>validators</secondary></indexterm>\r
+               <para><guilabel>Validators</guilabel> set the validation test to be preformed to determine whether the action trigger is executed.</para>\r
+               <table xml:id="Validatorstable">\r
+                       <title>Action Trigger Validators</title>\r
+                       \r
+                       <tgroup cols="2">\r
+                               <colspec colnum="1" colname="col1" colwidth="1.0*"/>\r
+                               <colspec colnum="2" colname="col2" colwidth="3.0*"/>\r
+                               <thead>\r
+                                       <row>\r
+                                               <entry>Field</entry>\r
+                                               <entry>Description</entry>\r
+                                       </row>\r
+                               </thead>\r
+                               <tbody>\r
+                                       <row>\r
+                                               <entry><guilabel>Module Name</guilabel></entry>\r
+                                               <entry>The name of the subroutine in \r
+                                               <filename>/openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm</filename> to validate the action trigger.</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry><guilabel>Description</guilabel></entry>\r
+                                               <entry>Description of validation test to run.</entry>\r
+                                       </row>\r
+                               </tbody>        \r
+                       </tgroup>\r
+               </table>\r
+               <para>You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the <filename>Reactor.pm</filename> Perl module.</para>\r
+       </section>      \r
+       <section xml:id="ProcessingActionTriggers">     \r
+               <title>Processing Action Triggers</title>\r
+               <indexterm><primary>action triggers</primary><secondary>processing</secondary></indexterm>\r
+               <para>To run the action triggers, an Evergreen administrator will need to run the trigger processing script <command>/openils/bin/action_trigger_runner.pl \r
+               <option>--process-hooks</option> <option>--run-pending</option></command>. This should be set up as a cron job to run \r
+               periodically.</para> \r
+               <para>You have several options when running the script:</para>\r
+               <itemizedlist>\r
+                       <listitem><option>--run-pending</option>: Run the pending events.</listitem>\r
+                       <listitem><option>--process-hooks</option>: Create hook events</listitem>\r
+                       <listitem><option>--osrf-config=[<varname>config_file</varname>]</option>: OpenSRF core config file.  Defaults to: \r
+                       <filename>/openils/conf/opensrf_core.xml</filename>.</listitem>\r
+                       <listitem><option>--custom-filters=[<varname>filter_file</varname>]</option>: File containing a JSON Object which describes any hooks that should\r
+                       use a user-defined filter to find their target objects.  Defaults to: <filename>/openils/conf/action_trigger_filters.json</filename></listitem>\r
+                       <listitem><option>--max-sleep=[<varname>seconds</varname>]</option>: When in process-hooks mode, wait up to [<varname>seconds</varname>] for the lock file to go away.  \r
+                       Defaults to 3600 (1 hour).</listitem>\r
+                       <listitem><option>--hooks=hook1[,hook2,hook3,...]</option>: Define which hooks to create events for.  If none are defined, it defaults to the list of hooks defined \r
+                       in the <option>--custom-filters</option> option.</listitem>\r
+                       <listitem><option>--debug-stdout</option>: Print server responses to stdout (as JSON) for debugging.</listitem>\r
+                       <listitem><option>--lock-file=[<varname>file_name</varname>]</option>: Sets the lock file for the process.</listitem>\r
+                       <listitem><option>--help</option>: Show help information.</listitem>\r
+               </itemizedlist>\r
+       </section>                                                                                                                                      \r
+</chapter>\r
+\r
diff --git a/2.0/admin/admin-booking.xml b/2.0/admin/admin-booking.xml
new file mode 100644 (file)
index 0000000..1a5ae44
--- /dev/null
@@ -0,0 +1,310 @@
+<?xml version='1.0' encoding='UTF-8'?>\r
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
+   xml:lang="EN" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="admin-booking">\r
+   <info>\r
+      <title>Booking Module Administration</title>\r
+      <legalnotice>\r
+         <para><emphasis role="bold">Adapted with permission from original material by the <link\r
+                  xlink:title="http://docs.evergreen-ils.org/1.6/draft/html/"\r
+                  xlink:href="http://docs.evergreen-ils.org/1.6/draft/html/">Evergreen\r
+                  Community</link></emphasis></para>\r
+      </legalnotice>\r
+\r
+      <abstract>\r
+         <para>The Evergreen booking module is included in Evergreen 1.6.1.x and above.The following\r
+            documentation will include information about making cataloged items bookable; making\r
+            non-bibliographic items bookable; and setting permissions in the booking module for\r
+            staff.</para>\r
+      </abstract>\r
+   </info>\r
+   <section xml:id="MakeCataloguedItemBookable">\r
+      <title>Make a Cataloged Item Bookable in Advance</title>\r
+       <indexterm><primary>booking reservation</primary><secondary>making a cataloged item bookable</secondary></indexterm>\r
+      <para>If their permission settings allow, staff members can make items bookable. Staff members\r
+         can do this in advance of a booking request, or they can do it on the fly.</para>\r
+      <para>If you know in advance of the request that an item will need to be booked, you can make\r
+         the item bookable.</para>\r
+\r
+\r
+      <procedure>\r
+         <step>\r
+            <para>In the staff client, select <menuchoice>\r
+                  <guimenu>Search</guimenu>\r
+                  <guimenuitem>Search the Catalog</guimenuitem>\r
+               </menuchoice></para>\r
+         </step>\r
+         <step>\r
+            <para>Begin a title search to find an item.</para>\r
+         </step>\r
+         <step>\r
+            <para>Click the title of the item that you want to book.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>The <guilabel>Record Summary</guilabel> will appear. In this view you can see\r
+               information about the item and its locations. Click <menuchoice>\r
+                  <guimenu>Actions for this Record</guimenu>\r
+                  <guimenuitem>Holdings Maintenance</guimenuitem>\r
+               </menuchoice> in the top right corner of the screen.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>The <guilabel>Holdings Maintenance</guilabel> screen will appear. In this screen,\r
+               you can view the volumes and copies of an item avaialable at each branch. To view the\r
+               barcodes and other information for each copy, click the arrow adjacent to the branch\r
+               with the copy that you need to view. Click on successive arrows until you find the\r
+               copy that you need to view.</para>\r
+         </step>\r
+         <step>\r
+            <para>Select the item that you want to make bookable. Right click to open the menu, and\r
+               click <guimenuitem>Make Item Bookable</guimenuitem>.</para>\r
+         </step>\r
+         <step>\r
+            <para>The item has now been added to the list of resources that are bookable. To book\r
+               the item, return to the <guilabel>Record Summary</guilabel>, and proceed with\r
+               booking..</para>\r
+         </step>\r
+\r
+      </procedure>\r
+      <note>\r
+         <para>In Evergreen 1.6.1, there is no way to make an item “unbookable” after it has been\r
+            made bookable and has been reserved. The <guibutton>Delete Selected</guibutton> button\r
+            on this screen deletes the resource from the screen, but the item will be able to be\r
+            booked after it has been returned.</para>\r
+      </note>\r
+\r
+   </section>\r
+   <section xml:id="MakeItemBookableOnTheFly">\r
+      <title>Make a Cataloged Item Bookable On the Fly</title>\r
+      <para>If a patron wants to book an item immediately that does not have bookable status, you\r
+         can book the item on the fly if you have the appropriate permissions.</para>\r
+\r
+      <procedure>\r
+         <step>\r
+            <para>Follow steps one through five in <xref linkend="MakeCataloguedItemBookable"\r
+               />.</para>\r
+         </step>\r
+         <step>\r
+            <para>Select the item that you want to make bookable. Right click to open the menu, and\r
+               click <guimenuitem>Book Item Now</guimenuitem>.</para>\r
+         </step>\r
+         <step>\r
+            <para>A <guilabel>Reservations</guilabel> screen will appear in a new tab, and you can\r
+               make the reservation.</para>\r
+         </step>\r
+\r
+      </procedure>\r
+\r
+   </section>\r
+   <section xml:id="MakeNon-CataloguedItemBookable">\r
+      <title>Create a Bookable Status for Non-Bibliographic Items</title>\r
+       <indexterm><primary>booking reservation</primary><secondary>non-bibliographic items</secondary></indexterm>\r
+      <para>Staff with the required permissions can create a bookable status for non-bibliographic\r
+         items. For example, staff can book conference rooms or laptops. You will be able to create\r
+         types of resources, specify the names of individual resources within each type, and set\r
+         attributes to describe those resources. You can then bring the values together through the\r
+            <guilabel>Resource Attribute Map</guilabel>.</para>\r
+      <procedure>\r
+         <step>\r
+            <para>First, create the type of resource that you want to make bookable. Select <menuchoice>\r
+                  <guimenu>Admin</guimenu>\r
+                  <guisubmenu>Server Administration</guisubmenu>\r
+                  <guisubmenu>Booking</guisubmenu>\r
+                  <guimenuitem>Resource Types</guimenuitem>\r
+               </menuchoice>.</para>\r
+         </step>\r
+         <step>\r
+            <para>A list of resource types will appear. You may also see titles of cataloged items\r
+               on this screen if they were added using the <guilabel>Make Item Bookable</guilabel>\r
+               or <guilabel>Book Now</guilabel> links. You should not attempt to add cataloged items\r
+               on this screen; it is best to use the aforementioned links to make those items\r
+               bookable. In this screen, you will create a type of resource.</para>\r
+         </step>\r
+         <step>\r
+            <para>In the right corner, click <guibutton>New Resource Type</guibutton>.</para>\r
+         </step>\r
+         <step>\r
+            <para>A box will appear in which you will create a type of resource. In this box, you\r
+               can set fines, determine “elbow room” periods between reservations on this type of\r
+               resource, and indicate if this type of resource can be transferred to another\r
+               library. Click <guibutton>Save</guibutton> when you have entered the needed\r
+               information.</para>\r
+         </step>\r
+         <step>\r
+            <para>After you click <guibutton>Save</guibutton>, the box will disappear. Refresh the\r
+               screen to see the item that you have added.</para>\r
+         </step>\r
+         <step>\r
+            <para>Next, set the attributes for the type of resource that you have created. Select <menuchoice>\r
+                  <guimenu>Server Administration</guimenu>\r
+                  <guisubmenu>Booking</guisubmenu>\r
+                  <guimenuitem>Resource Attributes</guimenuitem>\r
+               </menuchoice>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Click <guibutton>New Resource Attribute</guibutton>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>A box will appear in which you can add the attributes of the resource. Attributes\r
+               are descriptive information that is provided to the staff member when the booking\r
+               request is made. For example, an attribute of the projector may be a cart that allows\r
+               for its transportation. Other attributes might be number of seats available in a\r
+               room, or MAC or PC attributes for a laptop. Click <guibutton>Save</guibutton> when\r
+               the necessary information has been entered.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>The box will disappear. Refresh the screen to see the added attribute.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Next, add the values for the resource attributes. A value can be a number, yes/no,\r
+               or any other meaningful information. Select <menuchoice>\r
+                  <guimenu>Server Administration</guimenu>\r
+                  <guisubmenu>Booking</guisubmenu>\r
+                  <guimenuitem>Resource Attribute Values</guimenuitem>\r
+               </menuchoice>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Select <guibutton>New Resource Attribute Value</guibutton>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>A pop up box will appear. Select the <guilabel>Resource Attribute</guilabel> from\r
+               the drop down box. Add the value. You can add multiple values for this field. Click\r
+                  <guibutton>Save</guibutton> when the required information has been added.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>If you refresh the screen, the attribute value may not appear, but it has been\r
+               saved.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Next, identify the specific objects that are associated with this resource type.\r
+               Click <menuchoice>\r
+                  <guimenu>Admin</guimenu>\r
+                  <guisubmenu>Server Administration</guisubmenu>\r
+                  <guisubmenu>Booking</guisubmenu>\r
+                  <guimenuitem>Resources</guimenuitem>\r
+               </menuchoice>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Click <guibutton>New Resource</guibutton>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>A pop-up box will appear. Add information for the resource and click\r
+                  <guibutton>Save</guibutton>. Repeat this process for each resource.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Refresh the screen, and the resource(s) that you added will appear.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Finally, use <guilabel>Resource Attribute Maps</guilabel> to bring together the\r
+               resource and its attributes. Select <menuchoice>\r
+                  <guimenu>Admin</guimenu>\r
+                  <guisubmenu>Server Administration</guisubmenu>\r
+                  <guisubmenu>Booking</guisubmenu>\r
+                  <guimenuitem>Resource Attribute Maps</guimenuitem>\r
+               </menuchoice>.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Select <guibutton>New Resource Attribute Map</guibutton></para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>Select the resource that you want to match with its attributes, then click\r
+                  <guibutton>Save</guibutton>. Repeat for all applicable resources.</para>\r
+         </step>\r
+\r
+         <step>\r
+            <para>You have now created bookable, non-bibliographic resource(s) with\r
+               attributes.</para>\r
+         </step>\r
+\r
+      </procedure>\r
+   </section>\r
+   <section xml:id="SettingBookingPermissions">\r
+      <title>Setting Booking Permissions</title>\r
+       <indexterm><primary>booking reservation</primary><secondary>setting booking permissions</secondary></indexterm>\r
+      <para>Administrators can set permissions so that staff members can view reservations, make\r
+         reservations, and make bibliographic or non-bibliographic items bookable.</para>\r
+\r
+      <para>If a staff member attempts to book an item for which they do not have the appropriate\r
+         permissions, they will receive an error message.</para>\r
+\r
+      <para>To set permissions, select <menuchoice>\r
+            <guimenu>Admin</guimenu>\r
+            <guisubmenu>Server Administration</guisubmenu>\r
+            <guimenuitem>Permissions</guimenuitem>\r
+         </menuchoice>.</para>\r
+\r
+      <para>Staff members should be assigned the following permissions to do common tasks in the\r
+         booking module. These permissions could be assigned to front line staff members, such as\r
+         circulation staff. Permissions with an asterisk (<emphasis role="bold">*</emphasis>) are\r
+         already included in the <emphasis role="bold">Staff</emphasis> permission group. All other\r
+         booking permissions must be applied individually.</para>\r
+\r
+      <itemizedlist>\r
+         <listitem>\r
+            <para><emphasis role="bold">View Reservations:</emphasis> VIEW_TRANSACTION*</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Use the pull list:</emphasis>\r
+               RETRIEVE_RESERVATION_PULL_LIST</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Capture reservations:</emphasis> CAPTURE_RESERVATION</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Assist patrons with pickup and return:</emphasis>\r
+               VIEW_USER*</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete reservations:</emphasis>\r
+               ADMIN_BOOKING_RESERVATION</para>\r
+         </listitem>\r
+      </itemizedlist>\r
+\r
+      <para>The following permissions allow users to do more advanced tasks, such as making items\r
+         bookable, booking items on the fly, and creating non-bibliographic resources for\r
+         booking.</para>\r
+\r
+      <itemizedlist>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete booking resource type:</emphasis>\r
+               ADMIN_BOOKING_RESOURCE_TYPE</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete booking resource attributes:</emphasis>\r
+               ADMIN_BOOKING_RESOURCE_ATTR</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete booking resource attribute\r
+                  values:</emphasis> ADMIN_BOOKING_RESOURCE_ATTR_VALUE</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete booking resource:</emphasis>\r
+               ADMIN_BOOKING_RESOURCE</para>\r
+         </listitem>\r
+         <listitem>\r
+            <para><emphasis role="bold">Create/update/delete booking resource attribute\r
+                  maps:</emphasis> ADMIN_BOOKING_RESOURCE_ATTR_MAP</para>\r
+         </listitem>\r
+      </itemizedlist>\r
+\r
+      <para>In addition to having the permissions listed above, staff members will need a valid\r
+         working location in their profiles. This should be done when registering new staff members.</para>\r
+\r
+      <!-- Pages 14-16 of source document from http://evergreen-ils.org/dokuwiki/doku.php?id=booking ommitted at conversion (Jeremy Buhler, Oct 6 2010).  Rationale: subject is covered elsewhere in the Book of Evergreen and it confuses 'working location' with 'home library', both of which should already be set for all staff accounts. -->\r
+\r
+   </section>\r
+</chapter>\r
diff --git a/2.0/admin/serversideinstallation_2.0.xml b/2.0/admin/serversideinstallation_2.0.xml
new file mode 100644 (file)
index 0000000..89a6f5f
--- /dev/null
@@ -0,0 +1,1745 @@
+<?xml version="1.0" encoding="UTF-8"?>\r
+<chapter version="5.0" xml:id="serversideinstallation" xml:lang="EN" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink">\r
+       <info>\r
+               <title>Server-side Installation of Evergreen Software</title>\r
+               <abstract>\r
+                       <para>This section describes installation of the Evergreen server-side software and its associated components.\r
+                       Installation, configuration, testing and verification \r
+                       of the software is straightforward if you follow some simple directions.</para>\r
+               </abstract>\r
+       </info>\r
+       <para>Installing, configuring and testing the Evergreen server-side software is straightforward with the current\r
+       stable software release. </para>\r
+       <para>The current version of the Evergreen server-side software runs as a native application on any of several\r
+       well-known <systemitem class="osname">Linux</systemitem> distributions \r
+       (e.g., <systemitem class="osname">Ubuntu</systemitem> and <systemitem class="osname">Debian</systemitem>). \r
+       It does not currently run as a native application on the <systemitem class="osname">Microsoft Windows</systemitem> \r
+       operating system (e.g., <systemitem class="osname">WindowsXP</systemitem>, <systemitem class="osname">WindowsXP\r
+       Professional</systemitem>, <systemitem class="osname">Windows7</systemitem>), but the software can still be\r
+       installed and run on <systemitem class="osname">Windows</systemitem> via a so-called\r
+       <emphasis>virtualized</emphasis> Linux-guest Operating System (using, for example,\r
+       <application>"VirtualBox"</application> or <application>"VMware"</application>\r
+       to emulate a <systemitem class="osname">Linux</systemitem>\r
+       environment). It can also be installed to run on other <systemitem class="osname">Linux</systemitem> \r
+       systems via virtualized environments (using, for example, <application>"VirtualBox"</application> or\r
+       <application>"VMware"</application>). More information on virtualized environments can be found in \r
+       <xref linkend="serversideinstallation-virtual"/>.</para>\r
+       <para>Installation of the Evergreen Staff Client software is reviewed in <xref linkend="staffclientinstallation"/>. </para>\r
+       <para>The Evergreen server-side software has dependencies on particular versions of certain major software\r
+       sub-components. Successful installation of Evergreen software requires that software versions agree with those\r
+       listed here:</para>\r
+       <table xml:id="serversideinstall-software-dependencies">\r
+               <?dbfo keep-together="always" ?>\r
+               <title>Evergreen Software Dependencies</title>\r
+               <indexterm>\r
+                       <primary>Evergreen software dependencies</primary>\r
+               </indexterm>\r
+               <tgroup align="left" cols="3" colsep="1" rowsep="1">\r
+                       <colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>\r
+                       <colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>\r
+                       <colspec colname="PostgreSQL" colnum="3" colwidth="1.0*"/>\r
+                       <thead>\r
+                               <row>\r
+                                       <entry>Evergreen</entry>\r
+                                       <entry>OpenSRF</entry>\r
+                                       <entry>PostgreSQL</entry>\r
+                               </row>\r
+                       </thead>\r
+                       <tbody>\r
+                               <row>\r
+                                       <entry>2.0</entry>\r
+                                       <entry>1.6.2</entry>\r
+                                       <entry>8.4</entry>\r
+                               </row>\r
+                       </tbody>\r
+               </tgroup>\r
+       </table>\r
+       <section xml:id="serversideinstallation-all">\r
+               <title>Installing Server-Side Software</title>\r
+               <para>This section describes the installation of the major components of Evergreen server-side software.</para>\r
+               <para>As far as possible, you should perform the following steps in the exact order given since the\r
+               success of many steps relies on the successful completion of earlier steps. You should make backup\r
+               copies of files and environments when you are instructed to do so. In the event of installation problems\r
+               those copies can allow you to back out of a step gracefully and resume the installation from a known\r
+               state. See <xref linkend="backingup"/> for further information.</para>\r
+               <para>Of course, after you successfully complete and test the entire Evergreen installation you should\r
+               take a final snapshot backup of your system(s). This can be the first in the series of regularly\r
+               scheduled system backups that you should probably also begin.</para>\r
+               <section xml:id="serversideinstallation-opensrf">\r
+                       <indexterm>\r
+                               <primary>OpenSRF</primary>\r
+                               <secondary>installation</secondary>\r
+                       </indexterm>\r
+                       <title>Installing OpenSRF 1.6.2 On <systemitem class="osname">Ubuntu</systemitem> or\r
+                               <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
+                       <para>This section describes the installation of the latest version of the Open Service Request\r
+                       Framework (OpenSRF), a major component of the Evergreen server-side software, on \r
+                       <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>\r
+                       systems. Evergreen software is integrated with and depends on the OpenSRF software\r
+                       system.</para>\r
+                       <para>Follow the steps outlined here and run the specified tests to ensure that OpenSRF is\r
+                       properly installed and configured. Do <emphasis><emphasis role="bold">not</emphasis></emphasis>\r
+                       continue with any further Evergreen installation steps\r
+                       until you have verified that OpenSRF has been successfully installed and tested.</para>\r
+                       <note>\r
+                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)\r
+                               platforms. OpenSRF 1.6.2 has been tested on <systemitem class="osname">Debian Lenny (5.0)</systemitem>,  <systemitem class="osname">Debian Squeeze (6.0)</systemitem> \r
+                               and <systemitem class="osname">Ubuntu Lucid Lynx (10.04)</systemitem>, <systemitem class="osname">Debian Lenny (5.0)</systemitem>, \r
+                               <systemitem class="osname">CentOS 5</systemitem>, <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem>.</para>\r
+                               <para>In the following instructions, you are asked to perform certain steps as \r
+                               either the <systemitem class="username">root</systemitem> user, the \r
+                               <systemitem class="username">opensrf</systemitem> user, or the \r
+                               <systemitem class="username">postgres</systemitem> user.</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Debian</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>su -</command> and enter the password of the\r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>sudo su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
+                               different user, issue the command <command>su - USERNAME</command>. For example, to\r
+                               switch from the <systemitem class="username">root</systemitem> user to the \r
+                               <systemitem class="username">opensrf</systemitem> user, issue the command \r
+                               <command>su - opensrf</command>. Once you have become a non-root user, to become \r
+                               the <systemitem class="username">root</systemitem> user again, simply issue the command\r
+                               <command>exit</command>.</para>\r
+                       </note>\r
+                       <procedure>\r
+                               <step>\r
+                                       <title>Add New <systemitem class="username">opensrf</systemitem> User</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, add the\r
+                                       <systemitem class="username">opensrf</systemitem> user to the system.\r
+                                       In the following example, the default shell for the \r
+                                       <systemitem class="username">opensrf</systemitem> user is automatically set\r
+                                       to <command>/bin/bash</command> to inherit a reasonable environment:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       useradd -m -s /bin/bash opensrf\r
+       passwd opensrf</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Download and Unpack Latest OpenSRF Version</title>\r
+                                       <indexterm>\r
+                                               <primary>OpenSRF</primary>\r
+                                               <secondary>download</secondary>\r
+                                       </indexterm>\r
+                                       <para>The latest version of OpenSRF can be found here:\r
+                                       <ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.6.2.tar.gz"></ulink> .\r
+                                       As the <systemitem class="username">opensrf</systemitem> user, change to\r
+                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
+                                       and extract OpenSRF. The new subdirectory\r
+                                       <filename class="directory">/home/opensrf/OpenSRF-1.6.2</filename> will be created:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /home/opensrf\r
+       wget http://evergreen-ils.org/downloads/OpenSRF-1.6.2.tar.gz\r
+       tar zxf OpenSRF-1.6.2.tar.gz</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Install Prerequisites to Build OpenSRF</title>\r
+                                       <para>In this section you will install and configure a set of prerequisites that will be\r
+                                       used to build OpenSRF. In a following step you will actually build the OpenSRF software \r
+                                       using the <command>make</command> utility.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
+                                       below to build the prerequisites from the software distribution that you just downloaded\r
+                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
+                                       example with the keyword corresponding to the name of one of the\r
+                                       <systemitem class="osname">Linux</systemitem> listed distributions. \r
+                                       For example, to install the prerequisites for Ubuntu version 10.04 (Lucid Lynx) you would\r
+                                       enter this command: <command>make -f src/extras/Makefile.install ubuntu-lucid</command> .</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/OpenSRF-1.6.2\r
+       make -f src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
+                                       <itemizedlist>\r
+                                       <listitem>\r
+                                               <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem>\r
+                                               <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm></para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><option>ubuntu-lucid</option> for <systemitem class="osname">Ubuntu Lucid Lynx\r
+                                               (10.04)</systemitem></para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><option>centos</option> for <systemitem class="osname">CentOS 5</systemitem></para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><option>rhel</option> for <systemitem class="osname">Red Hat Enterprise Linux 5</systemitem></para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                                       <para>This will install a number of packages on the system that are required by OpenSRF,\r
+                                       including some Perl modules from CPAN. You can say <literal>No</literal> to the initial\r
+                                       CPAN configuration prompt to allow it to automatically configure itself to download and\r
+                                       install Perl modules from CPAN. The CPAN installer will ask you a number of times whether\r
+                                       it should install prerequisite modules - say <literal>Yes</literal>.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Build OpenSRF</title>\r
+                                       <para>In this section you will configure, build and install the OpenSRF\r
+                                       components that support other Evergreen services.</para>\r
+                                       <substeps>\r
+                                               <step>\r
+                                                       <title>Configure OpenSRF</title>\r
+                                                       <indexterm>\r
+                                                               <primary>OpenSRF</primary>\r
+                                                               <secondary>configure</secondary>\r
+                                                       </indexterm>\r
+                                                       <para>As the <systemitem class="username">opensrf</systemitem>\r
+                                                       user, return to the new OpenSRF build directory and use the\r
+                                                       <command>configure</command> utility to prepare for the next\r
+                                                       step of compiling and linking the software. If you wish to\r
+                                                       include support for Python and Java, add the configuration\r
+                                                       options <option>--enable-python</option> and\r
+                                                       <option>--enable-java</option>, respectively:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /home/opensrf/OpenSRF-1.6.2\r
+       ./configure --prefix=/openils --sysconfdir=/openils/conf\r
+       make</userinput>\r
+                                                       </screen>\r
+                                                       <para>This step will take several minutes to complete.</para>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Compile, Link and Install OpenSRF</title>\r
+                                                       <para>As the <systemitem class="username">root</systemitem>\r
+                                                       user, return to the new OpenSRF build directory and use the\r
+                                                       <command>make</command> utility to compile, link and install\r
+                                                       OpenSRF:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/OpenSRF-1.6.2\r
+       make install</userinput>\r
+                                                       </screen>\r
+                                                       <para>This step will take several minutes to complete.</para>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Update the System Dynamic Library Path</title>\r
+                                                       <para>You must update the system dynamic library path to force\r
+                                                       your system to recognize the newly installed libraries. As the\r
+                                                       <systemitem class="username">root</systemitem> user, do this by\r
+                                                       creating the new file\r
+                                                       <filename>/etc/ld.so.conf.d/osrf.conf</filename> containing a\r
+                                                       new library path, then run the command\r
+                                                       <command>ldconfig</command> to automatically read the file and\r
+                                                       modify the system dynamic library path:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       echo "/openils/lib" > /etc/ld.so.conf.d/osrf.conf\r
+       ldconfig</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step xml:id="serversideinstallation-definedomains">\r
+                                                       <title>Define Public and Private OpenSRF Domains</title>\r
+                                                       <para>For security purposes, OpenSRF uses Jabber domains to separate services\r
+                                                       into public and private realms. On a single-server system the easiest way to\r
+                                                       define public and private OpenSRF domains is to define separate host names by \r
+                                                       adding entries to the file <filename>/etc/hosts</filename>.</para>\r
+                                                       <para>In the following steps we will use the example domains\r
+                                                       <systemitem class="domainname">public.localhost</systemitem> for the public\r
+                                                       domain and <systemitem class="domainname">private.localhost</systemitem> \r
+                                                       for the private domain. In an upcoming step, you will configure two special\r
+                                                       <systemitem class="service">ejabberd</systemitem> users\r
+                                                       to handle communications for these two domains.</para>\r
+                                                       <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                                       <filename>/etc/hosts</filename> and add the following example domains:</para>\r
+                                                       <indexterm>\r
+                                                               <primary>Jabber</primary>\r
+                                                       </indexterm>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       127.0.1.2  public.localhost   public\r
+       127.0.1.3  private.localhost  private</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Change File Ownerships</title>\r
+                                                       <para>Finally, as the <systemitem class="username">root</systemitem>\r
+                                                       user, change the ownership of all files installed in the\r
+                                                       directory <filename class="directory">/openils</filename> to the\r
+                                                       user <systemitem class="username">opensrf</systemitem>:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       chown -R opensrf:opensrf /openils</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                       </substeps>\r
+                               </step>\r
+                               <step xml:id="stop-ejabberd-service">\r
+                                       <title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
+                                       <indexterm>\r
+                                               <primary>ejabberd</primary>\r
+                                       </indexterm>\r
+                                       <para>Before continuing with configuration of <systemitem class="service">ejabberd</systemitem>\r
+                                       you must stop that service. As the <systemitem class="username">root</systemitem> user,\r
+                                       execute the following command to stop the service:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /etc/init.d/ejabberd stop</userinput>\r
+                                       </screen>\r
+                                       <para>If <systemitem class="service">ejabberd</systemitem> reports that it \r
+                                       is already stopped, there may have been a problem when it started back\r
+                                       in the installation step. If there are any remaining daemon processes such as\r
+                                       <systemitem class="daemon">beam</systemitem> or\r
+                                       <systemitem class="daemon">epmd</systemitem> \r
+                                       you may need to perform the following commands to kill them:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       epmd -kill\r
+       killall beam; killall beam.smp\r
+       rm /var/lib/ejabberd/*\r
+       echo 'ERLANG_NODE=ejabberd@localhost' >> /etc/default/ejabberd</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Edit the <systemitem class="service">ejabberd</systemitem> configuration</title>\r
+                                       <para>You must make several configuration changes for the\r
+                                       <systemitem class="service">ejabberd</systemitem> service before\r
+                                       it is started again.\r
+                                       As the <systemitem class="username">root</systemitem> user, edit the file\r
+                                       <filename>/etc/ejabberd/ejabberd.cfg</filename> and make the following changes:</para>\r
+                                       <substeps>\r
+                                               <step>\r
+                                                       <para>Change the line:</para>\r
+                                                       <literal>{hosts, ["localhost"]}.</literal>\r
+                                                       <para>to instead read:</para>\r
+                                                       <literal>{hosts, ["localhost", "private.localhost", "public.localhost"]}.</literal>\r
+                                                       <para/>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <para>Change the line:</para>\r
+                                                       <literal>{max_user_sessions, 10}</literal>\r
+                                                       <para>to instead read:</para>\r
+                                                       <literal>{max_user_sessions, 10000}</literal>\r
+                                                       <para/>\r
+                                                       <para>If the line looks something like this:</para>\r
+                                                       <literal>{access, max_user_sessions, [{10, all}]}</literal>\r
+                                                       <para>then change it to instead read:</para>\r
+                                                       <literal>{access, max_user_sessions, [{10000, all}]}</literal>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <para>Change all three occurrences of:</para>\r
+                                                       <literal>max_stanza_size</literal>\r
+                                                       <para>to instead read:</para>\r
+                                                       <literal>2000000</literal>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <para>Change both occurrences of:</para>\r
+                                                       <literal>maxrate</literal>\r
+                                                       <para>to instead read:</para>\r
+                                                       <literal>500000</literal>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <para>Comment out the line:</para>\r
+                                                       <literal>{mod_offline, []}</literal>\r
+                                                       <para>by placing two <literal>%</literal> comment signs in front\r
+                                                       so it instead reads:</para>\r
+                                                       <literal>%%{mod_offline, []}</literal>\r
+                                               </step>\r
+                                       </substeps>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-continued">\r
+                                       <title>Restart the <systemitem class="service">ejabberd</systemitem> service</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, restart the\r
+                                       <systemitem class="service">ejabberd</systemitem> service to test the\r
+                                       configuration changes and to register your users:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /etc/init.d/ejabberd start</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Register <systemitem class="username">router</systemitem> and\r
+                                               <systemitem class="username">opensrf</systemitem> as\r
+                                               <systemitem class="service">ejabberd</systemitem> users</title>\r
+                                       <para>The two <systemitem class="service">ejabberd</systemitem> users \r
+                                       <systemitem class="username">router</systemitem> and \r
+                                       <systemitem class="username">opensrf</systemitem> must be registered \r
+                                       and configured to manage OpenSRF router service and communications \r
+                                       for the two domains <literal>public.localhost</literal> and\r
+                                       <literal>private.localhost</literal> that you added to the file\r
+                                       <filename>/etc/hosts</filename> in a previous step\r
+                                       (see <xref linkend="serversideinstallation-definedomains"/>).\r
+                                       The users include:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>the <systemitem class="username">router</systemitem> user,\r
+                                                       to whom all requests to connect to an OpenSRF service will be\r
+                                                       routed;</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       which clients use to connect to OpenSRF services (you may name\r
+                                                       the user anything you like, but we use\r
+                                                       <literal>opensrf</literal> in these examples)</para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, execute the\r
+                                       <command>ejabberdctl</command> utility as shown below to register and create passwords\r
+                                       for the users <systemitem class="username">router</systemitem> and\r
+                                       <systemitem class="username">opensrf</systemitem> on each domain (remember to replace\r
+                                       <emphasis>NEWPASSWORD</emphasis> with the appropriate password):</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       # Note: the syntax for registering a user with ejabberdctl is:\r
+       #    ejabberdctl register USER DOMAIN PASSWORD\r
+       ejabberdctl register router  private.localhost NEWPASSWORD\r
+       ejabberdctl register router  public.localhost  NEWPASSWORD\r
+       ejabberdctl register opensrf private.localhost NEWPASSWORD\r
+       ejabberdctl register opensrf public.localhost  NEWPASSWORD</userinput>\r
+                                       </screen>\r
+                                       <para>Note that the users <systemitem class="username">router</systemitem> and\r
+                                       <systemitem class="username">opensrf</systemitem> and their respective passwords \r
+                                       will be used again in <xref linkend="serversideinstallation-passwords"/> when\r
+                                       we modify the OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename> .</para>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-createconfig">\r
+                                       <title>Create OpenSRF configuration files</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, \r
+                                       execute the following commands to create the new configuration files\r
+                                       <filename>/openils/conf/opensrf_core.xml</filename> and\r
+                                       <filename>/openils/conf/opensrf.xml</filename> from the example templates:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /openils/conf\r
+       cp opensrf.xml.example      opensrf.xml\r
+       cp opensrf_core.xml.example opensrf_core.xml</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-passwords">\r
+                                       <title>Update usernames and passwords in the OpenSRF configuration file</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
+                                       OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>\r
+                                       and update the usernames and passwords to match the values shown in the\r
+                                       following table. The left-hand side of <xref linkend="serversideinstallation-xpath-table-1"/>\r
+                                       shows common XPath syntax to indicate the approximate position within the XML\r
+                                       file that needs changes. The right-hand side of the table shows the replacement\r
+                                       values:</para>\r
+                                       <table xml:id="serversideinstallation-xpath-table-1">\r
+                                               <?dbfo keep-together="always" ?>\r
+                                               <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
+                                                       <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>\r
+                                                       <colspec colname="Value" colnum="2" colwidth="2.0*"/>\r
+                                                       <thead>\r
+                                                               <row>\r
+                                                                       <entry>XPath location</entry>\r
+                                                                       <entry>Value</entry>\r
+                                                               </row>\r
+                                                       </thead>\r
+                                                       <tbody>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/passwd </entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/passwd</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username, \r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                       </tbody>\r
+                                               </tgroup>\r
+                                       </table>\r
+                                       <para>You may also need to modify the file to specify the domains from which \r
+                                       <systemitem class="service">OpenSRF</systemitem> will accept connections,\r
+                                       and to which it will make connections.\r
+                                       If you are installing <application>OpenSRF</application> on a single server\r
+                                       and using the <systemitem class="domainname">private.localhost</systemitem> and\r
+                                       <systemitem class="domainname">public.localhost</systemitem> domains, \r
+                                       these will already be set to the correct values. Otherwise, search and replace\r
+                                       to match values for your own systems.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Set location of the persistent database</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
+                                       file <filename>/openils/conf/opensrf.xml</filename>, then find and modify the \r
+                                       element <literal>dbfile</literal> (near the end of the file) to set the \r
+                                       location of the persistent database. Change the default line:</para>\r
+                                       <literal>/openils/var/persist.db</literal>\r
+                                       <para>to instead read:</para>\r
+                                       <literal>/tmp/persist.db</literal>\r
+                                       <para>Following is a sample modification of that portion of the file:</para>\r
+                                       <programlisting language="xml"><![CDATA[\r
+<!-- Example of an app-specific setting override -->\r
+<opensrf.persist>\r
+  <app_settings>\r
+    <dbfile>/tmp/persist.db</dbfile>\r
+  </app_settings>\r
+</opensrf.persist>\r
+]]></programlisting>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-srfsh">\r
+                                       <title>Create configuration files for users needing <command>srfsh</command></title>\r
+                                       <para>In this section you will set up a special configuration file for each user\r
+                                       who will need to run the <command>srfsh</command> (pronounced <emphasis>surf\r
+                                       shell</emphasis>) utility.</para>\r
+                                       <indexterm>\r
+                                               <primary>srfsh</primary>\r
+                                       </indexterm>\r
+                                       <para>The software installation will automatically create the utility\r
+                                       <command>srfsh</command> (surf shell), a command line diagnostic tool for\r
+                                       testing and interacting with <application>OpenSRF</application>. It will be used\r
+                                       in a future step to complete and test the Evergreen installation. See \r
+                                       <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, copy the\r
+                                       sample configuration file <filename>/openils/conf/srfsh.xml.example</filename>\r
+                                       to the home directory of each user who will use <command>srfsh</command>. \r
+                                       For instance, do the following for the \r
+                                       <systemitem class="username">opensrf</systemitem> user:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cp /openils/conf/srfsh.xml.example  /home/opensrf/.srfsh.xml</userinput>\r
+                                       </screen>\r
+                                       <para>Edit each user's file <filename>~/.srfsh.xml</filename> and make the\r
+                                       following changes:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>domain</literal> to be the router hostname\r
+                                                       (following our domain examples,\r
+                                                       <systemitem class="domainname">private.localhost</systemitem> will give\r
+                                                       <command>srfsh</command> access to all OpenSRF services, while\r
+                                                       <systemitem class="domainname">public.localhost</systemitem>\r
+                                                       will only allow access to those OpenSRF services that are\r
+                                                       publicly exposed).</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>username</literal> and\r
+                                                       <literal>password</literal> to match the\r
+                                                       <literal>opensrf</literal> Jabber user for the chosen\r
+                                                       domain</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>logfile</literal> to be the full path for\r
+                                                       a log file to which the user has write access</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Modify <literal>loglevel</literal> as needed for testing</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>Change the owner of the file to match the owner of the home directory</para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                                       <para>Following is a sample of the file:</para>\r
+                                       <programlisting language="xml"><![CDATA[\r
+<?xml version="1.0"?>\r
+<!-- This file follows the standard bootstrap config file layout -->\r
+<!-- found in opensrf_core.xml -->\r
+<srfsh>\r
+<router_name>router</router_name>\r
+<domain>private.localhost</domain>\r
+<username>opensrf</username>\r
+<passwd>SOMEPASSWORD</passwd>\r
+<port>5222</port>\r
+<logfile>/tmp/srfsh.log</logfile>\r
+<!-- 0 None, 1 Error, 2 Warning, 3 Info, 4 debug, 5 Internal (Nasty) -->\r
+<loglevel>4</loglevel>\r
+</srfsh>\r
+]]></programlisting>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Modify the environmental variable <envar>PATH</envar> for the\r
+                                               <systemitem class="username">opensrf</systemitem> user</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, modify the\r
+                                       environmental variable <envar>PATH</envar> by adding a new file path to the\r
+                                       <systemitem class="username">opensrf</systemitem> user's shell configuration\r
+                                       file <filename>~/.bashrc</filename>:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       echo "export PATH=/openils/bin:\$PATH" >> ~/.bashrc</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Start OpenSRF</title>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, start the\r
+                                       <systemitem class="service">ejabberd</systemitem> and \r
+                                       <systemitem class="service">memcached</systemitem> services:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /etc/init.d/ejabberd start\r
+       /etc/init.d/memcached start</userinput>\r
+                                       </screen>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                       start OpenSRF as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       osrf_ctl.sh -l -a start_all</userinput>\r
+                                       </screen>\r
+                                       <para>The flag <option>-l</option> forces Evergreen to use \r
+                                       <systemitem class="domainname">localhost</systemitem> (your current system) \r
+                                       as the hostname. The flag <option>-a start_all</option>  starts the other \r
+                                       OpenSRF <systemitem class="service">router</systemitem> , \r
+                                       <systemitem class="service">Perl</systemitem> , and\r
+                                       <systemitem class="service">C</systemitem> services.</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>You can also start Evergreen without the\r
+                                                       <option>-l</option> flag, but the <command>osrf_ctl.sh</command>\r
+                                                       utility must know the fully qualified domain name for the system\r
+                                                       on which it will execute. That hostname was probably specified\r
+                                                       in the configuration file <filename>opensrf.xml</filename> which\r
+                                                       you configured in a previous step.</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>If you receive an error message similar to\r
+                                                       <emphasis>osrf_ctl.sh: command not found</emphasis>, then your\r
+                                                       environment variable <envar>PATH</envar> does not include the\r
+                                                       directory <filename class="directory">/openils/bin</filename>.\r
+                                                       As the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       edit the configuration file <filename>~/.bashrc</filename> and\r
+                                                       add the following line: \r
+                                                       <literal>export PATH=$PATH:/openils/bin</literal></para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Test connections to OpenSRF</title>\r
+                                       <para>Once you have installed and started OpenSRF, as the \r
+                                       <systemitem class="username">root</systemitem> user, test your connection to \r
+                                       <systemitem class="service">OpenSRF</systemitem> using the <command>srfsh</command> \r
+                                       utility and trying to call the <command>add</command> method on the OpenSRF \r
+                                       <systemitem class="service">math</systemitem> service:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /openils/bin/srfsh</userinput>\r
+                                               <computeroutput>\r
+       srfsh# <userinput>request opensrf.math add 2 2</userinput></computeroutput>\r
+                                               <computeroutput>\r
+       Received Data: 4\r
+       ------------------------------------\r
+       Request Completed Successfully\r
+       Request Time in seconds: 0.007519\r
+       ------------------------------------</computeroutput>\r
+                                       </screen>\r
+                                       <para>For other <command>srfsh</command> commands, type in\r
+                                       <userinput>help</userinput> at the prompt.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Stop OpenSRF</title>\r
+                                       <para>After OpenSRF has started, you can stop it at any time by using the\r
+                                       <command>osrf_ctl.sh</command> again. As the \r
+                                       <systemitem class="username">opensrf</systemitem> \r
+                                       user, stop OpenSRF as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       osrf_ctl.sh -l -a stop_all</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                       </procedure>\r
+               </section>\r
+               <section xml:id="serversideinstallation-ubuntudebian">\r
+                       <title>Installing Evergreen 2.0 On <systemitem class="osname">Ubuntu</systemitem> or\r
+                               <systemitem class="osname">Debian</systemitem></title>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Debian</secondary>\r
+                       </indexterm>\r
+                       <indexterm>\r
+                               <primary>Linux</primary>\r
+                               <secondary>Ubuntu</secondary>\r
+                       </indexterm>\r
+                       <para>This section outlines the installation process for the latest stable version of\r
+                       Evergreen.</para>\r
+                       <para>In this section you will download, unpack, install, configure and test the Evergreen\r
+                       system, including the Evergreen server and the PostgreSQL database system. You will make several\r
+                       configuration changes and adjustments to the software, including updates to configure the system\r
+                       for your own locale, and some updates needed to work around a few known issues.</para>\r
+                       <note>\r
+                               <para>The following steps have been tested on the x86 (32-bit) and x86-64 (64-bit)\r
+                               architectures. There may be differences between the Desktop and Server editions of\r
+                               <systemitem class="osname">Ubuntu</systemitem>. These instructions assume the Server\r
+                               edition.</para>\r
+                               <para>In the following instructions, you are asked to perform certain steps as \r
+                               either the <systemitem class="username">root</systemitem> user, the \r
+                               <systemitem class="username">opensrf</systemitem> user, or the \r
+                               <systemitem class="username">postgres</systemitem> user.</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Debian</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para><systemitem class="osname">Ubuntu</systemitem> -- To become the\r
+                                               <systemitem class="username">root</systemitem> user, issue the command\r
+                                               <command>sudo su -</command> and enter the password of the \r
+                                               <systemitem class="username">root</systemitem> user.</para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               <para>To switch from the <systemitem class="username">root</systemitem> user to a\r
+                               different user, issue the command <command>su - USERNAME</command>. For example, to\r
+                               switch from the <systemitem class="username">root</systemitem> user to the \r
+                               <systemitem class="username">opensrf</systemitem> user, issue the command \r
+                               <command>su - opensrf</command>. Once you have become a non-root user, to become the\r
+                               <systemitem class="username">root</systemitem> user again, simply issue the command\r
+                               <command>exit</command>.</para>\r
+                       </note>\r
+                       <procedure>\r
+                               <step>\r
+                                       <title>Install OpenSRF</title>\r
+                                       <para>Evergreen software is integrated with and depends on the Open Service\r
+                                       Request Framework (OpenSRF) software system. For further information on\r
+                                       installing, configuring and testing OpenSRF, see \r
+                                       <xref linkend="serversideinstallation-opensrf"/>.</para>\r
+                                       <para>Follow the steps outlined in that section and run the specified tests to\r
+                                       ensure that OpenSRF is properly installed and configured. Do \r
+                                       <emphasis><emphasis role="bold">not</emphasis></emphasis> continue with\r
+                                       any further Evergreen installation steps until you have verified that OpenSRF\r
+                                       has been successfully installed and tested.</para>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Download and Unpack Latest Evergreen Version</title>\r
+                                       <para>The latest version of Evergreen can be found here:\r
+                                       <ulink url="http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.1.tar.gz"></ulink> .\r
+                                       As the <systemitem class="username">opensrf</systemitem> user, change to\r
+                                       the directory <filename class="directory">/home/opensrf</filename> then download\r
+                                       and extract Evergreen. The new subdirectory\r
+                                       <filename class="directory">/home/opensrf/Evergreen-ILS-2.0.1</filename> will be created:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /home/opensrf\r
+       wget http://evergreen-ils.org/downloads/Evergreen-ILS-2.0.1.tar.gz\r
+       tar zxf Evergreen-ILS-2.0.1.tar.gz</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-installprereq">\r
+                                       <title>Install Prerequisites to Build Evergreen</title>\r
+                                       <para>In this section you will install and configure a set of prerequisites that will be\r
+                                       used later in <xref linkend="serversideinstallation-configure"/> and \r
+                                       <xref linkend="serversideinstallation-compile"/> to build the Evergreen software \r
+                                       using the <command>make</command> utility.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, enter the commands show\r
+                                       below to build the prerequisites from the software distribution that you just downloaded\r
+                                       and unpacked. Remember to replace <emphasis>[DISTRIBUTION]</emphasis> in the following\r
+                                       example with the keyword corresponding to the name of one of the \r
+                                       <systemitem class="osname">Linux</systemitem> distributions listed in the following\r
+                                       distribution keywords table <xref linkend="serversideinstallation-keywords-evergreen"/> .\r
+                                       For example, to install the prerequisites for Ubuntu version 10.05 (Karmic Koala) you would\r
+                                       enter this command: <command>make -f Open-ILS/src/extras/Makefile.install\r
+                                       ubuntu-lucid</command>.</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/Evergreen-ILS-2.0.1\r
+       make -f Open-ILS/src/extras/Makefile.install [DISTRIBUTION]</userinput>\r
+                                       </screen>\r
+                                       <itemizedlist>\r
+                                       \r
+                                       <listitem>\r
+                                               <para><option>debian-squeeze</option> for <systemitem class="osname">Debian Squeeze (6.0)</systemitem></para>\r
+                                       </listitem>\r
+                                       \r
+                                       <listitem>\r
+                                               <para><option>ubuntu-lucid</option> for  <systemitem class="osname">Ubuntu Lucid Lynx \r
+                                               (10.04)</systemitem></para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               </step>\r
+                               <step performance="optional" xml:id="serversideinstallation-postgresql-default">\r
+                                       <title>(OPTIONAL) Install the PostgreSQL Server</title>\r
+                                       <indexterm>\r
+                                               <primary>databases</primary>\r
+                                               <secondary>PostgreSQL</secondary>\r
+                                       </indexterm>\r
+                                       <para>Since the PostgreSQL server is usually a standalone server in multi-server\r
+                                       production systems, the prerequisite installer Makefile in the previous section\r
+                                       (see <xref linkend="serversideinstallation-installprereq"/>)\r
+                                       does not automatically install PostgreSQL. You must install the PostgreSQL server\r
+                                       yourself, either on the same system as Evergreen itself or on another system.\r
+                                       If your PostgreSQL server is on a different system, just skip this step.\r
+                                       If your PostgreSQL server will be on the same system as your Evergreen\r
+                                       software, you can install the required PostgreSQL server packages as described\r
+                                       in <xref linkend="InstallingPostgreSQL"/>, or you can visit the official \r
+                                       web site <link xl:href="http://www.postgresql.org/">http://www.postgresql.org</link>\r
+                                       for more information.</para>\r
+                                       <note>\r
+                                               <para>PostgreSQL version 8.4 is the minimum supported version to work \r
+                                               with Evergreen 2.0. If you have an older version of PostgreSQL, \r
+                                               you should upgrade before installing Evergreen. To find your current version \r
+                                               of PostgreSQL, as the <systemitem class="username">postgres</systemitem> \r
+                                               user execute the command <command>psql</command>, then type \r
+                                               <userinput>SELECT version();</userinput> to get detailed information \r
+                                               about your version of PostgreSQL.</para>\r
+                                       </note>\r
+                               </step>\r
+                               <step performance="optional">\r
+                                       <title>Install Perl Modules on PostgreSQL Server</title>\r
+                                       <para>If PostgreSQL is running on the same system as your Evergreen software,\r
+                                       then the Perl modules will automatically be available. Just skip this step.\r
+                                       Otherwise, continue if your PostgreSQL server is running on another system.</para>\r
+                                       <para>You will need to install several Perl modules on the other system. As the\r
+                                       <systemitem class="username">root</systemitem> user install the following Perl\r
+                                       modules:</para>\r
+                                       <para>as the root user, ensure the gcc compiler is installed:</para>\r
+<screen>\r
+<userinput>aptitude install gcc libxml-libxml-perl libxml-libxslt-perl</userinput>\r
+</screen>\r
+                                       <para>then install the Perl modules:</para>\r
+<screen>\r
+<userinput>perl -MCPAN -e shell</userinput>\r
+<prompt>cpan></prompt> <userinput>Business::ISBN</userinput>   \r
+<prompt>cpan></prompt> <userinput>install JSON::XS</userinput>\r
+<prompt>cpan></prompt> <userinput>Library::CallNumber::LC</userinput>\r
+<prompt>cpan></prompt> <userinput>install MARC::Record</userinput>\r
+<prompt>cpan></prompt> <userinput>install MARC::File::XML</userinput>\r
+<prompt>cpan></prompt> <userinput>cpan UUID::Tiny</userinput>\r
+</screen>\r
+                                       <para>For more information on installing Perl Modules vist the official\r
+                                       <link xl:href="http://www.cpan.org/">CPAN</link> site.</para>\r
+                                       <indexterm>\r
+                                               <primary>Perl</primary>\r
+                                               <secondary>CPAN</secondary>\r
+                                       </indexterm>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Update the System Dynamic Library Path</title>\r
+                                       <para>You must update the system dynamic library path to force your system to recognize\r
+                                       the newly installed libraries. As the <systemitem class="username">root</systemitem> user,\r
+                                       do this by creating the new file <filename>/etc/ld.so.conf.d/osrf.conf</filename>\r
+                                       containing a new library path, then run the command <command>ldconfig</command> to\r
+                                       automatically read the file and modify the system dynamic library path:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       echo "/usr/local/lib"     >> /etc/ld.so.conf.d/osrf.conf\r
+       echo "/usr/local/lib/dbd" >> /etc/ld.so.conf.d/osrf.conf\r
+       ldconfig</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step performance="optional">\r
+                                       <title>Restart the PostgreSQL Server</title>\r
+                                       <para>If PostgreSQL is running on the same system as the rest of Evergreen, as\r
+                                       the <systemitem class="username">root</systemitem> user you must restart\r
+                                       PostgreSQL to re-read the new library paths just configured. If PostgreSQL is\r
+                                       running on another system, you may skip this step.\r
+                                       As the <systemitem class="username">opensrf</systemitem> user,\r
+                                       execute the following command (remember to replace\r
+                                       <emphasis>PGSQL_VERSION</emphasis> with your installed PostgreSQL version,\r
+                                       for example <literal>8.4</literal>):</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       /etc/init.d/postgresql-PGSQL_VERSION restart</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-configure">\r
+                                       <title>Configure Evergreen</title>\r
+                                       <para>In this step you will use the <command>configure</command> and\r
+                                       <command>make</command> utilities to configure Evergreen so it can be compiled\r
+                                       and linked later in <xref linkend="serversideinstallation-compile"/>.</para>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, return to\r
+                                       the Evergreen build directory and execute these commands:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /home/opensrf/Evergreen-ILS-2.0.1\r
+       ./configure --prefix=/openils --sysconfdir=/openils/conf\r
+       make</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-compile">\r
+                                       <title>Compile, Link and Install Evergreen</title>\r
+                                       <para>In this step you will actually compile, link and install Evergreen and the \r
+                                       default Evergreen Staff Client.</para>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, return to the\r
+                                       Evergreen build directory and use the <command>make</command> utility as shown below:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/Evergreen-ILS-2.0.1\r
+       make STAFF_CLIENT_BUILD_ID=rel_2_0_1 install</userinput>\r
+                                       </screen>\r
+                                       <para>The Staff Client will also be automatically built, but you must remember\r
+                                       to set the variable <envar>STAFF_CLIENT_BUILD_ID</envar> to match the version of the \r
+                                       Staff Client you will use to connect to the Evergreen server.</para>\r
+                                       <para>The above commands will create a new subdirectory\r
+                                       <filename class="directory">/openils/var/web/xul/rel_2_0_1</filename> \r
+                                       containing the Staff Client.</para>\r
+                                       <para>To complete the Staff Client installation, as the\r
+                                       <systemitem class="username">root</systemitem> user execute the following commands to\r
+                                       create a symbolic link named <emphasis>server</emphasis> in the head of the Staff Client\r
+                                       directory <filename class="directory">/openils/var/web/xul</filename> that points to the\r
+                                       subdirectory <filename class="directory">/server</filename> of the new Staff Client\r
+                                       build:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cd /openils/var/web/xul\r
+       ln -sf rel_2_0_1/server server</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Copy the OpenSRF Configuration Files</title>\r
+                                       <para>In this step you will replace some OpenSRF configuration files that you set up in\r
+                                       <xref linkend="serversideinstallation-opensrf-createconfig"/> when you installed and\r
+                                       tested OpenSRF.</para>\r
+                                       <para>You must copy several example OpenSRF configuration files into place after first\r
+                                       creating backup copies for troubleshooting purposes, then change all the file ownerships\r
+                                       to <systemitem class="username">opensrf</systemitem>.\r
+                                       As the <systemitem class="username">root</systemitem> user, execute the following\r
+                                       commands:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       cd /openils/conf\r
+       cp opensrf.xml        opensrf.xml.BAK\r
+       cp opensrf_core.xml      opensrf_core.xml.BAK\r
+       cp opensrf.xml.example      opensrf.xml\r
+       cp opensrf_core.xml.example opensrf_core.xml\r
+       cp oils_web.xml.example     oils_web.xml\r
+       chown -R opensrf:opensrf /openils/</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Create and Configure PostgreSQL Database</title>\r
+                                       <indexterm>\r
+                                               <primary>databases</primary>\r
+                                               <secondary>PostgreSQL</secondary>\r
+                                       </indexterm>\r
+                                       <para>In this step you will create the Evergreen database. In the commands\r
+                                       below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis>\r
+                                       repository to match your PostgreSQL server\r
+                                       layout. For example, if you built PostgreSQL from source the path would be\r
+                                       <filename class="directory">/usr/local/share/contrib</filename> , and if you\r
+                                       installed the PostgreSQL 8.4 server packages on <systemitem class="osname">Ubuntu</systemitem>,\r
+                                       the path would be \r
+                                       <systemitem class="directory">/usr/share/postgresql/8.4/contrib/</systemitem> .</para>\r
+                                       <substeps>\r
+                                               <step>\r
+                                                       <para>\r
+                                                               <emphasis role="bold">Create and configure the database</emphasis>\r
+                                                       </para>\r
+                                                       <para>As the <systemitem class="username">postgres</systemitem>\r
+                                                       user on the PostgreSQL system create the PostgreSQL database,\r
+                                                       then set some internal paths:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the postgres user:\r
+       createdb evergreen -E UTF8 -T template0\r
+       createlang plperl   evergreen\r
+       createlang plperlu  evergreen\r
+       createlang plpgsql  evergreen</userinput>\r
+                                                       </screen>\r
+                                                       <para>Continue as the <systemitem class="username">postgres</systemitem> user\r
+                                                       and execute the SQL scripts as shown below (remember to adjust the paths as needed,\r
+                                                       where <emphasis>PGSQL_VERSION</emphasis> is your installed PostgreSQL\r
+                                                       version, for example <literal>8.4</literal>).</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the postgres user:\r
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tablefunc.sql evergreen\r
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/tsearch2.sql  evergreen\r
+       psql -f /usr/share/postgresql/PGSQL_VERSION/contrib/pgxml.sql     evergreen</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step xml:id="serversideinstallation-postgresqlcreateuser">\r
+                                                       <title>Create <systemitem class="username">evergreen</systemitem> PostgreSQL user</title>\r
+                                                       <para>As the <systemitem class="username">postgres</systemitem>\r
+                                                       user on the PostgreSQL system, create a new PostgreSQL user\r
+                                                       named <systemitem class="username">evergreen</systemitem> and\r
+                                                       assign a password (remember to replace <emphasis>NEWPASSWORD</emphasis>\r
+                                                       with an appropriate new password):</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the postgres user:\r
+       createuser -P -s evergreen</userinput>\r
+                                                               <computeroutput>\r
+       Enter password for new role: <userinput>NEWPASSWORD</userinput>\r
+       Enter it again: <userinput>NEWPASSWORD</userinput></computeroutput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Create database schema</title>\r
+                                                       <para>In this step you will create the database schema and configure your\r
+                                                       system with the corresponding database authentication details for the\r
+                                                       <emphasis>evergreen</emphasis> database user that you just created in\r
+                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>\r
+                                                       <para>As the <systemitem class="username">root</systemitem> user, enter\r
+                                                       the following commands and replace <emphasis>HOSTNAME, PORT,\r
+                                                       PASSWORD</emphasis> and <emphasis>DATABASENAME</emphasis> with appropriate\r
+                                                       values:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/Evergreen-ILS-2.0.1\r
+       perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
+         --service all --create-schema --create-offline \\r
+         --hostname HOSTNAME --port PORT \\r
+         --user evergreen --password PASSWORD --database DATABASENAME</userinput>\r
+                                                       </screen>\r
+                                                       <para>On most systems, <emphasis>HOSTNAME</emphasis> will be\r
+                                                       <emphasis role="bold">localhost</emphasis> and\r
+                                                       <emphasis>PORT</emphasis> will be <emphasis role="bold">5432</emphasis>.\r
+                                                       Of course, values for <emphasis>PASSWORD</emphasis> and\r
+                                                       <emphasis>DATABASENAME</emphasis> must match the values you used in \r
+                                                       <xref linkend="serversideinstallation-postgresqlcreateuser"/>.</para>\r
+                                                       <para>As the command executes, you may see warnings similar to:\r
+                                                       <literal>ERROR: schema SOMENAME does not exist</literal> (in fact,\r
+                                                       you may see one warning per schema) but they can be safely ignored.</para>\r
+                                                       <note>If you are entering the above command on a single line, do not\r
+                                                       include the <literal>\</literal> (backslash) characters. If you are using\r
+                                                       the <command>bash</command> shell, these should only be used at the end of\r
+                                                       a line at a <command>bash</command> prompt to indicate that the command is\r
+                                                       continued on the next line.</note>\r
+                                               </step>\r
+                                       </substeps>\r
+                               </step>\r
+                               <step>\r
+                                       <title>Configure the Apache web server</title>\r
+                                       <indexterm>\r
+                                               <primary>web server</primary>\r
+                                               <secondary>Apache</secondary>\r
+                                       </indexterm>\r
+                                       <para>In this step you will configure the Apache web server to support Evergreen\r
+                                       software.</para>\r
+                                       <para>First, you must enable some built-in Apache modules and install some\r
+                                       additional Apache configuration files. Then you will create a new Security\r
+                                       Certificate. Finally, you must make several changes to the Apache configuration\r
+                                       file.</para>\r
+                                       <substeps>\r
+                                               <step>\r
+                                                       <title>Enable the required Apache Modules</title>\r
+                                                       <para>As the <systemitem class="username">root</systemitem>\r
+                                                       user, enable some modules in the Apache server, then copy the\r
+                                                       new configuration files to the Apache server directories:</para>\r
+                                                       <indexterm>\r
+                                                               <primary>Apache modules</primary>\r
+                                                       </indexterm>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       a2enmod ssl     # enable mod_ssl\r
+       a2enmod rewrite # enable mod_rewrite\r
+       a2enmod expires # enable mod_expires</userinput>\r
+                                                       </screen>\r
+                                                       <para>As the commands execute, you may see warnings similar to:\r
+                                                       <literal>Module SOMEMODULE already enabled</literal> but you can\r
+                                                       safely ignore them.</para>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Copy Apache configuration files</title>\r
+                                                       <para>You must copy the Apache configuration files from the\r
+                                                       Evergreen installation directory to the Apache directory. As the\r
+                                                       <systemitem class="username">root</systemitem> user, perform the\r
+                                                       following commands:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       cd /home/opensrf/Evergreen-ILS-2.0.1\r
+       cp Open-ILS/examples/apache/eg.conf     /etc/apache2/sites-available/\r
+       cp Open-ILS/examples/apache/eg_vhost.conf  /etc/apache2/\r
+       cp Open-ILS/examples/apache/startup.pl     /etc/apache2/</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                               <step xml:id="serversideinstallation-createsslcertificate">\r
+                                                       <title>Create a Security Certificate</title>\r
+                                                       <para>In this step you will create a new Security Certificate (SSL Key)\r
+                                                       for the Apache server using the <command>openssl</command> command. For a\r
+                                                       public production server you must configure or purchase a signed SSL\r
+                                                       certificate, but for now you can just use a self-signed certificate and\r
+                                                       accept the warnings in the Staff Client and browser during testing and\r
+                                                       development. As the <systemitem class="username">root</systemitem> user,\r
+                                                       perform the following commands:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       mkdir /etc/apache2/ssl\r
+       cd /etc/apache2/ssl\r
+       openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</userinput>\r
+                                                       </screen>\r
+                                                       <para>You will be prompted for several items of information; enter\r
+                                                       the appropriate information for each item. The new files\r
+                                                       <filename>server.crt</filename> and <filename>server.key</filename> will\r
+                                                       be created in the directory \r
+                                                       <filename class="directory">/etc/apache2/ssl</filename> .</para>\r
+                                                       <note>This step generates a self-signed SSL certificate. You must install\r
+                                                       a proper SSL certificate for a public production system to avoid warning\r
+                                                       messages when users login to their account through the OPAC or when staff\r
+                                                       login through the Staff Client. For further information on\r
+                                                       installing a proper SSL certificate, see \r
+                                                       <xref linkend="serversideinstallation-ssl"/>.</note>\r
+                                               </step>\r
+                                               <step xml:id="serversideinstallation-modify-apache">\r
+                                                       <title>Update Apache configuration file</title>\r
+                                                       <para>You must make several changes to the new Apache\r
+                                                       configuration file\r
+                                                       <filename>/etc/apache2/sites-available/eg.conf</filename> . \r
+                                                       As the <systemitem class="username">root</systemitem> user,\r
+                                                       edit the file and make the following changes:</para>\r
+                                                       <itemizedlist>\r
+                                                               <listitem>\r
+                                                                       <para>In the section\r
+                                                                       <literal>&lt;Directory "/openils/var/cgi-bin"></literal>\r
+                                                                       replace the line:</para>\r
+                                                                       <literal>Allow from 10.0.0.0/8</literal>\r
+                                                                       <para>with the line:</para>\r
+                                                                       <literal>Allow from all</literal>\r
+                                                                       <warning>This change allows access to your configuration\r
+                                                                       CGI scripts from any workstation on any network. This is\r
+                                                                       only a temporary change to expedite testing and should be\r
+                                                                       removed after you have finished and successfully tested\r
+                                                                       the Evergreen installation. See \r
+                                                                       <xref linkend="serversideinstallation-postinstallation"/> \r
+                                                                       for further details on removing this change after the\r
+                                                                       Evergreen installation is complete.\r
+                                                                       </warning>\r
+                                                               </listitem>\r
+                                                               <listitem>\r
+                                                                       <para>Comment out the line:</para>\r
+                                                                       <literal>Listen 443</literal>\r
+                                                                       <para>since it conflicts with the same declaration in \r
+                                                                       the configuration file:</para>\r
+                                                                       <para><filename>/etc/apache2/ports.conf</filename>.</para>\r
+                                                               </listitem>\r
+                                                               <listitem>\r
+                                                                       <para>The following updates are needed to allow the logs\r
+                                                                       to function properly, but it may break other Apache\r
+                                                                       applications on your server:</para>\r
+                                                                       \r
+                                                                       <para>Edit the Apache configuration file and change the lines:</para>\r
+                                                                       <screen>\r
+                                                                               <userinput>\r
+       export APACHE_RUN_USER=www-data\r
+       export APACHE_RUN_GROUP=www-data</userinput>\r
+                                                                       </screen>\r
+                                                                       <para>to instead read:</para>\r
+                                                                       <screen>\r
+                                                                               <userinput>\r
+       export APACHE_RUN_USER=opensrf\r
+       export APACHE_RUN_GROUP=opensrf</userinput>\r
+                                                                       </screen>\r
+                                                               </listitem>\r
+                                                               <listitem>\r
+                                                                       <para>As the \r
+                                                                       <systemitem class="username">root</systemitem> user,\r
+                                                                       edit the Apache configuration file\r
+                                                                       <filename>/etc/apache2/apache2.conf</filename> and\r
+                                                                       modify the value for <literal>KeepAliveTimeout</literal>\r
+                                                                       and <literal>MaxKeepAliveRequests</literal> to match\r
+                                                                       the following:</para>\r
+                                                                       <screen>\r
+                                                                               <userinput>\r
+       KeepAliveTimeout       1\r
+       MaxKeepAliveRequests 100</userinput>\r
+                                                                       </screen>\r
+                                                               </listitem>\r
+                                                               <listitem>\r
+                                                                       <para>Further configuration changes to Apache may be\r
+                                                                       necessary for busy systems. These changes increase the\r
+                                                                       number of Apache server processes that are started to\r
+                                                                       support additional browser connections.</para>\r
+                                                                       <para>As the \r
+                                                                       <systemitem class="username">root</systemitem> user, \r
+                                                                       edit the Apache configuration file\r
+                                                                       <filename>/etc/apache2/apache2.conf</filename>, locate \r
+                                                                       and modify the section related to <emphasis>prefork\r
+                                                                       configuration</emphasis> to suit the load on your\r
+                                                                       system:</para>\r
+                                                                       <programlisting language="xml"><![CDATA[\r
+<IfModule mpm_prefork_module>\r
+   StartServers           20\r
+   MinSpareServers      5\r
+   MaxSpareServers     15\r
+   MaxClients      150\r
+   MaxRequestsPerChild 10000\r
+</IfModule>\r
+]]></programlisting>\r
+                                                               </listitem>\r
+                                                       </itemizedlist>\r
+                                               </step>\r
+                                               <step>\r
+                                                       <title>Enable the Evergreen web site</title>\r
+                                                       <para>Finally, you must enable the Evergreen web site. As the\r
+                                                       <systemitem class="username">root</systemitem> user, execute the\r
+                                                       following Apache configuration commands to disable the default\r
+                                                       <emphasis>It Works</emphasis> web page and enable the Evergreen\r
+                                                       web site, and then restart the Apache server:</para>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the root user:\r
+       # disable/enable web sites\r
+       a2dissite default\r
+       a2ensite eg.conf\r
+       # restart the server\r
+       /etc/init.d/apache2 reload</userinput>\r
+                                                       </screen>\r
+                                               </step>\r
+                                       </substeps>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-config">\r
+                                       <title>Update the OpenSRF Configuration File</title>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, edit the\r
+                                       OpenSRF configuration file <filename>/openils/conf/opensrf_core.xml</filename>\r
+                                       to update the Jabber usernames and passwords, and to specify the domain from\r
+                                       which we will accept and to which we will make connections.</para>\r
+                                       <para>If you are installing Evergreen on a single server and using the\r
+                                       <systemitem class="domainname">private.localhost</systemitem> / \r
+                                       <systemitem class="domainname">public.localhost</systemitem> domains, \r
+                                       these will already be set to the correct values. Otherwise, search and replace\r
+                                       to match your customized values.</para>\r
+                                       <para>The left-hand side of  <xref linkend="serversideinstallation-xpath-table-2"/>\r
+                                       shows common XPath syntax to indicate the approximate position within the XML\r
+                                       file that needs changes. The right-hand side of the table shows the replacement\r
+                                       values:</para>\r
+                                       <table xml:id="serversideinstallation-xpath-table-2">\r
+                                               <?dbfo keep-together="always" ?>\r
+                                               <title>Sample XPath syntax for editing "opensrf_core.xml"</title>\r
+                                               <tgroup align="left" cols="2" colsep="1" rowsep="1">\r
+                                                       <colspec colname="Xpath" colnum="1" colwidth="1.6*"/>\r
+                                                       <colspec colname="Value" colnum="2" colwidth="2.0*"/>\r
+                                                       <thead>\r
+                                                               <row>\r
+                                                                       <entry>XPath location</entry>\r
+                                                                       <entry>Value</entry>\r
+                                                               </row>\r
+                                                       </thead>\r
+                                                       <tbody>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/opensrf/passwd </entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/username</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">opensrf</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/gateway/passwd</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">opensrf</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username,\r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       first entry where server == public.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">public.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/username,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry>\r
+                                                                               <systemitem class="username">router</systemitem>\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                               <row>\r
+                                                                       <entry>/config/routers/router/transport/password,\r
+                                                                       second entry where server == private.localhost</entry>\r
+                                                                       <entry><systemitem class="domainname">private.localhost</systemitem>\r
+                                                                       password for\r
+                                                                       <systemitem class="username">router</systemitem> user\r
+                                                                       </entry>\r
+                                                               </row>\r
+                                                       </tbody>\r
+                                               </tgroup>\r
+                                       </table>\r
+                               </step>\r
+                               <step performance="optional">\r
+                                       <title>(OPTIONAL) Create Configuration Files for Users Needing <command>srfsh</command></title>\r
+                                       <para>When OpenSRF was installed in <xref linkend="serversideinstallation-opensrf"/>, the\r
+                                       software installation automatically created a utility named <command>srfsh</command> (surf\r
+                                       shell). This is a command line diagnostic tool for testing and interacting with\r
+                                       OpenSRF. It will be used in a future step to complete and test the Evergreen installation.\r
+                                       Earlier in <xref linkend="serversideinstallation-srfsh"/> you also created a configuration \r
+                                       file <filename>~/.srfsh.xml</filename> for each user that might need to use the utility.\r
+                                       See <xref linkend="serversideinstallation-testing"/> for further information.</para>\r
+                               </step>\r
+                               <step xml:id="serversideinstallation-opensrf-env">\r
+                                       <title>Modify the OpenSRF Environment</title>\r
+                                       <para>In this step you will make some minor modifications to the OpenSRF environment:</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       modify the shell configuration file <filename>~/.bashrc</filename> for\r
+                                                       user <systemitem class="username">opensrf</systemitem> by adding a Perl\r
+                                                       environmental variable, then execute the shell configuration file to load\r
+                                                       the new variables into your current environment.</para>\r
+                                                       <note>In a multi-server environment, you must add any\r
+                                                       modifications to <filename>~/.bashrc</filename> to the top of the file\r
+                                                       <emphasis>before</emphasis> the line <literal>[ -z "$PS1" ] &amp;&amp;\r
+                                                       return </literal>. This will allow headless (scripted) logins to load the\r
+                                                       correct environment.</note>\r
+                                                       <screen>\r
+                                                               <userinput>\r
+       # as the opensrf user:\r
+       echo "export PERL5LIB=/openils/lib/perl5:\$PERL5LIB" >> ~/.bashrc\r
+       . ~/.bashrc</userinput>\r
+                                                       </screen>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                               </step>\r
+                               <step performance="optional">\r
+                                       <title>(OPTIONAL) Enable and Disable Language Localizations</title>\r
+                                       <para>You can load translations such as Armenian (hy-AM), Canadian French\r
+                                       (fr-CA), and others into the database to complete the translations available in\r
+                                       the OPAC and Staff Client. For further information, see\r
+                                       <xref linkend="languagesandlocalization"/>.</para>\r
+                               </step>\r
+                       </procedure>\r
+               </section>\r
+               <section xml:id="serversideinstallation-starting">\r
+                       <title>Starting Evergreen</title>\r
+                       <para>In this section you will learn how to start the Evergreen services. \r
+                       For completeness, instructions for stopping Evergreen can be found later in \r
+                       <xref linkend="serversideinstallation-stopping"/>.</para>\r
+                       <procedure>\r
+                               <step>\r
+                                       <para>As the <systemitem class="username">root</systemitem>\r
+                                       user, start the <systemitem class="service">ejabberd</systemitem> and \r
+                                       <systemitem class="service">memcached</systemitem> services as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /etc/init.d/ejabberd start\r
+       /etc/init.d/memcached start</userinput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user,\r
+                                       start Evergreen as follows:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       osrf_ctl.sh -l -a start_all</userinput>\r
+                                       </screen>\r
+                                       <para>The flag <option>-l</option> forces Evergreen to use \r
+                                       <systemitem class="domainname">localhost</systemitem> (your current system) \r
+                                       as the hostname. The flag <option>-a start_all</option>  starts the other \r
+                                       OpenSRF <systemitem class="service">router</systemitem> , \r
+                                       <systemitem class="service">Perl</systemitem> , and\r
+                                       <systemitem class="service">C</systemitem> services.</para>\r
+                                       <itemizedlist>\r
+                                               <listitem>\r
+                                                       <para>You can also start Evergreen without the\r
+                                                       <option>-l</option> flag, but the <command>osrf_ctl.sh</command>\r
+                                                       utility must know the fully qualified domain name for the system\r
+                                                       on which it will execute. That hostname was probably specified\r
+                                                       in the configuration file <filename>opensrf.xml</filename> which\r
+                                                       you configured in a previous step.</para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>If you receive an error message similar to\r
+                                                       <emphasis>osrf_ctl.sh: command not found</emphasis>, then your\r
+                                                       environment variable <envar>PATH</envar> does not include the\r
+                                                       directory <filename class="directory">/openils/bin</filename>.\r
+                                                       As the <systemitem class="username">opensrf</systemitem> user,\r
+                                                       edit the configuration file <filename>~/.bashrc</filename> and\r
+                                                       add the following line: \r
+                                                       <literal>export PATH=$PATH:/openils/bin</literal></para>\r
+                                               </listitem>\r
+                                               <listitem>\r
+                                                       <para>If you receive an error message similar to <emphasis>Can't\r
+                                                       locate OpenSRF/System.pm in @INC ... BEGIN failed--compilation\r
+                                                       aborted</emphasis>, then your environment variable \r
+                                                       <emphasis role="bold">PERL5LIB</emphasis> does not include the \r
+                                                       directory <filename class="directory">/openils/lib/perl5</filename>.\r
+                                                       As the <systemitem class="username">opensrf</systemitem> user, \r
+                                                       edit the configuration file <filename>~/.bashrc</filename> and\r
+                                                       add the following line: \r
+                                                       <literal>export PERL5LIB=$PERL5LIB:/openils/lib/perl5</literal></para>\r
+                                               </listitem>\r
+                                       </itemizedlist>\r
+                               </step>\r
+                               <step>\r
+                                       <para>In this step you will generate the Web files needed by the Staff Client\r
+                                       and catalog, and update the proximity of locations in the Organizational Unit\r
+                                       tree (which allows <emphasis>Holds</emphasis> to work properly).</para>\r
+                                       <para>You must do this the first time you start Evergreen and after making any\r
+                                       changes to the library hierarchy.</para>\r
+                                       <para>As the <systemitem class="username">opensrf</systemitem> user, execute the\r
+                                       following command and review the results:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the opensrf user:\r
+       cd /openils/bin\r
+       ./autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+                                               <computeroutput>\r
+       Updating Evergreen organization tree and IDL using '/openils/conf/opensrf_core.xml'\r
+       Updating fieldmapper\r
+       Updating web_fieldmapper\r
+       Updating OrgTree\r
+       removing OrgTree from the cache for locale hy-AM...\r
+       removing OrgTree from the cache for locale cs-CZ...\r
+       removing OrgTree from the cache for locale en-CA...\r
+       removing OrgTree from the cache for locale en-US...\r
+       removing OrgTree from the cache for locale fr-CA...\r
+       removing OrgTree from the cache for locale ru-RU...\r
+       Updating OrgTree HTML\r
+       Updating locales selection HTML\r
+       Updating Search Groups\r
+       Refreshing proximity of org units\r
+       Successfully updated the organization proximity\r
+       Done</computeroutput>\r
+                                       </screen>\r
+                               </step>\r
+                               <step>\r
+                                       <para>As the <systemitem class="username">root</systemitem> user, restart the\r
+                                       Apache Web server:</para>\r
+                                       <screen>\r
+                                               <userinput>\r
+       # as the root user:\r
+       /etc/init.d/apache2 restart</userinput>\r
+                                       </screen>\r
+                                       <note>If the Apache Web server was running when you started the OpenSRF\r
+                                       services, you might not be able to successfully log into the OPAC or Staff\r
+                                       Client until the Apache Web server has been restarted.</note>\r
+                               </step>\r
+                       </procedure>\r
+               </section>\r
+               <section xml:id="serversideinstallation-testing">\r
+                       <title>Testing Your Evergreen Installation</title>\r
+                       <para>This section describes several simple tests you can perform to verify that the Evergreen\r
+                       server-side software has been installed and configured properly and is running as\r
+                       expected.</para>\r
+                       <simplesect xml:id="serversideinstallation-testing-connections">\r
+                               <title>Testing Connections to Evergreen</title>\r
+                               <para>Once you have installed and started Evergreen, test your connection to Evergreen. Start the\r
+                               <command>srfsh</command> application and try logging onto the Evergreen server using the default\r
+                               administrator username and password. Following is sample output generated by executing\r
+                               <command>srfsh</command> after a successful Evergreen installation. For help with\r
+                               <command>srfsh</command> commands, type <userinput>help</userinput> at the prompt.\r
+                               As the <systemitem class="username">opensrf</systemitem> user,\r
+                               execute the following commands to test your Evergreen connection:</para>\r
+                               <screen>\r
+                                       <userinput>\r
+       # as the opensrf user:\r
+       /openils/bin/srfsh</userinput>\r
+                                       <computeroutput>\r
+       srfsh% <userinput>login admin open-ils</userinput>\r
+       Received Data: "250bf1518c7527a03249858687714376"\r
+       ------------------------------------\r
+       Request Completed Successfully\r
+       Request Time in seconds: 0.045286\r
+       ------------------------------------\r
+       Received Data: {\r
+          "ilsevent":0,\r
+          "textcode":"SUCCESS",\r
+          "desc":" ",\r
+          "pid":21616,\r
+          "stacktrace":"oils_auth.c:304",\r
+          "payload":{\r
+             "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",\r
+             "authtime":420\r
+          }\r
+       }\r
+       ------------------------------------\r
+       Request Completed Successfully\r
+       Request Time in seconds: 1.336568\r
+       ------------------------------------</computeroutput>\r
+                               </screen>\r
+                               <para>If this does not work, try the following:</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <para>As the <systemitem class="username">opensrf</systemitem> user, run the\r
+                                               <filename>settings-tester.pl</filename> utility to review your Evergreen\r
+                                               installation for any system configuration problems:</para>\r
+                                               <screen>\r
+                                                       <userinput>\r
+       # as the opensrf user:\r
+       cd /home/opensrf\r
+       ./Evergreen-ILS-2.0.1/Open-ILS/src/support-scripts/settings-tester.pl</userinput>\r
+                                               </screen>\r
+                                               <para>If the output of <command>settings-tester.pl</command> does not help you\r
+                                               find the problem, please do not make any significant changes to your\r
+                                               configuration.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para>Follow the steps in the troubleshooting guide in \r
+                                               <xref linkend="troubleshooting"/>.</para>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <para>If you have followed the entire set of installation steps listed here\r
+                                               closely, you are probably extremely close to a working system. Gather your\r
+                                               configuration files and log files and contact the \r
+                                               <ulink url="http://open-ils.org/listserv.php">Evergreen Development Mailing List</ulink>\r
+                                               list for assistance before making any drastic changes to your system\r
+                                               configuration.</para>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                       </simplesect>\r
+                       <simplesect xml:id="serversideinstallation-running-staffclient">\r
+                               <title>Testing the Staff Client on Linux</title>\r
+                               <para>In this section you will confirm that a basic login on the Staff Client works\r
+                               properly.</para>\r
+                               <para>Run the Evergreen Staff Client on a Linux system by using the application\r
+                               <emphasis>XULRunner</emphasis> (installed automatically and by default with Firefox\r
+                               version 3.0 and later on Ubuntu and Debian distributions).</para>\r
+                               <para>As the <systemitem class="username">root</systemitem> user, start the Staff Client\r
+                               as shown:</para>\r
+                               <screen>\r
+                                       <userinput>\r
+       # as the root user:\r
+       xulrunner /home/opensrf/Evergreen-ILS-2.0.1/Open-ILS/xul/staff_client/build/application.ini</userinput>\r
+                               </screen>\r
+                               <para>A login screen for the Staff Client similar to this should appear:</para>\r
+                               <mediaobject>\r
+                                       <alt>Logging into the Staff Client</alt>\r
+                                       <imageobject>\r
+                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-1.png" format="PNG" scalefit="1" width="70%"/>\r
+                                       </imageobject>\r
+                               </mediaobject>\r
+                               <para>First, add the name of your Evergreen server to the field\r
+                               <literal>Hostname</literal> in the <literal>Server</literal> section. You will probably\r
+                               want to use <literal>127.0.0.1</literal>. After adding the server name, click Re-Test\r
+                               Server. You should now see the messages <literal>200:OK</literal> in the fields\r
+                               <literal>Status</literal> and <literal>Version</literal>.</para>\r
+                               <para>Because this is the initial run of the Staff Client, you will see a warning in the\r
+                               upper-right saying: <emphasis role="bold">Not yet configured for the specified\r
+                               server</emphasis>. To continue, you must assign a workstation name. Refer to\r
+                               <xref linkend="staffclientinstallation-workstationnames"/> for further details.</para>\r
+                               <para>Try to log into the Staff Client with the username <literal>admin</literal> and\r
+                               the password <literal>open-ils</literal>. If the login is successful, you will see the\r
+                               following screen:</para>\r
+                               <mediaobject>\r
+                                       <alt>Logging into the Staff Client</alt>\r
+                                       <imageobject>\r
+                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-4.png" format="PNG" scalefit="1" width="70%"/>\r
+                                       </imageobject>\r
+                               </mediaobject>\r
+                               <para>Otherwise, you may need to click <guibutton>'Add SSL Exception'</guibutton> in the\r
+                               main window. You should see a popup window titled <literal>Add Security Exception</literal>:</para>\r
+                               <mediaobject>\r
+                                       <alt>Adding an SSL Exception in the Staff Client</alt>\r
+                                       <imageobject>\r
+                                               <imagedata fileref="../media/serversideinstallation-staffclient-running-2.png" format="PNG" scalefit="1" width="70%"/>\r
+                                       </imageobject>\r
+                               </mediaobject>\r
+                               <para>Click <guibutton>'Get Certificate'</guibutton>, then click <guibutton>'Confirm\r
+                               Security Exception'</guibutton>, then click <guibutton>'Re-Test Server'</guibutton> in the\r
+                               main window and try to log in again.</para>\r
+                       </simplesect>\r
+                       <simplesect xml:id="serversideinstallation-starting-apache-server">\r
+                               <title>Testing the Apache Web Server</title>\r
+                               <para>In this section you will test the Apache configuration file(s), then restart the\r
+                               Apache web server.</para>\r
+                               <para>As the <emphasis role="bold">root</emphasis> user, execute the following\r
+                               commands. Note the use of <emphasis>restart</emphasis> to force the new Evergreen\r
+                               modules to be reloaded even if the Apache server is already running. Any problems found\r
+                               with your configuration files should be displayed:</para>\r
+                               <screen>\r
+                                       <userinput>\r
+       # as the root user:\r
+       apache2ctl configtest &amp;&amp; /etc/init.d/apache2 restart</userinput>\r
+                               </screen>\r
+                       </simplesect>\r
+                       <simplesect xml:id="serversideinstallation-stopping">\r
+                               <title>Stopping Evergreen</title>\r
+                               <para>In <xref linkend="serversideinstallation-starting"/> you learned how to start the\r
+                               Evergreen services. For completeness, following are instructions for stopping the\r
+                               Evergreen services.</para>\r
+                               <para>As the <systemitem class="username">opensrf</systemitem> user, stop all Evergreen\r
+                               services by using the following command:</para>\r
+                               <screen>\r
+                                       <userinput>\r
+       # as the opensrf user\r
+       #   stop the server; use "-l" to force hostname to be "localhost"\r
+       osrf_ctl.sh -l -a stop_all</userinput>\r
+                               </screen>\r
+                               <note>You can also stop Evergreen services <emphasis role="bold">without</emphasis> the\r
+                               <option>-l</option> flag, but the <command>osrf_ctl.sh</command> utility must know the\r
+                               fully qualified domain name for the system on which it will execute. That hostname may\r
+                               have been specified in the configuration file <filename>opensrf.xml</filename>, which\r
+                               you configured in a previous step.</note>\r
+                       </simplesect>\r
+               </section>\r
+               <section xml:id="serversideinstallation-postinstallation">\r
+                       <title>Post-Installation Chores</title>\r
+                       <para>There are several additional steps you may need to complete after Evergreen has been\r
+                       successfully installed and tested. Some steps may not be needed (e.g., setting up support for\r
+                       Reports).</para>\r
+                       <section>\r
+                               <title>Remove temporary Apache configuration changes</title>\r
+                               <para>You modified the Apache configuration file\r
+                               <filename>/etc/apache2/sites-available/eg.conf</filename> in an earlier step as a\r
+                               temporary measure to expedite testing (see \r
+                               <xref linkend="serversideinstallation-modify-apache"/> for further information).\r
+                               Those changes must now be reversed in order to deny unwanted access to your \r
+                               CGI scripts from users on other public networks.</para>\r
+                               <warning>\r
+                                       <para>\r
+                                               <emphasis>This temporary network update was done to expedite\r
+                                               testing. You <emphasis role="bold">must</emphasis> correct\r
+                                               this for a public production system.</emphasis>\r
+                                       </para>\r
+                               </warning>\r
+                               <para>As the <systemitem class="username">root</systemitem> user, edit the configuration\r
+                               file again and comment out the line <literal>Allow from all</literal> and uncomment the\r
+                               line <literal>Allow from 10.0.0.0/8</literal>, then change it to match your network\r
+                               address scheme.</para>\r
+                       </section>\r
+                       <section xml:id="serversideinstallation-ssl">\r
+                               <title>Configure a permanent SSL key</title>\r
+                               <para>You used the command <command>openssl</command> in an earlier step to\r
+                               temporarily create a new SSL key for the Apache server (see \r
+                               <xref linkend="serversideinstallation-createsslcertificate"/> for further\r
+                               information). This self-signed security certificate was adequate during\r
+                               testing and development, but will continue to generate warnings in the Staff\r
+                               Client and browser. For a public production server you should configure or\r
+                               purchase a signed SSL certificate.</para>\r
+                               <para>There are several open source software solutions that provide schemes to\r
+                               generate and maintain public key security certificates for your library\r
+                               system. Some popular projects are listed below; please review them for\r
+                               background information on why you need such a system and how you can provide\r
+                               it:</para>\r
+                               <itemizedlist>\r
+                                       <listitem>\r
+                                               <ulink url="http://www.openca.org/projects/openca/">http://www.openca.org/projects/openca/</ulink>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <ulink url="http://sourceforge.net/projects/ejbca/">http://sourceforge.net/projects/ejbca/</ulink>\r
+                                       </listitem>\r
+                                       <listitem>\r
+                                               <ulink url="http://pki.fedoraproject.org">http://pki.fedoraproject.org</ulink>\r
+                                       </listitem>\r
+                               </itemizedlist>\r
+                               <warning>\r
+                                       <para>\r
+                                               <emphasis>The temporary SSL key was only created to expedite\r
+                                               testing. You should install a proper SSL certificate for a public\r
+                                               production system.</emphasis>\r
+                                       </para>\r
+                               </warning>\r
+                       </section>\r
+                       <section>\r
+                               <title>(OPTIONAL) IP-Redirection</title>\r
+                               <para>By default, Evergreen is configured so searching the OPAC always starts in the\r
+                               top-level (regional) library rather than in a second-level (branch) library. Instead,\r
+                               you can use "IP-Redirection" to change the default OPAC search location to use the IP\r
+                               address range assigned to the second-level library where the seach originates. You must\r
+                               configure these IP ranges by creating the configuration file\r
+                               <filename>/openils/conf/lib_ips.txt</filename> and modifying the Apache startup script\r
+                               <filename>/etc/apache2/startup.pl</filename>.</para>\r
+                               <para>First, copy the sample file\r
+                               <filename>/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/examples/lib_ips.txt.example</filename>\r
+                               to <filename>/openils/conf/lib_ips.txt</filename>. The example file contains the single\r
+                               line: <literal>"MY-LIB 127.0.0.1 127.0.0.254"</literal>. You must modify the file to use\r
+                               the IP address ranges for your library system. Add new lines to represent the IP address\r
+                               range for each branch library. Replace the values for <literal>MY-LIB</literal> with the\r
+                               values for each branch library found in the table\r
+                               <literal>actor.org_unit</literal>.</para>\r
+                               <para>Finally, modify the Apache startup script\r
+                               <filename>/etc/apache2/startup.pl</filename> by uncommenting two lines as shown, then\r
+                               restarting the Apache server:</para>\r
+                               <programlisting language="xml"><![CDATA[\r
+# - Uncomment the following 2 lines to make use of the IP redirection code\r
+# - The IP file should contain a map with the following format:\r
+# - actor.org_unit.shortname <start_ip> <end_ip>\r
+# - e.g.  LIB123 10.0.0.1 10.0.0.254\r
+use OpenILS::WWW::Redirect qw(/openils/conf/opensrf_core.xml);\r
+OpenILS::WWW::Redirect->parse_ips_file('/openils/conf/lib_ips.txt');\r
+]]></programlisting>\r
+                       </section>\r
+                       <section>\r
+                               <title>(OPTIONAL) Set Up Support For Reports</title>\r
+                               <para>Evergreen reports are extremely powerful but require some simple configuration.\r
+                               See <xref linkend="report_starting_reporter_service"/> for information on starting and\r
+                               stopping the Reporter daemon processes.</para>\r
+                       </section>\r
+               </section>\r
+       </section>\r
+</chapter>\r
diff --git a/2.0/admin/sip.xml b/2.0/admin/sip.xml
new file mode 100644 (file)
index 0000000..7f670c9
--- /dev/null
@@ -0,0 +1,595 @@
+<?xml version="1.0" encoding="utf-8"?>\r
+<chapter xml:id="sipserver" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
+       <info>\r
+               <title>SIP Server</title>\r
+       </info>\r
+       <para><systemitem class="protocol">SIP</systemitem>, standing for <systemitem class="protocol">Standard Interchange Protocol</systemitem>, was developed by the \r
+       <orgname class="corporation">3M</orgname>corporation to be a common protocol for data transfer between ILS' \r
+       (referred to in <systemitem class="protocol">SIP</systemitem> as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>)\r
+       <indexterm><primary>Automated Circulation System</primary></indexterm> and a \r
+       third party device. Originally, the protocol was developed for \r
+       use with 3M SelfCheck (often abbreviated SC, not to be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common to find \r
+       <systemitem class="protocol">SIP</systemitem> in use in several other vendors' SelfCheck systems<indexterm><primary>SelfCheck</primary></indexterm>, as well as other non-SelfCheck devices. \r
+       Some examples include:</para>\r
+       <itemizedlist>\r
+               <listitem>Patron Authentication (computer access, subscription databases)</listitem>\r
+               <listitem>Automated Material Handling (AMH) <indexterm><primary>Automated Material Handling (AMH)</primary></indexterm>- The automated sorting of items, often to bins or \r
+               book carts, based on shelving location or other programmable criteria</listitem>\r
+       </itemizedlist>\r
+   \r
+       <section xml:id="Installing_SIP_Server">\r
+               <info>\r
+               <title>Installing the <systemitem class="protocol">SIP</systemitem> Server</title>\r
+               </info>\r
+                 <para>This is a rough intro to installing the <systemitem class="protocol">SIP</systemitem> server for Evergreen.</para>\r
+               <simplesect xml:id="Gettingthecode">\r
+                           <title>Getting the code</title>\r
+                               <para>Current <systemitem class="protocol">SIP</systemitem> code lives at github:</para>\r
+                               <screen><userinput>cd /opt</userinput></screen>\r
+                               <screen><userinput>git clone git://github.com/atz/SIPServer.git SIPServer</userinput></screen>\r
+                               <para>Or use the old style:</para>\r
+                               <screen><userinput>$ cd /opt</userinput></screen>\r
+                               <screen><userinput>$ sudo cvs -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip login</userinput></screen>\r
+                               <para>When prompted for the CVS password, just hit Enter (sudo password may be req'd)</para>\r
+                               <screen><userinput>$ sudo cvs -z3 -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip co -P SIPServer</userinput></screen>\r
+                                                        \r
+               </simplesect>\r
+               <simplesect xml:id="Configuring_Server">\r
+                       <title>Configuring the Server</title>\r
+                       <procedure>\r
+                       <step>\r
+                               <para>Type the following commands from the command prompt:</para><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>\r
+                               <screen><userinput>$ sudo su opensrf</userinput></screen>\r
+                               <screen><userinput>$ cd /openils/conf</userinput></screen>\r
+                               <screen><userinput>$ cp oils_sip.xml.example oils_sip.xml</userinput></screen>\r
+                       </step>\r
+                       <step>\r
+                               <para>Edit <filename>oils_sip.xml</filename><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>. \r
+                               Change the commented out &lt;server-params&gt; section to this:</para>\r
+<programlisting>\r
+&lt;server-params\r
+min_servers='1'\r
+min_spare_servers='0'\r
+max_servers='25'\r
+/&gt;\r
+</programlisting>\r
+                       </step>\r
+                       <step>\r
+                               <para> max_servers will directly correspond to the number of allowed <systemitem class="protocol">SIP</systemitem> clients. Set the number accordingly, but \r
+                               bear in mind that too many connections can \r
+                               exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), it is not recommended to exceed 100 \r
+                               <systemitem class="protocol">SIP</systemitem> client connections.</para>                                \r
+                       </step>\r
+                       </procedure>             \r
+               </simplesect>\r
+               <simplesect xml:id="Adding_SIP_users">\r
+                       <title>Adding <systemitem class="protocol">SIP</systemitem> Users</title>\r
+                       <procedure>\r
+                               <step>\r
+                                       <para>Type the following commands from the command prompt:</para><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>\r
+                                       <screen><userinput>$ sudo su opensrf</userinput></screen>\r
+                                       <screen><userinput>$ cd /openils/conf</userinput></screen>\r
+                                       <screen><userinput>$ cp oils_sip.xml.example oils_sip.xml</userinput></screen>\r
+                               </step>\r
+                               <step>\r
+                                       <para> in the &lt;accounts&gt; section, add <systemitem class="protocol">SIP</systemitem> client login information. Make sure that all \r
+                                       <varname>&lt;logins&gt;</varname> use the same institution attribute, and make \r
+                                       sure the institution is listed in <varname>&lt;institutions&gt;</varname>. All attributes in the <varname>&lt;login&gt;</varname> section will be \r
+                                       used by the <systemitem class="protocol">SIP</systemitem> client.</para>\r
+                               \r
+                               </step>\r
+                               <step>\r
+                                       <para> In Evergreen, create a new profile group called <systemitem class="groupname">SIP</systemitem>. \r
+                                       This group should be a sub-group of <systemitem class="groupname">Users</systemitem> \r
+                                       (not <systemitem class="groupname">Staff</systemitem> or <systemitem class="groupname">Patrons</systemitem>). \r
+                                       Set Editing Permission as <emphasis role="bold">group_application.user.sip_client</emphasis> and give the group the following permissions:</para>\r
+                                       <literallayout>\r
+                                       COPY_CHECKIN\r
+                                       COPY_CHECKOUT\r
+                                       RENEW_CIRC      \r
+                                       VIEW_CIRCULATIONS\r
+                                       VIEW_COPY_CHECKOUT_HISTORY      \r
+                                       VIEW_PERMIT_CHECKOUT\r
+                                       VIEW_USER\r
+                                       VIEW_USER_FINES_SUMMARY\r
+                                       VIEW_USER_TRANSACTIONS\r
+                                       </literallayout>\r
+                                       <para>OR use SQL like:</para>\r
+<screen>\r
+<userinput>\r
+INSERT INTO permission.grp_tree (id,name,parent,description,application_perm)\r
+VALUES (8, 'SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');\r
+\r
+INSERT INTO permission.grp_perm_map (grp,perm,depth) \r
+VALUES (8,15,0),(8,16,0),(8,17,0),(8,31,0),(8,32,0),(8,48,0),(8,54,0),(8,75,0),(8,82,0);\r
+</userinput>\r
+</screen>\r
+                                       \r
+                                       <para>Verify:</para>\r
+<screen>\r
+<userinput>\r
+SELECT *\r
+FROM permission.grp_perm_map JOIN permission.perm_list ON\r
+permission.grp_perm_map.perm=permission.perm_list.id\r
+WHERE grp=8;\r
+</userinput>\r
+</screen>\r
+                                       \r
+                                       <para>Keep in mind that the id <emphasis role="bold">(8)</emphasis> may not necessarily be available on your system.</para>                             \r
+                               </step>\r
+                               <step>\r
+                                       <para>For each account created in the &lt;login&gt; section of <filename>oils_sip.xml</filename>, create a user (via the staff client user editor) \r
+                                       that has the same username \r
+                                       and password and put that user into the <systemitem class="groupname">SIP</systemitem> group.</para>\r
+                                       <note><para>The expiration date will affect the <systemitem class="groupname">SIP</systemitem> users' connection so you might want to make a note of \r
+                                       this somewhere.</para></note>   \r
+                               </step>\r
+                       </procedure>             \r
+               </simplesect>\r
+               <simplesect xml:id="Running_SIP_server">\r
+                       <title>Running the server</title>\r
+                               <para>To start the <systemitem class="protocol">SIP</systemitem> server type the following commands from the command prompt:</para>\r
+                               <screen><userinput>$ sudo su opensrf</userinput></screen>\r
+                               <screen><userinput>$ oils_ctl.sh -d /openils/var/run -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip</userinput></screen>     \r
+               </simplesect>\r
+               <simplesect xml:id="Logging-SIP">\r
+                       <title>Logging-SIP</title><indexterm><primary>SIP</primary></indexterm>\r
+                       <simplesect>\r
+                               <title><systemitem class="service">Syslog</systemitem></title>\r
+                               <para>It is useful to log <systemitem class="protocol">SIP</systemitem> requests to a separate file especially during initial setup by modifying your \r
+                               syslog config file.</para><indexterm><primary>syslog</primary></indexterm>\r
+                               <procedure>\r
+                                       <step>\r
+                                               <para>Edit syslog.conf.</para>\r
+                                               <screen><userinput>$ sudo vi /etc/syslog.conf  # maybe /etc/rsyslog.conf</userinput></screen>   \r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Add this:</para>\r
+                                               <programlisting>local6.*                -/var/log/SIP_evergreen.log</programlisting>    \r
+                                       </step>\r
+                                       <step>\r
+                                               <para><systemitem class="service">Syslog</systemitem> expects the logfile to exist so create the file.</para>\r
+                                               <screen><userinput>$ sudo touch /var/log/SIP_evergreen.log</userinput></screen> \r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Restart <systemitem class="service">sysklogd</systemitem>.</para>\r
+                                               <screen><userinput>$ sudo /etc/init.d/sysklogd restart</userinput></screen>     \r
+                                       </step>\r
+                               </procedure>            \r
+                       </simplesect>\r
+                       <simplesect>\r
+                               <title><systemitem class="service">Syslog-NG</systemitem></title>\r
+                               \r
+                               <procedure>\r
+                                       <step>\r
+                                               <para>Edit logging config.</para><indexterm><primary>syslog-NG</primary></indexterm>\r
+                                               <screen><userinput>sudo vi /etc/syslog-ng/syslog-ng.conf</userinput></screen>   \r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Add:</para>\r
+<programlisting>\r
+# SIP2 for Evergreen\r
+filter    f_eg_sip { level(warn, err, crit) and facility(local6); };\r
+destination eg_sip { file("/var/log/SIP_evergreen.log"); };\r
+log { source(s_all); filter(f_eg_sip); destination(eg_sip); };\r
+</programlisting>      \r
+                                       </step>\r
+                                       <step>\r
+                                               <para><systemitem class="service">Syslog-ng</systemitem> expects the logfile to exist so create the file.</para>\r
+                                               <screen><userinput>$ sudo touch /var/log/SIP_evergreen.log</userinput></screen> \r
+                                       </step>\r
+                                       <step>\r
+                                               <para>Restart <systemitem class="service">syslog-ng</systemitem></para>\r
+                                               <screen><userinput>$ sudo /etc/init.d/syslog-ng restart</userinput></screen>    \r
+                                       </step>\r
+                               </procedure>            \r
+                       </simplesect>\r
+               </simplesect>   \r
+               <simplesect xml:id="Testing_SIP_Connection">\r
+                       <title>Testing Your <systemitem class="protocol">SIP</systemitem> Connection</title><indexterm><primary>SIP</primary></indexterm>\r
+                       <itemizedlist>\r
+                               <listitem>\r
+                                       <para>In the top level CVS checkout of the SIPServer code.</para>\r
+                                       <screen><userinput>$ cd SIPServer/t</userinput></screen>\r
+                               </listitem>\r
+                               <listitem>\r
+                                       <para> Edit <filename>SIPtest.pm</filename>, change the <varname>$instid</varname>, <varname>$server</varname>, <varname>$username</varname>, and \r
+                                       <varname>$password</varname> variables. This will be enough to test connectivity. \r
+                                       To run all tests, you'll need to change all the variables in the Configuration section.</para>\r
+                                       <screen><userinput>$ PERL5LIB=../ perl 00sc_status.t</userinput></screen>\r
+                                       <para>This should produce something like:</para>\r
+<screen>\r
+1..4\r
+ok 1 - Invalid username\r
+ok 2 - Invalid username\r
+ok 3 - login\r
+ok 4 - SC status\r
+</screen>\r
+                               </listitem>     \r
+                               <listitem>\r
+                                       <para> Don't be dismayed at <emphasis role="bold">Invalid Username</emphasis>. That's just one of the many tests that are run.</para>\r
+                               </listitem>                                             \r
+                       </itemizedlist>\r
+               </simplesect>\r
+               <simplesect xml:id="SIP-More_Testing">\r
+                       <title>More Testing</title>\r
+                       <procedure>\r
+                               <step>\r
+                                       <para>Once you have opened up either the <systemitem class="protocol">SIP</systemitem> OR <systemitem class="protocol">SIP2</systemitem> ports to be \r
+                                       accessible from outside you can do some testing via <systemitem class="protocol">telnet</systemitem>. You can try this with localhost \r
+                                       if you so wish, but we want to prove that <systemitem class="protocol">SIP2</systemitem> works from non-localhost. \r
+                                       Replace <varname>$instid</varname>, <varname>$server</varname>, <varname>$barcode</varname>, <varname>$username</varname>, \r
+                                       and <varname>$password</varname> variables below as necessary.</para>\r
+                                       <note><para>We are using <systemitem>6001</systemitem> here which is associated with <systemitem class="protocol">SIP2</systemitem> as per our configuration.</para></note><indexterm><primary>telnet</primary></indexterm>\r
+<screen>\r
+<userinput>$ telnet $server 6001</userinput>\r
+Connected to $server.\r
+Escape character is '^]'.\r
+<userinput>9300CN**$username**|CO**$password**|CP**$instid**</userinput>\r
+</screen>                                      \r
+                                       <para>You should get back.</para>\r
+                                       <screen>941</screen>\r
+                               </step>\r
+                               <step>\r
+                                       <para>Now just copy in the following line (with variables replaced) you don't need to hit enter, just paste!</para>\r
+                                       <screen>2300120080623    172148AO**$instid**|AA**$barcode**|AC$password|AD**$password**</screen>\r
+                                       <para>You will get back the patron information for $barcode (something similar to the what's below).</para>\r
+<screen>24  Y           00120100113    170738AEFirstName MiddleName LastName|AA**$barcode**|BLY|CQY\r
+|BHUSD|BV0.00|AFOK|AO**$instid**|\r
+</screen>\r
+                                       <para>The response declares it is a valid patron <varname>BLY</varname> with a valid password <varname>CQY</varname> and shows the user's \r
+                                       <varname>$name</varname>.</para>\r
+                               </step>\r
+                       </procedure>\r
+               </simplesect>\r
+       </section>\r
+       <section xml:id="SIP_Communication">\r
+               <info>\r
+                       <title><systemitem class="protocol">SIP</systemitem> Communication</title><indexterm><primary>SIP</primary></indexterm>\r
+               </info>\r
+               <para><systemitem class="protocol">SIP</systemitem> generally communicates over a <systemitem class="protocol">TCP</systemitem> connection (either raw sockets or over \r
+               <systemitem class="protocol">telnet</systemitem>), but can also communicate via serial connections and other methods. In Evergreen, \r
+               the most common deployment is a <systemitem class="protocol">RAW</systemitem> socket connection on port <systemitem>6001</systemitem>.</para>\r
+               <para><systemitem class="protocol">SIP</systemitem> communication consists of strings of messages, each message request and response begin with a 2-digit \r
+               <quote>command</quote> - Requests usually being an odd \r
+               number and responses usually increased by 1 to be an even number. The combination numbers for the request command and response is often referred to as a \r
+               <emphasis>Message Pair</emphasis> (for example, a 23 command is a request for patron status, a 24 response is a patron status, and the message pair 23/24 is \r
+               patron status message pair). The table in the next section shows the message pairs and a description of them.</para>\r
+               <para>For clarification, the <quote>Request</quote> is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the response \r
+               to the request ;).</para>\r
+               <para>Within each request and response, a number of fields (either a fixed width or separated with a <emphasis role="bold">|</emphasis> [pipe symbol] and preceeded with a \r
+               2-character field identifier) \r
+               are used. The fields vary between message pairs.</para>\r
+               <informaltable>\r
+                       <tgroup cols="4">\r
+                               <colspec colnum="1" colname="pair" colwidth="0.5*"/>\r
+                               <colspec colnum="2" colname="name" colwidth="1.0*"/>\r
+                               <colspec colnum="3" colname="supported" colwidth="1.0*"/>\r
+                               <colspec colnum="4" colname="details" colwidth="3.0*"/>\r
+                               <thead>\r
+                                       <row>\r
+                                               <entry>Pair</entry>\r
+                                               <entry>Name</entry>\r
+                                               <entry>Supported?</entry>\r
+                                               <entry>Details</entry>\r
+                                       </row>\r
+                               </thead>\r
+                               <tbody>\r
+                                       <row>\r
+                                               <entry>01</entry>\r
+                                               <entry>Block Patron</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_Block_Patron'>01_Block_Patron</link> - ACS responds with 24 Patron Status Response</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>09/10</entry>\r
+                                               <entry>Checkin</entry>\r
+                                               <entry>Yes (with extensions)</entry>\r
+                                               <entry><link linkend='SIP_Checkin'>09/10_Checkin</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>11/12</entry>\r
+                                               <entry>Checkout</entry>\r
+                                               <entry>Yes (no renewals)</entry>\r
+                                               <entry><link linkend='SIP_Checkout'>11/12_Checkout</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>15/16</entry>\r
+                                               <entry>Hold</entry>\r
+                                               <entry>No</entry>\r
+                                               <entry><link linkend='SIP_Hold'>15/16_Hold</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>17/18</entry>\r
+                                               <entry>Item Information</entry>\r
+                                               <entry>Yes (no extensions)</entry>\r
+                                               <entry><link linkend='SIP_Item_Information'>17/18_Item_Information</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>19/20</entry>\r
+                                               <entry>Item Status Update</entry>\r
+                                               <entry>No</entry>\r
+                                               <entry><link linkend='SIP_Item_Status_Update'>19/20_Item_Status_Update</link> - Returns Patron Enable response, but doesn't make any changes in EG</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>23/24</entry>\r
+                                               <entry>Patron Status</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_Patron_Status'>23/24_Patron_Status</link> - 63/64 <quote>Patron Information</quote> preferred</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>25/26</entry>\r
+                                               <entry>Patron Enable</entry>\r
+                                               <entry>No</entry>\r
+                                               <entry><link linkend='SIP_Patron_Enable'>25/26_Patron_Enable</link> - Used during system testing and validation</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>29/30</entry>\r
+                                               <entry>Renew</entry>\r
+                                               <entry>NO (maybe?)</entry>\r
+                                               <entry><link linkend='SIP_Renew'>29/30_Renew</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>35/36</entry>\r
+                                               <entry>End Session</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_End_Session'>35/36_End_Session</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>37/38</entry>\r
+                                               <entry>Fee Paid</entry>\r
+                                               <entry>No</entry>\r
+                                               <entry><link linkend='SIP_Fee_Paid'>37/38_Fee_Paid</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>63/64</entry>\r
+                                               <entry>Patron Information</entry>\r
+                                               <entry>Yes (no extensions)</entry>\r
+                                               <entry><link linkend='SIP_Patron_Information'>63/64_Patron_Information</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>65/66</entry>\r
+                                               <entry>Renew All</entry>\r
+                                               <entry>No</entry>\r
+                                               <entry><link linkend='SIP_Renew_All'>65/66_Renew_All</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>93/94</entry>\r
+                                               <entry>Login</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or <systemitem class="protocol">SIP</systemitem> will terminate</entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>97/96</entry>\r
+                                               <entry>Resend last message</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_Resend'>97/96_Resend</link></entry>\r
+                                       </row>\r
+                                       <row>\r
+                                               <entry>99/98</entry>\r
+                                               <entry>SC/ACS Status</entry>\r
+                                               <entry>Yes</entry>\r
+                                               <entry><link linkend='SIP_SC_ACS_Status'>99/98_SC_and_ACS_Status</link></entry>\r
+                                       </row>\r
+                               </tbody>\r
+                       </tgroup>\r
+               </informaltable>\r
+               <simplesect xml:id="SIP_Block_Patron">\r
+                       <title>01 Block Patron</title>\r
+                       <para>A selfcheck will issue a <command>Block Patron</command> command if a patron leaves their card in a selfcheck machine or if the selfcheck detects tampering (such as attempts \r
+                       to disable multiple items during a single item checkout, multiple failed pin entries, etc).</para><indexterm><primary>SelfCheck</primary></indexterm>\r
+                       <para>In Evergreen, this command does the following:</para>\r
+                               <itemizedlist>\r
+                                       <listitem>User alert message: <emphasis>CARD BLOCKED BY SELF-CHECK MACHINE</emphasis> (this is independent of the AL \r
+                                       <emphasis>Blocked Card Message</emphasis> field).</listitem>\r
+                                       <listitem>Card is marked inactive.</listitem>\r
+                               </itemizedlist>\r
+                       <para>The request looks like:</para>\r
+                       <screen>01&lt;card retained&gt;&lt;date&gt;[fields AO, AL, AA, AC]</screen>\r
+                       <para><emphasis>Card Retained</emphasis>: A single character field of <emphasis>Y</emphasis> or <emphasis>N</emphasis> - tells the ACS whether the SC has \r
+                       retained the card (ex: left in the machine) or not.</para> \r
+                       <para><emphasis>Date</emphasis>: An 18 character field for the date/time when the block occurred.</para> \r
+                       <para><emphasis>Format</emphasis>: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, <quote> Z</quote> (3 blanks and a Z) represents UTC(GMT/Zulu)</para>\r
+                       <para><emphasis>Fields</emphasis>: See <link linkend='SIP_Fields'>Fields</link> for more details.</para>\r
+                       <para>The response is a 24 <quote>Patron Status Response</quote> with the following:</para>\r
+                       <itemizedlist>\r
+                                       <listitem>Charge privileges denied</listitem>\r
+                                       <listitem>Renewal privileges denied</listitem>\r
+                                       <listitem>Recall privileges denied (hard-coded in every 24 or 64 response)</listitem>\r
+                                       <listitem>hold privileges denied</listitem>\r
+                                       <listitem>Screen Message 1 (AF): <emphasis>blocked</emphasis></listitem>\r
+                                       <listitem>Patron</listitem>\r
+\r
+                       </itemizedlist>\r
+               </simplesect>\r
+               <simplesect xml:id="SIP_Checkin">\r
+                       <title>09/10 Checkin</title>\r
+                       <para>The request looks like:</para>\r
+                       <screen>09&lt;No block (Offline)&gt;&lt;xact date&gt;&lt;return date&gt;[Fields AP,AO,AB,AC,CH,BI]</screen>\r
+                       <para><emphasis>No Block (Offline)</emphasis>: A single character field of <emphasis>Y</emphasis> or <emphasis>N</emphasis> - Offline transactions are not currently \r
+                       supported so send <emphasis>N</emphasis>.</para> \r
+                       <para><emphasis>xact date</emphasis>: an 18 character field for the date/time when the checkin occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - \r
+                       4 blanks when local time, <quote> Z</quote> (3 blanks and a Z) represents UTC(GMT/Zulu)</para> \r
+                       <para><emphasis>Fields</emphasis>: See <link linkend='SIP_Fields'>Fields</link> for more details.</para>\r
+                       <para>The response is a 10 <quote>Checkin Response</quote> with the following:</para>\r
+                       <screen>10&lt;resensitize>&lt;magnetic media&gt;&lt;alert&gt;&lt;xact date&gt;[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG]</screen>\r
+                       <para>Example (with a remote hold):</para>\r
+                       <screen>09N20100507    16593720100507    165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|</screen>\r
+<screen>\r
+101YNY20100623    165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996\r
+|CTBR3|CY373827|DANicholas Richard Woodard|CV02|\r
+</screen>\r
+                       <para>Here you can see a hold alert for patron <varname>CY</varname> <emphasis>373827</emphasis>, named <varname>DA</varname> <emphasis>Nicholas Richard Woodard</emphasis>, \r
+                       to be picked up at <varname>CT</varname> <quote>BR3</quote>. Since the transaction is happening \r
+                       at <varname>AO</varname> <quote>BR1</quote>, the alert type <varname>CV</varname> is 02 for <emphasis>hold at remote library</emphasis>. \r
+                       The possible values for <varname>CV</varname> are:</para>\r
+                       <itemizedlist>\r
+                                       <listitem>00: unknown</listitem>\r
+                                       <listitem>01: local hold</listitem>\r
+                                       <listitem>02: remote hold</listitem>\r
+                                       <listitem>03: ILL transfer (not used by EG)</listitem>\r
+                                       <listitem>04: transfer</listitem>\r
+                                       <listitem>99: other</listitem>\r
+                       </itemizedlist>\r
+                       <note>\r
+                               <para>the logic for Evergreen to determine the content is magnetic_media comes from either legacy circ scripts or search_config_circ_modifier. \r
+                               The default is non-magnetic.<indexterm><primary>magnetic media</primary></indexterm> \r
+                               The same is true for media_type (default 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide the \r
+                               call_number where available.</para>\r
+                               <para>Unlike the <varname>item_id</varname> (barcode), the <varname>title_id</varname> is actually a title string, unless the configuration forces the return of \r
+                               the bib ID.</para>\r
+                               <para>Don't be confused by the different branches that can show up in the same response line.</para>\r
+                               <itemizedlist>\r
+                                       <listitem><varname>AO</varname> is where the transaction took place,</listitem>\r
+                                       <listitem><varname>AQ</varname> is the <quote>permanent location</quote>, and</listitem>\r
+                                       <listitem><varname>CT</varname> is the <emphasis>destination location</emphasis> (i.e., pickup lib for a hold or target lib for a transfer).</listitem>\r
+                               </itemizedlist>\r
+                       </note>\r
+               </simplesect>\r
+        &nbs