VoIPong User's Manual

Murat Balaban


Table of Contents
1. Introduction
2. Features
3. Installation
3.1. Before you proceed: Prerequisites
3.2. Compilation & Installation
3.3. Installation via BSD ports system
4. Dynamic Shared Object Modules (DSOM)
5. Configuration
5.1. Configuration file: voipong.conf
5.1.1. GENERAL section
5.1.2. FILTERS section
5.2. Network - Algorithm mappings: voipongnets
5.2.1. Least False Positive (LFP) algorithm
5.2.2. Fixed (Fixed Port) algorithm
5.2.3. LRA-SIP Algorithm
6. Usage
6.1. Startup Parameters
6.2. Management Console: voipctl
6.3. Running VoIPong with a non-privileged user
6.4. VoIPong Live CD
7. Example Scenarios
7.1. Replaying a previous capture file
7.2. Capturing a Microsoft™ Netmeeting call
8. Frequently Asked Questions
9. Thanks

Chapter 1. Introduction

VoIPong is a sniffer utility which tries to detects Voice Over IP calls on a pipeline, and for those which have vocoder modules loaded, dumps actual conversation to seperate wave files. Currently it can catch calls made via a wide variety of protocols including SIP, H323, Cisco's Skinny Client Protocol. It can also catch calls made through dummy IP adapters which do not do any signalling but transport voice payload via RTP protocol.

It's been written in C language for performance reasons, proved to be running on Solaris, Linux and FreeBSD; though it's thought to compile and run on other platforms as well.

On a 45 Mbit/sec network traffic, it's been verified that VoIPong successfully detected all VoIP gateways and the VoIP calls. CPU utilization during the run has been found ranging between 66% - 80% on a 256MB RAM, Celeron 1700 Mhz Toshiba notebook.

With its powerful and extensible Dynamic Shared Object Modules (DSOM) subsystem, and its related API (will be documented later), new third party voice decoder modules can be coded and installed, resulting in a great flexibility. By default, VoIPong comes with two pre-written voice decoder modules for calls encoded with G711 (u-law) and G711 (a-law) . Audible output can be generated for calls encoded with any one of them.


Chapter 2. Features


Chapter 3. Installation

3.1. Before you proceed: Prerequisites

You should have pcap library installed beforehand. Please download libpcap from tcpdump.org and install it if you don't have it in your system. Please note that most Operating Systems and Linux distributions provide this library in their default installations.

Also, for .WAV file creation, you should have sox and soxmix tools installed. If you don't have those, please download them from sox.sourceforge.net and install it in your system.


3.2. Compilation & Installation

Download the latest VoIPong tarball from EnderUNIX and uncompress it:

# tar zxvf voipong-version.tar.gz
   
There are several pre-written Makefile files in the source directory. Examine each of them and choose the one which most suits your system. If you're running one of the the BSD type Operating Systems (i.e. FreeBSD, OpenBSD, NetBSD, Mac OSX); copy Makefile.bsd as Makefile; if you're using a Linux distribution then, copy Makefile.linux as Makefile. You might need to change CFLAGS and LDFLAGS variables accordingly:
# cp Makefile.bsd Makefile
   
Type make to compile voipong, voipctl and voice decoder modules:
# make
   
Type make install to copy compiled binaries, shared modules, configuration files, manual pages and related documentation into the proper locations:
# make install 
   



3.3. Installation via BSD ports system

BSD Operating Systems (FreeBSD, NetBSD, OpenBSD, Darwin etc.) has a ports system for easy package administration. VoIPong is a FreeBSD port, so you can install it from FreeBSD ports tree. VoIPong is located in /usr/ports/audio/voipong directory:

Change your current working directory to /usr/ports/audio/voipong and type:

# cd /usr/ports/audio/voipong
# make install clean
   
FreeBSD will fetch the tarball, uncompress it, compile the sources and install VoIPong for you.

Alternatively, you can install VoIPong .tbz package with pkg_add (1) command:

