Net::Ncap - Perl extension for the ncap(3) network data capture library.
Net::Ncap is a Perl binding to the ncap(3) network data capture library. The ncap documentation describes itself thusly:
- new(maxmsg) Creates a new Net::Ncap object. Methods are dispatched to their corresponding functions provided by the ncap library.
The optional parameter maxmsg determines the maximum size of an ncap payload that the library is willing to process (default 70000).
The following methods, for the most part, directly correspond to the functions provided by the ncap library. See ncap(3) for more details on what these functions do.
- add_if($name, Net-Ncap Documentation, Net-Ncap Documentation, Net-Ncap Documentation) Adds a network interface as a data source. The name of the interface is required (e.g. 'eth0'). A BPF program can be provided as a string with the bpf parameter (unless an NCAP filter has been provided via the filter() method). promisc determines whether or not the interface is opened in promiscuous mode (default 0). An optional array refererence to VLANs may also be provided for filtering based on tagged 802.1Q frames.
- drop_if($name) Removes the given network interface from the collection pool.
- add_nf($file, Net-Ncap Documentation) Adds the given NCAP file as a data source. If file is a reference, it is assumed to be an open file handle and is used directly. Otherwise it is assumed to be a file name and is opened for reading. An optional label can be provided for this source; by default the label is either the filename or file number, depending on what was provided in file.
- drop_nf($file) Removes the given NCAP file as a data source. The provided file can either be the file name, handle, or label (if one was provided).
- add_pf($file, Net-Ncap Documentation) Adds the given PCAP file as a data source. file can either be a file name or a file handle. Otherwise identical to add_nf(), including accepting an optional label.
- drop_pf($file) Removes the given PCAP file as a data source. The provided file can either be the file name, handle, or label (if one was provided).
- add_dg($socket) Adds the given socket handle as a data source.
- drop_dg($socket) Removes the given socket handle as a data source.
- filter($filter) Installs an NCAP filter described by the given string. If any BPFs (berkely packet filters) have been installed, this will fail.
- collect($callback, %opts) Collect data from the collection pool, invoking the subroutine referenced by callback for each matching ncap message. There are several named options available:
- polling Controls whether collection happens continuously (the default) or once.
- sigwrap Disabled by default. Controls whether signal handlers are installed for SIGHUP, SIGINT, and SIGTERM prior to passing control to the collection loop. Perl only sees these events when it is in context (i.e. during the callback). Until then they are queued by default, until perl can handle them. If you are polling on an interface that is not very busy, or if your filters only occasionally pass an interesting message, it might be a while before perl gets a chance to handle signals. With this option enabled, the program is interruptable. Whatever signal handlers were in place prior to invoking collect are restored once complete.
- timeout Disabled by default. Specifies a time window for which your callback will be invoked, regardless of whether any messages have matched your filters. In such a case, the message provided to the callback will be undef. Enabling timeout automatically enables sigwrap as described above.
- timeout_cb Specifies an optional alternate callback reference for timeout induced callbacks, rather than sending undef to the primary callback.
- stop() Halts the collection loop. There might be a few stray callbacks before the loop actually exits, depending on the granularity configured into the ncap library.
- write($fh, Net-Ncap Documentation) Writes the given ncap message to the provided file handle in the ncap portable binary format. If no message is provided, a proper file header is written instead.
- send($socket, Net-Ncap Documentation) Writes the given ncap message to the provided socket handle in the ncap portable binary format. If no Net::Ncap::ncap_msg object is provided, an NCAP file header is written instead. <em>flags<em> are an integer representation of any flags as would be provided to the send(2) function from the socket library (default MSG_DONTROUTE).
- callback($msg) The callback function is handed a single parameter, a reference to a message object. See below for more information. If collection was invoked with either sigwrap or timeout enabled, the callback might be invoked with
undef, depending on whether timeout_cb was provided.
The callback can abort the collection loop by invoking the stop() method on the Net::Ncap object.
The callback receives references to Net::Ncap::ncap_msg objects. The following accessors, for the most part, correspond to the the information available from the structs comprising an ncap message. See ncap(3) for more information on the low level format.
- label() The label associated with this data source. By default this will be the file name or interface name, unless an alternate label was associated with the source.
- src_packed() The source IP address in packed (network byte order) form. (i.e. either either a ip_addr or ip6_addr struct).
- dst_packed() The destination IP address in packed (network byte order) form.
- src() Returns an array reference containing the components of the source IP address. For IPv4 these represent the four 32 bit quads, for IPv6 these represent the eight 16-bit components.
- dst() Returns an array reference containing the components of the destination IP address, as above.
- sip() The source IP address as a string. For IPv4 this is dotted-quad, for IPv6 this is colon-hexadecimal.
- dip() The destination IP address as a string, as above.
- sport() The source port of the datagram. (undef for icmp)
- dport() The destination port of the datagram. (undef for icmp)
- sec() The seconds component of the datagram timestamp.
- nsec() The nanoseconds component of the datagram timestamp.
- nproto() The numeric network protocol type (IP or IPV6)
- tproto() The numeric transport protocol type (UDP, TCP, or ICMP)
- nname() The network protocol name
- tname() The transport protocol name
- payload() The binary (network format) record (for example, the DNS record)
- payload_ref() A scalar reference to the payload string.
- user1() User defined value
- user2() User defined value
- type() The ICMP type of the datagram. (undef for udp/tcp)
- code() The ICMP code of the datagram. (undef for udp/tcp)
- offset() The TCP offset of the datagram. (undef for icmp/udp)
- flags() The TCP flags of the datagram. (undef for icmp/udp)
ncap(3), pcap(3), Net::Pcap
Net::Ncap project page: http://tools.netsa.cert.org/wiki/display/tt/Net-Ncap
The ncap library can be downloaded from: ftp://ftp.isc.org/isc/ncap/
The pcap library can be downloaded from: http://www.tcpdump.org/
Matthew Sisk, <email@example.com>
COPYRIGHT AND LICENSE
Copyright (C) 2009 by Carnegie Mellon University
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, under the terms pursuant to Version 2, June 1991.
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 the GNU General Public License for more details.