device

Documentation

Overview

Package device provides a unified interface for TUN and TAP network devices.

Index

• Variables
• func DefaultDeviceName(deviceType DeviceType) string
• func GenerateMAC() net.HardwareAddr
• func GenerateRandomMAC() (net.HardwareAddr, error)
• type Config
  • func (c *Config) Validate() error
• type DeviceError
  • func (e *DeviceError) Error() string
  • func (e *DeviceError) Unwrap() error
• type DeviceType
  • func ParseDeviceType(s string) (DeviceType, error)
  • func (t DeviceType) String() string
• type NetworkDevice
  • func Create(cfg Config) (NetworkDevice, error)
  • func CreateTUN(cfg Config) (NetworkDevice, error)
• type TAPConfig
• type TAPDevice
  • func CreateTAP(cfg Config) (TAPDevice, error)

Variables

var (
	ErrDeviceNotSupported  = errors.New("device type not supported on this platform")
	ErrPermissionDenied    = errors.New("permission denied: device creation requires root/admin privileges")
	ErrDeviceAlreadyExists = errors.New("device already exists")
	ErrDeviceClosed        = errors.New("device is closed")
	ErrTAPNotSupported     = errors.New("TAP device not supported on this platform")
	ErrInvalidMACAddress   = errors.New("invalid MAC address")
)

Common device errors.

Functions

func DefaultDeviceName

func DefaultDeviceName(deviceType DeviceType) string

DefaultDeviceName returns the default interface name for the current platform.

func GenerateMAC

func GenerateMAC() net.HardwareAddr

GenerateMAC generates a random locally-administered MAC address.

func GenerateRandomMAC

func GenerateRandomMAC() (net.HardwareAddr, error)

GenerateRandomMAC generates a random locally-administered MAC address using crypto/rand.

Types

type Config

type Config struct {
	Type    DeviceType `yaml:"type"`    // Device type: "tun" (default) or "tap"
	Name    string     `yaml:"name"`    // Interface name (e.g., "bifrost0")
	Address string     `yaml:"address"` // IP address with prefix (e.g., "10.255.0.1/24")
	MTU     int        `yaml:"mtu"`     // MTU size (default: 1400)

	// TAP-specific configuration
	TAP TAPConfig `yaml:"tap,omitempty"`
}

Config contains network device configuration.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the device configuration.

type DeviceError

type DeviceError struct {
	Op  string // Operation that failed
	Err error  // Underlying error
}

DeviceError represents a device-specific error.

func (*DeviceError) Error

func (e *DeviceError) Error() string

func (*DeviceError) Unwrap

func (e *DeviceError) Unwrap() error

type DeviceType

type DeviceType int

DeviceType represents the type of network device.

const (
	// DeviceTUN represents a Layer 3 (IP packets) TUN device.
	DeviceTUN DeviceType = iota
	// DeviceTAP represents a Layer 2 (Ethernet frames) TAP device.
	DeviceTAP
)

func ParseDeviceType

func ParseDeviceType(s string) (DeviceType, error)

ParseDeviceType parses a device type from a string.

func (DeviceType) String

func (t DeviceType) String() string

String returns the string representation of the device type.

type NetworkDevice

type NetworkDevice interface {
	// Name returns the interface name (e.g., "bifrost0", "utun5").
	Name() string

	// Type returns the device type (TUN or TAP).
	Type() DeviceType

	// Read reads a packet/frame from the device.
	// For TUN devices, returns IP packets.
	// For TAP devices, returns Ethernet frames.
	Read(buf []byte) (int, error)

	// Write writes a packet/frame to the device.
	// For TUN devices, writes IP packets.
	// For TAP devices, writes Ethernet frames.
	Write(buf []byte) (int, error)

	// Close closes the device and releases resources.
	Close() error

	// MTU returns the Maximum Transmission Unit.
	MTU() int
}

NetworkDevice represents a TUN or TAP network interface.

func Create

func Create(cfg Config) (NetworkDevice, error)

Create creates a new network device based on the configuration.

func CreateTUN

func CreateTUN(cfg Config) (NetworkDevice, error)

CreateTUN creates a new TUN device (shorthand for Create with DeviceTUN).

type TAPConfig

type TAPConfig struct {
	MACAddress string `yaml:"mac_address"` // MAC address (auto-generated if empty)
	Bridge     string `yaml:"bridge"`      // Optional bridge interface to join
}

TAPConfig contains TAP-specific configuration.

type TAPDevice

type TAPDevice interface {
	NetworkDevice

	// MACAddress returns the MAC address of the TAP interface.
	MACAddress() net.HardwareAddr

	// SetMACAddress sets the MAC address of the TAP interface.
	SetMACAddress(mac net.HardwareAddr) error
}

TAPDevice extends NetworkDevice with TAP-specific functionality.

func CreateTAP

func CreateTAP(cfg Config) (TAPDevice, error)

CreateTAP creates a new TAP device (shorthand for Create with DeviceTAP).