Oreka 1.7 Developer's Guide

Revision 2


Table of Contents

1. Introduction
What is Oreka ?
License
2. Building
Getting the source code
Installing dependencies under Linux RHEL/CentOS 6 - 64 bit
Installing dependencies under Ubuntu
Building under Linux/Unix
Build under Windows with Visual Studio 2008 - 32 bit (VC9)
Building OrkTrack and OrkWeb
3. Installing
Installing OrkAudio
Using Installers
Manual Installation
Installing OrkWeb/OrkTrack
Using Installers
Manual Installation
4. Running
Running OrkAudio
File locations
Audio Output Files
Configuration Files
Log Files
Plugins Files
Configuring OrkAudio
Configuring the OrkAudio VoIP plugin
Running OrkTrack and OrkWeb
5. Testing
Testing OrkAudio
Record a simple SIP session
Generate fake recordings
Testing OrkWeb
Browse test data

Chapter 1. Introduction

Table of Contents

What is Oreka ?
License

What is Oreka ?

Oreka is an enterprise telephony recording and retrieval system with web based user interface. The project currently supports recording voice from VoIP SIP, Cisco Skinny (aka SCCP), raw RTP and runs on multiple operating systems and database systems.

It can record audio from most PBX and telephony systems such as BroadWorks, Metaswitch, Asterisk, FreeSwitch, OpenSIPS, Avaya, Nortel, Mitel, Siemens, Cisco Call Manager, Cosmocom, NEC, etc...

It is amongst others being used in Call Centers and Contact Centers for Quality monitoring (QM) purposes.

Oreka is sponsored by OrecX LLC. Professional open source support as well as commercial versions are available here

The platform currently comprises of three services:

  • OrkAudio: the audio capture and storage daemon with pluggable capture modules. This service is written in C++.
  • OrkTrack: logs all activity from one or more orkaudio services to any mainstream database. This service is implemented as a J2EE servlet based application.
  • OrkWeb: Web based user interface for retrieval. This service is implemented as a J2EE servlet based application using the Tapestry web development framework.

.

License

This program is free software, distributed under the terms of the GNU General Public License. Please refer to the GNU GPL licence for more information.

Chapter 2. Building

If you only want to run Oreka sofware, you can safely skip this section.

Getting the source code

Download the latest source code from sourceforge:

svn checkout svn://svn.code.sf.net/p/oreka/svn/trunk oreka-svn

Installing dependencies under Linux RHEL/CentOS 6 - 64 bit

Installing dependencies under Ubuntu

  • Boost: apt-get install libboost-dev
  • libpcap: apt-get install libpcap-dev
  • libsndfile: apt-get install libsndfile1-dev
  • Apache Portable Runtime: apt-get install libapr1-dev
  • Speex: apt-get install libspeex-dev
  • Log4cxx: apt-get install liblog4cxx10-dev
  • Adaptive Communication Environment (ACE): apt-get install libace-dev
  • Xerces-C: apt-get install libxerces-c-dev

Building under Linux/Unix

Build orkbasecxx on the command line:

  • Go to the root directory of the orkbasecxx
  • libtoolize
  • automake -a
  • make -f Makefile.cvs
  • ./configure
  • make
  • make install

Build orkaudio on the command line:

  • Go to the root directory of the orkaudio
  • libtoolize
  • automake -a
  • make -f Makefile.cvs
  • ./configure
  • make
  • make install

For debug binaries: modify above as follows:

  • ./configure --enable-debug=full
  • CXXFLAGS="-O0 -g3"
  • make -e

Build under Windows with Visual Studio 2008 - 32 bit (VC9)

Install and compile C++ dependencies in c:\devExt, edit the orkaudio and orkbase .vcproj files and search for "devExt" to see the exact required paths for each library

  • Load orkaudio\OrkAudio.sln into Visual Studio 2008
  • Select orkbase as active project, build
  • Select orkaudio as active project, build

Building OrkTrack and OrkWeb

As of Oreka version 1.0, installers for some platforms are available, e.g. Windows, CentOS/RHEL, .... The steps below are still useful for building for other platforms.

Install required software

  • Install Java 5 JDK
  • Install Eclipse 3.1 or later
  • Download OrkTrack and OrkWeb open source code and unzip to a work folder