# fetch \ 
        ftp://ftp.freebsd.org/pub/FreeBSD/releases/i386/5.4-RELEASE/packages/audio/voipong-2.0.tbz
# pkg_add voipong-2.0.tbz
   



Chapter 4. Dynamic Shared Object Modules (DSOM)

Since release 2.0 upwards, VoIPong provides a powerful dynamic framework for loading of 3rd party voice decoders into the running voipong executable at runtime. This is called Dynamic Shared Object Modules (DSOM) Framework. Simply put, DSOM vocoder modules are shared libraries with the .so extension. VoIPong looks for those shared libraries in the preconfigured modpath directory, loads them one by one. DSOM engine resident at VoIPong core, spots the initialization method in the shared module and invokes it allowing the module to register itself inside VoIPong runtime environment:

07/12/05 13:29:25: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcmu.so (@0x2813e370)
07/12/05 13:29:25: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcma.so (@0x28140390)
07/12/05 13:29:25: loaded 2 module(s)
   


For security reasons, the DSOMs are expected to be owned by the same user and group who is running the core VoIPong executable. For instance, if the user running the program has uid 1000 and gid 10; the modules should also be owned by uid 1000 and gid 10.

The naming convention is that the modules should start with the modvocoder_ keyword, and should include the name of the decoder in the module, followed by the .so extension. For example, the correct name for the g711 (u-law) module can be modvocoder_pcmu.so.

There are two pre-written voice decoder modules with VoIPong release 2.0:



To code and install your own vocoder module (i.e. for g726), VoIPong DSOM Decoder Writer's Guide will be available soon.


Chapter 5. Configuration

Configuration files are all installed into VoIPong directory: /usr/local/etc/voipong. Main configuration parameters are included in voipong.conf file. voipongnets file maps network addresses to their proper algorithms. DSOM modules for g711-ulaw and g711-alaw (modvocoder_pcmu.so, modvocoder_pcma.so) are installed to the path given with the modpath configuration file directive.


5.1. Configuration file: voipong.conf

Runtime configuration parameters vital to the smoothly operation of VoIPong server are defined in voipong.conf, formatted as a standart .ini file. There are two sections: GENERAL for general server settings, and FILTERS for setting up startup filters.


5.1.1. GENERAL section

  • logdir: specifies the log directory where voipong will save its logs e.g. /var/log

  • logfile: name of the main server log file e.g. voipong.log

  • outdir: path where output .WAV and/or .RAW files are to be written. e.g. /var/log/voipoutput

  • cdrfile: name of the CDR (Common Data Record) log file e.g. cdr.log

  • networksfile: path to the network/algorithm mappings file e.g. /usr/local/etc/voipong/voipongnets

  • pidfile: path to the pidfile e.g. /var/run/voipong.pid

  • soxpath: path to the sox executable e.g. /usr/local/bin/sox

  • modpath: path to the directory where vocoder DSOM modules are installed. e.g. /usr/local/etc/voipong/modules

  • soxmixpath: path to the soxmix executable e.g. /usr/local/bin/soxmix

  • mgmt_ipcpath: path to the UNIX domain socket for management console e.g. /tmp/voipongmgmt.sock

  • defalg: Default packet matching algorithm. This can currently only be lfp. Other algorithms are to be developed. e.g. lfp

  • rtp_idle_time: (in seconds) when this amount of time elapses and no RTP traffic is received for the call, the call is considered to be finished. e.g. 10

  • device: network device to sniff packets from e.g. eth0

  • promisc: set this to true 1 if you want VoIpong to set your sniffing device to promiscious mode. e.g. set this to 1 for true, 0 for false.

  • mixwaves: set this to true 1 if you want VoIPong to mix the seperate .WAV files into a single .WAV file. e.g. set this to 1 for true, 0 for false.

  • snaplen: maximum number of bytes to capture e.g. 1500

  • readtmt: specifies the read-from-device timeout in milliseconds. e.g. 500


