// CaptureInfo provides standardized information about a packet captured off
// the wire or read from a file.
type CaptureInfo struct {
// Timestamp is the time the packet was captured, if that is known.
// CaptureLength is the total number of bytes read off of the wire.
// Length is the size of the original packet. Should always be >=
// The packet source can place ancillary data of various types here.
// For example, the afpacket source can report the VLAN of captured
AncillaryData []interface{}
// PacketMetadata contains metadata for a packet.
type PacketMetadata struct {
// Truncated is true if packet decoding logic detects that there are fewer
// bytes in the packet than are detailed in various headers (for example, if
// the number of bytes in the IPv4 contents/payload is less than IPv4.Length).
// This is also set automatically for packets captured off the wire if
// CaptureInfo.CaptureLength < CaptureInfo.Length.
// Packet is the primary object used by gopacket. Packets are created by a
// Decoder's Decode call. A packet is made up of a set of Data, which
// is broken into a number of Layers as it is decoded.
//// Functions for outputting the packet as a human-readable string:
//// ------------------------------------------------------------------
// String returns a human-readable string representation of the packet.
// It uses LayerString on each layer to output the layer.
// Dump returns a verbose human-readable string representation of the packet,
// including a hex dump of all layers. It uses LayerDump on each layer to
//// Functions for accessing arbitrary packet layers:
//// ------------------------------------------------------------------
// Layers returns all layers in this packet, computing them as necessary
// Layer returns the first layer in this packet of the given type, or nil
// LayerClass returns the first layer in this packet of the given class,
LayerClass(LayerClass) Layer
//// Functions for accessing specific types of packet layers. These functions
//// return the first layer of each type found within the packet.
//// ------------------------------------------------------------------
// LinkLayer returns the first link layer in the packet
// NetworkLayer returns the first network layer in the packet
NetworkLayer() NetworkLayer
// TransportLayer returns the first transport layer in the packet
TransportLayer() TransportLayer
// ApplicationLayer returns the first application layer in the packet
ApplicationLayer() ApplicationLayer
// ErrorLayer is particularly useful, since it returns nil if the packet
// was fully decoded successfully, and non-nil if an error was encountered
// in decoding and the packet was only partially decoded. Thus, its output
// can be used to determine if the entire packet was able to be decoded.
//// Functions for accessing data specific to the packet:
//// ------------------------------------------------------------------
// Data returns the set of bytes that make up this entire packet.
// Metadata returns packet metadata associated with this packet.
Metadata() *PacketMetadata
// packet contains all the information we need to fulfill the Packet interface,
// and its two "subclasses" (yes, no such thing in Go, bear with me),
// eagerPacket and lazyPacket, provide eager and lazy decoding logic around the
// various functions needed to access this information.
// data contains the entire packet data for a packet
// initialLayers is space for an initial set of layers already created inside
// layers contains each layer we've already decoded
// last is the last layer added to the packet
// metadata is the PacketMetadata for this packet
decodeOptions DecodeOptions
// Pointers to the various important layers
application ApplicationLayer
func (p *packet) SetTruncated() {
p.metadata.Truncated = true
func (p *packet) SetLinkLayer(l LinkLayer) {
func (p *packet) SetNetworkLayer(l NetworkLayer) {
func (p *packet) SetTransportLayer(l TransportLayer) {
func (p *packet) SetApplicationLayer(l ApplicationLayer) {
if p.application == nil {
func (p *packet) SetErrorLayer(l ErrorLayer) {
func (p *packet) AddLayer(l Layer) {
p.layers = append(p.layers, l)
func (p *packet) DumpPacketData() {
fmt.Fprint(os.Stderr, p.packetDump())
func (p *packet) Metadata() *PacketMetadata {
func (p *packet) Data() []byte {
func (p *packet) DecodeOptions() *DecodeOptions {
func (p *packet) addFinalDecodeError(err error, stack []byte) {
fail := &DecodeFailure{err: err, stack: stack}
fail.data = p.last.LayerPayload()
func (p *packet) recoverDecodeError() {
if !p.decodeOptions.SkipDecodeRecovery {
if r := recover(); r != nil {
p.addFinalDecodeError(fmt.Errorf("%v", r), debug.Stack())
// LayerString outputs an individual layer as a string. The layer is output
// in a single line, with no trailing newline. This function is specifically
// designed to do the right thing for most layers... it follows the following
// * If the Layer has a String function, just output that.
// * Otherwise, output all exported fields in the layer, recursing into
// exported slices and structs.
// NOTE: This is NOT THE SAME AS fmt's "%#v". %#v will output both exported
// and unexported fields... many times packet layers contain unexported stuff
// that would just mess up the output of the layer, see for example the
// Payload layer and it's internal 'data' field, which contains a large byte
// array that would really mess up formatting.
func LayerString(l Layer) string {
return fmt.Sprintf("%v\t%s", l.LayerType(), layerString(reflect.ValueOf(l), false, false))
// Dumper dumps verbose information on a value. If a layer type implements
// Dumper, then its LayerDump() string will include the results in its output.
// LayerDump outputs a very verbose string representation of a layer. Its
// output is a concatenation of LayerString(l) and hex.Dump(l.LayerContents()).
// It contains newlines and ends with a newline.
func LayerDump(l Layer) string {
b.WriteString(LayerString(l))
if d, ok := l.(Dumper); ok {
if dump[len(dump)-1] != '\n' {
b.WriteString(hex.Dump(l.LayerContents()))
// layerString outputs, recursively, a layer in a "smart" way. See docs for
// LayerString for more details.
// i - value to write out
// anonymous: if we're currently recursing an anonymous member of a struct
// writeSpace: if we've already written a value in a struct, and need to
// write a space before writing more. This happens when we write various
// anonymous values, and need to keep writing more.
func layerString(v reflect.Value, anonymous bool, writeSpace bool) string {
// Let String() functions take precedence.
if s, ok := v.Interface().(fmt.Stringer); ok {
// Reflect, and spit out all the exported fields as key=value.
case reflect.Interface, reflect.Ptr:
return layerString(r, anonymous, writeSpace)
for i := 0; i < v.NumField(); i++ {
// Check if this is upper-case.
anonStr := layerString(f, true, writeSpace)
writeSpace = writeSpace || anonStr != ""
} else if ftype.PkgPath == "" { // exported
fmt.Fprintf(&b, "%s=%s", typ.Field(i).Name, layerString(f, false, writeSpace))
fmt.Fprintf(&b, "..%d..", v.Len())
for j := 0; j < v.Len(); j++ {
b.WriteString(layerString(v.Index(j), false, false))
return fmt.Sprintf("%v", v.Interface())
// LongBytesGoString returns a string representation of the byte slice shortened
// using the format '<type>{<truncated slice> ... (<n> bytes)}' if it
// exceeds a predetermined length. Can be used to avoid filling the display with
// very long byte strings.
func LongBytesGoString(buf []byte) string {
if len(buf) < longBytesLength {
return fmt.Sprintf("%#v", buf)
s := fmt.Sprintf("%#v", buf[:longBytesLength-1])
s = strings.TrimSuffix(s, "}")
return fmt.Sprintf("%s ... (%d bytes)}", s, len(buf))
func baseLayerString(value reflect.Value) string {
content := value.Field(0)
c := make([]byte, content.Len())
c[i] = byte(content.Index(i).Uint())
payload := value.Field(1)
p := make([]byte, payload.Len())
p[i] = byte(payload.Index(i).Uint())
return fmt.Sprintf("%s{Contents:%s, Payload:%s}", t.String(),
func layerGoString(i interface{}, b *bytes.Buffer) {
if s, ok := i.(fmt.GoStringer); ok {
b.WriteString(s.GoString())
if v, ok = i.(reflect.Value); !ok {
case reflect.Ptr, reflect.Interface:
if v.Kind() == reflect.Ptr {
layerGoString(v.Elem().Interface(), b)
b.WriteString(t.String())
for i := 0; i < v.NumField(); i++ {
if t.Field(i).Name == "BaseLayer" {
fmt.Fprintf(b, "BaseLayer:%s", baseLayerString(v.Field(i)))
} else if v.Field(i).Kind() == reflect.Struct {
fmt.Fprintf(b, "%s:", t.Field(i).Name)
layerGoString(v.Field(i), b)
} else if v.Field(i).Kind() == reflect.Ptr {
layerGoString(v.Field(i), b)
fmt.Fprintf(b, "%s:%#v", t.Field(i).Name, v.Field(i))
// LayerGoString returns a representation of the layer in Go syntax,
// taking care to shorten "very long" BaseLayer byte slices
func LayerGoString(l Layer) string {
func (p *packet) packetString() string {
fmt.Fprintf(&b, "PACKET: %d bytes", len(p.Data()))
if p.metadata.Truncated {
b.WriteString(", truncated")
if p.metadata.Length > 0 {
fmt.Fprintf(&b, ", wire length %d cap length %d", p.metadata.Length, p.metadata.CaptureLength)
if !p.metadata.Timestamp.IsZero() {
fmt.Fprintf(&b, " @ %v", p.metadata.Timestamp)
for i, l := range p.layers {
fmt.Fprintf(&b, "- Layer %d (%02d bytes) = %s\n", i+1, len(l.LayerContents()), LayerString(l))
func (p *packet) packetDump() string {
fmt.Fprintf(&b, "-- FULL PACKET DATA (%d bytes) ------------------------------------\n%s", len(p.data), hex.Dump(p.data))
for i, l := range p.layers {
fmt.Fprintf(&b, "--- Layer %d ---\n%s", i+1, LayerDump(l))
// eagerPacket is a packet implementation that does eager decoding. Upon
// initial construction, it decodes all the layers it can from packet data.
// eagerPacket implements Packet and PacketBuilder.
type eagerPacket struct {
var errNilDecoder = errors.New("NextDecoder passed nil decoder, probably an unsupported decode type")
func (p *eagerPacket) NextDecoder(next Decoder) error {
return errors.New("NextDecoder called, but no layers added yet")
d := p.last.LayerPayload()
// Since we're eager, immediately call the next decoder.
func (p *eagerPacket) initialDecode(dec Decoder) {
defer p.recoverDecodeError()
err := dec.Decode(p.data, p)
p.addFinalDecodeError(err, nil)
func (p *eagerPacket) LinkLayer() LinkLayer {
func (p *eagerPacket) NetworkLayer() NetworkLayer {
func (p *eagerPacket) TransportLayer() TransportLayer {
func (p *eagerPacket) ApplicationLayer() ApplicationLayer {
func (p *eagerPacket) ErrorLayer() ErrorLayer {
func (p *eagerPacket) Layers() []Layer {
func (p *eagerPacket) Layer(t LayerType) Layer {
for _, l := range p.layers {
func (p *eagerPacket) LayerClass(lc LayerClass) Layer {
for _, l := range p.layers {
if lc.Contains(l.LayerType()) {
func (p *eagerPacket) String() string { return p.packetString() }
func (p *eagerPacket) Dump() string { return p.packetDump() }
// lazyPacket does lazy decoding on its packet data. On construction it does
// no initial decoding. For each function call, it decodes only as many layers
// as are necessary to compute the return value for that function.
// lazyPacket implements Packet and PacketBuilder.
func (p *lazyPacket) NextDecoder(next Decoder) error {
func (p *lazyPacket) decodeNextLayer() {
d = p.last.LayerPayload()
// We've just set p.next to nil, so if we see we have no data, this should be
// the final call we get to decodeNextLayer if we return here.
defer p.recoverDecodeError()
p.addFinalDecodeError(err, nil)
func (p *lazyPacket) LinkLayer() LinkLayer {
for p.link == nil && p.next != nil {
func (p *lazyPacket) NetworkLayer() NetworkLayer {
for p.network == nil && p.next != nil {
func (p *lazyPacket) TransportLayer() TransportLayer {
for p.transport == nil && p.next != nil {
func (p *lazyPacket) ApplicationLayer() ApplicationLayer {
for p.application == nil && p.next != nil {
func (p *lazyPacket) ErrorLayer() ErrorLayer {
for p.failure == nil && p.next != nil {
func (p *lazyPacket) Layers() []Layer {
func (p *lazyPacket) Layer(t LayerType) Layer {
for _, l := range p.layers {
numLayers := len(p.layers)
for _, l := range p.layers[numLayers:] {
numLayers = len(p.layers)
func (p *lazyPacket) LayerClass(lc LayerClass) Layer {
for _, l := range p.layers {
if lc.Contains(l.LayerType()) {
numLayers := len(p.layers)
for _, l := range p.layers[numLayers:] {
if lc.Contains(l.LayerType()) {
numLayers = len(p.layers)
func (p *lazyPacket) String() string { p.Layers(); return p.packetString() }
func (p *lazyPacket) Dump() string { p.Layers(); return p.packetDump() }
// DecodeOptions tells gopacket how to decode a packet.
type DecodeOptions struct {
// Lazy decoding decodes the minimum number of layers needed to return data
// for a packet at each function call. Be careful using this with concurrent
// packet processors, as each call to packet.* could mutate the packet, and
// two concurrent function calls could interact poorly.
// NoCopy decoding doesn't copy its input buffer into storage that's owned by
// the packet. If you can guarantee that the bytes underlying the slice
// passed into NewPacket aren't going to be modified, this can be faster. If
// there's any chance that those bytes WILL be changed, this will invalidate
// SkipDecodeRecovery skips over panic recovery during packet decoding.
// Normally, when packets decode, if a panic occurs, that panic is captured
// by a recover(), and a DecodeFailure layer is added to the packet detailing
// the issue. If this flag is set, panics are instead allowed to continue up
// DecodeStreamsAsDatagrams enables routing of application-level layers in the TCP
// decoder. If true, we should try to decode layers after TCP in single packets.
// This is disabled by default because the reassembly package drives the decoding
// of TCP payload data after reassembly.
DecodeStreamsAsDatagrams bool
// Default decoding provides the safest (but slowest) method for decoding
// packets. It eagerly processes all layers (so it's concurrency-safe) and it
// copies its input buffer upon creation of the packet (so the packet remains
// valid if the underlying slice is modified. Both of these take time,
// though, so beware. If you can guarantee that the packet will only be used
// by one goroutine at a time, set Lazy decoding. If you can guarantee that
// the underlying slice won't change, set NoCopy decoding.
var Default = DecodeOptions{}
// Lazy is a DecodeOptions with just Lazy set.
var Lazy = DecodeOptions{Lazy: true}
// NoCopy is a DecodeOptions with just NoCopy set.
var NoCopy = DecodeOptions{NoCopy: true}
// DecodeStreamsAsDatagrams is a DecodeOptions with just DecodeStreamsAsDatagrams set.
var DecodeStreamsAsDatagrams = DecodeOptions{DecodeStreamsAsDatagrams: true}
// NewPacket creates a new Packet object from a set of bytes. The
// firstLayerDecoder tells it how to interpret the first layer from the bytes,
// future layers will be generated from that first layer automatically.
func NewPacket(data []byte, firstLayerDecoder Decoder, options DecodeOptions) Packet {
dataCopy := make([]byte, len(data))
packet: packet{data: data, decodeOptions: options},
p.layers = p.initialLayers[:0]
// If the following return statemet is REMOVED, and Lazy is FALSE, then
// eager packet processing becomes 17% FASTER. No, there is no logical
// explanation for this. However, it's such a hacky micro-optimization that
// we really can't rely on it. It appears to have to do with the size the
// compiler guesses for this function's stack space, since one symptom is
// that with the return statement in place, we more than double calls to
// runtime.morestack/runtime.lessstack. We'll hope the compiler gets better
// over time and we get this optimization for free. Until then, we'll have
// to live with slower packet processing.
packet: packet{data: data, decodeOptions: options},
p.layers = p.initialLayers[:0]
p.initialDecode(firstLayerDecoder)
// PacketDataSource is an interface for some source of packet data. Users may
// create their own implementations, or use the existing implementations in
// gopacket/pcap (libpcap, allows reading from live interfaces or from
// pcap files) or gopacket/pfring (PF_RING, allows reading from live
type PacketDataSource interface {
// ReadPacketData returns the next packet available from this data source.
// data: The bytes of an individual packet.
// ci: Metadata about the capture
// err: An error encountered while reading packet data. If err != nil,
// then data/ci will be ignored.
ReadPacketData() (data []byte, ci CaptureInfo, err error)
// ConcatFinitePacketDataSources returns a PacketDataSource that wraps a set
// of internal PacketDataSources, each of which will stop with io.EOF after
// reading a finite number of packets. The returned PacketDataSource will
// return all packets from the first finite source, followed by all packets from
// the second, etc. Once all finite sources have returned io.EOF, the returned
func ConcatFinitePacketDataSources(pds ...PacketDataSource) PacketDataSource {
type concat []PacketDataSource
func (c *concat) ReadPacketData() (data []byte, ci CaptureInfo, err error) {
data, ci, err = (*c)[0].ReadPacketData()
return nil, CaptureInfo{}, io.EOF
// ZeroCopyPacketDataSource is an interface to pull packet data from sources
// that allow data to be returned without copying to a user-controlled buffer.
// It's very similar to PacketDataSource, except that the caller must be more
// careful in how the returned buffer is handled.
type ZeroCopyPacketDataSource interface {
// ZeroCopyReadPacketData returns the next packet available from this data source.
// data: The bytes of an individual packet. Unlike with
// PacketDataSource's ReadPacketData, the slice returned here points
// to a buffer owned by the data source. In particular, the bytes in
// this buffer may be changed by future calls to
// ZeroCopyReadPacketData. Do not use the returned buffer after
// subsequent ZeroCopyReadPacketData calls.
// ci: Metadata about the capture
// err: An error encountered while reading packet data. If err != nil,
// then data/ci will be ignored.
ZeroCopyReadPacketData() (data []byte, ci CaptureInfo, err error)
// PacketSource reads in packets from a PacketDataSource, decodes them, and
// There are currently two different methods for reading packets in through
// Reading With Packets Function
// This method is the most convenient and easiest to code, but lacks
// flexibility. Packets returns a 'chan Packet', then asynchronously writes
// packets into that channel. Packets uses a blocking channel, and closes
// it if an io.EOF is returned by the underlying PacketDataSource. All other
// PacketDataSource errors are ignored and discarded.
// for packet := range packetSource.Packets() {
// Reading With NextPacket Function
// This method is the most flexible, and exposes errors that may be
// encountered by the underlying PacketDataSource. It's also the fastest
// in a tight loop, since it doesn't have the overhead of a channel
// read/write. However, it requires the user to handle errors, most
// importantly the io.EOF error in cases where packets are being read from
// packet, err := packetSource.NextPacket()
// } else if err != nil {
// log.Println("Error:", err)
// handlePacket(packet) // Do something with each packet.
type PacketSource struct {
// DecodeOptions is the set of options to use for decoding each piece
// of packet data. This can/should be changed by the user to reflect the
// way packets should be decoded.
// NewPacketSource creates a packet data source.
func NewPacketSource(source PacketDataSource, decoder Decoder) *PacketSource {
// NextPacket returns the next decoded packet from the PacketSource. On error,
// it returns a nil packet and a non-nil error.
func (p *PacketSource) NextPacket() (Packet, error) {
data, ci, err := p.source.ReadPacketData()
packet := NewPacket(data, p.decoder, p.DecodeOptions)
m.Truncated = m.Truncated || ci.CaptureLength < ci.Length
// packetsToChannel reads in all packets from the packet source and sends them
// to the given channel. This routine terminates when a non-temporary error
// is returned by NextPacket().
func (p *PacketSource) packetsToChannel() {
packet, err := p.NextPacket()
// Immediately retry for temporary network errors
if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
// Immediately retry for EAGAIN
if err == syscall.EAGAIN {
// Immediately break for known unrecoverable errors
if err == io.EOF || err == io.ErrUnexpectedEOF ||
err == io.ErrNoProgress || err == io.ErrClosedPipe || err == io.ErrShortBuffer ||
strings.Contains(err.Error(), "use of closed file") {
// Sleep briefly and try again
time.Sleep(time.Millisecond * time.Duration(5))
// Packets returns a channel of packets, allowing easy iterating over
// packets. Packets will be asynchronously read in from the underlying
// PacketDataSource and written to the returned channel. If the underlying
// PacketDataSource returns an io.EOF error, the channel will be closed.
// If any other error is encountered, it is ignored.
// for packet := range packetSource.Packets() {
// handlePacket(packet) // Do something with each packet.
// If called more than once, returns the same channel.
func (p *PacketSource) Packets() chan Packet {
p.c = make(chan Packet, 1000)