tuntap

README

tuntap

go get -u go.jamescun.com/netlink/tuntap

The tuntap package is an implementation of Linux TUNTAP devices for creating and using Layer-3 TUN and Layer-3 TAP devices.

While TUNTAP devices do not directly make use of netlink, it is the only device type that isn't created and configured through rtnetlink. This package bridges that gap, and is built in such a way as to be fully compatible with the rtnetlink package.

Examples

Below are some examples of how to use the tuntap package.

[!NOTE] Error handling is omitted in these examples for brevity.

Creating and configuring a device

package main

import (
	"net/netip"

	"go.jamescun.com/netlink/rtnetlink"
	"go.jamescun.com/netlink/rtnetlink/addr"
	"go.jamescun.com/netlink/rtnetlink/link"
	"go.jamescun.com/netlink/tuntap"
)

func main() {
	rt, _ := rtnetlink.New()

	// create a Layer-3 TUN device, without the intermediate TUNTAP packet
	// information header.
	tun, _ := tuntap.NewTUN("foo0", tuntap.NoPacketInfo())

	// configure the TUN device with the `100.64.0.1/24` IP Address.
	rt.AddAddr(
		tun.Index(),
		netip.MustParsePrefix("100.64.0.1/24"),
		addr.FlagPermanent,
	)

	// bring the TUN device up to receive packets.
	rt.SetLink(tun.Index(), link.Up)

	// use tun.Read() and tun.Write() to receive and transmit packets.
}

Documentation

Overview

Package tuntap implements creating TUN and TAP device using the TUNTAP device subsystem.

While TUNTAP devices do not directly make use of netlink, it is the only device type that isn't created and configured through rtnetlink. This package bridges that gap, and is built in such a way as to be fully compatible with the rtnetlink package.

Index

• type Device
  • func NewTAP(name string, opts ...DeviceOption) (Device, error)
  • func NewTUN(name string, opts ...DeviceOption) (Device, error)
• type DeviceOption
  • func MTU(mtu uint32) DeviceOption
  • func MultiQueue() DeviceOption
  • func NoPacketInfo() DeviceOption
  • func Persist() DeviceOption

Types

type Device

type Device interface {
	// Close the device, and unblock any in-flight read or write operation.
	Close() error

	// Name returns the name assigned to this link.
	//
	// This is safe to call even after the device has been closed, however if
	// the device has not been persisted, it may be reused.
	Name() string

	// Index returns the unique index of the link associated with this device,
	// which can be used with the rtnetlink package to configure it.
	//
	// This is safe to call even after the device has been closed, however if
	// the device has not been persisted, it may be reused.
	Index() int

	// Read data from the TUNTAP device, either a layer-3 packet for a TUN
	// device, or a layer-2 frame for a TAP device.
	//
	// Unless the [NoPacketInfo] device option is set, it will include the
	// TUNTAP frame header at the beginning of the bytes.
	Read([]byte) (int, error)

	// Write data to the TUNTAP device, either a layer-3 packet for a TUN
	// device, or a layer-2 frame for a TAP device.
	Write([]byte) (int, error)

	// SetDeadline sets the read and write deadlines associated with the
	// connection. It is equivalent to calling both SetReadDeadline and
	// SetWriteDeadline.
	SetDeadline(time.Time) error

	// SetReadDeadline sets the deadline for future Read calls and any
	// currently-blocked Read call.
	//
	// A zero value for t means Read will not time out.
	SetReadDeadline(time.Time) error

	// SetWriteDeadline sets the deadline for future Write calls and any
	// currently-blocked Write call.
	//
	// Even if write times out, it may return n > 0, indicating that some of
	// the data was successfully written.
	//
	// A zero value for t means Write will not time out.
	SetWriteDeadline(time.Time) error
}

Device is either a TUN device for receiving raw layer-3 packets, or a TAP device for receiving raw layer-2 packets, integrated with the Go networking polling infrastructure.

func NewTAP

func NewTAP(name string, opts ...DeviceOption) (Device, error)

NewTAP initializes a new layer-2 TAP device of the given name, optionally configured using the given DeviceOption.

The name must not be in-use already, unless the MultiQueue device option is specified.

func NewTUN

func NewTUN(name string, opts ...DeviceOption) (Device, error)

NewTUN initializes a new layer-3 TUN device of the given name, optionally configured using the given DeviceOption.

The name must not be in-use already, unless the MultiQueue device option is specified.

type DeviceOption

type DeviceOption func(*deviceOptions)

DeviceOption is a function that allows for additional configuration of a TUNTAP device when being created.

func MTU

func MTU(mtu uint32) DeviceOption

MTU is a DeviceOption that configures the Maximum Transmission Unit (MTU) for a TUNTAP device.

If not set, it will default to 1500.

func MultiQueue

func MultiQueue() DeviceOption

MultiQueue is a DeviceOption that configures a TUNTAP device to support multiple queues, in practice this means a device may be initialized multiple times for concurrency and performance.

func NoPacketInfo

func NoPacketInfo() DeviceOption

NoPacketInfo is a DeviceOption that configures a TUNTAP device to not include the TUNTAP frame header in each read.

func Persist

func Persist() DeviceOption

Persist is a DeviceOption that configures a TUNTAP device to persist beyond the lifetime of the process(es) that are using it.