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.

Stability

At this time, package raw is in a pre-v1.0.0 state. Changes are being made which may impact the exported API of this package and others in its ecosystem.

The general policy of this package is to only support the latest, stable version of Go. Compatibility shims may be added for prior versions of Go on an as-needed basis. If you would like to raise a concern, please file an issue.

If you depend on this package in your applications, please vendor it or use Go modules when building your application.

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 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 Interface
  • func InterfaceByIndex(i int) (Interface, error)
  • func InterfaceByName(name string) (Interface, error)
  • func Interfaces() ([]Interface, error)
  • func NewInterface(ifi *net.Interface) Interface
  • func NewInterfaceDelegate(index int, name string) Interface
• 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

	// 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 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 Interface

type Interface interface {
	Name() string
	Index() int
	MTU() int
	Flags() net.Flags
	Addrs() ([]net.Addr, error)
	HardwareAddr() net.HardwareAddr
}

func InterfaceByIndex

func InterfaceByIndex(i int) (Interface, error)

func InterfaceByName

func InterfaceByName(name string) (Interface, error)

func Interfaces

func Interfaces() ([]Interface, error)

func NewInterface

func NewInterface(ifi *net.Interface) Interface

func NewInterfaceDelegate

func NewInterfaceDelegate(index int, name string) Interface

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.