tstun

Documentation

Overview

Copyright (c) Tailscale Inc & AUTHORS SPDX-License-Identifier: BSD-3-Clause

Package tun creates a tuntap device, working around OS-specific quirks if necessary.

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

Index

• Constants
• Variables
• func DefaultMTU() uint32
• func Diagnose(logf logger.Logf, tunName string, err error)
• func New(logf logger.Logf, tunName string) (tun.Device, string, error)
• func NewFake() tun.Device
• type FilterFunc
• type Wrapper
  • func Wrap(logf logger.Logf, tdev tun.Device) *Wrapper
  • func WrapTAP(logf logger.Logf, tdev tun.Device) *Wrapper
  • func (t *Wrapper) BatchSize() int
  • func (t *Wrapper) Close() error
  • func (t *Wrapper) Events() <-chan tun.Event
  • func (t *Wrapper) EventsUpDown() chan tun.Event
  • func (t *Wrapper) File() *os.File
  • func (t *Wrapper) GetFilter() *filter.Filter
  • func (t *Wrapper) IdleDuration() time.Duration
  • func (t *Wrapper) InjectInboundCopy(packet []byte) error
  • func (t *Wrapper) InjectInboundDirect(buf []byte, offset int) error
  • func (t *Wrapper) InjectInboundPacketBuffer(pkt stack.PacketBufferPtr) error
  • func (t *Wrapper) InjectOutbound(pkt []byte) error
  • func (t *Wrapper) InjectOutboundPacketBuffer(pkt stack.PacketBufferPtr) error
  • func (t *Wrapper) InstallCaptureHook(cb capture.Callback)
  • func (t *Wrapper) MTU() (int, error)
  • func (t *Wrapper) Name() (string, error)
  • func (t *Wrapper) Read(buffs [][]byte, sizes []int, offset int) (int, error)
  • func (t *Wrapper) SetDestIPActivityFuncs(m map[netip.Addr]func())
  • func (t *Wrapper) SetDiscoKey(k key.DiscoPublic)
  • func (t *Wrapper) SetFilter(filt *filter.Filter)
  • func (t *Wrapper) SetStatistics(stats *connstats.Statistics)
  • func (t *Wrapper) SetWGConfig(wcfg *wgcfg.Config)
  • func (t *Wrapper) Unwrap() tun.Device
  • func (t *Wrapper) Write(buffs [][]byte, offset int) (int, error)

Constants

const FakeTUNName = "FakeTUN"

FakeTUNName is the name of the fake TUN device.

const MaxPacketSize = device.MaxContentSize

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

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 Wrapper.
	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 DefaultMTU

func DefaultMTU() uint32

DefaultMTU returns either the constant default MTU of 1280, or the value set in TS_DEBUG_MTU clamped to a maximum of 65536.

func Diagnose

func Diagnose(logf logger.Logf, tunName string, err error)

Diagnose tries to explain a tuntap device creation failure. It pokes around the system and logs some diagnostic info that might help debug why tun creation failed. Because device creation has already failed and the program's about to end, log a lot.

The tunName is the name of the tun device that was requested but failed. The err error is how the tun creation failed.

func New

func New(logf logger.Logf, tunName string) (tun.Device, string, error)

New returns a tun.Device for the requested device name, along with the OS-dependent name that was allocated to the device.

func NewFake

func NewFake() tun.Device

NewFake returns a tun.Device that does nothing.

Types

type FilterFunc

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

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

type Wrapper

type Wrapper struct {

	// PreFilterPacketInboundFromWireGuard is the inbound filter function that runs before the main filter
	// and therefore sees the packets that may be later dropped by it.
	PreFilterPacketInboundFromWireGuard FilterFunc
	// PostFilterPacketInboundFromWireGaurd is the inbound filter function that runs after the main filter.
	PostFilterPacketInboundFromWireGaurd FilterFunc
	// PreFilterPacketOutboundToWireGuardNetstackIntercept is a filter function that runs before the main filter
	// for packets from the local system. This filter is populated by netstack to hook
	// packets that should be handled by netstack. If set, this filter runs before
	// PreFilterFromTunToEngine.
	PreFilterPacketOutboundToWireGuardNetstackIntercept FilterFunc
	// PreFilterPacketOutboundToWireGuardEngineIntercept is a filter function that runs before the main filter
	// for packets from the local system. This filter is populated by wgengine to hook
	// packets which it handles internally. If both this and PreFilterFromTunToNetstack
	// filter functions are non-nil, this filter runs second.
	PreFilterPacketOutboundToWireGuardEngineIntercept FilterFunc
	// PostFilterPacketOutboundToWireGuard is the outbound filter function that runs after the main filter.
	PostFilterPacketOutboundToWireGuard FilterFunc

	// OnTSMPPongReceived, if non-nil, is called whenever a TSMP pong arrives.
	OnTSMPPongReceived func(packet.TSMPPongReply)

	// OnICMPEchoResponseReceived, if non-nil, is called whenever a ICMP echo response
	// arrives. If the packet is to be handled internally this returns true,
	// false otherwise.
	OnICMPEchoResponseReceived func(*packet.Parsed) bool

	// PeerAPIPort, if non-nil, returns the peerapi port that's
	// running for the given IP address.
	PeerAPIPort func(netip.Addr) (port uint16, ok bool)
	// contains filtered or unexported fields
}

