README ¶
netlink - netlink library for go
The netlink package provides a simple netlink library for go. Netlink
is the interface a user-space program in linux uses to communicate with
the kernel. It can be used to add and remove interfaces, set ip addresses
and routes, and configure ipsec. Netlink communication requires elevated
privileges, so in most cases this code needs to be run as root. Since
low-level netlink messages are inscrutable at best, the library attempts
to provide an api that is loosely modeled on the CLI provied by iproute2.
Actions like ip link add
will be accomplished via a similarly named
function like AddLink(). This library began its life as a fork of the
netlink functionality in
docker/libcontainer but was
heavily rewritten to improve testability, performance, and to add new
functionality like ipsec xfrm handling.
Local Build and Test
You can use go get command:
go get github.com/vishvananda/netlink
Testing dependencies:
go get github.com/vishvananda/netns
Testing (requires root):
sudo -E go test github.com/vishvananda/netlink
Examples
Add a new bridge and add eth1 into it:
package main
import (
"net"
"github.com/vishvananda/netlink"
)
func main() {
mybridge := &netlink.Bridge{netlink.LinkAttrs{Name: "foo"}}
_ := netlink.LinkAdd(mybridge)
eth1, _ := netlink.LinkByName("eth1")
netlink.LinkSetMaster(eth1, mybridge)
}
Add a new ip address to loopback:
package main
import (
"net"
"github.com/vishvananda/netlink"
)
func main() {
lo, _ := netlink.LinkByName("lo")
addr, _ := netlink.ParseAddr("169.254.169.254/32")
netlink.AddrAdd(lo, addr)
}
Future Work
Many pieces of netlink are not yet fully supported in the high-level interface. Aspects of virtually all of the high-level objects don't exist. Many of the underlying primitives are there, so its a matter of putting the right fields into the high-level objects and making sure that they are serialized and deserialized correctly in the Add and List methods.
There are also a few pieces of low level netlink functionality that still need to be implemented. Routing rules are not in place and some of the more advanced link types. Hopefully there is decent structure and testing in place to make these fairly straightforward to add.
Documentation ¶
Overview ¶
Package netlink provides a simple library for netlink. Netlink is the interface a user-space program in linux uses to communicate with the kernel. It can be used to add and remove interfaces, set up ip addresses and routes, and confiugre ipsec. Netlink communication requires elevated privileges, so in most cases this code needs to be run as root. The low level primitives for netlink are contained in the nl subpackage. This package attempts to provide a high-level interface that is loosly modeled on the iproute2 cli.
Index ¶
- Constants
- func AddrAdd(link Link, addr *Addr) error
- func AddrDel(link Link, addr *Addr) error
- func LinkAdd(link Link) error
- func LinkDel(link Link) error
- func LinkSetDown(link Link) error
- func LinkSetFastLeave(link Link, mode bool) error
- func LinkSetFlood(link Link, mode bool) error
- func LinkSetGuard(link Link, mode bool) error
- func LinkSetHairpin(link Link, mode bool) error
- func LinkSetHardwareAddr(link Link, hwaddr net.HardwareAddr) error
- func LinkSetLearning(link Link, mode bool) error
- func LinkSetMTU(link Link, mtu int) error
- func LinkSetMaster(link Link, master *Bridge) error
- func LinkSetMasterByIndex(link Link, masterIndex int) error
- func LinkSetName(link Link, name string) error
- func LinkSetNsFd(link Link, fd int) error
- func LinkSetNsPid(link Link, nspid int) error
- func LinkSetRootBlock(link Link, mode bool) error
- func LinkSetUp(link Link) error
- func NeighAdd(neigh *Neigh) error
- func NeighAppend(neigh *Neigh) error
- func NeighDel(neigh *Neigh) error
- func NeighSet(neigh *Neigh) error
- func NewIPNet(ip net.IP) *net.IPNet
- func ParseIPNet(s string) (*net.IPNet, error)
- func RouteAdd(route *Route) error
- func RouteDel(route *Route) error
- func XfrmPolicyAdd(policy *XfrmPolicy) error
- func XfrmPolicyDel(policy *XfrmPolicy) error
- func XfrmStateAdd(state *XfrmState) error
- func XfrmStateDel(state *XfrmState) error
- type Addr
- type Bridge
- type Device
- type Dir
- type Dummy
- type EncapType
- type Generic
- type IPVlan
- type IPVlanMode
- type Link
- type LinkAttrs
- type Macvlan
- type MacvlanMode
- type Mode
- type Ndmsg
- type Neigh
- type NsFd
- type NsPid
- type Protinfo
- type Proto
- type Route
- type Scope
- type Veth
- type Vlan
- type Vxlan
- type XfrmPolicy
- type XfrmPolicyTmpl
- type XfrmState
- type XfrmStateAlgo
- type XfrmStateEncap
Constants ¶
const ( NDA_UNSPEC = iota NDA_DST NDA_LLADDR NDA_CACHEINFO NDA_PROBES NDA_VLAN NDA_PORT NDA_VNI NDA_IFINDEX NDA_MAX = NDA_IFINDEX )
const ( NUD_NONE = 0x00 NUD_INCOMPLETE = 0x01 NUD_REACHABLE = 0x02 NUD_STALE = 0x04 NUD_DELAY = 0x08 NUD_PROBE = 0x10 NUD_FAILED = 0x20 NUD_NOARP = 0x40 NUD_PERMANENT = 0x80 )
Neighbor Cache Entry States.
const ( NTF_USE = 0x01 NTF_SELF = 0x02 NTF_MASTER = 0x04 NTF_PROXY = 0x08 NTF_ROUTER = 0x80 )
Neighbor Flags
const ( // Family type definitions FAMILY_ALL = nl.FAMILY_ALL FAMILY_V4 = nl.FAMILY_V4 FAMILY_V6 = nl.FAMILY_V6 )
Variables ¶
This section is empty.
Functions ¶
func AddrAdd ¶
AddrAdd will add an IP address to a link device. Equivalent to: `ip addr add $addr dev $link`
func AddrDel ¶
AddrDel will delete an IP address from a link device. Equivalent to: `ip addr del $addr dev $link`
func LinkAdd ¶
LinkAdd adds a new link device. The type and features of the device are taken fromt the parameters in the link object. Equivalent to: `ip link add $link`
func LinkDel ¶
LinkDel deletes link device. Either Index or Name must be set in the link object for it to be deleted. The other values are ignored. Equivalent to: `ip link del $link`
func LinkSetDown ¶
LinkSetUp disables link device. Equivalent to: `ip link set $link down`
func LinkSetFastLeave ¶
func LinkSetFlood ¶
func LinkSetGuard ¶
func LinkSetHairpin ¶
func LinkSetHardwareAddr ¶
func LinkSetHardwareAddr(link Link, hwaddr net.HardwareAddr) error
LinkSetHardwareAddr sets the hardware address of the link device. Equivalent to: `ip link set $link address $hwaddr`
func LinkSetLearning ¶
func LinkSetMTU ¶
LinkSetMTU sets the mtu of the link device. Equivalent to: `ip link set $link mtu $mtu`
func LinkSetMaster ¶
LinkSetMaster sets the master of the link device. Equivalent to: `ip link set $link master $master`
func LinkSetMasterByIndex ¶
LinkSetMasterByIndex sets the master of the link device. Equivalent to: `ip link set $link master $master`
func LinkSetName ¶
LinkSetName sets the name of the link device. Equivalent to: `ip link set $link name $name`
func LinkSetNsFd ¶
LinkSetNsPid puts the device into a new network namespace. The fd must be an open file descriptor to a network namespace. Similar to: `ip link set $link netns $ns`
func LinkSetNsPid ¶
LinkSetNsPid puts the device into a new network namespace. The pid must be a pid of a running process. Equivalent to: `ip link set $link netns $pid`
func LinkSetRootBlock ¶
func NeighAdd ¶
NeighAdd will add an IP to MAC mapping to the ARP table Equivalent to: `ip neigh add ....`
func NeighAppend ¶
NeighAppend will append an entry to FDB Equivalent to: `bridge fdb append...`
func NeighDel ¶
NeighDel will delete an IP address from a link device. Equivalent to: `ip addr del $addr dev $link`
func NeighSet ¶
NeighAdd will add or replace an IP to MAC mapping to the ARP table Equivalent to: `ip neigh replace....`
func ParseIPNet ¶
ParseIPNet parses a string in ip/net format and returns a net.IPNet. This is valuable because addresses in netlink are often IPNets and ParseCIDR returns an IPNet with the IP part set to the base IP of the range.
func XfrmPolicyAdd ¶
func XfrmPolicyAdd(policy *XfrmPolicy) error
XfrmPolicyAdd will add an xfrm policy to the system. Equivalent to: `ip xfrm policy add $policy`
func XfrmPolicyDel ¶
func XfrmPolicyDel(policy *XfrmPolicy) error
XfrmPolicyDel will delete an xfrm policy from the system. Note that the Tmpls are ignored when matching the policy to delete. Equivalent to: `ip xfrm policy del $policy`
func XfrmStateAdd ¶
XfrmStateAdd will add an xfrm state to the system. Equivalent to: `ip xfrm state add $state`
func XfrmStateDel ¶
XfrmStateDel will delete an xfrm state from the system. Note that the Algos are ignored when matching the state to delete. Equivalent to: `ip xfrm state del $state`
Types ¶
type Addr ¶
Addr represents an IP address from netlink. Netlink ip addresses include a mask, so it stores the address as a net.IPNet.
func AddrList ¶
AddrList gets a list of IP addresses in the system. Equivalent to: `ip addr show`. The list can be filtered by link and ip family.
func ParseAddr ¶
ParseAddr parses the string representation of an address in the form $ip/$netmask $label. The label portion is optional
type Device ¶
type Device struct {
LinkAttrs
}
Device links cannot be created via netlink. These links are links created by udev like 'lo' and 'etho0'
type EncapType ¶
type EncapType uint8
EncapType is an enum representing an ipsec template direction.
type Generic ¶
Generic links represent types that are not currently understood by this netlink library.
type IPVlan ¶
type IPVlan struct { LinkAttrs Mode IPVlanMode }
type IPVlanMode ¶
type IPVlanMode uint16
const ( IPVLAN_MODE_L2 IPVlanMode = iota IPVLAN_MODE_L3 IPVLAN_MODE_MAX )
type Link ¶
Link represents a link device from netlink. Shared link attributes like name may be retrieved using the Attrs() method. Unique data can be retrieved by casting the object to the proper type.
func LinkByIndex ¶
LinkByIndex finds a link by index and returns a pointer to the object.
func LinkByName ¶
LinkByName finds a link by name and returns a pointer to the object.
type LinkAttrs ¶
type LinkAttrs struct { Index int MTU int TxQLen uint32 // Transmit Queue Length Name string HardwareAddr net.HardwareAddr Flags net.Flags ParentIndex int // index of the parent link device MasterIndex int // must be the index of a bridge Namespace interface{} // nil | NsPid | NsFd }
LinkAttrs represents data shared by most link types
type Macvlan ¶
type Macvlan struct { LinkAttrs Mode MacvlanMode }
Macvlan links have ParentIndex set in their Attrs()
type MacvlanMode ¶
type MacvlanMode uint16
const ( MACVLAN_MODE_DEFAULT MacvlanMode = iota MACVLAN_MODE_PRIVATE MACVLAN_MODE_VEPA MACVLAN_MODE_BRIDGE MACVLAN_MODE_PASSTHRU MACVLAN_MODE_SOURCE )
type Neigh ¶
type Neigh struct { LinkIndex int Family int State int Type int Flags int IP net.IP HardwareAddr net.HardwareAddr }
Neigh represents a link layer neighbor from netlink.
func NeighDeserialize ¶
type Protinfo ¶
type Protinfo struct { Hairpin bool Guard bool FastLeave bool RootBlock bool Learning bool Flood bool }
Protinfo represents bridge flags from netlink.
func LinkGetProtinfo ¶
type Proto ¶
type Proto uint8
Proto is an enum representing an ipsec protocol.
const ( XFRM_PROTO_ROUTE2 Proto = syscall.IPPROTO_ROUTING XFRM_PROTO_ESP Proto = syscall.IPPROTO_ESP XFRM_PROTO_AH Proto = syscall.IPPROTO_AH XFRM_PROTO_HAO Proto = syscall.IPPROTO_DSTOPTS XFRM_PROTO_COMP Proto = syscall.IPPROTO_COMP XFRM_PROTO_IPSEC_ANY Proto = syscall.IPPROTO_RAW )
type Route ¶
Route represents a netlink route. A route is associated with a link, has a destination network, an optional source ip, and optional gateway. Advanced route parameters and non-main routing tables are currently not supported.
func RouteGet ¶
RouteGet gets a route to a specific destination from the host system. Equivalent to: 'ip route get'.
type Scope ¶
type Scope uint8
Scope is an enum representing a route scope.
const ( SCOPE_UNIVERSE Scope = syscall.RT_SCOPE_UNIVERSE SCOPE_SITE Scope = syscall.RT_SCOPE_SITE SCOPE_LINK Scope = syscall.RT_SCOPE_LINK SCOPE_HOST Scope = syscall.RT_SCOPE_HOST SCOPE_NOWHERE Scope = syscall.RT_SCOPE_NOWHERE )
type Vxlan ¶
type XfrmPolicy ¶
type XfrmPolicy struct { Dst *net.IPNet Src *net.IPNet Dir Dir Priority int Index int Tmpls []XfrmPolicyTmpl }
XfrmPolicy represents an ipsec policy. It represents the overlay network and has a list of XfrmPolicyTmpls representing the base addresses of the policy.
func XfrmPolicyList ¶
func XfrmPolicyList(family int) ([]XfrmPolicy, error)
XfrmPolicyList gets a list of xfrm policies in the system. Equivalent to: `ip xfrm policy show`. The list can be filtered by ip family.
type XfrmPolicyTmpl ¶
XfrmPolicyTmpl encapsulates a rule for the base addresses of an ipsec policy. These rules are matched with XfrmState to determine encryption and authentication algorithms.
type XfrmState ¶
type XfrmState struct { Dst net.IP Src net.IP Proto Proto Mode Mode Spi int Reqid int ReplayWindow int Auth *XfrmStateAlgo Crypt *XfrmStateAlgo Encap *XfrmStateEncap }
XfrmState represents the state of an ipsec policy. It optionally contains an XfrmStateAlgo for encryption and one for authentication.
func XfrmStateList ¶
XfrmStateList gets a list of xfrm states in the system. Equivalent to: `ip xfrm state show`. The list can be filtered by ip family.
type XfrmStateAlgo ¶
XfrmStateAlgo represents the algorithm to use for the ipsec encryption.