Oreka 0.6 Open Source User Manual
Revision 2
OrecX LLC
2007
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 by default. This can be changed using the AudioOutputPath configuration parameter described in . 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)
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: myrecordings-, nativecallid]]>
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 .
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.