pcap-0.4.5.1: A system-independent interface for user-level packet capture

Portabilitynon-portable
Stabilityexperimental
Maintainerbos@serpentine.com

Network.Pcap

Contents

Description

The Network.Pcap module is a high(ish) level binding to all of the functions in libpcap. See http://www.tcpdump.org for more information.

This module is built on the lower-level Network.Pcap.Base module, which is slightly more efficient. Don't use Network.Pcap.Base unless profiling data indicates that you need to.

Only a minimum of marshaling is done on received packets. To convert captured packet data to a ByteString (space efficient, and with O(1) access to every byte in a captured packet), use toBS.

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 BSD's struct sockaddr. See W.R.Stevens, TCP Illustrated, volume 2, for further elucidation.

This binding should be portable across systems that can use the libpcap from tcpdump.org. It does not yet work with Winpcap, a similar library for Windows, although adapting it should not prove difficult.

Synopsis

Types

data PcapHandle Source

Packet capture handle.

data DumpHandle Source

Dump file handle.

type BpfProgram = ForeignPtr BpfProgramTagSource

Compiled Berkeley Packet Filter program.

type Callback = PktHdr -> Ptr Word8 -> IO ()Source

the type of the callback function passed to dispatch or loop.

type CallbackBS = PktHdr -> ByteString -> IO ()Source

Callback using ByteString for packet body.

data Direction Source

The direction in which packets are to be captured. See setDirection.

Constructors

InOut

incoming and outgoing packets (the default)

In

incoming packets

Out

outgoing packets

data Link Source

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_UNKNOWN Int

unknown 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_REDBACK_SMARTEDGE

Redback SmartEdge 400/800

DLT_PPP_SERIAL

PPP over serial with HDLC encapsulation

DLT_PPP_ETHER

PPP over ethernet

DLT_SYMANTEC_FIREWALL

Symantec Enterprise Firewall

DLT_C_HDLC

Cisco HDLC

DLT_IEEE802_11

IEEE 802.11 wireless

DLT_FRELAY

Frame Relay

DLT_LOOP

OpenBSD loopback device

DLT_ENC

Encapsulated packets for IPsec

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

DLT_HHDLC

Siemens HiPath HDLC

DLT_IP_OVER_FC

RFC 2625 IP-over-Fibre Channel

DLT_SUNATM

Full Frontal ATM on Solaris with SunATM

DLT_IEEE802_11_RADIO
  1. 11 plus a number of bits of link-layer information
DLT_ARCNET_LINUX

Linux ARCNET header

DLT_APPLE_IP_OVER_IEEE1394

Apple IP-over-IEEE 1394

DLT_MTP2_WITH_PHDR

SS7, C7 MTP2 with pseudo-header

DLT_MTP2

SS7, C7 Message Transfer Part 2 (MPT2)

DLT_MTP3

SS7, C7 Message Transfer Part 3 (MPT3)

DLT_SCCP

SS7, C7 SCCP

DLT_DOCSIS

DOCSIS MAC frame

DLT_LINUX_IRDA

Linux IrDA packet

DLT_USER0

Reserved for private use

DLT_USER1

Reserved for private use

DLT_USER2

Reserved for private use

DLT_USER3

Reserved for private use

DLT_USER4

Reserved for private use

DLT_USER5

Reserved for private use

DLT_USER6

Reserved for private use

DLT_USER7

Reserved for private use

DLT_USER8

Reserved for private use

DLT_USER9

Reserved for private use

DLT_USER10

Reserved for private use

DLT_USER11

Reserved for private use

DLT_USER12

Reserved for private use

DLT_USER13

Reserved for private use

DLT_USER14

Reserved for private use

DLT_USER15

Reserved for private use

DLT_PPP_PPPD

Outgoing packets for ppp daemon

DLT_GPRS_LLC

GPRS LLC

DLT_GPF_T

GPF-T (ITU-T G.7041/Y.1303)

DLT_GPF_F

GPF-F (ITU-T G.7041/Y.1303)

DLT_LINUX_LAPD

Raw LAPD for vISDN (not generic LAPD)

