|
| Network.Pcap | | Portability | non-portable | | Stability | experimental | | Maintainer | nickburlett@mac.com, dominic.steinitz@blueyonder.co.uk |
|
|
|
|
|
| Description |
The Pcap modules is a binding to all of the functions in
libpcap (See http://www.tcpdump.org for more information.)
Only a minimum of mashalling is done; for light duty applications,
the user can extract the length of the captured buffer
from the packet header record and use peekArray to convert the
captured data to a list. For illustration:
import Pcap
import Foreign
main = do
let
printIt :: PktHdr -> Ptr Word8 -> IO ()
printIt ph bytep = do
a <- peekArray (fromIntegral (caplen ph)) bytep
print a
p <- openLive "em0" 100 True 10000
s <- withForeignPtr p $ \ptr -> do
dispatch ptr (-1) printIt
return ()
Users requiring higher perfomance (such as O(1) access to any byte
in a packet) should roll their own marshalling functions.
Note that the SockAddr exported here is not the SockAddr from
Network.Socket. The SockAddr from Network.Socket corresponds to
struct sockaddr_in in BSD terminology. The SockAddr record here
is BDS's struct sockaddr. See W.R.Stevens, TCP Illustrated, volume 2,
for further eluciadation.
This binding should be portable for systems that can use the libpcap
from tcpdump.org. It will not work with Winpcap, a similar library
for Windows, although adapting it should not prove difficult.
|
|
| Synopsis |
|
|
|
|
| Types
|
|
|
| packet capture descriptor
|
|
|
| savefile descriptor
|
|
|
| Compiled Berkeley Packet Filter program
|
|
|
| the type of the callback function passed to dispatch or loop.
|
|
|
Datalink types.
This covers all of the datalink types defined in bpf.h.
Types defined on your system may vary.
| | Constructors | | DLT_NULL | no link layer encapsulation
| | DLT_EN10MB | 10 Mbit per second (or faster) ethernet
| | DLT_EN3MB | original 3 Mbit per second ethernet
| | DLT_AX25 | amateur radio AX.25
| | DLT_PRONET | Proteon ProNET Token Ring
| | DLT_CHAOS | Chaos
| | DLT_IEEE802 | IEEE 802 networks
| | DLT_ARCNET | ARCNET
| | DLT_SLIP | Serial line IP
| | DLT_PPP | Point-to-point protocol
| | DLT_FDDI | FDDI
| | DLT_ATM_RFC1483 | LLC SNAP encapsulated ATM
| | DLT_RAW | raw IP
| | DLT_SLIP_BSDOS | BSD OS serial line IP
| | DLT_PPP_BSDOS | BSD OS point-to-point protocol
| | DLT_ATM_CLIP | Linux classical IP over ATM
| | DLT_PPP_SERIAL | PPP over serial with HDLC encapsulation
| | DLT_PPP_ETHER | PPP over ethernet
| | DLT_C_HDLC | Cisco HDLC
| | DLT_IEEE802_11 | IEEE 802.11 wireless
| | DLT_LOOP | OpenBSD loopback device
| | DLT_LINUX_SLL | Linux cooked sockets
| | DLT_LTALK | Apple LocalTalk
| | DLT_ECONET | Acorn Econet
| | DLT_IPFILTER | OpenBSD's old ipfilter
| | DLT_PFLOG | OpenBSD's pflog
| | DLT_CISCO_IOS | Cisco IOS
| | DLT_PRISM_HEADER | Intersil Prism II wireless chips
| | DLT_AIRONET_HEADER | Aironet (Cisco) 802.11 wireless
|
|  Instances | |
|
|
|
| The interface structure
| | Constructors | | Interface | | | ifName :: String | the interface name
| | ifDescription :: String | interface description string (if any)
| | ifAddresses :: [PcapAddr] | address families supported by this interface
| | ifFlags :: Word32 | |
|
| | Instances | |
|
|
|
| The address structure
| | Constructors | | | Instances | |
|
|
|
| The socket address record. Note that this is not the same as
SockAddr from Network.Sockets. (That is a Haskell version of
struct sockaddr_in. This is the real struct sockaddr from the BSD
network stack.)
| | Constructors | | SockAddr | | | sockAddrFamily :: Family | an address family exported by Network.Socket
| | sockAddrAddr :: [Word8] | |
|
| | Instances | |
|
|
|
| The network address record. Both the address and mask are in
network byte order.
| | Constructors | | Network | | | netAddr :: Word32 | IPv4 network address
| | netMask :: Word32 | IPv4 netmask
|
|
| | Instances | |
|
|
|
| Constructors | | PktHdr | | | sec :: Word32 | timestamp (seconds)
| | usec :: Word32 | timestamp (microseconds)
| | caplen :: Word32 | number of bytes present in capture
| | len :: Word32 | number of bytes on the wire
|
|
| | Instances | |
|
|
|
| Constructors | | Statistics | | | recv :: Word32 | packets received
| | drop :: Word32 | packets dropped by libpcap
| | ifdrop :: Word32 | packets dropped by the interface
|
|
| | Instances | |
|
|
| Device opening
|
|
|
| :: String | filename
| | -> IO Pcap | | | openOffline opens a "savefile" for reading. The file foramt is the
as used for tcpdump. The string "-" is a synonym for stdin.
|
|
|
|
| :: String | device name
| | -> Int | snapshot length
| | -> Bool | set to promiscuous mode?
| | -> Int | timeout in milliseconds
| | -> IO Pcap | | openLive is used to get a packet descriptor that can be used to
look at packates on the network. The arguments are the device name,
the snapshot legnth (in bytes), the promiscuity of the interface
(True == promiscuous) and a timeout in milliseconds.
Using "any" as the device name will capture packets from all interfaces.
On some systems, reading from the "any" device is incompatible with
setting the interfaces into promiscuous mode. In that case, only packets
whose link layer addresses match those of the interfaces are captured.
|
|
|
|
| :: Link | datalink type
| | -> Int | snapshot length
| | -> IO Pcap | packet capture descriptor
| | openDead is used to get a packet capture descriptor without opening
a file or device. It is typically used to test packet filter compilation
by setFilter. The arguments are the linktype and the snapshot length.
|
|
|
|
| :: Ptr PcapTag | packet capture descriptor
| | -> String | savefile name
| | -> IO Pdump | davefile descriptor
| | openDump opens a "savefile" for writing. This savefile is written to
by the dump function. The arguments are a raw packet capture descriptor
and the filename, with "-" as a synonym for stdout.
|
|
|
| Filter handling
|
|
|
| :: Ptr PcapTag | packet capture descriptor
| | -> String | filter string
| | -> Bool | optimize?
| | -> Word32 | IPv4 network mask
| | -> IO () | | | Set a filter on the specified packet capture descriptor. Valid filter
strings are those accepted by tcpdump.
|
|
|
|
| :: Int | snapshot length
| | -> Link | datalink type
| | -> String | filter string
| | -> Bool | optimize?
| | -> Word32 | IPv4 network mask
| | -> IO BpfProgram | | | Compile a filter for use by another program using the Berkeley Packet
Filter library.
|
|
|
| Device utilities
|
|
|
| lookupDev returns the name of a device suitable for use with
openLive and lookupNet. If you only have one interface, it is the
function of choice. If not, see findAllDevs.
|
|
|
| findAllDevs returns a list of all the network devices that can
be opened by openLive. It returns only those devices that the
calling process has sufficient privileges to open, so it may not
find every device on the system.
|
|
|
| :: String | device name
| | -> IO Network | | | Return the network address and mask for the specified interface
name. Only valid for IPv4. For other protocols,
use findAllDevs and search the Address list for the associated
network mask.
|
|
|
| Interface control
|
|
| Blocking mode
|
|
|
| Set a packet capture descriptor into non-blocking mode, if the
second argument is True, otherwise put it in blocking mode. Note
that the packet capture descripto must have been obtaine from openLive.
|
|
|
| Return the blocking status of the packet capture descriptor. Ture
indicates that the descriptor is non-blocking. Descriptors referring
savefiles opened by openDump always reutre False.
|
|
| Link layer utilities
|
|
|
| Returns the datalink type associated with the given pcap descriptor.
|
|
|
| Sets the datalink type for a given pcap descriptor.
|
|
|
| List all the datalink types supported by a pcap descriptor. Entries
from the resulting list are valid arguments to setDatalink.
|
|
| Packet processing
|
|
|
| :: Ptr PcapTag | packet capture descriptor
| | -> Int | number of packets to process
| | -> Callback | packet processing function
| | -> IO Int | number of packets read
| Collect and process packets. The arguments are the packet capture
descriptor, the count and a callback function.
The count is the maximum number of packets to process before returning.
A count of -1 means process all of the packets received in one buffer
(if a live capture) or all of the packets in a savefile (if offline).
The callback function is passed two arguments, a packet header
record and a pointer to the packet data (Ptr Word8). THe header
record contains the number of bytes captured, whcih can be used
to marshal the data into a list or array.
|
|
|
|
| :: Ptr PcapTag | packet cpature descriptor
| | -> Int | number of packet to read
| | -> Callback | packet processing function
| | -> IO Int | number of packets read
| Similar to dispatch, but loop until the number of packets specified
by the second argument are read. A negative value loops forever.
It does not return when a live read tiemout occurs. Use dispatch instead
if you wnat to specify a timeout.
|
|
|
|
| :: Ptr PcapTag | packet capture descriptor
| | -> IO (PktHdr, Ptr Word8) | packet header and data of the next packet
| | Read the next packet (by calling dispatch with a count of 1).
|
|
|
|
| :: Ptr PcapDumpTag | savefile descriptor
| | -> Ptr PktHdr | packet header record
| | -> Ptr Word8 | packet data
| | -> IO () | | | Write the packet data given by the second and third arguments
to a savefile opened by openDead. dump is designed so it can be
easily used as a default callback function by dispatch or loop.
|
|
|
| Miscellaneous
|
|
|
| Returns the number of packets received, the number of packets
dropped by the packet filter and the number of packets dropped
by the interface (before processing by the packet filter).
|
|
|
| Major version number of the library.
|
|
|
| Minor version number of the library.
|
|
|
| isSwapped is True if the current savefile uses a different
byte order than the one native to the system.
|
|
|
| The snapshot length that was used in the call to openLive.
|
|
| Produced by Haddock version 2.4.2 |
