path: root/documentation/oreka-user-manual.xml

<?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 1.0 Open Source User Manual</title>

  <subtitle>Revision 3</subtitle>

  <bookinfo>
    <copyright>
      <holder>OrecX LLC</holder>

      <year>2008</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 log4cxx-0.9.7_0.9.7-1_i386.deb</para>
          </listitem>

          <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 id="folderscheme">
        <title>Audio Output Files</title>

        <para>Audio output files are written to the [install
        directory]/AudioRecordings under windows and in /var/log/orkaudio
        under Linux by default. This can be changed using the <emphasis>AudioOutputPath</emphasis> configuration parameter described in <xref linkend="configuring" />. 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 id="configuring">
      <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>
	  
          <listitem>
            <para><emphasis>AudioOutputPath </emphasis>this parameter controls the root directory where capture and storage audio files are stored. It can be a relative or absolute path.</para>
          </listitem>
	  
          <listitem>
            <para><emphasis>TapeFileNaming </emphasis>this parameter controls the final transcoded file naming scheme. It is a csv list of elements. If an element matches a keyword, it will be replaced by the corresponding value. If an element does not match any keyword, it will be used verbatim in the file name. Example: <programlisting><![CDATA[<TapeFileNaming>myrecordings-, nativecallid</TapeFileNaming>]]></programlisting>
with a native call ID of FDBCE@69.13.45.6 will result in the following file name: myrecordings-FDBCE@69.13.45.6.wav. If this parameter is missing, the default naming scheme applies which is a timestamp plus the internal tracking ID. The list of possible keywords for now is limited to nativecallid and trackingid. When this parameter is set, the audio file output directory structure becomes flat, i.e. all files will be stored directly in the directory set by the AudioOutputPath configuration parameter instead of being distributed to the default year/month/day/hour folder tree structure described in <xref linkend="folderscheme" />.</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>
        <title>Logging recordings to the database</title>
  
        <para>Refer to section below in OrkWeb - OrkTrack for more details.</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>

      <section>
        <title id="orkwebprerequisites">Pre-requisites</title>

        <para>OrkWeb/OrkTrack need the following prerequiste
        software:<emphasis></emphasis></para>
  
        <para>
        <itemizedlist>
            <listitem> The Java Runtime Environment JRE 5.0 from <ulink url="http://java.sun.com">http://java.sun.com</ulink></listitem>
            <listitem> The Apache Tomcat servlet container version 5.X from <ulink url="http://tomcat.apache.org">http://tomcat.apache.org</ulink></listitem>
            <listitem> The MySQL server version 4.X from <ulink url="http://www.mysql.com">http://www.mysql.com</ulink></listitem>
        </itemizedlist>
        </para>
      </section>
      
      <section>      
        <title id="orkwebinstallers">Using Installers</title>

        <para>Installers for several platforms are provided, e.g. Windows, 
        CentOS 5 (32-bit), CentOS 4 (32-bit), Linux SuSE (32-bit).  
        If your platform does not have an installer, use the manual installation
        steps described below.
        </para>
      </section>

      <section>      
        <title id="orkwebmanualinstall">Manual Installation</title>
      
        <para>Install the prerequisite software above, accepting 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-1.0-orkweb-orktrack.zip</emphasis>. Unzip this file
        into a temporary directory and execute the following steps:</para>

        <para><itemizedlist>
          <listitem>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.</listitem>
          <listitem>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/</listitem>
          <listitem>Edit /etc/orkweb/database.hbm.xml file (c:\oreka\database.hbm.xml 
            on Windows) in order to supply the right DB username, DB password 
            and JDBC URL.</listitem>
          <listitem>Copy orkweb.war and orktrack.war to the 
          {TOMCAT_HOME}/webapps folder</listitem>
          <listitem>Start MySQL (or whatever database engine you are using)</listitem>
          <listitem>Start Tomcat</listitem>
          <listitem>Tomcat should automatically deploy orktrack and orkweb to
            {TOMCAT_HOME}/webapps/orktrack and {TOMCAT_HOME}/webapps/orkweb
            folders</listitem>
          <listitem>Edit {TOMCAT_HOME}/webapps/orktrack/WEB-INF/web.xml and
            {TOMCAT_HOME}/webapps/orkweb/WEB-INF/web.xml and ensure that the 
            paths to the config files (logging.properties, database.hbm.xml and
            orktrack.config.xml) are correct, e.g. /etc/orkweb/ for Linux
          </listitem>
          <listitem>Restart Tomcat</listitem>
        </itemizedlist></para>
      </section>  
    </section>

    <section>
      <title>Running</title>

      <para><itemizedlist>
        <listitem>Start the database server.</listitem> 
        <listitem>Start Tomcat.</listitem>
        <listitem>Point your browser to <ulink url="http://localhost:8080/orkweb">
        http://localhost:8080/orkweb</ulink>. This will bring up a
        login screen.</listitem> 
        <listitem>Login as admin/admin.</listitem>
      </itemizedlist></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>Set <emphasis>EnableReporting</emphasis> to true.</listitem>
          <listitem>If OrkTrack is deployed on a different server than OrkAudio,
            set <emphasis>TrackerHostname</emphasis> OrkTrack's hostname.</listitem>
        </itemizedlist></para>

      <para>Make sure /etc/orkweb/ (Linux) or c:\oreka\database.hbm.xml (Windows)     
      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 currently 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>