5.1.2. FILTERS section

  • startup: Pcap filter string. This filter will be set during startup procedures. To see detailed usage of pcap filters, see pcap(3) manual page. e.g. "udp"


5.2. Network - Algorithm mappings: voipongnets

Sniffing out voice is a tough task. You cannot design an algorithm and expect to catch all the VoIP calls. VoIP is relatively new and it is not a highly standardized technology. So there have to be several call catching algorithms for various setups. VoIPong provides a framework where you can set the call catching algorithm which you think will best suit your VoIP infrastructure. This results in a much more specialized and successful call sniffing.


5.2.1. Least False Positive (LFP) algorithm

This algorithm tries to detect calls generated via VoIP devices conforming to RTP and RTCP RFCs. This algorithm should detect and record a broad range of calls. The most obvious advantage of this algorithm is that you'll have barely no false positives. This is why this method is named as LFP. The #1 disadvantage will be that this will not be able to catch calls if there are no RTCP packets or the devices do not conform to RFCs. To use this algorithm, you will need to specify a network to use with it in your voipongnets file.

172.16.1.0/255.255.255.0   lfp
10.30.0.0/255.255.252.0    lfp
       



5.2.2. Fixed (Fixed Port) algorithm

Some VoIP devices (e.g. Grandstream™ IP adapters) use a fixed port to send and receive RTP datagrams, and they do not conform to RFCs, and do not send any link control information (RTCP packets). If you have such devices in your network, you can specify their algorithm as fixed in the voipongnets file. This algorithm cannot be used with networks, it can only be used with hosts, so netmask address should always be 255.255.255.255. Please note that, after the fixed keyword, you are expected to set the fixed port number the device is using. For example, suppose that you have a device which uses port 40000 to send RTP packets, you should add this line to your voipongnets file:

172.16.1.101/255.255.255.255   fixed   40000
       



5.2.3. LRA-SIP Algorithm

LRA-SIP will follow SIP signalling packets, and will spot the RTP/RTCP session from the SDP packets. This algorithm is not implemented yet, however I will be working on it for the next release (probably 2.1.?)


Chapter 6. Usage

Similar to other sniffer tools at the market, VoIPong needs to get a copy of the voice traffic you're interested in. If you're sharing a hub with one of the endpoints of the voice conversation, you will not need to do anything, since hub devices inherently copy traffic to all its ports. If you are in a switched environment, some network administration will be needed. Most modern switch devices has a handy "monitor port" which you can use for copying traffic going through one or more switch ports. So you'll need to copy one of the endpoints' traffic to that monitor port, and connect the computer on which VoIPong is running. If you're running VoIPong on a gateway machine, where this machine has already access to all the voice traffic, you will not need to do anything.


6.1. Startup Parameters

You can use -h switch to see available startup parameters:

[murat@efe ~/voipong]$ ./voipong -h
usage: voipong [options]
options:
-h this screen
-v version info
-f run in foreground (don't become a daemon)
-d debug level. Valid levels are 0 through 4. Default: 0
-c config file path
   
-v switch shows VoIPong version information:
[murat@efe ~/voipong]$ ./voipong -v
EnderUNIX VOIPONG Voice Over IP Sniffer Release 2.0-DEVEL
Copyright (C) 2004 Murat Balaban murat || enderunix.org
All rights reserved.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

For more information on licensing, please see LICENSE
file included in the voipong source distribution.
[murat@efe ~/voipong]$ 
   
You can set the debug log level by -d switch. Valid levels are 0 through 4, latter being the most verbose. Default configuration file is /usr/local/etc/voipong/voipong.conf. You can use alternate configuration file by issuing -c switch and providing full path to the alternate configuration file. If you don't want VoIPong to daemonize, but instead you want it to stay at your terminal and dump log messages to the terminal, you will need to issue -f switch.

So, If you want VoIPong to stay at the terminal, and you want to see as many log messages as possible, you should fire VoIPong as such:

[root@devel ~]$ voipong -d4 -f
EnderUNIX VOIPONG Voice Over IP Sniffer starting...
Release 2.0-DEVEL, running on devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]