Wrapper augments a tun.Device with packet filtering and injection.

func Wrap

func Wrap(logf logger.Logf, tdev tun.Device) *Wrapper

func WrapTAP

func WrapTAP(logf logger.Logf, tdev tun.Device) *Wrapper

func (*Wrapper) BatchSize

func (t *Wrapper) BatchSize() int

func (*Wrapper) Close

func (t *Wrapper) Close() error

func (*Wrapper) Events

func (t *Wrapper) Events() <-chan tun.Event

Events returns a TUN event channel that contains all non-Up, non-Down events. It is named Events because it is the set of events that we want to expose to wireguard-go, and Events is the name specified by the wireguard-go tun.Device interface.

func (*Wrapper) EventsUpDown

func (t *Wrapper) EventsUpDown() chan tun.Event

EventsUpDown returns a TUN event channel that contains all Up and Down events.

func (*Wrapper) File

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

func (*Wrapper) GetFilter

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

func (*Wrapper) IdleDuration

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

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

Its value should only be presumed accurate to roughly 10ms granularity. If there's never been activity, the duration is since the wrapper was created.

func (*Wrapper) InjectInboundCopy

func (t *Wrapper) 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 (*Wrapper) InjectInboundDirect

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

InjectInboundDirect makes the Wrapper 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 (*Wrapper) InjectInboundPacketBuffer

func (t *Wrapper) InjectInboundPacketBuffer(pkt stack.PacketBufferPtr) error

InjectInboundPacketBuffer makes the Wrapper device behave as if a packet with the given contents was received from the network. It takes ownership of one reference count on the packet. The injected packet will not pass through inbound filters.

This path is typically used to deliver synthesized packets to the host networking stack.

func (*Wrapper) InjectOutbound

func (t *Wrapper) InjectOutbound(pkt []byte) error

InjectOutbound makes the Wrapper 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 (*Wrapper) InjectOutboundPacketBuffer

func (t *Wrapper) InjectOutboundPacketBuffer(pkt stack.PacketBufferPtr) error

InjectOutboundPacketBuffer logically behaves as InjectOutbound. It takes ownership of one reference count on the packet, and the packet may be mutated. The packet refcount will be decremented after the injected buffer has been read.

func (*Wrapper) InstallCaptureHook

func (t *Wrapper) InstallCaptureHook(cb capture.Callback)

func (*Wrapper) MTU

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

func (*Wrapper) Name

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

func (*Wrapper) Read

func (t *Wrapper) Read(buffs [][]byte, sizes []int, offset int) (int, error)

func (*Wrapper) SetDestIPActivityFuncs

func (t *Wrapper) SetDestIPActivityFuncs(m map[netip.Addr]func())

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

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

func (*Wrapper) SetDiscoKey

func (t *Wrapper) SetDiscoKey(k key.DiscoPublic)

SetDiscoKey sets the current discovery key.

It is only used for filtering out bogus traffic when network stack(s) get confused; see Issue 1526.

func (*Wrapper) SetFilter

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

func (*Wrapper) SetStatistics

func (t *Wrapper) SetStatistics(stats *connstats.Statistics)

SetStatistics specifies a per-connection statistics aggregator. Nil may be specified to disable statistics gathering.

func (*Wrapper) SetWGConfig

func (t *Wrapper) SetWGConfig(wcfg *wgcfg.Config)

SetNetMap is called when a new NetworkMap is received. It currently (2023-03-01) only updates the IPv4 NAT configuration.

func (*Wrapper) Unwrap

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

Unwrap returns the underlying tun.Device.

func (*Wrapper) Write

func (t *Wrapper) Write(buffs [][]byte, offset int) (int, error)

Write accepts incoming packets. The packets begins at buffs[:][offset:], like wireguard-go/tun.Device.Write.