water

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.

water/waterutil has some useful functions to interpret MAC frame headers and IP packet headers. It also contains some constants such as protocol numbers and ethernet frame types.

See https://github.com/songgao/packets for functions for parsing various packets.

Supported Platforms

• Linux
• Windows
• macOS (point-to-point TUN only)

Installation

go get -u github.com/labulakalia/water
go get -u github.com/labulakalia/water/waterutil

Documentation

http://godoc.org/github.com/labulakalia/water

Example

TAP on Linux:

package main

import (
	"log"

	"github.com/songgao/packets/ethernet"
	"github.com/labulakalia/water"
)

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

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

	for {
		frame.Resize(1500)
		n, err := ifce.Read([]byte(frame))
		if err != nil {
			log.Fatal(err)
		}
		frame = frame[:n]
		log.Printf("Dst: %s\n", frame.Destination())
		log.Printf("Src: %s\n", frame.Source())
		log.Printf("Ethertype: % x\n", frame.Ethertype())
		log.Printf("Payload: % x\n", frame.Payload())
	}
}

This piece of code creates a TAP interface, and prints some header information for every frame. After pull up the main.go, you'll need to bring up the interface and assign an IP address. All of these need root permission.

sudo go run main.go

In a new terminal:

sudo ip addr add 10.1.0.10/24 dev O_O
sudo ip link set dev O_O up

Wait until the output main.go terminal, try sending some ICMP broadcast message:

ping -c1 -b 10.1.0.255

You'll see output containing the IPv4 ICMP frame:

2016/10/24 03:18:16 Dst: ff:ff:ff:ff:ff:ff
2016/10/24 03:18:16 Src: 72:3c:fc:29:1c:6f
2016/10/24 03:18:16 Ethertype: 08 00
2016/10/24 03:18:16 Payload: 45 00 00 54 00 00 40 00 40 01 25 9f 0a 01 00 0a 0a 01 00 ff 08 00 01 c1 08 49 00 01 78 7d 0d 58 00 00 00 00 a2 4c 07 00 00 00 00 00 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 36 37

TUN on macOS

package main

import (
	"log"

	"github.com/labulakalia/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 it!

$ sudo go run main.go

This is a point-to-point only interface. Use ifconfig to see its attributes. You need to bring it up and assign IP addresses (apparently replace utun2 if needed):

$ sudo ifconfig utun2 10.1.0.10 10.1.0.20 up

Now send some ICMP packets to the interface:

$ ping 10.1.0.20

You'd see the ICMP packets printed out:

2017/03/20 21:17:30 Interface Name: utun2
2017/03/20 21:17:40 Packet Received: 45 00 00 54 e9 1d 00 00 40 01 7d 6c 0a 01 00 0a 0a 01 00 14 08 00 ee 04 21 15 00 00 58 d0 a9 64 00 08 fb a5 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 36 37

Caveats

1. Only Point-to-Point user TUN devices are supported. TAP devices are not supported natively by macOS.
2. Custom interface names are not supported by macOS. Interface names are automatically generated serially, using the utun<#> naming convention.

TUN on Windows:

To use it with windows,you will need to download file wintun.dll in running dir.

package main

import (
	"log"

	"github.com/labulakalia/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])
	}
}

go run main.go

In a new cmd (admin right):

# Replace with your device name, it can be achieved by ifce.Name().
netsh interface ip set address name="Ehternet 2" source=static addr=10.1.0.10 mask=255.255.255.0 gateway=none

ping 10.1.0.255

You'll see output containing the IPv4 ICMP frame same as the Linux version.

TAP on Windows:

To use it with windows, you will need to install a tap driver, or OpenVPN client for windows.

It's compatible with the Linux code.

package main

import (
	"log"

	"github.com/songgao/packets/ethernet"
	"github.com/songgao/water"
)

func main() {
	ifce, err := water.New(water.Config{
		DeviceType: water.TAP,
	})
	if err != nil {
		log.Fatal(err)
	}
	var frame ethernet.Frame

	for {
		frame.Resize(1500)
		n, err := ifce.Read([]byte(frame))
		if err != nil {
			log.Fatal(err)
		}
		frame = frame[:n]
		log.Printf("Dst: %s\n", frame.Destination())
		log.Printf("Src: %s\n", frame.Source())
		log.Printf("Ethertype: % x\n", frame.Ethertype())
		log.Printf("Payload: % x\n", frame.Payload())
	}
}