(c) Murat Balaban http://www.enderunix.org/
20/11/05 19:33:33: EnderUNIX VOIPONG Voice Over IP Sniffer starting...
20/11/05 19:33:33: Release 2.0-DEVEL running on devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]. (c) Murat Balaban http://www.enderunix.org/ [pid: 23627]
20/11/05 19:33:33: Default matching algorithm: lfp
20/11/05 19:33:33: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcmu.so (@0x2817f3bc)
20/11/05 19:33:33: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcma.so (@0x281813e0)
20/11/05 19:33:33: loaded 2 module(s)
20/11/05 19:33:33: loadnet(10.0.0.145/255.255.255.255) method: fixed 49604
20/11/05 19:33:33: loadnet(172.16.0.10/255.255.0.0) method: lfp 
20/11/05 19:33:33: fxp0 has been opened in  promisc mode. (43.43.43.0/255.255.255.192)
   



6.2. Management Console: voipctl

VoIPong provides the user with the ability to administer the server at runtime. You can use voipctl command for this purpose. When fired, voipctl will connect VoIPong and will wait for user's commands:

[root@efe ~/voipong]$ voipctl 

Connected to VoIPong Management Console

System:
efe.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]


voipong> 
   
help is the same old "help":
voipong> help
Commands:
help : this one
quit : quit management console
uptime : Server uptime
setdebug [level] : set debug level to [level]
logrotate : rotate server's logs
shutdown : shutdown server
rusage : CPU usage statistics for the server
loadnets : Reload voipongnets file
info : General server information
shcall : Show currently monitored calls
shrtcp : Show currently RTCP cache
killcall [id] : end monitoring session with [id]
voipong> 
   
uptime shows how long the server has been running:
voipong> uptime
Server uptime: 5 minutes 57 seconds

voipong>
   
!!: You can use !! command to issue the last command you typed. (same as in sh):
voipong> !!
Server uptime: 6 minutes 13 seconds

voipong>
   
logrotate command rotates server logs:
voipong> logrotate
Logrotate successfull
voipong>
   
shutdown command will shutdown the server and close management console connection
voipong> shutdown
   
rusage command will give information related to server's CPU utilization
voipong> rusage

Current CPU usage stats:
----------------------------------------
Total "user" time : 0 seconds
Total used "system" time : 0 seconds
Shared Memory Size : 384 KB
Integral Memory Size : 1512 KB
Integral stack Size : 1024 KB
Page requests : 70
Page errors : 0
Block input operations : 0
Block output operations : 2
Messages sent : 1
Messages received : 1
Signals : 0
Voluntary "context switch"s : 78
Involuntary "context switch"s : 1
voipong> 
   
loadnets command will re-read voipongnets and re-load network/algorithms mapping table
voipong> loadnets
Networks file has been reloaded successfuly
voipong>
   
info command will give general server information
voipong> info

General Server Info:
--------------------------:
Server version : Release 2.0-DEVEL
System : efe.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]
Current work. direct. : /usr/home/murat/voipong
Log level : 4
Process ID (PID) : 16240
User : root [Charlie &]
Group : 0
voipong> 
   
setdebug command will change runtime log verbosity
voipong> setdebug 4
# set new debug level to 4

voipong>
   
shcall command will list calls currently monitored
voipong> shcall



ID    NODE1            PORT1 NODE2            PORT2 STIME             DURATION 
----- ---------------- ----- ---------------- ----- ----------------- ------------

01123 41.27.13.1       12000 31.12.11.8       24000 24/10/05 11:11:23 33 seconds

Total listed: 1
voipong> 
   
shrtcp command will show current RTCP cache
voipong> shrtcp



ID    NODE1            PORT1 NODE2            PORT2 STIME            
----- ---------------- ----- ---------------- ----- -----------------

01123 41.27.13.1       12001 31.12.11.8       24001 24/10/05 11:11:23

Total listed: 1
voipong>
   
