From d72580401d00361c328649ecff4c35835c7bd882 Mon Sep 17 00:00:00 2001 From: Henri Herscher Date: Thu, 23 Mar 2006 17:15:42 +0000 Subject: First checkin git-svn-id: https://oreka.svn.sourceforge.net/svnroot/oreka/trunk@200 09dcff7a-b715-0410-9601-b79a96267cd0 --- documentation/oreka-user-manual.xml | 633 ++++++++++++++++++++++++++++++++++++ 1 file changed, 633 insertions(+) create mode 100644 documentation/oreka-user-manual.xml (limited to 'documentation/oreka-user-manual.xml') diff --git a/documentation/oreka-user-manual.xml b/documentation/oreka-user-manual.xml new file mode 100644 index 0000000..9823e08 --- /dev/null +++ b/documentation/oreka-user-manual.xml @@ -0,0 +1,633 @@ + + + + + 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 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. +
+ +
+ + \ No newline at end of file -- cgit v1.2.3