Same as Linux version, but you don't need to bring up the device by hand, the only thing you need is to assign an IP address to it.

go run main.go

It will output a lot of lines because of some windows services and dhcp. You will need admin right to assign IP.

In a new cmd (admin right):

# Replace with your device name, it can be achieved by ifce.Name().
netsh interface ip set address name="Ehternet 2" source=static addr=10.1.0.10 mask=255.255.255.0 gateway=none

The main.go terminal should be silenced after IP assignment, try sending some ICMP broadcast message:

ping 10.1.0.255

You'll see output containing the IPv4 ICMP frame same as the Linux version.

Specifying interface name

If you are going to use multiple TAP devices on the Windows, there is a way to specify an interface name to select the exact device that you need:

	ifce, err := water.New(water.Config{
		DeviceType: water.TAP,
		PlatformSpecificParams: water.PlatformSpecificParams{
			ComponentID:   "tap0901",
			InterfaceName: "Ethernet 3",
			Network:       "192.168.1.10/24",
		},
	})

TODO

• tuntaposx for TAP on Darwin

Alternatives

tuntap: https://code.google.com/p/tuntap/

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
• type Config
• type DevicePermissions
• type DeviceType
• type Interface
  • func New(config Config) (ifce *Interface, err error)
  • func NewTAP(ifName string) (ifce *Interface, err error)
  • func NewTUN(ifName string) (ifce *Interface, err error)
  • func (ifce *Interface) IsTAP() bool
  • func (ifce *Interface) IsTUN() bool
  • func (ifce *Interface) Name() string
• type PlatformSpecificParams

Constants

const (
	TUN
	TAP
)

TUN and TAP device types.

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 DevicePermissions

type DevicePermissions struct {
	// Owner is the ID of the user which will be granted ownership of the
	// device.  If set to a negative value, the owner value will not be
	// changed.  By default, Linux sets the owner to -1, which allows any user.
	Owner uint

	// Group is the ID of the group which will be granted access to the device.
	// If set to a negative value, the group value will not be changed.  By
	// default, Linux sets the group to -1, which allows any group.
	Group uint
}

DevicePermissions determines the owner and group owner for the newly created interface.

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 NewTAP

func NewTAP(ifName string) (ifce *Interface, err error)

NewTAP creates a new TAP interface whose name is ifName. If ifName is empty, a default name (tap0, tap1, ... ) will be assigned. ifName should not exceed 16 bytes. TAP interfaces are not supported on darwin. ifName cannot be specified on windows, you will need ifce.Name() to use some cmds.

Deprecated: This function may be removed in the future. Please use New() instead.

func NewTUN

func NewTUN(ifName string) (ifce *Interface, err error)

NewTUN creates a new TUN interface whose name is ifName. If ifName is empty, a default name (tap0, tap1, ... ) will be assigned. ifName should not exceed ifName cannot be specified on windows, you will need ifce.Name() to use some cmds.

Deprecated: This function will be removed in the future. Please use New() instead.

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 {
	// Name is the name to be set for the interface to be created. This overrides
	// the default name assigned by OS such as tap0 or tun0. A zero-value of this
	// field, i.e. an empty string, indicates that the default name should be
	// used.
	Name string

	// Persist specifies whether persistence mode for the interface device
	// should be enabled or disabled.
	Persist bool

	// Permissions, if non-nil, specifies the owner and group owner for the
	// interface.  A zero-value of this field, i.e. nil, indicates that no
	// changes to owner or group will be made.
	Permissions *DevicePermissions

	// MultiQueue specifies whether the multiqueue flag should be set on the
	// interface.  From version 3.8, Linux supports multiqueue tuntap which can
	// uses multiple file descriptors (queues) to parallelize packets sending
	// or receiving.
	MultiQueue bool
}

PlatformSpecificParams defines parameters in Config that are specific to Linux. A zero-value of such type is valid, yielding an interface with OS defined name.