killcall will end monitoring the call by id
voipong> killcall 2
transport_simplecmd: server returned error: No such session by ID: 2

cannot process killcall command
voipong> 
   
q, quit, exit commands will end management session
voipong> q
Bye!
[root@efe /home/murat/voipong]$ 
   



6.3. Running VoIPong with a non-privileged user

It is strongly advised that you avoid running VoIPong with super-user, but use a non-privileged special user created only for it. This section describes the steps you should take to accomplish this. Note that these steps should be done after you compiled and installed VoIPong successfully.

  • Create voipong user and group

    # pw group add voipong
    # pw user add voipong -g voipong -m -s /usr/local/bin/bash
       
    
  • Change ownership of voipong, voipctl and /usr/local/etc/voipong directory to voipong user:

    # chown voipong /usr/local/bin/voipong
    # chown voipong /usr/local/bin/voipctl
    # chown -R voipong /usr/local/etc/voipong
    # chgrp -R voipong /usr/local/etc/voipong
       
    
  • Change ownership of BPF device files (/dev/bpf*) to voipong user:

    # chown voipong /dev/bpf*
       
    
  • Switch user to voipong:

    # su - voipong
    To see all of the directories on your FreeBSD system, type
    
            ls -R / | more
                    -- Dru genesis@istar.ca
    %
       
    
  • Create runtime directories:

    % mkdir logs
    % mkdir output
    % mkdir run
       
    
  • Change log, pid and output directory paths to the new directories in voipong.conf

    logdir = /home/voipong/logs/
    logfile = voipong.log
    outdir = /home/voipong/output/
    cdrfile = /home/voipong/output/voipcdr.log
    pidfile = /home/voipong/run/voipong.pid
    mgmt_ipcpath = /home/voipong/run/voipongmgmt.sock
       
    
  • You can now run voipong

    % id
    uid=1042(voipong) gid=1042(voipong) groups=1042(voipong)
    % voipong -d4 -f
    EnderUNIX VOIPONG Voice Over IP Sniffer starting...
    Release 2.0-DEVEL, running on devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]
    
    (c) Murat Balaban http://www.enderunix.org/
    20/11/05 22:34:03: EnderUNIX VOIPONG Voice Over IP Sniffer starting...
    20/11/05 22:34:03: Release 2.0-DEVEL running on devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]. (c) Murat Balaban http://www.enderunix.org/ [pid: 41334]
    20/11/05 22:34:03: Default matching algorithm: lfp
    20/11/05 22:34:03: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcmu.so (@0x2817f3bc)
    20/11/05 22:34:03: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcma.so (@0x281813e0)
    20/11/05 22:34:03: loaded 2 module(s)
    20/11/05 22:34:03: loadnet(10.0.0.145/255.255.255.255) method: fixed 49604
    20/11/05 22:34:03: loadnet(172.16.0.10/255.255.0.0) method: lfp 
    20/11/05 22:34:03: fxp0 has been opened in  promisc mode. (43.43.43.0/255.255.255.128)
       
    
  • You can check whether the daemon is running with the correct user with voipctl

    % id
    uid=1042(voipong) gid=1042(voipong) groups=1042(voipong)
    % voipctl
    
    
    
    Connected to VoIPong Management Console
    
    System:
    devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]
    
    
    voipong> info
    
    General Server Info:
    --------------------------:
    Server version            : Release 2.0-DEVEL
    System                    : devel.enderunix.org [FreeBSD 4.11-STABLE FreeBSD 4.11-STABLE #0: Tue Sep i386]
    Current work. direct.     : /usr/home/voipong
    Log level                 : 4
    Mix Voice Flag            : true
    Process ID (PID)          : 41334
    User                      : voipong [VoIPong Kullanicisi]
    Group                     : 1042
    voipong> 
       
    

6.4. VoIPong Live CD

Omer Faruk Sen maintains VoIPong LiveCD! based on FreeSBIE project. LiveCD is an ISO image which can be burnt into a blank CD directly, and includes pre-installed VoIPong release along with several boot-time scripts for configuring the OS and VoIPong.

Please find the gzip'ed ISO images here:


Chapter 7. Example Scenarios

You can try VoIPong with Microsoft Netmeeting. Set up netmeeting so that it uses G711 at both ends, and make a voice call. You'll see the calls captured and wave files created after your call finishes.

If you do not have a testbed, do not want so much pain to test VoIPong, you can replay a test capture file in your machine and see if it is catched.


7.1. Replaying a previous capture file

  • Download this test call capture, where me and Baris are talking about EnderUNIX team.

  • Download and install tcpreplay tool. Tcpreplay tool reads pcap capture files, and re-injects the packets into a live network.

  • Start VoIPong

    04/12/05 16:27:20: EnderUNIX VOIPONG Voice Over IP Sniffer starting...
    04/12/05 16:27:20: Release 2.0-DEVEL running on efe.enderunix.org [FreeBSD 5.4-STABLE FreeBSD 5.4-STABLE #0: Sun Oct 23 16:39:41 EEST 2005     mb@efe.enderunix.org:/usr/src/sys/i386/compile/EFE i386]. (c) Murat Balaban http://www.enderunix.org/ [pid: 1075]
    04/12/05 16:27:20: Default matching algorithm: lfp
    04/12/05 16:27:20: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcmu.so (@0x2817f3bc)
    04/12/05 16:27:20: loadmodule: /usr/local/etc/voipong/modules/modvocoder_pcma.so (@0x281813e0)
    04/12/05 16:27:20: loaded 2 module(s)
    04/12/05 16:27:20: loadnet(10.30.0.11/255.255.255.255) method: fixed 40000
    04/12/05 16:27:20: em0 has been opened in  promisc mode. (192.168.1.0/255.255.255.0)
       
    
  • Start tcpreplay with the test capture you just downloaded at step 1.

    [root@efe ~/calls/ok]$ /usr/local/sbin/tcpreplay -i em0 endercall2.pcap
    sending on: em0
     4534 packets (1344595 bytes) sent in 141.44 seconds
     9506.2 bytes/sec 0.07 megabits/sec 32 packets/sec
       
    
  • You will see that VoIPong immediately starts monitoring your call. Following lines will appear in your voipong.log file:

    24/10/05 20:47:23: created a call recording instance!
    24/10/05 20:47:23: [68826] VoIP call has been detected.
    24/10/05 20:47:23: [68826] 10.0.0.145:49604 < -- > 10.0.0.200:49606
    24/10/05 20:47:23: [68826] Encoding 0-PCMU-8KHz, recording.......
       
    

    At the end of the call, you'll see that two .WAV files are created:

    24/10/05 20:52:52: [68826] maximum idle time [10 secs] has been elapsed for this call, the call might have been ended.
    24/10/05 20:52:52: [68826] .WAV file output/20051204/session-enc0-PCMU-8KHz-10.0.0.145,49604-10.0.0.200,49606.wav has been created successfully
    24/10/05 20:52:52: [68826] .WAV file output/20051204/session-enc0-PCMU-8KHz-10.0.0.200,49606-10.0.0.145,49604.wav has been created successfully
       
    
    # ls /var/log/output/20051024/
    session-enc0-PCMU-8KHz-10.0.0.200,49606-10.0.0.145,49604.wav        session-enc0-PCMU-8KHz-10.0.0.145,49604-10.0.0.200,49606.wav
       
    
  • You can play output files with several utilities including play, xmms etc.:

    # play /var/log/voipoutput/20051025/session-enc0-PCMU-8KHz-10.0.0.145,49604-10.0.0.200,49606.wav
       
    

Chapter 8. Frequently Asked Questions

This is a a non-complete list of questions frequently asked at voipong mailing list. You can have a more recent and updated one within the FAQ at VoIPong web site.


Chapter 9. Thanks

Please find a list of people and organizations who contributed or gave support to VoIPong here .