Linux networking in Golang
Go
Latest commit 104e65a Aug 19, 2016 @milosgajdos83 committed on GitHub Merge pull request #18 from kdomanski/fix-parse-mac
Oh, this is fantastic! Can't believe I missed this one! Excellent work! Thank you.
Permalink
Failed to load latest commit information.
examples fixed import paths and example code Oct 18, 2015
.gitignore Removing dependency on Docker/licontainer fork Oct 28, 2014
LICENSE Apply Apache License v2.0 Oct 18, 2014
README.md Turned on Go code highlighting Jan 19, 2016
Vagrantfile Fix Vagrant box name Oct 27, 2014
bridge_linux.go Updated README with new methods and cleaned up comments for those met… Jan 18, 2016
bridge_linux_test.go First tenus commit \o/ Jul 29, 2014
doc.go First tenus commit \o/ Jul 29, 2014
helpers_linux.go Added a "random" domain to Docker unix socket HTTP request Jul 29, 2016
helpers_linux_test.go First tenus commit \o/ Jul 29, 2014
link_linux.go Updated README with new methods and cleaned up comments for those met… Jan 18, 2016
link_linux_test.go First tenus commit \o/ Jul 29, 2014
macvlan_linux.go fix MAC verification logic Aug 9, 2016
macvlan_linux_test.go Small cleanup and refactoring. Dec 4, 2014
macvtap_linux.go fixed import paths and example code Oct 18, 2015
macvtap_linux_test.go Added macvtap tests. Renamed docknet_linux to tenus_linux. Dec 4, 2014
network.go fixed import paths and example code Oct 18, 2015
tenus_linux_test.go Added macvtap tests. Renamed docknet_linux to tenus_linux. Dec 4, 2014
veth_linux.go
veth_linux_test.go Added txlength option into veth tests Oct 29, 2014
vlan_linux.go fix MAC verification logic Aug 9, 2016
vlan_linux_test.go First tenus commit \o/ Jul 29, 2014

README.md

Linux networking in Golang

tenus is a Golang package which allows you to configure and manage Linux network devices programmatically. It communicates with Linux Kernel via netlink to facilitate creation and configuration of network devices on the Linux host. The package also allows for more advanced network setups with Linux containers including Docker.

tenus uses runc's implementation of netlink protocol. The package only works with newer Linux Kernels (3.10+) which are shipping reasonably new netlink protocol implementation, so if you are running older kernel this package won't be of much use to you I'm afraid. I have developed this package on Ubuntu Trusty Tahr which ships with 3.13+ and verified its functionality on Precise Pangolin with upgraded kernel to version 3.10. I could worked around the netlink issues by using ioctl syscalls, but I decided to prefer "pure netlink" implementation, so suck it old Kernels.

At the moment only functional tests are available, but the interface design should hopefully allow for easy (ish) unit testing in the future. I do appreciate that the package's test coverage is not great at the moment, but the core functionality should be covered. I would massively welcome PRs.

Get started

There is a Vagrantfile available in the repo so using vagrant is the easiest way to get started:

milosgajdos@bimbonet ~ $ git clone https://github.com/milosgajdos83/tenus.git
milosgajdos@bimbonet ~ $ vagrant up

Note using the provided Vagrantfile will take quite a long time to spin the VM as vagrant will setup Ubuntu Trusty VM with all the prerequisities:

  • it will install golang and docker onto the VM
  • it will export GOPATH and go get the tenus package onto the VM
  • it will also "pull" Docker ubuntu image so that you can run the tests once the VM is set up

At the moment running the tests require Docker to be installed, but in the future I'd love to separate tests per interface so that you can run only chosen test sets.

Once the VM is running, cd into particular repo directory and you can run the tests:

milosgajdos@bimbonet ~ $ cd $GOPATH/src/github.com/milosgajdos83/tenus
milosgajdos@bimbonet ~ $ sudo go test

If you don't want to use the provided Vagrantfile, you can simply run your own Linux VM (with 3.10+ kernel) and follow the regular golang development flow:

milosgajdos@bimbonet ~ $ go get github.com/milosgajdos83/tenus
milosgajdos@bimbonet ~ $ cd $GOPATH/src/github.com/milosgajdos83/tenus
milosgajdos@bimbonet ~ $ sudo go test

Once you've got the package and ran the tests (you don't need to run the tests!), you can start hacking. Below you can find simple code samples to get started with the package.

Examples

Below you can find a few code snippets which can help you get started writing your own programs.

New network bridge, add dummy link into it

The example below shows a simple program example which creates a new network bridge, a new dummy network link and adds it into the bridge.

package main

import (
    "fmt"
    "log"

    "github.com/milosgajdos83/tenus"
)

