add Sys() for access to fd/handle

.travis.yml

@@ -1,7 +1,5 @@
 language: go
-go:
- - "1.12.1"
- - "1.10.8"
+
 go_import_path: github.com/songgao/water
 install: go get -u golang.org/x/lint/golint
 script: make ci
@@ -10,4 +8,11 @@ matrix:
  include:
  - os: linux
  dist: xenial
+ go: 1.12.1
+ - os: linux
+ dist: xenial
+ go: 1.10.8
+ - os: osx
+ go: 1.12.1
  - os: osx
+ go: 1.10.8

README.md

@@ -1,16 +1,9 @@
-# water
+[![Build Status](https://travis-ci.org/songgao/water.svg?branch=master)](https://travis-ci.org/songgao/water)
+[![GoDoc](https://godoc.org/github.com/songgao/water?status.svg)](https://godoc.org/github.com/songgao/water)
 
-`water` is a native Go library for [TUN/TAP](http://en.wikipedia.org/wiki/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.
+`water` is a pure Go package for working with
+[TUN/TAP](http://en.wikipedia.org/wiki/TUN/TAP) interfaces. It works well with
+Go's standard library and has no external dependency.
 
 ## Supported Platforms
 
@@ -19,15 +12,18 @@ See https://github.com/songgao/packets for functions for parsing various packets
 * macOS (point-to-point TUN only)
 
 ## Installation
+
 ```
 go get -u github.com/songgao/water
-go get -u github.com/songgao/water/waterutil
 ```
 
 ## Documentation
-[http://godoc.org/github.com/songgao/water](http://godoc.org/github.com/songgao/water)
 
-## Example
+* [Linux](http://godoc.org/github.com/songgao/water?GOOS=linux)
+* [macOS](http://godoc.org/github.com/songgao/water?GOOS=darwin)
+* [Windows](http://godoc.org/github.com/songgao/water?GOOS=windows)
+
+## Getting Started
 
 ### TAP on Linux:
 
@@ -234,9 +230,3 @@ If you are going to use multiple TAP devices on the Windows, there is a way to s
  },
  })
 ```
-
-## TODO
-* tuntaposx for TAP on Darwin
-
-## Alternatives
-`tuntap`: [https://code.google.com/p/tuntap/](https://code.google.com/p/tuntap/)

doc.go

@@ -1,4 +1,11 @@
-// 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.
+// Package water encapsulates system calls for working with TUN/TAP interfaces,
+// in pure Go.
+//
+// Platform specific docs:
+//
+// Linux: https://godoc.org/github.com/songgao/water?GOOS=lnux
+//
+// macOS: https://godoc.org/github.com/songgao/water?GOOS=darwin
+//
+// Windows: https://godoc.org/github.com/songgao/water?GOOS=windows
 package water

if.go

@@ -5,23 +5,36 @@ import (
  "io"
 )
 
-// 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
-type Interface struct {
- isTAP bool
+// Interface represents a TUN/TAP interface.
+type Interface interface {
+ // Use Read() and Write() methods to read from and write into this TUN/TAP
+ // interface. In TAP interface, each call corresponds to an Ethernet frame.
+ // In TUN mode, each call corresponds to an IP packet.
  io.ReadWriteCloser
- name string
+
+ // IsTUN returns true if ifce is a TUN interface.
+ IsTUN() bool
+ // IsTAP returns true if ifce is a TAP interface.
+ IsTAP() bool
+ // DeviceType returns the interface's device type.
+ Type() DeviceType
+ // Name returns the name of the interface.
+ Name() string
+ // Sys returns the underlying system interface for the interface. This is
+ // useful if caller needs to perform system calls directly on the tun/tap
+ // device.
+ //
+ // On Unix systems, this returns a file descriptor of uintptr type. On
+ // Windows, this returns a syscall.Handle.
+ Sys() interface{}
 }
 
 // DeviceType is the type for specifying device types.
 type DeviceType int
 
-// TUN and TAP device types.
+// Constants for TUN and TAP interfaces.
 const (
- _ = iota
+ _ DeviceType = iota
  TUN
  TAP
 )
@@ -49,7 +62,7 @@ func defaultConfig() Config {
 var zeroConfig Config
 
 // New creates a new TUN/TAP interface using config.
-func New(config Config) (ifce *Interface, err error) {
+func New(config Config) (ifce Interface, err error) {
  if zeroConfig == config {
  config = defaultConfig()
  }
@@ -63,18 +76,3 @@ func New(config Config) (ifce *Interface, err error) {
  return nil, errors.New("unknown device type")
  }
 }
-
-// IsTUN returns true if ifce is a TUN interface.
-func (ifce *Interface) IsTUN() bool {
- return !ifce.isTAP
-}
-
-// IsTAP returns true if ifce is a TAP interface.
-func (ifce *Interface) IsTAP() bool {
- return ifce.isTAP
-}
-
-// Name returns the interface name of ifce, e.g. tun0, tap1, tun0, etc..
-func (ifce *Interface) Name() string {
- return ifce.name
-}

if_linux.go

@@ -10,7 +10,7 @@ import (
 // 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 NewTAP(ifName string) (ifce *Interface, err error) {
+func NewTAP(ifName string) (ifce Interface, err error) {
  fmt.Println("Deprecated: NewTAP(..) may be removed in the future. Please use New() instead.")
  config := Config{DeviceType: TAP}
  config.Name = ifName
@@ -22,7 +22,7 @@ func NewTAP(ifName string) (ifce *Interface, err error) {
 // 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 NewTUN(ifName string) (ifce *Interface, err error) {
+func NewTUN(ifName string) (ifce Interface, err error) {
  fmt.Println("Deprecated: NewTUN(..) may be removed in the future. Please use New() instead.")
  config := Config{DeviceType: TUN}
  config.Name = ifName

if_nix.go

@@ -0,0 +1,32 @@
+// +build linux darwin
+
+package water
+
+import "io"
+
+type ifce struct {
+ deviceType DeviceType
+ fd uintptr
+ name string
+ io.ReadWriteCloser
+}
+
+func (i *ifce) IsTUN() bool {
+ return i.deviceType == TUN
+}
+
+func (i *ifce) IsTAP() bool {
+ return i.deviceType == TAP
+}
+
+func (i *ifce) Type() DeviceType {
+ return i.deviceType
+}
+
+func (i *ifce) Name() string {
+ return i.name
+}
+
+func (i *ifce) Sys() interface{} {
+ return i.fd
+}

ipv4_darwin_test.go

@@ -22,7 +22,7 @@ func setupIfce(t *testing.T, self net.IP, remote net.IP, dev string) {
  }
 }
 
-func teardownIfce(t *testing.T, ifce *Interface) {
+func teardownIfce(t *testing.T, ifce Interface) {
  if err := ifce.Close(); err != nil {
  t.Fatal(err)
  }

ipv4_linux_test.go

@@ -25,7 +25,7 @@ func setupIfce(t *testing.T, ipNet net.IPNet, dev string) {
  }
 }
 
-func teardownIfce(t *testing.T, ifce *Interface) {
+func teardownIfce(t *testing.T, ifce Interface) {
  if err := ifce.Close(); err != nil {
  t.Fatal(err)
  }

ipv4_test.go

@@ -10,7 +10,7 @@ import (
 
 const BUFFERSIZE = 1522
 
-func startRead(t *testing.T, ifce *Interface) (dataChan <-chan []byte, errChan <-chan error) {
+func startRead(t *testing.T, ifce Interface) (dataChan <-chan []byte, errChan <-chan error) {
  dataCh := make(chan []byte)
  errCh := make(chan error)
  go func() {

ipv4_windows_test.go

@@ -26,7 +26,7 @@ func setupIfce(t *testing.T, ipNet net.IPNet, dev string) {
  }
 }
 
-func teardownIfce(t *testing.T, ifce *Interface) {
+func teardownIfce(t *testing.T, ifce Interface) {
  if err := ifce.Close(); err != nil {
  t.Fatal(err)
  }

params_linux.go

@@ -37,6 +37,11 @@ type PlatformSpecificParams struct {
  // interface. From version 3.8, Linux supports multiqueue tuntap which can
  // uses multiple file descriptors (queues) to parallelize packets sending
  // or receiving.
+ //
+ // 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
  MultiQueue bool
 }
 

syscalls_darwin.go

@@ -59,11 +59,12 @@ type sockaddrCtl struct {
 
 var sockaddrCtlSize uintptr = 32
 
-func openDev(config Config) (ifce *Interface, err error) {
+func openDev(config Config) (Interface, error) {
  if config.DeviceType != TUN {
  return nil, errors.New("only tun is implemented on this platform")
  }
  var fd int
+ var err error
  // Supposed to be socket(PF_SYSTEM, SOCK_DGRAM, SYSPROTO_CONTROL), but ...
  //
  // In sys/socket.h:
@@ -118,9 +119,10 @@ func openDev(config Config) (ifce *Interface, err error) {
  return nil, fmt.Errorf("setting non-blocking error")
  }
 
- return &Interface{
- isTAP: false,
- name: string(ifName.name[:ifNameSize-1 /* -1 is for \0 */]),
+ return &ifce{
+ deviceType: config.DeviceType,
+ fd: uintptr(fd),
+ name: string(ifName.name[:ifNameSize-1 /* -1 is for \0 */]),
  ReadWriteCloser: &tunReadCloser{
  f: os.NewFile(uintptr(fd), string(ifName.name[:])),
  },

syscalls_linux_go1.11.go

@@ -7,8 +7,9 @@ import (
  "syscall"
 )
 
-func openDev(config Config) (ifce *Interface, err error) {
+func openDev(config Config) (Interface, error) {
  var fdInt int
+ var err error
  if fdInt, err = syscall.Open(
  "/dev/net/tun", os.O_RDWR|syscall.O_NONBLOCK, 0); err != nil {
  return nil, err
@@ -19,9 +20,10 @@ func openDev(config Config) (ifce *Interface, err error) {
  return nil, err
  }
 
- return &Interface{
- isTAP:  config.DeviceType == TAP,
- ReadWriteCloser: os.NewFile(uintptr(fdInt), "tun"),
+ return &ifce{
+ deviceType: config.DeviceType,
+ fd: uintptr(fdInt),
  name: name,
+ ReadWriteCloser: os.NewFile(uintptr(fdInt), "tun"),
  }, nil
 }

syscalls_linux_legacy.go

@@ -6,8 +6,9 @@ import (
  "os"
 )
 
-func openDev(config Config) (ifce *Interface, err error) {
+func openDev(config Config) (Interface, error) {
  var file *os.File
+ var err error
  if file, err = os.OpenFile(
  "/dev/net/tun", os.O_RDWR, 0); err != nil {
  return nil, err
@@ -18,9 +19,10 @@ func openDev(config Config) (ifce *Interface, err error) {
  return nil, err
  }
 
- return &Interface{
- isTAP:  config.DeviceType == TAP,
- ReadWriteCloser: file,
+ return &ifce{
+ deviceType: config.DeviceType,
+ fd: file.Fd(),
  name: name,
+ ReadWriteCloser: file,
  }, nil
 }