tun

Documentation

Index

• Constants
• Variables
• func Checksum(data []byte, initial uint16) uint16
• func GSOSplit(in []byte, options GSOOptions, outBufs [][]byte, sizes []int, outOffset int) (int, error)
• func PseudoHeaderChecksum(protocol uint8, srcAddr, dstAddr []byte, totalLen uint16) uint16
• type Device
  • func CreateTUN(name string, mtu int) (Device, error)
  • func CreateTUNFromFile(file *os.File, mtu int) (Device, error)
  • func CreateUnmonitoredTUNFromFD(fd int) (Device, string, error)
• type Event
• type GRODevice
• type GSOOptions
• type GSOType
  • func (g GSOType) String() string
• type NativeTun
  • func (tun *NativeTun) BatchSize() int
  • func (tun *NativeTun) Close() error
  • func (tun *NativeTun) DisableTCPGRO()
  • func (tun *NativeTun) DisableUDPGRO()
  • func (tun *NativeTun) Events() <-chan Event
  • func (tun *NativeTun) File() *os.File
  • func (tun *NativeTun) MTU() (int, error)
  • func (tun *NativeTun) Name() (string, error)
  • func (tun *NativeTun) Read(bufs [][]byte, sizes []int, offset int) (int, error)
  • func (tun *NativeTun) Write(bufs [][]byte, offset int) (int, error)

Constants

const (
	EventUp = 1 << iota
	EventDown
	EventMTUUpdate
)

Variables

var ErrTooManySegments = errors.New("too many segments")

ErrTooManySegments is returned by Device.Read() when segmentation overflows the length of supplied buffers. This error should not cause reads to cease.

Functions

func Checksum

func Checksum(data []byte, initial uint16) uint16

Checksum computes an IP checksum starting with the provided initial value. The length of data should be at least 128 bytes for best performance. Smaller buffers will still compute a correct result.

func GSOSplit

func GSOSplit(in []byte, options GSOOptions, outBufs [][]byte, sizes []int, outOffset int) (int, error)

GSOSplit splits packets from 'in' into outBufs[<index>][outOffset:], writing the size of each element into sizes. It returns the number of buffers populated, and/or an error. Callers may pass an 'in' slice that overlaps with the first element of outBuffers, i.e. &in[0] may be equal to &outBufs[0][outOffset]. GSONone is a valid options.GSOType regardless of the value of options.NeedsCsum. Length of each outBufs element must be greater than or equal to the length of 'in', otherwise output may be silently truncated.

func PseudoHeaderChecksum

func PseudoHeaderChecksum(protocol uint8, srcAddr, dstAddr []byte, totalLen uint16) uint16

PseudoHeaderChecksum computes an IP pseudo-header checksum. srcAddr and dstAddr must be 4 or 16 bytes in length.

Types

type Device

type Device interface {
	// File returns the file descriptor of the device.
	File() *os.File

	// Read one or more packets from the Device (without any additional headers).
	// On a successful read it returns the number of packets read, and sets
	// packet lengths within the sizes slice. len(sizes) must be >= len(bufs).
	// A nonzero offset can be used to instruct the Device on where to begin
	// reading into each element of the bufs slice.
	Read(bufs [][]byte, sizes []int, offset int) (n int, err error)

	// Write one or more packets to the device (without any additional headers).
	// On a successful write it returns the number of packets written. A nonzero
	// offset can be used to instruct the Device on where to begin writing from
	// each packet contained within the bufs slice.
	Write(bufs [][]byte, offset int) (int, error)

	// MTU returns the MTU of the Device.
	MTU() (int, error)

	// Name returns the current name of the Device.
	Name() (string, error)

	// Events returns a channel of type Event, which is fed Device events.
	Events() <-chan Event

	// Close stops the Device and closes the Event channel.
	Close() error

	// BatchSize returns the preferred/max number of packets that can be read or
	// written in a single read/write call. BatchSize must not change over the
	// lifetime of a Device.
	BatchSize() int
}

