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.
Index ¶
Constants ¶
const ( EventUp = 1 << iota EventDown EventMTUUpdate )
Variables ¶
var ErrReadOnClosedChan = errors.Join( os.ErrClosed, errors.New("tun: read on closed Tun channel"), )
var ErrReadOnClosedPipe = errors.Join( os.ErrClosed, errors.New("tun: read on closed Tun"), )
Functions ¶
Types ¶
type CallbackTUN ¶ added in v0.5.0
CallbackTUN wraps a Tun interface adding callbacks for read and write operations.
type Channel ¶ added in v0.5.0
type Channel struct {
// contains filtered or unexported fields
}
Channel is a batched communication channel for byte slices that partially implements Tun interface. For bi-directional full Tun implementation see Pipe.
type Forwarder ¶ added in v0.5.0
type Forwarder struct {
// contains filtered or unexported fields
}
Forwarder manages bidirectional forwarding between two TUN devices. It runs two goroutines: one for reading from the read TUN and one for writing to the write TUN. The forwarder can be reconfigured dynamically (e.g., swap TUN devices) without stopping.
For bi-directional forwarding see Point2Point.
func NewForwarder ¶ added in v0.5.0
NewForwarder creates a new Forwarder with the given buffer pool (can be nil). It starts the reader and writer goroutines. The forwarder initially has no TUN devices and must be configured via SetReadTun and SetWriteTun.
func (*Forwarder) SetReadTun ¶ added in v0.5.0
SetReadTun dynamically replaces the TUN device used for reading. The old read TUN (if any) is closed. If the forwarder is stopped, this call does nothing.
func (*Forwarder) SetWriteTun ¶ added in v0.5.0
SetWriteTun dynamically replaces the TUN device used for writing. The old write TUN (if any) is closed. If the forwarder is stopped, this call does nothing.
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.
type Point2Point ¶ added in v0.5.0
type Point2Point struct {
// contains filtered or unexported fields
}
Point2Point manages bidirectional forwarding between two TUN devices, conventionally named A and B. It can be reconfigured dynamically (e.g., swap TUN devices) without stopping.
func NewP2P ¶ added in v0.5.0
func NewP2P(pool bufpool.Pool) *Point2Point
NewP2P creates a new Point2Point instance using the provided buffer pool. Point2Point start with no TUN devices and must be configured using SetA and SetB.
func (*Point2Point) SetA ¶ added in v0.5.0
func (p *Point2Point) SetA(tun Tun)
SetA configures the given TUN device as endpoint A. Endpoint A will be used for reading packets to send to B, and will also receive packets coming from B (i.e., writes from B to A are written to this TUN).
func (*Point2Point) SetB ¶ added in v0.5.0
func (p *Point2Point) SetB(tun Tun)
SetB configures the given TUN device as endpoint B. Endpoint B will be used for reading packets to send to A, and will also receive packets coming from A (i.e., writes from A to B are written to this TUN).
func (*Point2Point) Stop ¶ added in v0.5.0
func (p *Point2Point) Stop()
Stop gracefully shuts down both internal forwarders, releasing all resources and waiting for goroutines to finish.
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).
// Callers must size bufs from the source Tun's BatchSize(); a single Read
// may yield multiple logical packets, and some native TUN implementations
// can require multiple buffers even for one inbound frame.
// 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. Callers must chunk writes
// using the destination Tun's BatchSize() and handle partial writes.
Write(bufs [][]byte, offset int) (int, error)
// MWO stands for Minimal Write Offset.
// It is typically used by native tun implementations to reserver space for
// OS specific headers.
MWO() int
// MRO stands for Minimal Read Offset.
// It isn't used anywhere at the moment but added for future use.
MRO() int
// 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 this Tun can
// read or write in a single read/write call. BatchSize must not change over
// the lifetime of a Device. Callers must not assume symmetric batch
// compatibility across two different Tun implementations: reads should be
// sized from the source Tun, and writes should be chunked for the
// destination Tun.
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.
Source Files