raw

README

raw

Package raw enables reading and writing data at the device driver level for a network interface. MIT Licensed.

Deprecated: use github.com/mdlayher/packet on Linux instead. This package is unmaintained.

For more information about using sockets with Ethernet frames in Go, check out my blog post: Network Protocol Breakdown: Ethernet and Go.

Unmaintained

This repository was one of my first major Go networking libraries. Although I have updated it on Linux to incorporate modern Go best practices (asynchronous I/O, runtime network poller integration), the non-Linux platform code is effectively unmaintained and does not have the same level of functionality.

I encourage all Linux users of this package to migrate to github.com/mdlayher/packet, which is a modern AF_PACKET library. The existing *raw.Conn APIs now call directly into the equivalent *packet.Conn APIs, and a level of indirection can be removed by migrating to that package.

Documentation

Overview

Package raw enables reading and writing data at the device driver level for a network interface.

Deprecated: use github.com/mdlayher/packet on Linux instead. This package is unmaintained.

Unmaintained

This repository was one of my first major Go networking libraries. Although I have updated it on Linux to incorporate modern Go best practices (asynchronous I/O, runtime network poller integration), the non-Linux platform code is effectively unmaintained and does not have the same level of functionality.

I encourage all Linux users of this package to migrate to https://github.com/mdlayher/packet, which is a modern AF_PACKET library. The existing *raw.Conn APIs now call directly into the equivalent *packet.Conn APIs, and a level of indirection can be removed by migrating to that package.

Index

• Variables
• type Addr
  • func (a *Addr) Network() string
  • func (a *Addr) String() string
• type Config
• type Conn
  • func ListenPacket(ifi *net.Interface, proto uint16, cfg *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)
  • func (c *Conn) SetBPF(filter []bpf.RawInstruction) error
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetPromiscuous(b bool) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Stats() (*Stats, error)
  • func (c *Conn) WriteTo(b []byte, addr net.Addr) (int, error)
• type Stats

Variables

var ErrNotImplemented = errors.New("raw: not implemented")

ErrNotImplemented is returned when certain functionality is not yet implemented for the host operating system.

Types

type Addr

type Addr struct {
	HardwareAddr net.HardwareAddr
}

Addr is a network address which can be used to contact other machines, using their hardware addresses.

func (*Addr) Network

func (a *Addr) Network() string

Network returns the address's network name, "raw".

func (*Addr) String

func (a *Addr) String() string

String returns the address's hardware address.

type Config

type Config struct {
	// Linux only: call socket(7) with SOCK_DGRAM instead of SOCK_RAW.
	// Has no effect on other operating systems.
	LinuxSockDGRAM bool

	// Linux only: do not accumulate packet socket statistic counters.  Packet
	// socket statistics are reset on each call to retrieve them via getsockopt,
	// but this package's default behavior is to continue accumulating the
	// statistics internally per Conn.  To use the Linux default behavior of
	// resetting statistics on each call to Stats, set this value to true.
	NoCumulativeStats bool

	// Linux only: initial filter to apply to the connection. This avoids
	// capturing random packets before SetBPF is called.
	Filter []bpf.RawInstruction

	// BSD only: configure the BPF direction flag to allow selection of inbound
	// only (0 - default) or bidirectional (1) packet processing.
	// Has no effect on other operating systems.
	BPFDirection int
}

A Config can be used to specify additional options for a Conn.

type Conn

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

Conn is an implementation of the net.PacketConn interface which can send and receive data at the network interface device driver level.

func ListenPacket

func ListenPacket(ifi *net.Interface, proto uint16, cfg *Config) (*Conn, error)

ListenPacket creates a net.PacketConn which can be used to send and receive data at the network interface device driver level.

ifi specifies the network interface which will be used to send and receive data.

proto specifies the protocol (usually the EtherType) which should be captured and transmitted. proto, if needed, is automatically converted to network byte order (big endian), akin to the htons() function in C.

cfg specifies optional configuration which may be operating system-specific. A nil Config is equivalent to the default configuration: send and receive data at the network interface device driver level (usually raw Ethernet frames).

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Conn) ReadFrom

func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)

ReadFrom implements the net.PacketConn ReadFrom method.

func (*Conn) SetBPF

func (c *Conn) SetBPF(filter []bpf.RawInstruction) error

SetBPF attaches an assembled BPF program to the connection.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline implements the net.PacketConn SetDeadline method.

func (*Conn) SetPromiscuous

func (c *Conn) SetPromiscuous(b bool) error

SetPromiscuous enables or disables promiscuous mode on the interface, allowing it to receive traffic that is not addressed to the interface.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline implements the net.PacketConn SetReadDeadline method.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the net.PacketConn SetWriteDeadline method.

func (*Conn) Stats

func (c *Conn) Stats() (*Stats, error)

Stats retrieves statistics from the Conn.

Only supported on Linux at this time.

func (*Conn) WriteTo

func (c *Conn) WriteTo(b []byte, addr net.Addr) (int, error)

WriteTo implements the net.PacketConn WriteTo method.

type Stats

type Stats struct {
	// The total number of packets received.
	Packets uint64

	// The number of packets dropped.
	Drops uint64
}

Stats contains statistics about a Conn.