Oreka 1.7 Open Source User Manual

Revision 5


Table of Contents

1. Introduction
What is Oreka
License
Architecture
Compatibility
Getting VoIP traffic to the Oreka Server
2. OrkAudio
Installing OrkAudio under Linux CentOS/RHEL
Installing OrkAudio under Windows
File locations
Audio Output Files
Configuration Files
Log Files
Plugins Files
Configuring
Configuring the VoIP plugin
Configure audio files path and file names
Running OrkAudio
Troubleshooting
OrkAudio does not record any VoIP traffic
Only one side of the conversation is recorded
Metadata is not detected
3. OrkWeb - OrkTrack
Installing
Running
Logging recordings to the database
Retrieving recordings
Multi-criteria retrieval
Sorting results
Replaying recordings
Troubleshooting
Cannot login as admin/admin
Cannot replay recordings
I don't get the latest recordings

Chapter 1. Introduction

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

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.

Architecture

The Oreka system consists of a combination of the following 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.
.

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.

Compatibility

The Oreka system runs on Linux, BSD and all versions of Microsoft Windows starting from Windows XP/Server 2003. Oreka supports most major database systems including MySQL, PostgreSQL, Oracle and MS-SQL. MySQL is the default database.

Getting VoIP traffic to the Oreka Server

Before Oreka can start recording, ensure that VoIP traffic is seen on a server interface. Use SPAN port mirroring to get the right traffic to the Oreka server. Two configurations are possible:

  • SPAN monitoring the entire VoIP VLAN so that all traffic to and from phones is intercepted;
  • SPAN monitoring the PSTN Gateways and the Signalling server (e.g. SIP proxy, Cisco Call Manager, Avaya Communication Manager, ...)

This is to ensure that both the media traffic (RTP) and signalling (SIP or Skinny) are intercepted by the recorder.

Once the VoIP traffic appears on the server, you are ready to start using the Oreka software.

Mechanisms to get VoIP traffic

In terms of insertion point, Oreka can intercept packets via several mechanisms:

  • Ethernet switch SPAN monitoring port: for Ethernet switches that have this capability. For Cisco, see http://www.cisco.com/en/US/products/hw/switches/ps708/products_tech_note09186a008015c612.shtml. This is the most popular solution.
  • Ethernet tap: requires additional hardware, this option has become fairly cheap lately. See Netoptics Teeny Tap or Barracuda Ethernet Tap products for example.
  • Being installed directly on the PBX or media gateway server. Not ideal.
  • Old style Ethernet hub inserted in the Ethernet path, i.e. all traffic copied to all ports. Not recommended, do this only for testing or low traffic sites.
  • Setup the machine as an Ethernet bridge inserted in the Ethernet path. Not recommended, do this only for testing.

Chapter 2. OrkAudio

Installing OrkAudio under Linux CentOS/RHEL

OrkAudio comes as an automated installer for Linux CentOS/RHEL which you can download from The Oreka sourceforge project page.

Installation steps:

  • Make sure you have installed the right OS, e.g. CentOS or RHEL 6 in the example below as well as the right platform. If the installer says x86_64 you must use 64 bit OS. If the installer says i386, you must use a 32 bit OS
  • Untar the installer, e.g.:
    tar -xvf orkaudio-1.7-844-os-x86_64.centos6-installer.sh.tar
  • Run the installer:
    ./orkaudio-1.7-844-os-x86_64.centos6-installer.sh
  • In order to increase your chances of Oreka working out of the box, accept all defaults.

Installing OrkAudio under Windows

OrkAudio comes as an automated installer for Windows XP or Windows Server 2003 or newer) which you can download from The Oreka sourceforge project page. Simply run the installer. In order to increase your chances of Oreka working out of the box, accept all defaults.

File locations

Audio Output Files

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 AudioOutputPath configuration parameter described in the section called “Configuring”. They are classified according to the following scheme:

yyyy/MM/dd/hh

Audio file themselves are named after the following scheme:

yyyyMMdd_hhmmss_trackingID.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

Configuration of OrkAudio and its plugins is performed by modifying the config.xml file. Core OrkAudio configuring parameters are the following:

  • EnableReporting this parameter controls wether recording activity is reported to OrkTrack

  • StorageAudioFormat this parameter controls the final file format of the tapes. valid values are the following: gsm, ulaw, alaw and pcmwav

  • CapturePlugin this parameter controls which audio capture plugin should be used. Use VoIP.dll under Windows or libvoip.so under Linux

  • AudioOutputPath this parameter controls the root directory where capture and storage audio files are stored. It can be a relative or absolute path.

  • TapeFileNaming see the section called “Configure audio files path and file names”

Configuring the VoIP plugin

VoIP plugin specific configuration is found in the config.xml file under the VoIpPlugin tag.

Selecting Network Device(s) to intercept traffic from

