Oreka 0.5 Open Source User Manual

Oreka 0.5 Open Source User Manual Revision 1 OrecX LLC 2006 Introduction

What is Oreka 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.

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: This is the audio capture background service. It supports VoIP and Sound Device based recording OrkTrack: This service filters out unwanted recordings and logs records to any popular SQL database OrkWeb: This service is the the web interface accessible via any standard compliant web browser 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 Win2k. Oreka supports most major database systems including IBM DB2, Oracle, MySQL and PostgreSQL. MySQL is the default database.

OrkAudio

Installing under Windows OrkAudio comes as an automated installer such as orkaudio-0.5-2-win32-installer.exe. Copy this file in a temporary folder on the target machine and run the installer by double clicking this file.

Installing under Linux Redhat/CentOS/Fedora 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: yum install boost-devel yum install libpcap rpm -i xercesc-2.7.0-1.i386.rpm rpm -i ACE-5.4.8-1.i386.rpm rpm -i log4cxx-0.9.7-1.i386.rpm rpm -i libsndfile-1.0.13-1.i386.rpm rpm -i orkbasecxx-0.5-1.i386.rpm rpm -i orkaudio-0.5-1.i386.rpm

Installing under Debian/Ubuntu Linux OrkAudio needs a set of external libraries that can be installed using the debian packaging system Make sure that contrib is listed as a source in /etc/apt/sources.list and install them using the following commands: apt-get install libace-dev apt-get install libboost-dev apt-get install liblog4cpp-dev apt-get install libpcap0.7-dev apt-get install libxerces26-dev apt-get install libsndfile1-dev OrkAudio comes as an archive of dpkg packages such as orkaudio-0.X-X-ubuntu-5.04-i386-binary-DEBs.tar. untar this file in a temporary folder on the target machine and install the packages using the following commands: dpkg -i log4cxx-0.9.7_0.9.7-1_i386.deb dpkg -i orkbasecxx_X.X-1_i386.deb dpkg -i orkaudio_X.X-1_i386.deb

File locations

Audio Output Files 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: 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 SoundDevice.dll - libsounddevice.so : Sound Card based recording 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. Valid values are VoIP.dll and SoundDevice.dll (or libvoip.so and libsounddevice.so under Linux)

Configuring the 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.

Configuring the SoundDevice plugin SoundDevice specific configuration is found in the config.xml file under the SoundDevice tag. The SampleRate 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.

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 orkaudio on the command line.

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 winpcap3.1 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 Ethereal can be useful for that.

Not possible to replay recorded files Recoded wav files should all be replayable by a media player such as Windows Media Player. Here is the checklist Make sure the file is not being processed by OrkAudio. Try again later.

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

OrkWeb - OrkTrack

Installing OrkWeb/OrkTrack need the following prerequiste software: The Java Runtime Environment JRE 5.0 from http://java.sun.com The Apache Tomcat servlet container version 5.X from http://tomcat.apache.org The MySQL server version 4.X from http://www.mysql.com Install the prerequisite software with all defaults and make note of the Tomcat admin password as well as the MySQL root password. OrkWeb/OrkTrack comes in the form of a zip file such as oreka-0.5-2-orkweb-orktrack.zip. Unzip this file into a temporary directory and execute the following steps: 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. 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/ 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. Copy orkweb.war and orktrack.war to the {TOMCAT_HOME}/webapps folder Start Tomcat Tomcat should automatically deploy orktrack and orkweb to {TOMCAT_HOME}/webapps/orktrack and {TOMCAT_HOME}/webapps/orkweb folders 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/... Restart Tomcat

Running Start the database server. Start the Tomcat servlet container and point your browser to http://localhost:8080/orkweb. This will bring up a login screen. Login as admin/admin.

Logging recordings to the database In order to get OrkAudio to report recording activity to OrkTrack, do the followig changes to OrkAudio's config.xml: Set EnableReporting to true. If OrkTrack is deployed on a different server than OrkAudio, set TrackerHostname OrkTrack's hostname. 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.

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 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): Setup OrkAudio to output files in the Tomcat webapps/ROOT directory: edit OrkAudio's config.xml file. Set the AudioOutputPath parameter to the Tomcat webapps/ROOT directory. By default, this is c:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\ROOT under windows. Restart OrkAudio and watch new audio files being written to the Tomcat webapps/ROOT directory. It should now be possible to replay those new recordings using OrkWeb, simply by clicking on the recording's play button.

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

Cannot replay recordings If you fail to replay recordings through OrkWeb, here is the checklist: Make sure you are using Microsoft Internet Explorer Make sure you have followed the procedure described in for getting audio files accessible via http Make sure the file you are looking for is actually present in the Tomcat webapps ROOT folder 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

I don't get the latest recordings Make sure the end date in the multi-criteria seach form is not in the past.