func CreateTUN

func CreateTUN(name string, mtu int) (Device, error)

CreateTUN creates a Device with the provided name and MTU.

func CreateTUNFromFile

func CreateTUNFromFile(file *os.File, mtu int) (Device, error)

CreateTUNFromFile creates a Device from an os.File with the provided MTU.

func CreateUnmonitoredTUNFromFD

func CreateUnmonitoredTUNFromFD(fd int) (Device, string, error)

CreateUnmonitoredTUNFromFD creates a Device from the provided file descriptor.

type Event

type Event int

type GRODevice

type GRODevice interface {
	Device
	// DisableUDPGRO disables UDP GRO if it is enabled.
	DisableUDPGRO()
	// DisableTCPGRO disables TCP GRO if it is enabled.
	DisableTCPGRO()
}

GRODevice is a Device extended with methods for disabling GRO. Certain OS versions may have offload bugs. Where these bugs negatively impact throughput or break connectivity entirely we can use these methods to disable the related offload.

Linux has the following known, GRO bugs.

torvalds/linux@e269d79c7d35aa3808b1f3c1737d63dab504ddc8 broke virtio_net TCP & UDP GRO causing GRO writes to return EINVAL. The bug was then resolved later in torvalds/linux@89add40066f9ed9abe5f7f886fe5789ff7e0c50e. The offending commit was pulled into various LTS releases.

UDP GRO writes end up blackholing/dropping packets destined for a vxlan/geneve interface on kernel versions prior to 6.8.5.

type GSOOptions

type GSOOptions struct {
	// GSOType represents the type of segmentation offload.
	GSOType GSOType
	// HdrLen is the sum of the layer 3 and 4 header lengths. This field may be
	// zero when GSOType == GSONone.
	HdrLen uint16
	// CsumStart is the head byte index of the packet data to be checksummed,
	// i.e. the start of the TCP or UDP header.
	CsumStart uint16
	// CsumOffset is the offset from CsumStart where the 2-byte checksum value
	// should be placed.
	CsumOffset uint16
	// GSOSize is the size of each segment exclusive of HdrLen. The tail segment
	// may be smaller than this value.
	GSOSize uint16
	// NeedsCsum may be set where GSOType == GSONone. When set, the checksum
	// at CsumStart + CsumOffset must be a partial checksum, i.e. the
	// pseudo-header sum.
	NeedsCsum bool
}

GSOOptions is loosely modeled after struct virtio_net_hdr from the VIRTIO specification. It is a common representation of GSO metadata that can be applied to support packet GSO across tun.Device implementations.

type GSOType

type GSOType int

GSOType represents the type of segmentation offload.

const (
	GSONone GSOType = iota
	GSOTCPv4
	GSOTCPv6
	GSOUDPL4
)

func (GSOType) String

func (g GSOType) String() string

type NativeTun

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

func (*NativeTun) BatchSize

func (tun *NativeTun) BatchSize() int

func (*NativeTun) Close

func (tun *NativeTun) Close() error

func (*NativeTun) DisableTCPGRO

func (tun *NativeTun) DisableTCPGRO()

DisableTCPGRO disables TCP GRO if it is enabled. See the GRODevice interface for cases where it should be called.

func (*NativeTun) DisableUDPGRO

func (tun *NativeTun) DisableUDPGRO()

DisableUDPGRO disables UDP GRO if it is enabled. See the GRODevice interface for cases where it should be called.

func (*NativeTun) Events

func (tun *NativeTun) Events() <-chan Event

func (*NativeTun) File

func (tun *NativeTun) File() *os.File

func (*NativeTun) MTU

func (tun *NativeTun) MTU() (int, error)

func (*NativeTun) Name

func (tun *NativeTun) Name() (string, error)

func (*NativeTun) Read

func (tun *NativeTun) Read(bufs [][]byte, sizes []int, offset int) (int, error)

func (*NativeTun) Write

func (tun *NativeTun) Write(bufs [][]byte, offset int) (int, error)