raw

README

raw

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

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

Portions of this code are taken from the Go standard library. The Go standard library is Copyright (c) 2012 The Go Authors. All rights reserved. The Go license can be found at https://golang.org/LICENSE.

Documentation

Overview

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

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 is returned when certain functionality is not yet
	// implemented for the host operating system.
	ErrNotImplemented = errors.New("raw: not implemented")
)

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

	// Experimental: Linux only (for now, but can be ported to BSD):
	// disables repeated socket reads due to internal timeouts, at the expense
	// of losing the ability to cancel a ReadFrom operation by calling the Close
	// method of the net.PacketConn.
	//
	// Not recommended for programs which may need to open and close multiple
	// sockets during program runs.  This may save some CPU time by avoiding a
	// busy loop for programs which do not need timeouts, or programs which keep
	// a single socket open for the entire duration of the program.
	NoTimeouts 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
}

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.