tun

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 9, 2026 License: CC0-1.0 Imports: 4 Imported by: 0

Documentation

Overview

Package tun provides a TUN (network tunnel) interface for handling virtual network devices. It defines the Tun interface, which is compatible with wireguard-go and similar projects, along with utility functions for I/O adaptation, testing, and bidirectional packet copying.

The package includes:

  • Tun: Core interface for reading/writing network packets in batches
  • IO: Adapter that wraps Tun to implement io.ReadWriteCloser for single-packet operations
  • Pipe: Creates paired connected Tun implementations for testing (similar to net.Pipe)
  • Copy: Bidirectional packet copying between two Tun implementations

Index

Constants

View Source
const (
	EventUp = 1 << iota
	EventDown
	EventMTUUpdate
)

Variables

View Source
var ErrReadOnClosedPipe = errors.Join(
	os.ErrClosed,
	errors.New("tun: read on closed Tun"),
)
View Source
var ErrWriteOnClosedPipe = errors.Join(
	os.ErrClosed,
	errors.New("tun: write on closed Tun"),
)

Functions

func Copy

func Copy(a, b Tun) error

Copy copies packets bidirectionally between two Tun implementations. It uses the batch nature of the Tun interface for optimal performance. Copy blocks until one of the Tuns is closed or encounters an error, then closes both Tuns and returns the first error encountered (if any).

func Pipe

func Pipe(batch int, mtu int) (Tun, Tun)

Pipe creates two connected Tun implementations that are bound together. Packets written to one Tun can be read from the other, similar to net.Pipe. The returned Tun instances share a bidirectional channel-based connection.

Types

type Event

type Event int

type IO

type IO struct {
	Tun
	// contains filtered or unexported fields
}

IO is an io.ReadWriteCloser wrapper for a Tun. It adapts the batch-oriented Tun interface to the single-buffer io.ReadWriteCloser interface, handling one packet at a time.

func NewIO

func NewIO(tun Tun) *IO

NewIO creates a new IO wrapper for the given Tun.

func (*IO) Close

func (r *IO) Close() error

Close implements io.Closer. It closes the underlying Device.

func (*IO) Read

func (r *IO) Read(p []byte) (int, error)

Read implements io.Reader. It reads a single packet from the Device.

func (*IO) Write

func (r *IO) Write(p []byte) (int, error)

Write implements io.Writer. It writes a single packet to the Device.

type Tun

type Tun interface {
	// File returns the file descriptor of the tun device.
	// It may be nil for virtual/mock/etc implementations.
	File() *os.File

	// Read a batch of packets from Tun.
	// If original source (e.g. linux tun interface) ruturn additional headers,
	// they are stripped under the hood.
	// 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 Tun 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 tun (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
}

Tun interface is borrowed from wireguard-go. There is multiple projects that use same or similar interfaces so it is a good choice for a de-facto standard role.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL