Table of Contents
Table of Contents
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.
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.
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.
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.
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:
This is to ensure that both the media traffic (RTP) and signalling (SIP, Skinny, H.323, UNISTIM, ...) 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:
Table of Contents
OrkAudio comes as an automated installer for Windows. Get it at orkaudio-1.2-673-os-win32-installer.zip. Copy this file in a temporary folder on the target machine and run the installer by double clicking this file.
An OrkAudio installer for CentOS 5, 32-bit is available at orkaudio-1.2-671-os-i386.centos5-installer.sh.tar. After you download it, untar it (e.g. tar -xvf) and run it accepting all default options.
OrkAudio also 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
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
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_capturePort.extension
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 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 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)
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)
AudioOutputPath this parameter controls the root directory where capture and storage audio files are stored. It can be a relative or absolute path.
TapeFileNaming 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:
<TapeFileNaming>myrecordings-, nativecallid</TapeFileNaming>
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 the section called “Audio Output Files”. See the section called “Configure audio files path and file names” for more details.
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.
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.
OrkAudio gives you the ability to configure the path and file name of the recorded audio files. To modify the default naming scheme:
Here are the dynamic keywords accepted as in the TapeFileNaming and TapePathNaming directives:
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.
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.
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.
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.
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.
Table of Contents
OrkWeb/OrkTrack need the following prerequiste software:
Start by installing MySQL or any database compatible with hibernate.
Then use the OrkWeb Windows installer orkweb-1.2-669-os-win32-installer.zip or Linux installer orkweb-1.2-669-os-linux-installer.sh.tar. The Linux installer works on RHEL, CentOS, Fedora and Linux SuSE.
Install the prerequisite software above, accepting 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-1.2-669-orktrack-orkweb.zip. Unzip this file into a temporary directory and execute the following steps:
In order to get OrkAudio to report recording activity to OrkTrack, do the followig changes to OrkAudio's config.xml:
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.
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.
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 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):
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.
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”
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 the section called “Replaying recordings” 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 the section called “Not possible to replay recorded files”