link

Documentation

Overview

Package link provides access to network interfaces and their parameters, such as link type and flags. In addition, it provides the IP layer offset for each link type and implements default BPF filtering to maximize throughput (by selecting only packets that subsequently can be processed / parsed by the routines provided by slimcap).

Index

• Constants
• Variables
• type CaptureLengthStrategy
• type EtherType
  • func (t EtherType) HasValidIPLayer() bool
• type Interface
  • func Interfaces() ([]Interface, error)
  • func NewInterface(name string) (iface Interface, err error)
  • func (i Interface) IsUp() (bool, error)
  • func (i Interface) String() string
• type Link
  • func FindAllLinks() ([]*Link, error)
  • func New(ifName string, opts ...func(*Link)) (link *Link, err error)
  • func (l *Link) IsUp() (bool, error)
• type Type
  • func (l Type) BPFFilter() func(snapLen int) []bpf.RawInstruction
  • func (l Type) IPHeaderOffset() byte

Constants

const (

	// IPLayerOffsetEthernet denotes the ethernet header offset
	IPLayerOffsetEthernet = 14

	// LayerOffsetPPPOE denotes the additional offset for PPPOE (session) packets
	LayerOffsetPPPOE = 8
)

Variables

var (

	// ErrNotExist denotes that the interface in question does not exist
	ErrNotExist = errors.New("interface does not exist")

	// ErrNotUp denotes that the interface in question is not up
	ErrNotUp = errors.New("interface is currently not up")
)

var (

	// CaptureLengthFixed denotes a simple fixed snaplen strategy
	CaptureLengthFixed = func(snaplen int) CaptureLengthStrategy {
		return func(l *Link) int {
			return snaplen
		}
	}

	// CaptureLengthMinimalIPv4Header indicates that the minimal necessary length to
	// facilitate IPv4 layer analysis should be chosen
	CaptureLengthMinimalIPv4Header = func(l *Link) int {
		return int(l.Type.IPHeaderOffset()) + ipv4.HeaderLen
	}

	// CaptureLengthMinimalIPv6Header indicates that the minimal necessary length to
	// facilitate IPv6 layer analysis should be chosen
	CaptureLengthMinimalIPv6Header = func(l *Link) int {
		return int(l.Type.IPHeaderOffset()) + ipv6.HeaderLen
	}

	// CaptureLengthMinimalIPv4Transport indicates that the minimal necessary length to
	// facilitate IPv4 transport layer analysis should be chosen
	CaptureLengthMinimalIPv4Transport = func(l *Link) int {
		return int(l.Type.IPHeaderOffset()) + ipv4.HeaderLen + 14
	}

	// CaptureLengthMinimalIPv6Transport indicates that the minimal necessary length to
	// facilitate IPv6 transport layer analysis should be chosen
	CaptureLengthMinimalIPv6Transport = func(l *Link) int {
		return int(l.Type.IPHeaderOffset()) + ipv6.HeaderLen + 14
	}
)

var EmptyEthernetLink = Link{
	Interface: Interface{
		Type: TypeEthernet,
	},
}

EmptyEthernetLink provides a quick access to a plain / empty ethernet-type link

var ErrIndexOutOfBounds = errors.New("interface index out of bounds")

ErrIndexOutOfBounds denotes the (unlikely) case of an invalid index being outside the range of an int

Types

type CaptureLengthStrategy

type CaptureLengthStrategy = func(l *Link) int

CaptureLengthStrategy denotes a strategy to calculate an optimal snaplen for a link (type) depending on the use case

type EtherType

type EtherType uint16

EtherType denotes the protocol encapsulated in the payload of the ethernet frame

const (

	// EtherTypeIPv4 denotes an IPv4 ethernet frame
	EtherTypeIPv4 EtherType = 0x0800

	// EtherTypeIPv6 denotes an IPv6 ethernet frame
	EtherTypeIPv6 EtherType = 0x86DD
)

func (EtherType) HasValidIPLayer

func (t EtherType) HasValidIPLayer() bool

HasValidIPLayer determines if the ethernet frame has a valid IPv4 or IPv6 layer

type Interface

type Interface struct {
	Name  string
	Index int
	Type  Type
}

Interface is the low-level representation of a network interface

func Interfaces

func Interfaces() ([]Interface, error)

Interfaces returns all host interfaces

func NewInterface

func NewInterface(name string) (iface Interface, err error)

NewInterface instantiates a new network interface and obtains its basic parameters

func (Interface) IsUp

func (i Interface) IsUp() (bool, error)

IsUp determines if an interface is currently up (at the time of the call)

func (Interface) String

func (i Interface) String() string

String returns the name of the network interface (Stringer interface)

type Link

type Link struct {
	Interface
}

Link denotes a link, i.e. an interface (wrapped) and its link type

func FindAllLinks

func FindAllLinks() ([]*Link, error)

FindAllLinks retrieves all system network interfaces and their link type

func New

func New(ifName string, opts ...func(*Link)) (link *Link, err error)

New instantiates a new link / interface

func (*Link) IsUp

func (l *Link) IsUp() (bool, error)

IsUp returns if a link / interface is up

type Type

type Type int

Type denotes the linux interface type

const (

	// TypeInvalid denotes an invalid link type
	TypeInvalid Type = iota

	// TypeEthernet denotes a link of type ARPHRD_ETHER
	TypeEthernet Type = 1

	// TypeLoopback denotes a link of type ARPHRD_LOOPBACK
	TypeLoopback Type = 772

	// TypePPP denotes a link of type ARPHRD_PPP
	TypePPP Type = 512

	// TypeIP6IP6 denotes a link of type ARPHRD_TUNNEL6
	TypeIP6IP6 Type = 769

	// TypeGRE denotes a link of type ARPHRD_IPGRE
	TypeGRE Type = 778

	// TypeGRE6 denotes a link of type ARPHRD_IP6GRE
	TypeGRE6 Type = 823

	// TypeNone denotes a link of type ARPHRD_NONE:
	// Tunnel / anything else (confirmed: Wireguard, OpenVPN)
	TypeNone Type = 65534
)

func (Type) BPFFilter

func (l Type) BPFFilter() func(snapLen int) []bpf.RawInstruction

BPFFilter returns the link / interface specific raw BPF instructions to filter for valid packets only

func (Type) IPHeaderOffset

func (l Type) IPHeaderOffset() byte

IPHeaderOffset returns the link / interface specific payload offset for the IP header c.f. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_arp.h