Oreka TR 1.8 - Quick Start Guide

Revision 2692

Chapter 1. Introduction

WARNING: This guide covers quick setting up of Oreka TR for port mirroring. For any other uses, such as TDM recording or SIPREC recording, please get in touch with <support@orecx.com>

The main Oreka TR components are listed below:

OrkAudio: this is the audio capture background service. It supports VoIP and TDM based recording.
OrkTrack: this service centrally tracks activity on the entire system and logs recordings to any popular SQL database.
OrkWeb: this service is the web interface accessible via any standard compliant web browser. It relies on the Tomcat web server.

For the sake of simplicity, Oreka TR will be referred to simply as Oreka in the rest of this document.

Chapter 2. Pre-requisites

Table of Contents

Server Specs
Operating System
Database
Getting VoIP traffic to the Oreka Server
About Audio Files

Server Specs

Test Server (PC or Laptop)

Pentium IV or Atom, 1 GHz CPU
512 MB RAM
500 MB Hard Drive

Production Server

0-20 concurrent calls: Atom 1GHz
0-100 concurrent calls: two cores, 2.6 GHz, 4MB L2 cache
100-200 concurrent calls: four cores, 2.6 GHz, 8MB L2 cache
Over 200 concurrent calls: four cores CPU 2.6 GHz, 12MB L2 cache
4 GB RAM
2 fast Hard Drives (Server grade 10K RPM), one for the OS, one for storing the recordings

Operating System

Oreka TR runs on Linux and Windows platforms.

OrecX's preferred platform is Linux CentOS 6 - 64 bit. All desktop and server versions of Windows are supported, starting from Windows XP and 2003 server.

For support of other operating systems, please inquire at <support@orecx.com>.

Database

MySQL is recommended as Orecx LLC's primary database environment. Oreka also supports most major database systems including Oracle, MS-SQL and PostgreSQL.

Getting VoIP traffic to the Oreka Server

