Copyright © 2004 , 2005 Murat Balaban. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
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 actual 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.
Simple, optimized, extendable, fast code
Easy debugging
Easy installation and administration
Powerful management console (voipctl) for run-time server administration
Detailed logging
CSV style CDR (Call Detail Record) logs
Dynamic framework for multiple call-catching algorithms to co-exist together
Dynamic Shared Object Modules (DSOM) for loading of third party voice codec modules at runtime.
Users can choose the best algorithm to suit their networks.
Produces audible output (.wav) for G711 (u-law) and G711 (a-law) codecs.
Output can be merged into one single file via soxmix.
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.
Download the latest VoIPong tarball from EnderUNIX and uncompress it:
# tar zxvf voipong-version.tar.gzThere 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 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 MakefileType make to compile voipong, voipctl and voice decoder modules:
# makeType make install to copy compiled binaries, shared modules, configuration files, manual pages and related documentation into the proper locations:
# make install
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 cleanFreeBSD 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
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:
modvocoder_pcmu.so: g711 (u-law) decoder (payload type 0)
modvocoder_pcma.so: g711 (a-law) decoder (payload type 8)
To code and install your own vocoder module (i.e. for g726), VoIPong DSOM Decoder Writer's Guide will be available soon.
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.
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.
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
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"
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.
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
Some VoIP devices (e.g. Grandstream(TM) 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
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.?)
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.
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)
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> shutdownrusage 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]$
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>
Omer Faruk Sen has 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:
Version 2.0 MD5: 2458d372b0113771eb642987ce0b2f43
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.
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
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.
Please find a list of people and organizations who contributed or gave support to VoIPong here .