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 PlatformSpecificParams

type PlatformSpecificParams struct {
}

PlatformSpeficParams

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