Before Oreka can start recording, ensure that VoIP traffic is seen on a server interface. Use SPAN monitoring (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 Signaling server (e.g. SIP proxy, Cisco Call Manager, Avaya Communication Manager, ...)

This is to ensure that both the media traffic (RTP) and signaling (SIP, Skinny, H.323, UNISTIM, ...) are intercepted by the recorder. Use a packet analyzer such as the free Wireshark tool to verify that both types of packets are appearing on the Oreka server's interface.

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

Here is an example port mirroring configuration guide by Cisco: http://www.cisco.com/en/US/products/hw/switches/ps708/products_tech_note09186a008015c612.shtml

Alternative mechanisms to get VoIP traffic

Port mirroring is the recommended packet capture mechanism, but if port mirroring is not an option, Oreka can intercept packets through other mechanisms:

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.
Set up the machine as an Ethernet bridge inserted in the Ethernet path. Not recommended, do this only for testing.

About Audio Files

Oreka uses the compressed GSM format to store audio recording files.

This format uses about 1.6 KBytes for 1 sec of recording (or 13 kbits/sec).

As an example, 2,000 hours of audio would require approximately 10 GBs of disk space.

Chapter 3. Installing Oreka

Table of Contents

Installing on Linux
Installing on Windows
Installing on Multiple Servers
Applying License Files

Installing on Linux

Here are the steps to install Oreka using installers on Linux, mainly CentOS and RedHat. Other Linux systems may require RPM files. For more information, contact <support@orecx.com>.

Requirements

You need to be logged in as "root" to install the Oreka software.
You need an internet connection to download MySQL, Java and Tomcat.

Typical Installation

Install OrkAudio:
- Use the installer file provided to you by OrecX, e.g. orkaudio-1.6-819-x2546.i386.centos6-installer.sh.tar
- Untar it: tar -xvf orkaudio-1.6-819-x2546.i386.centos6-installer.sh.tar.
- Run the installer: ./orkaudio-1.6-819-x2546.i386.centos6-installer.sh.tar (accept all required components)
Install OrkWeb (includes OrkTrack):
OrkWeb and OrkTrack require a database engine, preferably MySQL, Java and Tomcat. Java and Tomcat are downloaded and installed by the OrkWeb installer provided to you by OrecX. MySQL, on the other hand, needs to be downloaded and installed separately.
- If the database server (MySQL) is not already installed, install it: e.g. yum install mysql-server
- If the MySQL service is not already running, start it: e.g. service mysqld start
- Make sure that MySQL will restart automatically after a system reboot: e.g. chkconfig mysqld on
- Untar the OrkWeb installer provided to you by OrecX: e.g. tar -xvf orkweb-1.7-2586-linux-installer.sh.tar
- Run the installer: ./orkweb-1.7-2586-linux-installer.sh.tar
The OrkWeb installer will prompt you for the MySQL "root" user password. By default, MySQL is installed with no default password. The installer will then prompt you for the installation of Java and Tomcat. Accept the default directories. It will finally install OrkWeb and OrkTrack under Tomcat.
The installer configures the Tomcat service to be automatically started after a reboot. However, it will not run the Tomcat service at the end of the installation. You will need to start it yourself after you apply the license file, as described in a later section.

Installing on Windows

Requirements

You need to be logged in as Administrator before proceeding.
Access to the internet is highly recommended for download of the Oreka software, and MySQL.

Installation

Install OrkAudio
Use the installer file provided to you by OrecX, e.g. orkaudio-1.7-862-x2688-win32-vc9.zip. Copy this file to a temporary folder on the target machine, unzip it and run the embedded executable. This will install WinPcap as well as OrkAudio.
Install OrkWeb (includes OrkTrack)
OrkWeb and OrkTrack require a database engine, preferably MySQL, Java and Tomcat. Java and Tomcat are included in the OrkWeb installer provided to you by OrecX. However, MySQL needs to be downloaded and installed separately.
- Install MySQL: you can download the MySQL Windows Essentials for your platform at http://dev.mysql.com/downloads/mysql/5.6.html#win32. Install it accepting all the defaults. Take note of the "root" password if you assign one. It will be needed when you install OrkWeb.
- Install OrkWeb: unzip the OrkWeb installer provided to you by OrecX, e.g. orkweb-1.7-2586-win32-installer.zip.
- Run the embedded executable. This will first install Java, then Tomcat (accept all default options) and finally OrkWeb and OrkTrack.
- Make sure to enter the correct MySQL "root" password when installing OrkWeb. You can always update it later in the database.hbm.xml file in the OrkWeb installation folder (C:\Program Files\OrkWeb) by default.

Installing on Multiple Servers

When installing on multiple servers, the recorder (OrkAudio) runs on a different server than OrkWeb/OrkTrack. Thus, additional configuration is required. Here's a brief summary.

Communication with OrkTrack

The recorder needs to communicate to OrkTrack to report the recording metadata to be stored in the database. Thus, it needs to know where OrkTrack is running.

Make sure the <TrackerHostname> entry in the OrkAudio config.xml is properly set to the OrkWeb/OrkTrack hostname or IP address.

OrkWeb access to media files

For OrkWeb to be able to access the media files stored on the recorder's server, a web server application such as Apache httpd or Apache Tomcat needs to be installed and configured on the recorder's server. For a quick solution, use the OrkWeb installer and install only the Tomcat and Java Run-Time components. E.g., run ./orkweb-1.7-2586-x64-linux-installer.sh --nomysql --nooreka on Linux. In Windows, you can stop the installer after Java and Tomcat are installed.

For more details, contact <support@orecx.com>.

Applying License Files

When you request a trial setup, OrecX provides you with license files. You need to apply those licenses files to OrkAudio and OrkWeb for Oreka as a whole to run correctly.

Applying the OrkAudio License File

Store the OrkAudio license file (e.g. orkaudio-30-days-trial-license-20131005.txt) provided to you by OrecX in the folder where OrkAudio was installed, typically /etc/orkaudio in Linux and C:\Program Files\OrkAudio on Windows. Make sure to rename the file to license.txt.

Warning: under Windows, you need to make sure file extensions are shown (go to My Computer/Explore/Tools/Folder Options/View and uncheck "Hide extensions for known file types"). Otherwise you risk naming the file licence.txt.txt without realizing it.

Whenever a new license file is applied, the orkaudio service must be restarted for the change to take effect.

Applying the OrkWeb License File

To apply the OrkWeb license file, e.g. orkweb-30-days-trial-license-20131005.txt copy and paste its content into the Input License box in OrkWeb, accessible from the login page the first time the software is accessed, or from the Account page at subsequent tries.

Chapter 4. Running Oreka

Table of Contents

Starting OrkAudio
Starting OrkWeb and OrkTrack
Accessing OrkWeb (User Interface)

Once Oreka is installed and VoIP traffic is properly detected at one of the interfaces, Oreka is ready to start recording. Ensure that OrkAudio and OrkWeb/OrkTrack (i.e. Tomcat) services are running.

Also, it is very important that VoIP traffic is correctly reaching the Oreka server. If you are unsure whether this is the case, refer to section the section called “Getting VoIP traffic to the Oreka Server” before proceeding.

Starting OrkAudio

On Linux

Start : start the OrkAudio service, e.g. "service orkaudio start".
Storage: by default, OrkAudio stores audio files in the /var/log/orkaudio/audio directory, using a date-based directory hierarchy.
Logging: OrkAudio logs important messages to files under /var/log/orkaudio, mainly orkaudio.log.

In Windows

Start : start the OrkAudio service with Start/Run..., then type services.msc. This opens the Services Manager application. Start the service by right-clicking on OrkAudio and choosing Start.
Storage: by default, OrkAudio stores audio files to C:\oreka\audio, using a date-based directory hierarchy.
Logging: OrkAudio writes log info to the installation folder, the default being C:\Program Files\OrkAudio. The main file is orkaudio.log.

Starting OrkWeb and OrkTrack

On Linux

Start : before starting OrkWeb and OrkTrack, ensure that the database server is running. Start the Tomcat web server where OrkWeb and OrkTrack are installed (e.g. "service tomcat start").
Logging: Tomcat writes log information to the /opt/tomcat5/conf/logs/catalina.out file, while OrkWeb and OrkTrack write to /var/log/orkweb/orkweb.log.

In Windows

Start : before starting OrkWeb and OrkTrack, ensure that the database server is running. Then start the Tomcat web server where OrkWeb and OrkTrack are installed. Go to Start/Run... and type services.msc. This opens the Services Manager application. Start Tomcat by right-clicking on the Apache Tomcat service and choosing Start.
Logging: Tomcat writes log information to the Tomcat logs folder, the default being C:\Program Files\Apache Software Foundation\Tomcat 7.0\logs\catalina.out. OrkWeb and OrkTrack write their log to C:\Program Files\OrkWeb\orkweb.log.

Accessing OrkWeb (User Interface)

Open any standard web Browser and type the following URL: http://localhost:8080/orkweb. If you are accessing from a location other than the server on which Oreka was installed, replace localhost with the hostname or IP address of the Oreka server.

This will bring up a login screen. Login as admin/admin.

You will be presented with a license input screen. Copy the content of the license text file issued to you by OrecX and paste it into the text box.

Congratulations: you are now ready to start using Oreka!

Chapter 5. Troubleshooting

Table of Contents

OrkAudio is not recording
OrkAudio recordings only appear as .mcf files
OrkWeb not accessible
Cannot play back recordings in OrkWeb
Local and Remote party appear as IP addresses
Cannot hear audio when listening to a call in Live Monitoring
No recordings appear in the Browse page

Below are the most common questions that arise from the installation process. If you are still having issues after you consult these tips, contact <support@orecx.com>.

OrkAudio is not recording

OrkAudio is not recording. No files are appearing under the <AudioOutputPath> directory configured in OrkAudio's config.xml file.

Verify that there is VoIP traffic reaching the Oreka server. You can do this using a third-party tool such as WireShark. Refer to the section called “Getting VoIP traffic to the Oreka Server” for more detail.
Ensure that the OrkAudio service is running.
Ensure that the OrkAudio license file is properly applied and has not expired. To verify, you can restart the orkaudio service and check at the bottom of the orkaudio.log file to see if the last re-start, marked by "OrkAudio service starting", shows any license-related ERROR.
It may be that OrkAudio is listening to the wrong interface. Configure it to listen on the right NIC(s) by editing the <Devices> parameter in the config.xml. You will need to restart the orkaudio service for the change to take effect. A list of available devices is output to the orkaudio.log file when OrkAudio starts up. Here are a couple of configuration examples:
- Linux: <Devices> eth1, eth2 </Devices>
- Windows: <Devices> \Device\NPF_{43FAFE81-8776-1334-9EB3-B273CCA778C5} </Devices>

OrkAudio recordings only appear as .mcf files

OrkAudio does not seem to be recording properly: only .mcf files appear in the audio folders. There are no .wav files.

Ensure that the OrkAudio license file is properly applied and has not expired. To verify, you can restart the orkaudio service and check at the bottom of the orkaudio.log file to see if the last restart marked by "OrkAudio service starting" shows any license-related ERROR. See the section called “Starting OrkAudio” for the location of the log files.

OrkWeb not accessible

Accessing OrkWeb from the Browser does not work.

Ensure that the database engine, e.g. MySQL, is running properly.
Ensure Tomcat is running properly. One way to verify is to try http://localhost:8080. You should get the Tomcat page. If you don't, Tomcat is not running (replace "localhost" in the URL with the hostname or IP address of the Oreka server if the Browser is running at another location than the Oreka server).
Ensure that port 8080 is not blocked by a firewall or other such program.

If all the conditions above are met, you can look into the Tomcat and OrkWeb log files for more information. See the section called “Starting OrkWeb and OrkTrack” for the location of the log files.

Note: if accessing Tomcat returns Error 404, restart the Tomcat service.

Cannot play back recordings in OrkWeb

OrkWeb is running well, but playing back recordings does not work.

For audio files, make sure that you can play them directly into a media player such as Windows Media Player. This is to verify that there is no audio device or driver problem on your workstation.
For audio files, make sure that the AudioOutputPath entry in the OrkAudio config.xml file matches the corresponding docBase entry in Tomcat's server.xml for path="/audio". If either of these entries need to be modified, restart its corresponding service (OrkAudio or Tomcat).
Open the Sun Java Console (e.g. available from the Tools menu in Internet Explorer) and note what happens when you attempt to play back the file.

You can also look into the Tomcat and OrkWeb log files for more information. See the section called “Starting OrkWeb and OrkTrack” for the location of the log files.

Local and Remote party appear as IP addresses

Recordings Local and Remote party appear as IP addresses instead of phone numbers or extensions in OrkWeb.

Very often this is an issue of Oreka seeing only the RTP packets (media) and not the signalling packets (SIP, Skinny, Avaya, ...). Verify that you are properly getting all voice packets to the Oreka server. Use a network monitor utility such as WireShark if necessary.

Cannot hear audio when listening to a call in Live Monitoring

There is no audio when listening to calls in the Live Monitoring page.

Make sure port 59120 is not blocked by a firewall or other such program.
Open the Sun Java Console (e.g. available from the Tools menu in Internet Explorer) and note what happens when you attempt to listen to a call.

No recordings appear in the Browse page

No recordings appear in the Browse page.

Make sure the End date in the multi-criteria search form is not in the past.