View on
Michael Robinton > Net-Connection-Sniffer-0.36 > Net::Connection::Sniffer



Annotate this POD

View/Report Bugs
Module Version: 0.36   Source  


Net::Connection::Sniffer -- gather stats on network connections


  use Net::Connection::Sniffer;



Net::Connection::Sniffer is a perl module to gather connection statistics by listening to ethernet traffic. Traffic is filtered using standard BPF notation as described in the tcpdump documentation and implemented using the standard pcap library to sniff packets on host network interfaces.


Create a directory with appropriate permissions for the pid file and the profile statistics dump file. Typical installation:

  mkdir -p /var/run/nc.sniffer

Edit the file to change or set the following:

  my $config = {

  # specify the directory for the pid file for this daemon.
  # The directory must exist and have writable permissions.
  # [required]
        piddir  =>  '/var/run/nc.sniffer',

  # specify the directory for the statistics file for this 
  # daemon. The directory must exist and have writable
  # permissions
  # [required]
        sniffer =>  '/var/run/nc.sniffer',

  # BPF filter statement. See examples below.
  # [required]
        bpf     => 'src host and tcp port 80',

  # size of the portion of packet to capture, defaults
  # to the minimum size necessary to determine the
  # source and destination IP addresses and port numbers
  # [optional]          ETH_head + IPV4_head + 4

  #     snaplen => 38,

  # filter condition: payload must contain this string.
  # case insensitive match of the payload data to this string. 
  # [optional]

  #     match   => 'somestring',

  # filter condition: payload must NOT contain this string.
  # case insensitive match of the payload data to this string.
  # [optional]

  #     nomatch => 'some.other.string',

  # offset of the payload from the packet start
  # typically at least 60 for tcp, 44 for udp
  # [optional]... but [required] for 'match', 'nomatch'
  #     payload => 44,

  # UDP listen port to trigger a dump file
  # [optional]
        port    => 10004,

  # HOST address on which to listen for dump request
  # may be one of a HOSTNAME, IP address, or
  # [optional] default == INADDR_LOOPBACK
        host    => 'INADDR_LOOPBACK',

  # ALLOWED connecting host(s)
  # may be HOSTNAME or IP address
  # [optional] default
        allowed => ['',],


To generate a web report to STDOUT with or without a cache file, edit the nc.sniffer.cgi.sample file to change or set the configuration parameters. See Net::Connection::Sniffer::Report::web_report or the sample file for details.

  Usage: <!--#exec cmd="./nc.sniffer.cgi 0" -->
    or   <!--#exec cmd="./nc.sniffer.cgi 1" -->

where an argument of "0" produces a report ordered by /24 by usage and an argument of "1" produces a report ordered by subdomain by usage.

REMOTE CONFIGURATION, multiple hosts ^

To configure the reporting function to retrieve statistics from multiple remote hosts (and localhost) do the following:

        1) read the config section of
        2) read the config section of

On the remote host(s), install in an appropriate sandbox account and install an ssh certificate to permit access to the sandbox ssh executable as well as the directory from which to rsync the stats file on that host. should be installed mode 755 or as appropriate to be accessed remotely by the ssh -e function.

On the web host, configure nc.sniffer.coalesce.cgi and place the execution cgi string in your web page to produce the report

nc.sniffer.coalesce.cgi should be SUID to the web user, not root, so that the web engine can safely execute the script. The ssh certificate must be generated for the web user and go in the nobody:nogroup/.ssh directory (or equivalent web user directory).

  usage: <!--#exec cmd="./nc.sniffer.coalesce.cgi" -->


Launch the daemon with the command: start

  Syntax: start

          -d switch may be added to
           redirect output to STDERR

On most systems it will be necessary to wrap a shell script around if the path for perl is not in scope during boot.

  # shell script ''
  /path/to/ $*

A sample shell script is included in the distribution as

To run multiple copies of nc.sniffer for data collection on various ports or IP's at the same time, name them:

  start         start daemon if not running, write pid file
  stop          stop a running daemon
  restart       do stop, then start
  status        report if daemon running or not
  dump          refresh/write statistics file
  config        print configuration to STDOUT


The statistics information will be written to the file specified in the configuration upon receipt of a SIG USR1

        SIG     TERM            write stats file, terminate
        SIG     HUP             write stats file, start over
        SIG     USR1            write statistics file

UDP listener -- statistics file dump ^

If the nc.sniffer daemon is configured for a UDP listen port, sending a message dump will produce the same result as SIG USR1. The daemon will respond OK timestamp, but this is NOT syncronized with the file dump and only indicates that the statistics file should not have a timestamp earlier that the epoch value returned. When either a dump or SIG USR1 is issued, you must check the ctime of the file to determine if it has been updated.


Net::Connection::Sniffer uses libpcap. The data collection is accomplished using a selectable capture device which is NOT SUPPORTED on Windows and some older BSD platforms. The next two paragraphs are from the pcap library and describe the platform limitations.

Some BPF ...devices do not support select() or poll() (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace DAG devices)...

