water

package module
v0.0.1 Latest Latest
Warning

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

Go to latest
Published: Jul 9, 2026 License: BSD-3-Clause Imports: 6 Imported by: 0

README

water

water is a native Go library for TUN/TAP interfaces.

water is designed to be simple and efficient. It

  • wraps almost only syscalls and uses only Go standard types;
  • exposes standard interfaces; plays well with standard packages like io, bufio, etc.;
  • does not handle memory management (allocating/destructing slice). It's up to user to decide whether/how to reuse buffers.

Supported Platforms

Platform TUN TAP
Linux ✅ ✅
Windows ✅ (Wintun) ❌
macOS ✅ (point-to-point) ❌
FreeBSD / OpenBSD / NetBSD ✅ ✅

Installation

go get github.com/l0caldadmin/water

Documentation

https://pkg.go.dev/github.com/l0caldadmin/water

Examples

TAP on Linux
package main

import (
	"log"

	"github.com/l0caldadmin/water/waterutil"
	"github.com/l0caldadmin/water"
)

func main() {
	config := water.Config{
		DeviceType: water.TAP,
	}
	config.Name = "O_O"

	ifce, err := water.New(config)
	if err != nil {
		log.Fatal(err)
	}

	frame := make([]byte, 1500)
	for {
		n, err := ifce.Read(frame)
		if err != nil {
			log.Fatal(err)
		}
		buf := frame[:n]
		log.Printf("Dst: %s", waterutil.MACDestination(buf))
		log.Printf("Src: %s", waterutil.MACSource(buf))
	}
}

Bring it up:

sudo go run main.go &
sudo ip addr add 10.1.0.10/24 dev O_O
sudo ip link set dev O_O up
ping -c1 -b 10.1.0.255
TUN on macOS
package main

import (
	"log"

	"github.com/l0caldadmin/water"
)

func main() {
	ifce, err := water.New(water.Config{
		DeviceType: water.TUN,
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Interface Name: %s\n", ifce.Name())

	packet := make([]byte, 2000)
	for {
		n, err := ifce.Read(packet)
		if err != nil {
			log.Fatal(err)
		}
		log.Printf("Packet Received: % x\n", packet[:n])
	}
}
sudo go run main.go &
sudo ifconfig utun2 10.1.0.10 10.1.0.20 up
ping 10.1.0.20
macOS caveats
  1. Only point-to-point TUN devices are supported natively. TAP is not supported.
  2. Custom interface names are not supported. Names are assigned automatically as utun<N>.
TUN on Windows (Wintun)

Windows uses the Wintun driver. TAP mode is not supported on this backend.

package main

import (
	"log"

	"github.com/l0caldadmin/water"
)

func main() {
	ifce, err := water.New(water.Config{
		DeviceType: water.TUN,
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Interface Name: %s\n", ifce.Name())

	packet := make([]byte, 2000)
	for {
		n, err := ifce.Read(packet)
		if err != nil {
			log.Fatal(err)
		}
		log.Printf("Packet Received: % x\n", packet[:n])
	}
}

Run as Administrator. Assign an IP address after the interface appears:

netsh interface ip set address name="wintun" source=static addr=10.1.0.10 mask=255.255.255.0 gateway=none

Alternatives

Documentation

Overview

Package water is a simple TUN/TAP interface library that efficiently works with standard packages like io, bufio, etc.. Use waterutil with it to work with TUN/TAP packets/frames.

Index

Constants

View Source
const (
	TUN
	TAP
)

TUN and TAP device types.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// DeviceType specifies whether the device is a TUN or TAP interface. A
	// zero-value is treated as TUN.
	DeviceType DeviceType

	// PlatformSpecificParams defines parameters that differ on different
	// platforms. See comments for the type for more details.
	PlatformSpecificParams
}

Config defines parameters required to create a TUN/TAP interface. It's only used when the device is initialized. A zero-value Config is a valid configuration.

type DeviceType

type DeviceType int

DeviceType is the type for specifying device types.

type Interface

type Interface struct {
	io.ReadWriteCloser
	// contains filtered or unexported fields
}

Interface is a TUN/TAP interface.

MultiQueue(Linux kernel > 3.8): With MultiQueue enabled, user should hold multiple interfaces to send/receive packet in parallel. Kernel document about MultiQueue: https://www.kernel.org/doc/Documentation/networking/tuntap.txt

func New

func New(config Config) (ifce *Interface, err error)

New creates a new TUN/TAP interface using config.

func (*Interface) IsTAP

func (ifce *Interface) IsTAP() bool

IsTAP returns true if ifce is a TAP interface.

func (*Interface) IsTUN

func (ifce *Interface) IsTUN() bool

IsTUN returns true if ifce is a TUN interface.

func (*Interface) Name

func (ifce *Interface) Name() string

Name returns the interface name of ifce, e.g. tun0, tap1, tun0, etc..

type MacOSDriverProvider

type MacOSDriverProvider int

MacOSDriverProvider enumerates possible MacOS TUN/TAP implementations

const (
	// MacOSDriverSystem refers to the default P2P driver
	MacOSDriverSystem MacOSDriverProvider = 0
	// MacOSDriverTunTapOSX refers to the third-party tuntaposx driver
	// see https://sourceforge.net/p/tuntaposx
	MacOSDriverTunTapOSX MacOSDriverProvider = 1
)

type PlatformSpecificParams

type PlatformSpecificParams struct {
	// Name is the name for the interface to be used.
	//
	// For TunTapOSXDriver, it should be something like "tap0".
	// For SystemDriver, the name should match `utun[0-9]+`, e.g. utun233
	Name string

	// Driver should be set if an alternative driver is desired
	// e.g. TunTapOSXDriver
	Driver MacOSDriverProvider
}

PlatformSpecificParams defines parameters in Config that are specific to macOS. A zero-value of such type is valid, yielding an interface with OS defined name. Currently it is not possible to set the interface name in macOS.

Directories

Path Synopsis
Package waterutil provides utility functions for interpreting TUN/TAP MAC farme headers and IP packet headers.
Package waterutil provides utility functions for interpreting TUN/TAP MAC farme headers and IP packet headers.

Jump to

Keyboard shortcuts

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