Building using Eclipse

  • Run Eclipse
  • /File/Switch workspace/ -> select folder containing the orkweb and orktrack code
  • Set the compiler compliance for the worskspace to Java 5 (Java 1.5) /Window/preferences/ -> /java/compiler/
  • Import user libraries:
    • Get the external java dependencies pack and unzip it into {WORKSPACE}/lib
    • Edit oreka.userlibraries, search and replace the absolute path to jar files with your own.
    • /Window/preferences/ -> /java/buildpath/user libraries/ -> import -> select your modified oreka.userlibraries file
  • /File/import existing project into workspace/ -> select 1. orkbasej, 2. orktrack 3. orkweb
  • /Window/open perspective/java
  • At this point, all three projects should compile automatically without an error

Chapter 3. Installing

Installing OrkAudio

Using Installers

You can use the OrkAudio Windows or Linux (RHEL/CentOS) installers that are published on the sourceforge project page.

Manual Installation

Installing Prerequisite Software for OrkAudio

For Linux libraries, please refer to the section called “Installing dependencies under Linux RHEL/CentOS 6 - 64 bit”

For Windows, download and install the latest Winpcap (choose the windows installer version). This is a network packet capture library http://www.winpcap.org

Installing OrkAudio manually after a fresh win32 build

  • Download the win32 installer from the oreka sourceforge project page
  • Unzip and run the installer. This will set up the environment
  • Build your modified version of OrkAudio, or OrkAudio plugin in release mode
  • Copy the modified OrkAudio.exe, OrkBase.dll, VoIp.dll or Generator.dll to your install folder, replacing old files

Installing OrkWeb/OrkTrack

Using Installers

Start by installing MySQL or any database compatible with hibernate.

You can then use the OrkWeb Windows or Linux (RHEL/CentOS) installers that are published on the sourceforge OrkWeb/OrkTrack download page.

Manual Installation

Installing Prerequisite Software for OrkTrack and OrkWeb

  • Install MySQL or any database compatible with hibernate

  • Install Java 5 JDK or later.
  • Install Tomcat 5.5 or later, point it to the Java JDK by setting the JAVA_HOME environment variable to the root of the JDK
  • Make note of the Tomcat admin password
  • Get the external java dependencies package from the source code page.
  • Copy all jar files from the external java dependencies package to {TOMCAT_HOME}/shared/lib
  • Create a database for storing oreka data
  • Create a user/password for reading/writing the newly created database
  • Install Eclipse 3.1 or later

