pcap

Documentation

Overview

Package pcap allows users of gopacket to read packets off the wire or from pcap files.

This package is meant to be used with its parent, http://code.google.com/p/gopacket, although it can also be used independently if you just want to get packet data from the wire.

Reading PCAP Files

The following code can be used to read in data from a pcap file.

if handle, err := pcap.OpenOffline("/path/to/my/file"); err != nil {
  panic(err)
} else {
  packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
  for packet := range packetSource.Packets() {
    handlePacket(packet)  // Do something with a packet here.
  }
}

Reading Live Packets

The following code can be used to read in data from a live device, in this case "eth0".

if handle, err := pcap.OpenLive("eth0", 1600, true, 0); err != nil {
  panic(err)
} else if err := handle.SetBPFFilter("tcp and port 80"); err != nil {  // optional
  panic(err)
} else {
  packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
  for packet := range packetSource.Packets() {
    handlePacket(packet)  // Do something with a packet here.
  }
}

Index

• Constants
• func Version() string
• type Handle
  • func OpenLive(device string, snaplen int32, promisc bool, timeout time.Duration) (handle *Handle, _ error)
  • func OpenOffline(file string) (handle *Handle, err error)
  • func (p *Handle) Close()
  • func (p *Handle) Error() error
  • func (p *Handle) LinkType() layers.LinkType
  • func (p *Handle) ReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)
  • func (p *Handle) SetBPFFilter(expr string) (err error)
  • func (p *Handle) SetLinkType(dlt layers.LinkType) error
  • func (p *Handle) SetTimestampSource(t TimestampSource) error
  • func (p *Handle) Stats() (stat *Stats, err error)
  • func (p *Handle) SupportedTimestamps() (out []TimestampSource)
  • func (p *Handle) WritePacketData(data []byte) (err error)
  • func (p *Handle) ZeroCopyReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)
• type Interface
  • func FindAllDevs() (ifs []Interface, err error)
• type InterfaceAddress
• type NextError
  • func (n NextError) Error() string
• type Stats
• type TimestampSource
  • func TimestampSourceFromString(s string) (TimestampSource, error)
  • func (t TimestampSource) String() string

Constants

const BlockForever = time.Duration(0)

BlockForever, when passed into OpenLive, causes it to block forever waiting for packets.

Functions

func Version

func Version() string

Version returns pcap_lib_version.

Types

type Handle

type Handle struct {
	// contains filtered or unexported fields
}

Handle provides a connection to a pcap handle, allowing users to read packets off the wire (Next), inject packets onto the wire (Inject), and perform a number of other functions to affect and understand packet output.

func OpenLive

func OpenLive(device string, snaplen int32, promisc bool, timeout time.Duration) (handle *Handle, _ error)

OpenLive opens a device and returns a *Handle. It takes as arguments the name of the device ("eth0"), the maximum size to read for each packet (snaplen), whether to put the interface in promiscuous mode, and a timeout.

func OpenOffline

func OpenOffline(file string) (handle *Handle, err error)

OpenOffline opens a file and returns its contents as a *Handle.

func (*Handle) Close

func (p *Handle) Close()

Close closes the underlying pcap handle.

func (*Handle) Error

func (p *Handle) Error() error

Error returns the current error associated with a pcap handle (pcap_geterr).

func (*Handle) LinkType

func (p *Handle) LinkType() layers.LinkType

LinkType returns pcap_datalink, as a layers.LinkType.

func (*Handle) ReadPacketData

func (p *Handle) ReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)

NextError returns the next packet read from the pcap handle, along with an error code associated with that packet. If the packet is read successfully, the returned error is nil.

func (*Handle) SetBPFFilter

func (p *Handle) SetBPFFilter(expr string) (err error)

SetBPFFilter compiles and sets a BPF filter for the pcap handle.

func (*Handle) SetLinkType

func (p *Handle) SetLinkType(dlt layers.LinkType) error

SetLinkType calls pcap_set_datalink on the pcap handle.

func (*Handle) SetTimestampSource

func (p *Handle) SetTimestampSource(t TimestampSource) error

SetTimestampSource sets the type of timestamp generator PCAP uses when attaching timestamps to packets.

func (*Handle) Stats

func (p *Handle) Stats() (stat *Stats, err error)

Stats returns statistics on the underlying pcap handle.

func (*Handle) SupportedTimestamps

func (p *Handle) SupportedTimestamps() (out []TimestampSource)

SupportedTimestamps returns a list of supported timstamp types for this handle.

func (*Handle) WritePacketData

func (p *Handle) WritePacketData(data []byte) (err error)

WritePacketData calls pcap_sendpacket, injecting the given data into the pcap handle.

func (*Handle) ZeroCopyReadPacketData

func (p *Handle) ZeroCopyReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)

ZeroCopyReadPacketData reads the next packet off the wire, and returns its data. The slice returned by ZeroCopyReadPacketData points to bytes owned by the the Handle. Each call to ZeroCopyReadPacketData invalidates any data previously returned by ZeroCopyReadPacketData. Care must be taken not to keep pointers to old bytes when using ZeroCopyReadPacketData... if you need to keep data past the next time you call ZeroCopyReadPacketData, use ReadPacketDataData, which copies the bytes into a new buffer for you.

data1, _, _ := handle.ZeroCopyReadPacketData()
// do everything you want with data1 here, copying bytes out of it if you'd like to keep them around.
data2, _, _ := handle.ZeroCopyReadPacketData()  // invalidates bytes in data1

type Interface

type Interface struct {
	Name        string
	Description string
	Addresses   []InterfaceAddress
}

Interface describes a single network interface on a machine.

func FindAllDevs

func FindAllDevs() (ifs []Interface, err error)

FindAllDevs attempts to enumerate all interfaces on the current machine.

type InterfaceAddress

type InterfaceAddress struct {
	IP      net.IP
	Netmask net.IPMask
}

InterfaceAddress describes an address associated with an Interface. Currently, it's IPv4/6 specific.

type NextError

type NextError int32

NextError is the return code from a call to Next.

const (
	NextErrorOk             NextError = 1
	NextErrorTimeoutExpired NextError = 0
	NextErrorReadError      NextError = -1
	// NextErrorNoMorePackets is returned when reading from a file (OpenOffline) and
	// EOF is reached.  When this happens, Next() returns io.EOF instead of this.
	NextErrorNoMorePackets NextError = -2
	NextErrorNotActivated  NextError = -3
)

func (NextError) Error

func (n NextError) Error() string

NextError implements the error interface.

type Stats

type Stats struct {
	PacketsReceived  int
	PacketsDropped   int
	PacketsIfDropped int
}

Stats contains statistics on how many packets were handled by a pcap handle, and what was done with those packets.

type TimestampSource

type TimestampSource C.int

TimestampSource tells PCAP which type of timestamp to use for packets.

func TimestampSourceFromString

func TimestampSourceFromString(s string) (TimestampSource, error)

TimestampSourceFromString translates a string into a timestamp type, case insensitive.

func (TimestampSource) String

func (t TimestampSource) String() string

String returns the timestamp type as a human-readable string.