DLT_A429

ARINC 429

DLT_A653_ICM

ARINC 653 Interpartition Communication messages

DLT_USB

USB packet

DLT_BLUETOOTH_HCI_H4

Bluetooth HCI UART transport layer (part H:4)

DLT_MFR

Multi Link Frame Relay (FRF.16)

DLT_IEEE802_16_MAC_CPS

IEEE 802.16 MAC Common Part Sublayer

DLT_USB_LINUX

USB packets, beginning with a Linux USB header

DLT_CAN20B

Controller Area Network (CAN) v2.0B

DLT_IEEE802_15_4_LINUX

IEEE 802.15.4, with address fields padded

DLT_PPI

Per Packet Information encapsulated packets

DLT_IEEE802_16_MAC_CPS_RADIO
  1. 16 MAC Common Part Sublayer with radiotap radio header
DLT_IEEE802_15_4

IEEE 802.15.4, exactly as in the spec

data Interface Source

The interface structure.

Constructors

Interface 

Fields

ifName :: String

the interface name

ifDescription :: String

interface description string (if any)

ifAddresses :: [PcapAddr]

address families supported by this interface

ifFlags :: Word32
 

data PcapAddr Source

The address structure.

Constructors

PcapAddr 

Fields

addrSA :: SockAddr

interface address

addrMask :: Maybe SockAddr

network mask

addrBcast :: Maybe SockAddr

broadcast address

addrPeer :: Maybe SockAddr

address of peer, of a point-to-point link

data SockAddr Source

