First checkin

git-svn-id: https://oreka.svn.sourceforge.net/svnroot/oreka/trunk@200 09dcff7a-b715-0410-9601-b79a96267cd0

1 files changed, 633 insertions, 0 deletions

diff --git a/documentation/oreka-user-manual.xml b/documentation/oreka-user-manual.xml
new file mode 100644
index 0000000..9823e08
--- /dev/null
+++ b/documentation/oreka-user-manual.xml
@@ -0,0 +1,633 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+
+  <title>Oreka 0.5 Open Source User Manual</title>
+
+  <subtitle>Revision 1</subtitle>
+
+  <bookinfo>
+    <copyright>
+      <holder>OrecX LLC</holder>
+
+      <year>2006</year>
+    </copyright>
+  </bookinfo>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <section>
+      <title>What is Oreka</title>
+
+      <para>Oreka is an open source cross-platform system for recording and retrieval of
+      audio streams. The project currently supports VoIP and sound device
+      based capture. The user interface is web based.</para>
+    </section>
+    
+    <section>
+		<title>License</title>
+		<para>
+		This program is free software, distributed under the terms of the GNU General Public License. Please refer to <ulink url="http://www.gnu.org/copyleft/gpl.html">the GNU GPL licence</ulink> for more information.
+		</para>
+    </section>
+    
+    <section>
+      <title>Architecture</title>
+
+      <para>The Oreka system consists of a combination of the following three
+      services</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>OrkAudio: This is the audio capture background service. It
+          supports VoIP and Sound Device based recording</para>
+        </listitem>
+
+        <listitem>
+          <para>OrkTrack: This service filters out unwanted recordings and
+          logs records to any popular SQL database</para>
+        </listitem>
+
+        <listitem>
+          <para>OrkWeb: This service is the the web interface accessible via
+          any standard compliant web browser</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The system supports multiple instances of OrkAudio reporting to
+      OrkTrack so that multiple recording servers can be seen as one recording
+      system. OrkTrack and OrkWeb can run on the same server or on two
+      separate servers.</para>
+    </section>
+
+    <section>
+      <title>Compatibility</title>
+
+      <para>The Oreka system runs on Linux, BSD and all versions of Microsoft Windows starting from Win2k. Oreka supports most major database
+      systems including IBM DB2, Oracle, MySQL and PostgreSQL. MySQL is the default database.</para>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>OrkAudio</title>
+
+    <section>
+      <title>Installing under Windows</title>
+
+      <para>OrkAudio comes as an automated installer such as
+      <emphasis>orkaudio-0.5-2-win32-installer.exe</emphasis>. Copy this file
+      in a temporary folder on the target machine and run the installer by
+      double clicking this file.</para>
+    </section>
+
+    <section>
+      <title>Installing under Linux Redhat/CentOS/Fedora</title>
+
+      <para>OrkAudio comes as a set of RPM packages. Copy those files in a
+      temporary folder on the target machine and install them using the
+      following commands:<itemizedlist>
+          <listitem>
+            <para>yum install boost-devel</para>
+          </listitem>
+
+          <listitem>
+            <para>yum install libpcap</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i xercesc-2.7.0-1.i386.rpm</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i ACE-5.4.8-1.i386.rpm</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i log4cxx-0.9.7-1.i386.rpm</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i libsndfile-1.0.13-1.i386.rpm</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i orkbasecxx-0.5-1.i386.rpm</para>
+          </listitem>
+
+          <listitem>
+            <para>rpm -i orkaudio-0.5-1.i386.rpm</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para></para>
+    </section>
+
+    <section>
+      <title>Installing under Debian/Ubuntu Linux</title>
+
+      <para>OrkAudio needs a set of external libraries that can be installed using the debian packaging system
+      Make sure that <emphasis>contrib</emphasis> is listed as a source in <emphasis>/etc/apt/sources.list</emphasis> and install them using the
+      following commands:<itemizedlist>
+      
+          <listitem>
+            <para>apt-get install libace-dev</para>
+          </listitem>
+
+          <listitem>
+            <para>apt-get install libboost-dev</para>
+          </listitem>
+	  
+          <listitem>
+            <para>apt-get install liblog4cpp-dev</para>
+          </listitem>
+
+          <listitem>
+            <para>apt-get install libpcap0.7-dev</para>
+          </listitem>
+	  
+          <listitem>
+            <para>apt-get install libxerces26-dev</para>
+          </listitem>
+
+          <listitem>
+            <para>apt-get install libsndfile1-dev</para>
+          </listitem>
+	  
+	</itemizedlist></para>
+	  
+      <para>OrkAudio comes as an archive of dpkg packages such as <emphasis>orkaudio-0.X-X-ubuntu-5.04-i386-binary-DEBs.tar</emphasis>. 
+      untar this file in a temporary folder on the target machine and install the packages using the
+      following commands:<itemizedlist>	
+
+          <listitem>
+            <para>dpkg -i orkbasecxx_X.X-1_i386.deb</para>
+          </listitem>
+
+          <listitem>
+            <para>dpkg -i orkaudio_X.X-1_i386.deb</para>
+          </listitem>
+
+	</itemizedlist></para>
+	
+    </section>
+
+    <section>
+      <title>File locations</title>
+
+      <section>
+        <title>Audio Output Files</title>
+
+        <para id="folderscheme">Audio output files are written to the [install
+        directory]/AudioRecordings under windows and in /var/log/orkaudio
+        under Linux. They are classified according to the following
+        scheme:</para>
+
+        <para><emphasis>yyyy/MM/dd/hh</emphasis></para>
+
+        <para>Audio file themselves are named after the following
+        scheme:</para>
+
+        <para><emphasis>yyyyMMdd_hhmmss_capturePort.extension</emphasis></para>
+      </section>
+
+      <section>
+        <title>Configuration Files</title>
+
+        <para>Configuration files are located in the install directory under
+        Windows and in /etc/oreka under Linux. The files are:</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para><emphasis>config.xml</emphasis> : this is the main
+              OrkAudio configuration file. Plugins also read their
+              configration parameters from subsections of this file.</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis>logging.properties</emphasis> : this is the
+              log4j logging configuration file which allows for great
+              flexibility in logging scope and output format.</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+
+      <section>
+        <title>Log Files</title>
+
+        <para>Log files are located in the install directory under Windows and
+        in /var/log/oreka under Linux. By default, Oreka produces the
+        following output:</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para><emphasis>orkaudio.log</emphasis> : this is the main
+              OrkAudio logfile.</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis>tapelist.log</emphasis> : this logfile contains
+              the details (metadata) for each recording that was performed by
+              OrkAudio</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+
+      <section>
+        <title>Plugins Files</title>
+
+        <para>Plugins exist as dll files under Windows and as DSO (Dynamic
+        Shared Objects) with .so extensions under Linux. They are located in
+        [install dir]/audiocaptureplugins under Windows and in /usr/lib under
+        Linux.</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para><emphasis>VoIp.dll - libvoip.so</emphasis> : VoIP
+              recording plugin</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis>SoundDevice.dll - libsounddevice.so</emphasis> :
+              Sound Card based recording</para>
+            </listitem>
+
+            <listitem>
+              <para><emphasis>Generator.dll - libgenerator.so</emphasis> :
+              Audio generator for faking audio capture (useful when
+              testing)</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+    </section>
+
+    <section>
+      <title>Configuring</title>
+
+      <para>Configuration of OrkAudio and its plugins is performed by
+      modifying the config.xml file. Core OrkAudio configuring parameters are
+      the following:</para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para><emphasis>EnableReporting </emphasis>this parameter controls
+            wether recording activity is reported to OrkTrack</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis>StorageAudioFormat </emphasis>this parameter
+            controls the final file format of the tapes. valid values are the
+            following: gsm, ulaw, alaw and pcmwav</para>
+          </listitem>
+
+          <listitem>
+            <para><emphasis>CapturePlugin </emphasis>this parameter controls
+            which audio capture plugin should be used. Valid values are
+            VoIP.dll and SoundDevice.dll (or libvoip.so and libsounddevice.so
+            under Linux)</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <section>
+        <title>Configuring the VoIP plugin</title>
+
+        <para>VoIP plugin specific configuration is found in the config.xml
+        file under the <emphasis>VoIpPlugin</emphasis> tag. It is possible to
+        configure the network device to monitor (i.e. when you have one device
+        dedicated to sniffing). Also for OrkAudio to get voice session
+        direction, remote and local party right, it is necessary to instruct
+        the VoIP plugin how to identify which IP addresses are local
+        telephones (hardphones or softphones) and which are not. To do this,
+        it is possible to give a csv list of IP addresses that are reserved as
+        <emphasis>Media Gateways</emphasis>, i.e. IP addresses that host such
+        services as PBX, PSTN gateway, conferencing or such. Further, it is
+        possible to specify a csv list of local LAN masks (only necessary when
+        LAN masks are not the standard 192.168.x.x or 10.x.x.x or 172.31.x.x).
+        The way the VoIP plugin decides wether an IP address is a local
+        telelephone is as follows: 1. IP Address needs to be on LAN and 2. IP
+        Address cannot be a <emphasis>Media Gateway</emphasis>.</para>
+      </section>
+
+      <section>
+        <title>Configuring the SoundDevice plugin</title>
+
+        <para>SoundDevice specific configuration is found in the config.xml
+        file under the <emphasis>SoundDevice</emphasis> tag. The
+        <emphasis>SampleRate</emphasis> tag controls how many samples per
+        second will be recorded. For telephony grade recording, use 8000. For
+        FM radio equivalent recording quality, 16000 can be used. For CD
+        quality, 44100 can be used. Recorded file size will be directly
+        proportional to this number.</para>
+      </section>
+    </section>
+
+    <section>
+      <title>Running OrkAudio</title>
+
+      <para>Under Windows, start the OrkAudio service in the NT services
+      control panel (start/run/services.msc).</para>
+
+      <para>Under Linux, start the OrkAudio service by typing
+      <emphasis>orkaudio</emphasis> on the command line.</para>
+    </section>
+
+    <section>
+      <title>Troubleshooting</title>
+
+      <para></para>
+
+      <section>
+        <title>OrkAudio does not record any VoIP traffic</title>
+
+        <para>If no recordings appear in the
+        <emphasis>AudioOutputPath</emphasis> directory, Here is the
+        checklist:</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para>Windows users only: Make sure winpcap3.1 is properly installed (start/programs
+              should contain a Winpcap entry</para>
+            </listitem>
+
+            <listitem>
+              <para>Make sure that the VoIP plugin records from the right
+              network interface(s) specified in the
+              <emphasis>Devices</emphasis> xml tag of the config.xml file. A
+              list of all network interfaces is shown in orkaudio.log at
+              startup.</para>
+            </listitem>
+
+            <listitem>
+              <para>Make sure that RTP traffic is actually present on the
+              specified network interface(s). A packet sniffer such as
+              Ethereal can be useful for that.</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+
+      <section>
+        <title id="notpossiblereplay">Not possible to replay recorded
+        files</title>
+
+        <para>Recoded wav files should all be replayable by a media player
+        such as Windows Media Player. Here is the checklist</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Make sure the file is not being processed by OrkAudio. Try
+            again later.</para>
+          </listitem>
+
+        </itemizedlist>
+      </section>
+
+      <section>
+        <title>Only one side of the conversation is recorded</title>
+
+        <para>Make sure that RTP traffic for both sides is actually seen on
+        the considered network interface. A packet sniffer such as Ethereal
+        can be used for that.</para>
+      </section>
+
+      <section>
+        <title>Metadata is not detected</title>
+
+        <para>Make sure that the signalling is SIP or Cisco Skinny. It is
+        possible to turn on SIP and Skinny debugging by editing
+        logging.properties such as this:</para>
+
+        <para><blockquote>
+            <para>log4j.logger.packet.skinny=DEBUG</para>
+
+            <para>log4j.logger.packet.sip=DEBUG</para>
+          </blockquote>If those settings do not generate extra entries in
+        orkaudio.log, it means that no SIP or Skinny traffic is
+        detected.</para>
+      </section>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>OrkWeb - OrkTrack</title>
+
+    <section>
+      <title id="orkwebinstalling">Installing</title>
+
+      <para>OrkWeb/OrkTrack need the following prerequiste
+      software:<emphasis></emphasis></para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para>The Java Runtime Environment JRE 5.0 from <ulink url="http://java.sun.com">http://java.sun.com</ulink></para>
+          </listitem>
+
+          <listitem>
+            <para>The Apache Tomcat servlet container version 5.X from <ulink
+            url="http://tomcat.apache.org">http://tomcat.apache.org</ulink></para>
+          </listitem>
+
+          <listitem>
+            <para>The MySQL server version 4.X from <ulink
+            url="http://www.mysql.com">http://www.mysql.com</ulink></para>
+          </listitem>
+        </itemizedlist>Install the prerequisite software with all defaults and
+      make note of the Tomcat admin password as well as the MySQL root
+      password.</para>
+
+      <para>OrkWeb/OrkTrack comes in the form of a zip file such as
+      <emphasis>oreka-0.5-2-orkweb-orktrack.zip</emphasis>. Unzip this file
+      into a temporary directory and execute the following steps:</para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para>Copy lib.zip to {TOMCAT_HOME}/shared/lib and "unzip here".
+            You should now have an additional collection of jar files directly
+            under this shared/lib directory.</para>
+          </listitem>
+
+          <listitem>
+            <para>Copy ConfigFiles.zip to c:\ and "unzip to here" so as to get
+            a c:\oreka folder with orkaudio and orkweb subdirectories. Under
+            Linux, you can unzip to a folder such as /etc/oreka/</para>
+          </listitem>
+
+          <listitem>
+            <para>Edit c:\oreka\orkweb\mysql.hbm.xml and
+            c:\oreka\orktrack\mysql.hbm.xml or the linux equivalent files in
+            order to supply the right DB username, DB password and JDBC
+            URL.</para>
+          </listitem>
+
+          <listitem>
+            <para>Copy orkweb.war and orktrack.war to the
+            {TOMCAT_HOME}/webapps folder</para>
+          </listitem>
+
+          <listitem>
+            <para>Start Tomcat</para>
+          </listitem>
+
+          <listitem>
+            <para>Tomcat should automatically deploy orktrack and orkweb to
+            {TOMCAT_HOME}/webapps/orktrack and {TOMCAT_HOME}/webapps/orkweb
+            folders</para>
+          </listitem>
+
+          <listitem>
+            <para>Under Linux only, edit
+            {TOMCAT_HOME}/webapps/orktrack/WEB-INF/web.xml and
+            {TOMCAT_HOME}/webapps/orkweb/WEB-INF/web.xml and change the paths
+            to the config files (log4j.properties, mysql.hbm.xml and
+            orktrack.config.xml) to /etc/oreka/...</para>
+          </listitem>
+
+          <listitem>
+            <para>Restart Tomcat</para>
+          </listitem>
+        </itemizedlist></para>
+    </section>
+
+    <section>
+      <title>Running</title>
+
+      <para>Start the database server. Start the Tomcat servlet container and
+      point your browser to <ulink
+      url="http://localhost:8080/orkweb">http://localhost:8080/orkweb</ulink>. This will bring up a
+      login screen. Login as admin/admin.</para>
+
+      <para></para>
+    </section>
+
+    <section>
+      <title>Logging recordings to the database</title>
+
+      <para>In order to get OrkAudio to report recording activity to OrkTrack,
+      do the followig changes to OrkAudio's config.xml:</para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para>Set <emphasis>EnableReporting</emphasis> to true.</para>
+          </listitem>
+
+          <listitem>
+            <para>If OrkTrack is deployed on a different server than OrkAudio,
+            set <emphasis>TrackerHostname</emphasis> OrkTrack's
+            hostname.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>Make sure c:\oreka\orktrack\mysql.hbm.xml or the equivalent Linux
+      file contains the right database access URL and credentials. If OrkTrack
+      is up and running under Tomcat and the OrkAudio service is recording
+      traffic, database entries should start appearing. Use OrkWeb to browse
+      them.</para>
+    </section>
+
+    <section>
+      <title>Retrieving recordings</title>
+
+      <section>
+        <title>Multi-criteria retrieval</title>
+
+        <para>The retrieval screen has two panes. The left hand pane contains
+        all possible search criteria. Using more than one criteria will filter
+        results by a combination of all criteria. The right hand pane is a
+        list of all entries that match all of the search criteria.</para>
+      </section>
+
+      <section>
+        <title>Sorting results</title>
+
+        <para>It is possible to sort results by clicking on the appropriate
+        results column headings. Sort order is toggled by multiple clicking of
+        the column headings.</para>
+      </section>
+
+      <section>
+        <title id="replayingrecordings">Replaying recordings</title>
+
+        <para>Replaying recordings via OrkWeb is currrently only possible
+        using Internet Explorer. Audio Files need to be accessible via http.
+        Here is what needs to be done for that (repeat for each instance of
+        OrkAudio):</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para>Setup OrkAudio to output files in the Tomcat webapps/ROOT
+              directory: edit OrkAudio's config.xml file. Set the
+              <emphasis>AudioOutputPath</emphasis> parameter to the Tomcat
+              webapps/ROOT directory. By default, this is c:\Program
+              Files\Apache Software Foundation\Tomcat 5.5\webapps\ROOT under
+              windows.</para>
+            </listitem>
+
+            <listitem>
+              <para>Restart OrkAudio and watch new audio files being written
+              to the Tomcat webapps/ROOT directory.</para>
+            </listitem>
+
+            <listitem>
+              <para>It should now be possible to replay those new recordings
+              using OrkWeb, simply by clicking on the recording's play
+              button.</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+    </section>
+
+    <section>
+      <title>Troubleshooting</title>
+
+      <para></para>
+
+      <section>
+        <title>Cannot login as admin/admin</title>
+
+        <para>Most likely, the database server is down or there is something
+        wrong in the database URL and credentials in the hibernate
+        configuration file. Please refer to <xref
+        linkend="orkwebinstalling" /></para>
+      </section>
+
+      <section>
+        <title>Cannot replay recordings</title>
+
+        <para>If you fail to replay recordings through OrkWeb, here is the
+        checklist:</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para>Make sure you are using Microsoft Internet Explorer</para>
+            </listitem>
+
+            <listitem>
+              <para>Make sure you have followed the procedure described in
+              <xref linkend="replayingrecordings" /> for getting audio files
+              accessible via http</para>
+            </listitem>
+
+            <listitem>
+              <para>Make sure the file you are looking for is actually present
+              in the Tomcat webapps ROOT folder</para>
+            </listitem>
+
+            <listitem>
+              <para>If the file is present, try to replay it locally with a
+              media player such as Windows Media Player. If it does not
+              replay, please refer to <xref
+              linkend="notpossiblereplay" /></para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
+
+      <section>
+        <title>I don't get the latest recordings</title>
+
+        <para>Make sure the <emphasis>end date</emphasis> in the
+        multi-criteria seach form is not in the past.</para>
+      </section>
+
+    </section>
+  </chapter>
+</book>
\ No newline at end of file