func main() {
    // Create a new network bridge
    br, err := tenus.NewBridgeWithName("mybridge")
    if err != nil {
        log.Fatal(err)
    }

    // Bring the bridge up
    if err = br.SetLinkUp(); err != nil {
        fmt.Println(err)
    }

    // Create a dummy link
    dl, err := tenus.NewLink("mydummylink")
    if err != nil {
        log.Fatal(err)
    }

    // Add the dummy link into bridge
    if err = br.AddSlaveIfc(dl.NetInterface()); err != nil {
        log.Fatal(err)
    }

    // Bring the dummy link up
    if err = dl.SetLinkUp(); err != nil {
        fmt.Println(err)
    }
}

New network bridge, veth pair, one peer in Docker

The example below shows how you can create a new network bride, configure its IP address, add a new veth pair and send one of the veth peers into Docker with a given name.

!! You must make sure that particular Docker is runnig if you want the code sample below to work properly !! So before you compile and run the program below you should create a particular docker with the below used name:

milosgajdos@bimbonet ~ $ docker run -i -t --rm --privileged -h vethdckr --name vethdckr ubuntu:14.04 /bin/bash
package main

import (
    "fmt"
    "log"
    "net"

    "github.com/milosgajdos83/tenus"
)

func main() {
    // CREATE BRIDGE AND BRING IT UP
    br, err := tenus.NewBridgeWithName("vethbridge")
    if err != nil {
        log.Fatal(err)
    }

    brIp, brIpNet, err := net.ParseCIDR("10.0.41.1/16")
    if err != nil {
        log.Fatal(err)
    }

    if err := br.SetLinkIp(brIp, brIpNet); err != nil {
        fmt.Println(err)
    }

    if err = br.SetLinkUp(); err != nil {
        fmt.Println(err)
    }

    // CREATE VETH PAIR
    veth, err := tenus.NewVethPairWithOptions("myveth01", tenus.VethOptions{PeerName: "myveth02"})
    if err != nil {
        log.Fatal(err)
    }

    // ASSIGN IP ADDRESS TO THE HOST VETH INTERFACE
    vethHostIp, vethHostIpNet, err := net.ParseCIDR("10.0.41.2/16")
    if err != nil {
        log.Fatal(err)
    }

    if err := veth.SetLinkIp(vethHostIp, vethHostIpNet); err != nil {
        fmt.Println(err)
    }

    // ADD MYVETH01 INTERFACE TO THE MYBRIDGE BRIDGE
    myveth01, err := net.InterfaceByName("myveth01")
    if err != nil {
        log.Fatal(err)
    }

    if err = br.AddSlaveIfc(myveth01); err != nil {
        fmt.Println(err)
    }

    if err = veth.SetLinkUp(); err != nil {
        fmt.Println(err)
    }

    // PASS VETH PEER INTERFACE TO A RUNNING DOCKER BY PID
    pid, err := tenus.DockerPidByName("vethdckr", "/var/run/docker.sock")
    if err != nil {
        fmt.Println(err)
    }

    if err := veth.SetPeerLinkNsPid(pid); err != nil {
        log.Fatal(err)
    }

    // ALLOCATE AND SET IP FOR THE NEW DOCKER INTERFACE
    vethGuestIp, vethGuestIpNet, err := net.ParseCIDR("10.0.41.5/16")
    if err != nil {
        log.Fatal(err)
    }

    if err := veth.SetPeerLinkNetInNs(pid, vethGuestIp, vethGuestIpNet, nil); err != nil {
        log.Fatal(err)
    }
}

Working with existing bridges and interfaces

The following examples show how to retrieve exisiting interfaces as a tenus link and bridge

package main

import (
    "fmt"
    "log"
    "net"

    "github.com/milosgajdos83/tenus"
)

func main() {
    // RETRIEVE EXISTING BRIDGE
    br, err := tenus.BridgeFromName("bridge0")
    if err != nil {
        log.Fatal(err)
    }

    // REMOVING AN IP FROM A BRIDGE INTERFACE (BEFORE RECONFIGURATION)
    brIp, brIpNet, err := net.ParseCIDR("10.0.41.1/16")
    if err != nil {
        log.Fatal(err)
    }
    if err := br.UnsetLinkIp(brIp, brIpNet); err != nil {
        log.Fatal(err)
    }

    // RETRIEVE EXISTING INTERFACE
    dl, err := tenus.NewLinkFrom("eth0")
    if err != nil {
        log.Fatal(err)
    }

    // RENAMING AN INTERFACE BY NAME
    if err := tenus.RenameInterfaceByName("vethPSQSEl", "vethNEWNAME"); err != nil {
        log.Fatal(err)
    }

}

VLAN and MAC VLAN interfaces

You can check out VLAN and Mac VLAN examples, too.

More examples

Repo contains few more code sample in examples folder so make sure to check them out if you're interested.

TODO

This is just a rough beginning of the project which I put together over couple of weeks in my free time. I'd like to integrate this into my own Docker fork and test the advanced netowrking functionality with the core of Docker as oppose to configuring network interfaces from a separate golang program, because advanced networking in Docker was the main motivation for writing this package.

Documentation

More in depth package documentation is available via godoc