splice

README

Splice

A high-level and multi-os library for manipulating network interfaces, links, and routes.

This library is still considered beta, the interfaces may change until 1.0 is released.

Splice provides a high-level library for manipulating network interfaces, network links, and routes. Splice provides a common interface for multiple operating systems.

Getting Started

Add Splice to Your Workspace

go get gitlab.com/ArroyoNetworks/splice

Examples

Add an Address to an Interface

package main

import (
    "fmt"
    "net"
    "gitlab.com/ArroyoNetworks/splice"
)

func main() {

    var err error

    _, address, err := net.ParseCIDR("127.1.1.0/24")
    intf, err := net.InterfaceByName("eth0")    
    err = splice.AddressAdd(intf, address)

    if err != nil {
        fmt.Println("Failed to Add Address")
        fmt.Println(err)
    }

}

Bring an Interface Down

package main

import (
    "fmt"
    "net"
    "gitlab.com/ArroyoNetworks/splice"
)

func main() {

    var err error

    intf, err := net.InterfaceByName("wlan0")    
    err = splice.LinkBringDown(intf)

    if err != nil {
        fmt.Println("Failed to Bring Down Interface")
        fmt.Println(err)
    }

}

Add a Route to the Routing Table

package main

import (
    "fmt"
    "net"
    "gitlab.com/ArroyoNetworks/splice"
)

func main() {

    var err error

    _, dest, err := net.ParseCIDR("172.10.0.0/24")
    intf, err := net.InterfaceByName("wlan0")    

    err = splice.RouteAddViaInterface(dest, intf)

    if err != nil {
        fmt.Println("Failed to Add Route")
        fmt.Println(err)
    }

}

Supported Operating Systems

Linux

The following are supported on Linux systems:

• IP Address Configuration
• Interface Link Manipulation
• Route Manipulation

Dependencies

The following are third-party dependencies used for providing Linux support:

• https://github.com/vishvananda/netlink

Unit Tests

Linux unit tests are automatically ran in a temporary networking namespace in order to prevent accidental alteration of the system's networking configuration. Because of this, test for Linux require the cap_net_admin capability.

1. Download the Test Dependencies

    go get -t gitlab.com/ArroyoNetworks/splice
   

2. Run the Unit Tests

    sudo -E go test github.com/ArroyoNetworks/splice
   

macOS

Not yet implemented.

Windows

Not yet implemented.

License

Copyright 2017 Arroyo Networks, LLC. All rights reserved.
This project is governed by a BSD-style license. See LICENSE for the full license text.

Documentation

Overview

Provides a high-level library for manipulating network interfaces, links, and routes. Splice provides a unified interface for multiple operating systems.

Index

• func AddressAdd(intf *net.Interface, address *net.IPNet) error
• func AddressDelete(intf *net.Interface, address *net.IPNet) error
• func AddressList(intf *net.Interface) ([]*net.IPNet, error)
• func LinkBringDown(intf *net.Interface) error
• func LinkBringUp(intf *net.Interface) error
• func RouteAddViaGateway(destination *net.IPNet, gateway net.IP) error
• func RouteAddViaInterface(destination *net.IPNet, intf *net.Interface) error
• func RouteExistsTo(destination net.IP) bool
• func RouteHasEntry(destination *net.IPNet) bool

Functions

func AddressAdd

func AddressAdd(intf *net.Interface, address *net.IPNet) error

Adds an IP address to an interface. This is equivalent to 'ip address add <address> dev <intf.Name>'

func AddressDelete

func AddressDelete(intf *net.Interface, address *net.IPNet) error

Removes an IP address from an interface. This is equivalent to 'ip address del <address> dev <intf.Name>'

func AddressList

func AddressList(intf *net.Interface) ([]*net.IPNet, error)

Returns a list of IP addresses configured on the given interface. This is equivalent to 'ip address show <interface>'

func LinkBringDown

func LinkBringDown(intf *net.Interface) error

Administratively brings down the given network interface.

func LinkBringUp

func LinkBringUp(intf *net.Interface) error

Administratively brings up the given network interface.

func RouteAddViaGateway

func RouteAddViaGateway(destination *net.IPNet, gateway net.IP) error

Adds a new route to the given IP network, routed by the given gateway. This is equivalent to 'ip route add <destination> via <gateway>'.

func RouteAddViaInterface

func RouteAddViaInterface(destination *net.IPNet, intf *net.Interface) error

Adds a new route to the given IP network, send out the given interface. This is equivalent to 'ip route add <destination> dev <intf.Name>'.

func RouteExistsTo

func RouteExistsTo(destination net.IP) bool

Determines if a route to the destination IP is available. This will always return true if a default route exists, regardless if the gateway can actually reach the destination.

func RouteHasEntry

func RouteHasEntry(destination *net.IPNet) bool

Determines if the routing table has a specific entry for the given destination network.