The socket address record. Note that this is not the same as SockAddr from Network.Socket. (That is a Haskell version of C's struct sockaddr_in. This is the real struct sockaddr from the BSD network stack.)

Constructors

SockAddr 

Fields

saFamily :: !Family

an address family exported by Network.Socket

saAddr :: !ByteString
 

data Network Source

The network address record. Both the address and mask are in network byte order.

Constructors

Network 

Fields

netAddr :: !Word32

IPv4 network address

netMask :: !Word32

IPv4 netmask

data PktHdr Source

Constructors

PktHdr 

Fields

hdrSeconds :: !Word32

timestamp (seconds)

hdrUseconds :: !Word32

timestamp (microseconds)

hdrCaptureLength :: !Word32

number of bytes present in capture

hdrWireLength :: !Word32

number of bytes on the wire

Instances

data Statistics Source

Constructors

Statistics 

Fields

statReceived :: !Word32

packets received

statDropped :: !Word32

packets dropped by libpcap

statIfaceDropped :: !Word32

packets dropped by the network interface

Device opening

openOfflineSource

Arguments

:: FilePath

name of dump file to read

-> IO PcapHandle 

openOffline opens a dump file for reading. The file format is the same as used by tcpdump and Wireshark. The string "-" is a synonym for stdin.

openLiveSource

Arguments

:: String

device name

-> Int

snapshot length

-> Bool

set interface to promiscuous mode?

-> Int64

timeout in microseconds

-> IO PcapHandle 

openLive is used to get a PcapHandle that can be used to look at packets on the network. The arguments are the device name, the snapshot length (in bytes), the promiscuity of the interface (True == promiscuous) and a timeout in microseconds.

The timeout allows the packet filter to delay while accumulating multiple packets, which is more efficient than reading packets one by one. A timeout of zero will wait indefinitely for "enough" packets to arrive.

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.

openDeadSource

Arguments

:: Link

datalink type

-> Int

snapshot length

-> IO PcapHandle 

openDead is used to get a PcapHandle without opening a file or device. It is typically used to test packet filter compilation by setFilter. The arguments are the link type and the snapshot length.

openDumpSource

Arguments

:: PcapHandle

packet capture handle

-> FilePath

name of dump file to write to

-> IO DumpHandle 

openDump opens a dump file for writing. This dump file is written to by the dump function.

Filter handling

setFilterSource

Arguments

:: PcapHandle

handle on which to set filter

-> String

filter string

-> Bool

optimize?

-> Word32

IPv4 network mask

-> IO () 

Set a filter on the specified packet capture handle. Valid filter strings are those accepted by tcpdump.

compileFilterSource

Arguments

:: 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 :: IO StringSource

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 :: IO [Interface]Source

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.

lookupNetSource

Arguments

:: 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 Interface list for the associated network mask.

Interface control

setNonBlockSource

Arguments

:: PcapHandle

must have been obtained from openLive

-> Bool

set/unset blocking mode

-> IO () 

Set the given PcapHandle into non-blocking mode if the second argument is True, otherwise put it in blocking mode. Note that the PcapHandle must have been obtained from openLive.

getNonBlock :: PcapHandle -> IO BoolSource

Return the blocking status of the PcapHandle. True indicates that the handle is non-blocking. Handles referring to dump files opened by openDump always return False.

setDirection :: PcapHandle -> Direction -> IO ()Source

Specify the direction in which packets are to be captured. Complete functionality is not necessarily available on all platforms.

Link layer utilities

datalink :: PcapHandle -> IO LinkSource

Returns the datalink type associated with the given handle.

setDatalink :: PcapHandle -> Link -> IO ()Source

Sets the datalink type for the given handle.

listDatalinks :: PcapHandle -> IO [Link]Source

List all the datalink types supported by the given handle. Entries from the resulting list are valid arguments to setDatalink.

Packet processing

dispatchSource

Arguments

:: PcapHandle 
-> Int

number of packets to process

-> Callback

packet processing function

-> IO Int

number of packets read

Collect and process packets.

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 dump file (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, which can be used to marshal the data into a list, array, or ByteString (using toBS).

loopSource

Arguments

:: PcapHandle 
-> Int

number of packets to read (-1 == loop forever)

-> 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.

This function does not return when a live read timeout occurs. Use dispatch instead if you want to specify a timeout.

next :: PcapHandle -> IO (PktHdr, Ptr Word8)Source

Read the next packet (equivalent to calling dispatch with a count of 1).

dumpSource

Arguments

:: DumpHandle 
-> Ptr PktHdr

packet header record

-> Ptr Word8

packet data

-> IO () 

Write the packet data given by the second and third arguments to a dump file opened by openDead. dump is designed so it can be easily used as a default callback function by dispatch or loop.

ByteString variants

dispatchBSSource

Arguments

:: PcapHandle 
-> Int

number of packets to process

-> CallbackBS

packet processing function

-> IO Int

number of packets read

Variant of dispatch for use with ByteString.

loopBSSource

Arguments

:: PcapHandle 
-> Int

number of packets to read (-1 == loop forever)

-> CallbackBS

packet processing function

-> IO Int

number of packets read

Variant of loop for use with ByteString.

dumpBSSource

Arguments

:: DumpHandle 
-> Ptr PktHdr

packet header record

-> ByteString

packet data

-> IO () 

Sending packets

sendPacketSource

Arguments

:: PcapHandle 
-> Ptr Word8

packet data (including link-level header)

-> Int

packet size

-> IO () 

Send a raw packet through the network interface.

sendPacketBSSource

Arguments

:: PcapHandle 
-> ByteString

packet data (including link-level header)

-> IO () 

Variant of sendPacket for use with ByteString.

Conversion

toBS :: (PktHdr, Ptr Word8) -> IO (PktHdr, ByteString)Source

Represent a captured packet as a ByteString. Suitable for use as is with the result of next, or use curry toBS inside a Callback with dispatch.

hdrTime :: PktHdr -> Int64Source

Get the timestamp of a packet as a single quantity, in microseconds.

hdrDiffTime :: PktHdr -> DiffTimeSource

Get the timestamp of a packet as a DiffTime.

Miscellaneous

statistics :: PcapHandle -> IO StatisticsSource

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).

version :: PcapHandle -> IO (Int, Int)Source

Version of the library. The returned pair consists of the major and minor version numbers.

isSwapped :: PcapHandle -> IO BoolSource

isSwapped returns True if the current dump file uses a different byte order than the one native to the system.

snapshotLen :: PcapHandle -> IO IntSource

The snapshot length that was used in the call to openLive.