VON@Link
TeamRecord
v1.2 for Linux
VON@Link
TeamRecord
v1.2 for Linux
Last updated: Oct. 31, 2010
1 Introduction
1.1 Who should read this guide
1.2 Conventions
1.3 System requirements
1.4 Installation
1.4.1 Updating an installation
1.5 Obtaining an evaluation serial number
1.6 Codecs2 Network setup
2.1 Using a hub for 6 phones or less
2.2 Using port mirroring on a managed switch for more than 6 phones
2.2.1 Configuring port mirroring on a switch3 Accessing the TeamRecord Web Application
3.1 Web address
3.2 Login
3.3 Changing the password4 Network cards
4.1 Using udev
4.2 Include subnet in discovery
4.3 Exclude IP address from discovery
4.4 Subscription service5 Managing phones
5.1 Discovering phones
5.2 Adding a phone
5.3 Listing phones
5.4 Login as
5.5 Editing a phone
5.6 Deleting a phone
5.7 Advanced phone options
6 Setting record options
6.1 Record remote callers
6.2 Check disk space7 Log
8 Managers
8.1 Adding a Manager
8.2 Listing Managers10 Deleting recordings
Appendix A Configuring cgi-binAppendix B HTML Template Customization
Appendix C Resetting the Administrator PasswordAppendix D Allowing remote administration access
Appendix E Increasing the size of the packet queue
Appendix F Alert notification on queue full
Appendix G Capturing a daily network trace
Appendix H Capturing a network trace for a call
This guide is for persons responsible for installing and administrating VONaLink TeamRecord on Linux.
Read answers to frequently asked questions at www.vonalink.com/faq
Unless otherwise stated:
TeamRecord requires the use of a web server, such as Apache. Install Apache according to your Linux distribution.
If you are using Vonage Click to call or the post record URL, install curl for your Linux distribution.
To install TeamRecord:
During installation, the web application teamrecord is copied into:
/usr/bin/cgi-bin
All other program files are installed into:
/var/opt/vonalink
Calls will be saved to:
/var/opt/vonalink/call
When TeamRecord is already installed and you wish to update the installation, you do not need to un-install. Run install-teamrecord.sh on top of the previous installation. Recordings and configuration are maintained.
Before you can use TeamRecord , you must obtain an evaluation serial number. An evaluation serial number may be requested at www.vonalink.com/download
VoIP phone calls use a variety of algorithms, known as codecs, to encode speech packets. Only G711 codec is supported
TeamRecord works by unobtrusively monitoring network packets as they travel between your phone and VoIP provider. The network setup depends on the type of VoIP phone that you have. For 6 phones or less you could use a 8 port hub. For more than 6 phones, you will need a network switch with SPAN or port mirroring capability.
If your computer has 2 network adapters, TeamRecord can monitor both of them.
Using TeamRecord on a wireless network is not supported.
A network hub is a "dumb" device that allows computers connected to the same hub to read all packets that flow through the hub. Because of this, TeamRecord running on one computer can read the network packets destined for a phone plugged into the same hub. In contrast, a unmanaged network switch is a "smart" device that improves performance by allowing packets between the specified sender and receiver only, so network monitoring is not possible.
The price of a hub is less than that of a unmanaged switch. Because the cost difference between a hub and unmanaged switch is small, and most people prefer the performance of a unmanaged switch, most computer stores stock unmanaged switches. You will need to shop at a store that carry a wide range of network devices to find a hub. Some models are listed on the Support page.
Ports on a router are
switched, so a hub is still needed.. 
A IP phone resembles the typical home phone, but connects directly to a network. A soft phone is a software program that runs on your computer and uses the
connected microphone and headset.
Managed or smart network switches typically have a feature known as port mirroring, port monitoring, or Switched Port Analyzer (SPAN). The network switch is configured such that all traffic from the port designated as the Observe (source) Port is mirrored to the port designated as the Analysis (target) Port. Some models are listed on the Support page.
The following diagram shows the TeamRecord server as having 2 network adapters (NIC). It is possible to have only one adapter and connect it to the Analysis Port of the switch, but the TeamRecord server is then isolated from the rest of the network. To allow TeamRecord server access to and from the rest of the network, a second adapter is needed.
If 2 network adapters are used, set the network adapter used for monitoring with a static IP address.
Follow the steps in the User Guide for your network switch to enable port mirroring. Many of today's switches allow configuration via a web browser. For the Source Port, choose the port that connects to your PBX or broadband. For the Target Port, choose the port that connects to the TeamRecord server. Choose to mirror both send and receive packets.
s
To login from the same machine that TeamRecord is installed, use:
To start things off, a TeamRecord administrator has already been created. The user name is admin and the password is vonalink. Login to TeamRecord with this user. User names and passwords are case sensitive.
During the first login to
TeamRecord as admin, you must change the
password.
Since all TeamRecord systems start with the same initial password for admin,
failure to change the password on your TeamRecord system will allow
unauthorized access.
Click on the Preferences link. Type in a new password in the password fields and click on Save Preferences.
If your server has multiple network interface cards (NIC), you can select which ones to monitor. By default, TeamRecord will monitor up to 2 cards.
Login to TeamRecord as admin, click on Administration link. For security reasons, network configuration is available only if you access TeamRecord from the local machine:
Unselect the Monitor checkboxes of any NIC that you do not wish to monitor, and click on Save Network Configuration. Changes will take effect after you reboot or restart the vonapkt daemon.
To restart the vonapkt daemon:
sudo /etc/init.d/vonapkt.sh restart
If your server has more than one network interface card (NIC), it is recommended that the Linux program udev be used to assign names to the interfaces deterministically.
To assign the motherboard NIC as eth0, and the add-on NIC as eth1, create a rule file in /etc/udev/rules.d
For example, the file could be called 10-nic.rules and contain:
KERNEL=="eth?", SYSFS{address}=="00:30:1b:41:85:54", NAME="eth0" # MAC of
first NIC in lowercase
KERNEL=="eth?", SYSFS{address}=="00:17:9a:7e:7b:e7", NAME="eth1" # MAC of second
NIC in lowercase
By default, phones with IP addresses in the same subnet as the monitoring network card will be discovered. For example, if the IP address of the network card is 192.168.0.100, phones with IP address starting with 192.168.0 will be discovered. To include phones from other subnets, enter the subnet and click on Include Subnet.
If your PBX is on the same subnet as the phones, the PBX must be excluded from the discovery process. Enter the IP address of the PBX and click on Exclude Address.
TeamRecord provides an optional mechanism for custom client application to receive notification of call events. Specify the TCP/IP port to which clients can connect, and click on Save Port.
For security reasons, a client is allowed to connect to the Subscription service only if its IP address is in the allow list. Enter a IP address or a IP subnet, and click on Add Client IP Address.
Login to TeamRecord as admin, click on Administration link. For security reasons, phone management is available only if you access TeamRecord from the local machine:
To show the list of discovered phones on your network, click on Discover link. If a connected phone is not displayed, make an outbound call on that phone and then refresh the web page.
By default, phones with IP addresses in the same subnet as the monitoring network card will be discovered. For example, if the IP address of the network card is 192.168.0.100, phones with IP address starting with 192.168.0 will be discovered. To add other subnets, see Include subnet in discovery.
Click on the link under the Phone column to add a discovered phone using its phone number. This is the preferred method.
| Type | Typically, you specific a phone as a Handset. However, if the handsets are remote and you are recording a PBX, select PBX and enter the number of lines that the PBX will handle. Each line requires a TeamRecord phone license. |
| Phone | Specify the phone number of the phone. |
| Associated phone | Some VoIP providers such as Packet8 use different phone numbers for incoming and outgoing calls. Specify the associated phone number of the phone. |
| Provider | Specify the provider of the VoIP service. If your provider is not listed, choose Other. |
| IP address for audio | This field is used only in the special case where the IP address of the audio packets is different from the phone's IP address. |
| Location | Optionally specify the location of the phone. |
| Group | Optionally assign a phone to a group. The group name cannot contain spaces. Managers may be setup to access certain groups of phones only. Using the API, all phones in a specific group may be deleted. |
| Record incoming calls | Select this checkbox to record incoming calls. |
| Record outgoing calls | Select this checkbox to record outgoing calls. |
| Allow start/stop API | Select this checkbox to allow recording to be started and stopped via API |
| Record frequency | Specify how often calls should be recorded. |
| Allow login | Select this checkbox if you want to allow a user to login to TeamRecord using the phone as the user name. |
| Password | If Allow login is selected, specify a password. |
Click on Add Phone.
Below the Add Phone section of the page is a table showing current phones, if any.
From the list of phones, click on a link under the Phone column. The allows the administrator to login as a specific phone without entering a password.
From the list of phones, click on the Edit link for a phone.
See User Guide.
From the list of phones, click on the Delete link to remove that phone.
| Click to call | Select this checkbox to display a Call link. See User Guide. |
| Allow add/delete phone API | Select this checkbox to allow phones to be added or deleted via API |
Click on Save Advanced Phone Configuration.
Login to TeamRecord as admin, click on Administration link, followed by the Record link. For security reasons, record options are available only if you access TeamRecord from the local machine:
| Case insensitive phone ID | Select this checkbox if your phone IDs contain alphabetic characters and your PBX allow case insensitive phone IDs. |
| Record all remote | Select this checkbox to record inbound calls from all remote callers. Unselect this checkbox if only certain remote callers should be recorded. The latter option is useful if the remote name represents a queue name and you want to record calls only to that queue. |
| Allow start/stop API | Select this checkbox to allow recording to be started and stopped via API |
| Add tag to file name | The record start/stopped
API allows you to associate a tag with the
current call. Select this checkbox to include the tag in the filename.
Do not include a hyphen in the tag.
For example, if the phone ID is jsmith and the tag is 123, the file name would look something like this:
|
| Maximum duration | Specify the maximum duration of a recorded call in minutes. |
| Formats |
Choose between WAV or a compressed audio format. The minimum amount of disk space per minute is 250 K. Recordings are in stereo, with each caller on separate channels. This allows you to open the audio file in a sound editor such as Audacity and listen to the channels separately. |
| Save audio in Z I P file | Select this checkbox and enter a password if you wish to save the audio file within a password protected file. |
| Pre record URL | Specify the URL to call before recording.. |
| Post record URL | Specify the URL to call after recording is completed. |
If Record all remote checkbox is unchecked, specify the list of remote callers to be recorded. This is useful if the remote name represents a queue name and you want to record calls only to that queue. You can also create a Manager that is allowed to see only calls from specific queues.
Click on Save Record Configuration.
It is vital that sufficient free space is available in calls directory. The amount of free space is displayed in the upper right corner of the Calls page. If the amount of free space is less than 10%, the display is shown in red.
Login to TeamRecord as admin, click on Administration link. A log file is created for each day of the week. The log for each new day overwrites the one from one week ago. In this way, you have the last 7 days of logs without having to manually attend to them.
The log files are located under /var/opt/vonalink/log directory. They are named as vona-N.log where N is the day number from 0 to 6. For example, Sunday's log is vona-0.log.
Managers are a class of users that
Login to TeamRecord as admin, click on Administration link, followed by the Managers link.
| Login | Login name |
| Password | Initial password |
| Delete call | Select this checkbox if this Manager is allowed to delete calls |
| Show these groups only | If the Manager is allowed to see only calls from specific groups of phones, enter the names of the groups, separated by space. |
| Show these remote callers only | If the Manager is allowed to see only calls from specific remote
callers, enter the remote number or name. This is useful in a call
center where the inbound queue name is in the remote name of the call.
For example, if the Manager is allowed to see calls from queues:
ENGLISH SUPPORT enter ENGLISH SUPPORT/SPANISH SUPPORT Note the / that is used to separate the two names. |
Click on Add Manager.
Below the Add Manager section of the page is a table showing current Managers, if any.
Login to TeamRecord as admin, click on Administration link, followed by the License link. For security reasons, licensing is available only if you access TeamRecord from the local machine:
This page shows the ID of your computer as generated by TeamRecord. A TeamRecord serial number is associated with a particular computer. You will be asked for computer ID from this page when purchasing TeamRecord.
If your evaluation has expired, you will be not able to login to see the Computer ID. The computer ID can be found in the file:
/var/opt/vonalink/log/id.log
The computer ID is based on the MAC address of network interface eth0. If your server has more than one network interface, see using udev.
TeamRecord is licensed by the number of phones. To record more phones, purchase additional licenses and you will be provided with a new serial number. Enter the new serial number and click on Enter Upgrade Serial Number.
Only admin or Managers with delete call capability can delete recordings. Select the checkbox next to a call and click Delete Selected Calls Permanently.
During installation, the web application teamrecord is copied into:
/usr/bin/cgi-bin
This is the default cgi-bin directory for Ubuntu distribution. If your Linux distribution uses another directory for cgi-bin, you need to create a symbolic link to /usr/bin/cgi-bin/teamrecord
For example, on Gentoo distribution, the default cgi-bin directory is /var/www/localhost/cgi-bin, so create a symbolic link as follows:
cd /var/www/localhost/cgi-bin sudo ln -s /usr/lib/cgi-bin/teamrecord teamrecord
To configure apache to follow symbolic links:
sudo vi /etc/apache2/httpd.conf
and add:
<Directory "/var/www/localhost/cgi-bin">
Options -Indexes FollowSymLinks
</Directory>
The page that you see in the Web Application is generated from a HTML template that you can customized. The template is named TeamRecordTemplate.htm and it is found in /var/opt/vonalink/htm.
Before you change the standard template, it is recommended that you make a backup copy of it. If you comfortable with editing HTML, you can use a text editor to modify the template. Otherwise, use a visual HTML editor. The standard template has an embedded style sheet for controlling fonts and the color of table headings.
TeamRecord defines three comment tags to indicate the position of dynamic content.
| <!VL-USER> | Shows the user name |
| <!VL-TIME> | Shows the time |
| <!VL-BODY> | Shows the body |
Note: Keep the length of each line under 500 characters.
In the event that everyone forgot the password for the user admin, the password can be reset to the default password of vonalink.
PASSWORD=e6fffef1fcf9fefb
By default, some administrative tasks such as phone discovery, adding phones, etc. can only be done if you access TeamRecord locally using the IP address 127.0.0.1, as in:
To disable this security feature so that you can do administration from another machine, do the following:
1. Use a text editor to create the file /var/opt/vonalink/cfg/adminIP.cfg
2. Edit the file to have 1 line as follows:
CHECK_IP=N
This is
an advanced configuration, and may be needed for larger call centers.
TeamRecord uses shared memory to pass network packets between the vonard and vonapkt processes.
If you get the following in the log files (/var/opt/vonalink/log/vona-N.log where N is the day number):
Thu May 1 23:59:51 2008 vonard0: r: 2036 d: 0 p: 1016 m: 733 t: 220922 q: 668999 99% FULL
then the TeamRecord queue size must be increased.
To find out the current OS setting for maximum shared memory:
more /proc/sys/kernel/shmmax
To increase the size of shmmax, see the manual for your Linux distribution. Typically, you edit the file /etc/sysctl.conf
kernel.shmmax = value
To change shmmax at runtime:
sysctl -w kernel.shmmax=value
Use a text editor to create a file called /var/opt/vonalink/cfg/sq.cfg
SLOTS=nslots
nslots is the number of entries that the queue should have. The size of each entry is 220 bytes. Here is an example showing how to calculate this.
Say shmmax was 1G and you want TeamRecord to use 220M for the queue.
nslots = queue size in bytes / 220 bytes
= 220000000 / 220
= 1000000
So, sq.cfg should contain:
SLOTS=1000000
To take effect, restart TeamRecord:
sudo /etc/init.d/vonapkt.sh restart
Check the TeamRecord logs to make sure the queue is allocated successfully:
Fri May 2 00:03:51 2008 Max. shared memory: 1073741824 Fri May 2 00:03:51 2008 SQueue create: slots: 1000000 bytes/slot: 220 Fri May 2 00:03:51 2008 SQueue create: key: 0x3d204 Fri May 2 00:03:51 2008 SQueue create: shmid: 98304 Fri May 2 00:03:51 2008 SQueue create: ID: 0 slots: 1000000 bytes/slot: 220 Fri May 2 00:04:01 2008 SQueue attach: key: 0x3d204 Fri May 2 00:04:01 2008 SQueue attach: shmid: 98304 Fri May 2 00:04:01 2008 Packet Monitor: Attached to shared queue
TeamRecord can launch a shell script when the queue is filled past a threshold. The threshold is 60%.
Create a file called:
/var/opt/vonalink/bin/alert.sh
Two parameters will be passed to the script. The first parameter is the subject. The second parameter is the message body. The file must have execute attribute set.
Typically, the script will send an e-mail message to the administrator.
To test your script, create an empty file:
touch /var/opt/vonalink/spool/event/test.qfull
To troubleshoot fully, it is sometimes necessary to capture the network traffic for an extended period of time. The following is a shell script that can be scheduled to start and stop capture. Since the amount of network traffic can be huge, a series of files are used. When the capture stops, the files are compressed.
1. Copy and paste the following into a file called /var/opt/vonalink/log/trace/logudp.sh
#!/bin/sh
if [[ $1 == "stop" ]]; then
echo "Stopping"
killall tcpdump
for i in /var/opt/vonalink/log/trace/*pcap*
do
echo "Compressing" $i
gzip $i
mv $i.gz /var/opt/vonalink/log/trace/save
done
exit
fi
# Change $nic as needed
#nic="eth1"
outdir="/var/opt/vonalink/log/trace"
# max file size in units of 1,000,000 bytes
maxsize=500
now=`date '+%F-%H-%M'`
outfile=$outdir/$now.pcap
/usr/sbin/tcpdump -i $nic -s 0 -C $maxsize -w $outfile udp &
2. Make logudp.sh executable
chmod +x /var/opt/vonalink/log/trace/logudp.sh
3. Make a directory and change directory permissions
mkdir /var/opt/vonalink/log/trace/save chmod 777 /var/opt/vonalink/log/trace/save chmod 777 /var/opt/vonalink/log/trace
4. Start the script using cron
/var/opt/vonalink/log/trace/logudp.sh
5. Stop the script using cron
/var/opt/vonalink/log/trace/logudp.sh stop
The procedure is performed only if requested by VONaLink technical support.
1. Open up a Terminal window
2. Type:
cd /var/opt/vonalink/log/trace 3. If the computer has one network card, type:
./trace.sh
Go to step 5.
4. If the computer has more than one network card, determine the name of the card being used for monitoring. Type:
ifconfig
The cards are named eth0, eth1, etc. If the card used for monitoring is eth0, type:
./trace.sh eth0
If the card is eth1, type:
./trace.sh eth1
and so on.
5. Talk on your VoIP phone. Hang up.
6. Stop tracing by pressing Ctrl-C
7. A pcap file is saved in the current directory. If the file is large, compress it with gzip.
8. Send the file to Technical Support
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.