...On most versions of most BSDs (including Mac OS X), select() and poll() do not work correctly on BPF devices. While a BPF file descriptor will be returned ...on most of those versions (the exceptions being FreeBSD 4.3 and 4.4), a simple select() or poll() will not return even after a... specified timeout expires... ...In FreeBSD 4.6 and later, select() and poll() work correctly on BPF devices...


BPF examples

The bpf entry in the configuration hash uses the standard language documented in detail in the tcpdump man(1) page. The bpf statement must contain at a minimum, 'host somename [or IP address]'. The host specification must be for a single unique IP address and be the first such specification if there are multiple src/dest host specifications in the statment.

Capture all traffic to/from a particular host:

  bpf   => 'host',

Capture traffic to/from your mail server:

  bpf   => 'host and tcp port 25',

Capture request traffic arriving at your DNS server:

  bpf   => 'dst host and udp port 53',

Capture response traffic leaving your DNS server:

  bpf   => 'src host and udp port 53',

Content MATCH/NOMATCH examples

The match and nomatch configuration entries can be used to further discriminate which packets to sniff. When the match entry is set, only packets which meet the BPF criteria AND have matching data within the packet capture buffer are selected for analysis. Conversely, when the nomatch entry is set, packets which meet the BPF criteria and match the nomatch string are unconditionally dropped. match and nomatch may both be set.

NOTE: that matches are made on a case insensitive basis.

Capture request traffic arriving at the DNS port with a query for From RFC1035, we know that a datagram might need to use the domain names F.ISI.ARPA, FOO.F.ISI.ARPA, ARPA, and the root. Ignoring the other fields of the message, these domain names might be represented as:

    20 |      decimal 1        |           F           |
    22 |      decimal 3        |           I           |
    24 |           S           |           I           |
    26 |      decimal 4        |           A           |
    28 |           R           |           P           |
    30 |           A           |           0           |

    40 |      decmial 3        |           F           |
    42 |           O           |           O           |
    44 | 1  1|            decimal 20                   |

    64 | 1  1|            decimal 26                   |

    92 |      decimal 0        |                       |

Our examples would be represented in the datagram as follows:

    20 |      decimal 10       |           s           |
    22 |           o           |           m           |
    24 |           e           |           d           |
    26 |           o           |           m           |
    28 |           a           |           i           |
    30 |           n           |      decimal 3        |
    30 |           c           |           o           |
    30 |           m           |      decimal 0        |

This translates to the perl string:

        where 10 becomes hex \x{a}

  $string = "\x{a}somedomain\x{3}com"

The offset of the query QUESTION is:

  ETH header    16
  IP header     20
  UDP header    8
  Query head    12

and the snaplen needs to be long enough to alway capture the domain name. There, our example configuration becomes:

  bpf     => 'dst host and udp port 53',
  match   => "\x{a}somedomain\x{3}com",
  snaplen => 90,
        # eth head + ip head + udp head + query head
  payload => 54,


The dump file is written in a format compatible with that produced by Data::Dumper. It may be imported for analysis using Perl's 'do' or by using File::SafeDO.

  # start:        1145923212,     Mon Apr 24 17:00:12 2006
  # current:      1145923334,     Mon Apr 24 17:02:14 2006
  # hits:         3832 per minute
  # bytes:        5927 per second
  # users:        1234 users now
  # device:       eth1:1  non-promiscuous
  # bpf:          dst host
  # [optional if match/nomatch present]
  # fragment:   nn -- mm
  # contains:   match.string
  # excludes:   nomatch.string
    my $dump = {
       ''     => {
                B       => 240,
                C       => 4,
                E       => 1145760699,
                N       => ['hostname1','hostname2','...'],
                R       => 723,
                S       => 1145757331,
                T       => 1145790478,
                W       => 43359,


Only one function is exported by This function is called in the script to launch the nc.sniffer daemon.


Launch the nc.sniffer daemon.

  input:        config hash
  returns:      nothing (exits)


The pcap library (libpcap) which is part of tcpdump and is included in most *nix distributions. Available from:

NetAddr::IP::Util which is part of distribution NetAddr::IP









There is a memory leak when run under Perl 5.0503 that has not yielded to debug attempts. This leak is not present in Perl 5.0601. Not tested in other versions. From reading through the Changes file for the transition between versions 5.005 and 5.6, I'm reasonably sure it is a scalar leak in Perl itself that was corrected with the updates to 5.6.

My recommend fix for now when running with Perl versions older than 5.6 is to restart the daemon daily to prevent excessive memory consumption.

COPYRIGHT 2004 - 2014 ^

Michael Robinton <>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free
  Software Foundation; either version 2, or (at your option) any
  later version, or

  b) the "Artistic License" which comes with this distribution.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the

        Free Software Foundation, Inc.
        59 Temple Place, Suite 330
        Boston, MA  02111-1307, USA

or visit their web page on the internet at:


Michael Robinton <>


        man (1) tcpdump
        man (3) pcap


syntax highlighting: