tstun

Documentation

Overview

Package tstun provides a TUN struct implementing the tun.Device interface with additional features as required by wgengine.

Index

• Constants
• Variables
• func NewFakeTUN() tun.Device
• type FilterFunc
• type TUN
  • func WrapTUN(logf logger.Logf, tdev tun.Device) *TUN
  • func (t *TUN) Close() error
  • func (t *TUN) Events() chan tun.Event
  • func (t *TUN) File() *os.File
  • func (t *TUN) Flush() error
  • func (t *TUN) GetFilter() *filter.Filter
  • func (t *TUN) IdleDuration() time.Duration
  • func (t *TUN) InjectInboundCopy(packet []byte) error
  • func (t *TUN) InjectInboundDirect(buf []byte, offset int) error
  • func (t *TUN) InjectOutbound(packet []byte) error
  • func (t *TUN) MTU() (int, error)
  • func (t *TUN) Name() (string, error)
  • func (t *TUN) Read(buf []byte, offset int) (int, error)
  • func (t *TUN) SetDestIPActivityFuncs(m map[netaddr.IP]func())
  • func (t *TUN) SetFilter(filt *filter.Filter)
  • func (t *TUN) Unwrap() tun.Device
  • func (t *TUN) Write(buf []byte, offset int) (int, error)

Constants

const MaxPacketSize = device.MaxContentSize

MaxPacketSize is the maximum size (in bytes) of a packet that can be injected into a tstun.TUN.

const PacketStartOffset = device.MessageTransportHeaderSize

PacketStartOffset is the minimal amount of leading space that must exist before &packet[offset] in a packet passed to Read, Write, or InjectInboundDirect. This is necessary to avoid reallocation in wireguard-go internals.

Variables

var (
	// ErrClosed is returned when attempting an operation on a closed TUN.
	ErrClosed = errors.New("device closed")
	// ErrFiltered is returned when the acted-on packet is rejected by a filter.
	ErrFiltered = errors.New("packet dropped by filter")
)

Functions

func NewFakeTUN

func NewFakeTUN() tun.Device

NewFakeTUN returns a fake TUN device that does not depend on the operating system or any special permissions. It primarily exists for testing.

Types

type FilterFunc

type FilterFunc func(*packet.Parsed, *TUN) filter.Response

FilterFunc is a packet-filtering function with access to the TUN device. It must not hold onto the packet struct, as its backing storage will be reused.

type TUN

type TUN struct {

	// PreFilterIn is the inbound filter function that runs before the main filter
	// and therefore sees the packets that may be later dropped by it.
	PreFilterIn FilterFunc
	// PostFilterIn is the inbound filter function that runs after the main filter.
	PostFilterIn FilterFunc
	// PreFilterOut is the outbound filter function that runs before the main filter
	// and therefore sees the packets that may be later dropped by it.
	PreFilterOut FilterFunc
	// PostFilterOut is the outbound filter function that runs after the main filter.
	PostFilterOut FilterFunc
	// contains filtered or unexported fields
}

TUN wraps a tun.Device from wireguard-go, augmenting it with filtering and packet injection. All the added work happens in Read and Write: the other methods delegate to the underlying tdev.

func WrapTUN

func WrapTUN(logf logger.Logf, tdev tun.Device) *TUN

func (*TUN) Close

func (t *TUN) Close() error

func (*TUN) Events

func (t *TUN) Events() chan tun.Event

func (*TUN) File

func (t *TUN) File() *os.File

func (*TUN) Flush

func (t *TUN) Flush() error

func (*TUN) GetFilter

func (t *TUN) GetFilter() *filter.Filter

func (*TUN) IdleDuration

func (t *TUN) IdleDuration() time.Duration

IdleDuration reports how long it's been since the last read or write to this device.

Its value is only accurate to roughly second granularity. If there's never been activity, the duration is since 1970.

func (*TUN) InjectInboundCopy

func (t *TUN) InjectInboundCopy(packet []byte) error

InjectInboundCopy takes a packet without leading space, reallocates it to conform to the InjectInboundDirect interface and calls InjectInboundDirect on it. Injecting a nil packet is a no-op.

func (*TUN) InjectInboundDirect

func (t *TUN) InjectInboundDirect(buf []byte, offset int) error

InjectInboundDirect makes the TUN device behave as if a packet with the given contents was received from the network. It blocks and does not take ownership of the packet. The injected packet will not pass through inbound filters.

The packet contents are to start at &buf[offset]. offset must be greater or equal to PacketStartOffset. The space before &buf[offset] will be used by Wireguard.

func (*TUN) InjectOutbound

func (t *TUN) InjectOutbound(packet []byte) error

InjectOutbound makes the TUN device behave as if a packet with the given contents was sent to the network. It does not block, but takes ownership of the packet. The injected packet will not pass through outbound filters. Injecting an empty packet is a no-op.

func (*TUN) MTU

func (t *TUN) MTU() (int, error)

func (*TUN) Name

func (t *TUN) Name() (string, error)

func (*TUN) Read

func (t *TUN) Read(buf []byte, offset int) (int, error)

func (*TUN) SetDestIPActivityFuncs

func (t *TUN) SetDestIPActivityFuncs(m map[netaddr.IP]func())

SetDestIPActivityFuncs sets a map of funcs to run per packet destination (the map keys).

The map ownership passes to the TUN. It must be non-nil.

func (*TUN) SetFilter

func (t *TUN) SetFilter(filt *filter.Filter)

func (*TUN) Unwrap

func (t *TUN) Unwrap() tun.Device

Unwrap returns the underlying TUN device.

func (*TUN) Write

func (t *TUN) Write(buf []byte, offset int) (int, error)

Write accepts an incoming packet. The packet begins at buf[offset:], like wireguard-go/tun.Device.Write.