It is possible to configure the network device to monitor for VoIP traffic using the <Devices> directive. While OrkAudio attempts to automatically select the server interface on which it detects VoIP traffic, you may need to configure the interface manually if orkaudio.log shows no sign of traffic. E.g.

In Windows:

<Devices>\Device\NPF_{E0E496FA-DABF-47C1-97C2-DD914DFD3354}</Devices>

In Linux:

<Devices>eth2</Devices>

Several comma-separated interfaces may be configured in the examples above

Configure audio files path and file names

OrkAudio gives you the ability to configure the path and file name of the recorded audio files. To modify the default naming scheme:

  • Add TapeFileNaming to the list of processors in the orkaudio config.xml file: <TapeProcessors>BatchProcessing, TapeFileNaming</TapeProcessors>
  • Add comma-separated entries such as the following:
    • <TapePathNaming>myrecording,[hour],[min],[sec],_,[shortdirection],_,[remoteparty],_,[localparty],_,[hostname]</TapePathNaming>
    • <TapeFileNaming>mypathprefix/,[year],[month],/,[day]</TapeFileNaming>

Here are the dynamic keywords accepted as in the TapeFileNaming and TapePathNaming directives:

  • [nativecallid] This is the call ID extracted from the underlying protocol (SIP, Cisco Skinny, ...)
  • [trackingid] This is the internal Oreka tracking ID
  • [direction] in, out or unkn
  • [shortdirection] I, O or U
  • [remoteparty]
  • [localentrypoint]
  • [localparty]
  • [localip]
  • [remoteip]
  • [hostname]
  • [year]
  • [day]
  • [month]
  • [hour] in 24 hours format
  • [min]
  • [sec]

Running OrkAudio

Under Windows, start the OrkAudio service in the NT services control panel (start/run/services.msc).

Under Linux, start the OrkAudio service by typing:

service orkaudio start

Troubleshooting

OrkAudio does not record any VoIP traffic

If no recordings appear in the AudioOutputPath directory, Here is the checklist:

  • Windows users only: Make sure winpcap is properly installed (start/programs should contain a Winpcap entry

  • Make sure that the VoIP plugin records from the right network interface(s) specified in the Devices xml tag of the config.xml file. A list of all network interfaces is shown in orkaudio.log at startup.

  • Make sure that RTP traffic is actually present on the specified network interface(s). A packet sniffer such as Wireshark can be useful for that.

Only one side of the conversation is recorded

Make sure that RTP traffic for both sides is actually seen on the considered network interface. A packet sniffer such as Wireshark can be used for that.

Metadata is not detected

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:

log4j.logger.packet.skinny=DEBUG

log4j.logger.packet.sip=DEBUG

If those settings do not generate extra entries in orkaudio.log, it means that no SIP or Skinny traffic is detected.

Chapter 3. OrkWeb - OrkTrack

Installing

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.

Running

  • Start the database server.
  • Start Tomcat.
  • Point your browser to http://localhost:8080/orkweb. This will bring up a login screen.
  • Login as admin/admin.

Logging recordings to the database

If OrkWeb is up and running, any new recording done by OrkAudio should show up in OrkWeb (just do a page refresh)

If OrkTrack is deployed on a different server than OrkAudio, set TrackerHostname to OrkTrack's hostname.

Make sure /etc/orkweb/database.hbm.xml (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.

Retrieving recordings

Multi-criteria retrieval

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.

Sorting results

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.

Replaying recordings

Replaying recordings via OrkWeb is currently only possible using Internet Explorer. If Windows Media Player is installed and working, a simple click on a recording's play button should initiate replay.

Troubleshooting

Cannot login as admin/admin

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 the section called “Installing”

Cannot replay recordings

If you fail to replay recordings through OrkWeb, here is the checklist:

  • Make sure your copy of Windows Media Player works well by opening it from the start menu and trying to replay a sample audio file.
  • Verify that the file you are attempting to replay is actually present in the OrkAudio storage folder as configured in the recorder's config.xml file.
    					<AudioOutputPath>c:/oreka/audio/</AudioOutputPath> 
    				  
  • Make sure that a correct context path is configured in Tomcat's server.xml for the storage location of the media files. Make this context path matches the OrkAudio AudioOutputPath. Following the example above, ensure that Tomcat's $tomcat/conf/server.xml contains an entry such as:
    					<Context path="/audio" docBase="c:/oreka/audio/" ></Context> 
    				  
    If this parameter does not exist already, just add it under the <Host> section. Make sure Tomcat is restarted after such a change.
  • If the file is present, try to replay it locally with a media player such as Windows Media Player.
  • Make sure URLs are valid: retrieve the full URL to an audio file by doing a "view source" on the browse page and search for ".wav". Copy the complete URL and paste is directly into a browser's address bar to check if the file can be downloaded manually.

I don't get the latest recordings

Make sure the end date in the multi-criteria seach form is not in the past.