Installing OrkTrack

  • Create a folder for configuration and logging such as c:\oreka\
  • Copy orkbasej/java/logging.template.properties to this folder, rename it to logging.properties and change according to needs
  • Copy orkbasej/java/database.hbm.template.xml to this folder, rename it to database.hbm.xml and change according to needs
  • Copy orktrack/orktrack.config.xml to this folder and change according to needs
  • Modify orktrack/WEB-INF/web.xml and make it point to those newly created config files
  • Copy orktrack/deploy-template.xml to orktrack/deploy.xml and change deploy.xml according to your setup.
  • Run Tomcat
  • Run deploy.xml as ant script in Eclipse (Right click/Run as). This should result in the following message:

    "[echo] OK - Deployed application at context path /orktrack"

  • Point your browser to your Tomcat manager (e.g. http://localhost:8080/manager/html) and check that orktrack has started, otherwise, check Tomcat logs

Installing OrkWeb

  • Create a folder for configuration and logging such as c:\oreka\ (use the same one as orktrack)
  • Copy orkbasej/java/logging.template.properties to this folder, rename it to logging.properties and change according to needs
  • Copy orkbasej/java/database.hbm.template.xml to this folder, rename it database.hbm.xml and change according to needs
  • Modify orkweb/WEB-INF/web.xml and make it point to those newly created config files
  • Copy orktrack/deploy-template.xml to orktrack/deploy.xml and change deploy.xml according to your setup.
  • Run Tomcat
  • Run deploy.xml as ant script in Eclipse (Right click/Run as). This should result in the following message:

    "[echo] OK - Deployed application at context path /orkweb"

  • Point your browser to your Tomcat manager (e.g. http://localhost:8080/manager/html) and check that orkweb has started, otherwise, check Tomcat logs
  • Point your browser to the newly deployed application (e.g. http://localhost:8080/orkweb/app)

Chapter 4. Running

Running OrkAudio

Windows:

  • To run on the windows command line, open a cmd box, navigate to the install directory and issue the following command:

    c:\Program Files\orkaudio> OrkAudio.exe debug

  • To install as an NT service, issue the following command (not needed if OrkAudio was deployed using the windows installer):

    c:\Program Files\orkaudio> OrkAudio.exe install

  • To run as an NT service, go start/run and enter

    services.msc

    pick the orkaudio service and start it
  • To uninstall service, issue the following command:

    c:\Program Files\orkaudio> OrkAudio.exe uninstall

Linux:

  • To run attached to the tty, issue the following command:

    # orkaudio debug

  • To run as a daemon, issue the following command:

    # orkaudio

File locations

Audio Output Files

Audio output files those will be written to the [install directory]/AudioRecordings under windows and in /var/log/orkaudio under Linux. They are classified according to the following scheme:

yyyy/MM/dd/hh

Audio file themselves are named after the following scheme:

yyyyMMdd_hhmmss_capturePort.extension

Configuration Files

Configuration files are located in the install directory under Windows and in /etc/oreka under Linux. The files are:

  • config.xml: this is the main OrkAudio configuration file. Plugins also read their configration parameters from subsections of this file.
  • logging.properties: this is the log4j logging configuration file which allows for great flexibility in logging scope and output format.

Log Files

Log files are located in the install directory under Windows and in /var/log/oreka under Linux. By default, Oreka produces the following output:

  • orkaudio.log: this is the main OrkAudio logfile.
  • tapelist.log: this logfile contains the details (metadata) for each recording that was performed by OrkAudio

Plugins Files

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.

  • VoIp.dll - libvoip.so: VoIP recording plugin
  • Generator.dll - libgenerator.so: Audio generator for faking audio capture (useful when testing)

Configuring OrkAudio

Configuration of OrkAudio is performed by modifying the config.xml file.

Audio compression can be tuned using the StorageAudioFormat config parameter. A value of native turns off compression while values of gsm , ulaw (G.711 standard american telephony encoding) or alaw (G.711 standard european telephony encoding) can be used to enable compression.

The plugin to use for audio capture is selected using the CapturePluginPath and CapturePlugin configuration parameters. CapturePluginPath is relative to the install directory. CapturePlugin is the full plugin name including extension (e.g. .dll or .so)

Reporting to OrkTrack can be enabled by setting EnableReporting to true and by specifying the right TrackerHostname

Configuring the OrkAudio VoIP plugin

VoIP plugin specific configuration is found in the config.xml file under the "VoIpPlugin" 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 Media Gateways, 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 Media Gateway.

Running OrkTrack and OrkWeb

Once the OrkWeb installer is used or the war files deployed to Tomcat as described in the section called “Installing OrkTrack”, run the Tomcat service. You can then access the application from your prefered browser by entering http://localhost:8080/orkweb. Replace localhost by the server hostname or ip address if necessary. The default login is admin/admin.

Chapter 5. Testing

Testing OrkAudio

Record a simple SIP session

Install OrkAudio on a windows computer that has a SIP softphone installed. Run it on the command line as described in the section called “Running OrkAudio” and make a phone call to any number. The call should be logged to the screen with the right metadata. The associated GSM compressed audio file should be found in the OrkAudio install directory in date/time based subfolders as described in the section called “Audio Output Files”

Generate fake recordings

This involves using the Generator Plugin to create fake audio streams that OrkAudio will record and compress to disk.The CapturePlugin configuration parameter needs to be changed to generator.dll. An existing audio file can be used as the basis of the generated audio streams. This file is specified in the AudioFilename configuration parameter and needs to be a 16 bit samples, mono, 8KHz audio file.

Once configured, run OrkAudio, you should see the generated audio streams logged to the console. Audio files should also start appearing in subfolders as described in the section called “Audio Output Files”

Testing OrkWeb

Browse test data

  • Edit orkbasej/java/net/sf/oreka/test/FillDatabase.java and point it to your own hibernate config file created earlier
  • Run FillDatabase.java as a Java application. This will fill your oreka database with test data
  • Point your browser to orkweb as described above
  • Browse the test data