genetlink: github.com/mdlayher/genetlink Index | Examples | Files | Directories

package genetlink

import "github.com/mdlayher/genetlink"

Package genetlink implements generic netlink interactions and data types.

If you have any questions or you'd like some guidance, please join us on Gophers Slack (https://invite.slack.golangbridge.org) in the #networking channel!

Index

Examples

Package Files

conn.go doc.go family.go family_linux.go message.go

Constants

const Protocol = 0x10 // unix.NETLINK_GENERIC

Protocol is the netlink protocol constant used to specify generic netlink.

type Conn Uses

type Conn struct {
    // contains filtered or unexported fields
}

A Conn is a generic netlink connection. A Conn can be used to send and receive generic netlink messages to and from netlink.

A Conn is safe for concurrent use, but to avoid contention in high-throughput applications, the caller should almost certainly create a pool of Conns and distribute them among workers.

This example demonstrates using a genetlink.Conn's high level interface to query for a specific generic netlink family.

Code:

c, err := genetlink.Dial(nil)
if err != nil {
    log.Fatalf("failed to dial generic netlink: %v", err)
}
defer c.Close()

// Ask generic netlink about the generic netlink controller (nlctrl)'s
// family information.
const name = "nlctrl"
family, err := c.GetFamily(name)
if err != nil {
    // If a family doesn't exist, the error can be checked using
    // netlink.IsNotExist.
    if netlink.IsNotExist(err) {
        log.Printf("%q family not available", name)
        return
    }

    log.Fatalf("failed to query for family: %v", err)
}

log.Printf("%s: %+v", name, family)

This example demonstrates using a genetlink.Conn's high level interface to query for all known generic netlink families.

Code:

c, err := genetlink.Dial(nil)
if err != nil {
    log.Fatalf("failed to dial generic netlink: %v", err)
}
defer c.Close()

// Ask generic netlink about all families registered with it.
families, err := c.ListFamilies()
if err != nil {
    log.Fatalf("failed to query for families: %v", err)
}

for i, f := range families {
    log.Printf("#%02d: %+v", i, f)
}

This example demonstrates using a genetlink.Conn's high level and low level interfaces to detect if nl80211 (netlink 802.11 WiFi device generic netlink family) is available, and if it is, sending a request to it to retrieve all WiFi interfaces.

Code:

c, err := genetlink.Dial(nil)
if err != nil {
    log.Fatalf("failed to dial generic netlink: %v", err)
}
defer c.Close()

// Constants which are sourced from nl80211.h.
const (
    name = "nl80211"

    nl80211CommandGetInterface = 5

    nl80211AttributeInterfaceIndex = 3
    nl80211AttributeInterfaceName  = 4
    nl80211AttributeAttributeMAC   = 6
)

// Ask generic netlink if nl80211 is available.
family, err := c.GetFamily(name)
if err != nil {
    if netlink.IsNotExist(err) {
        log.Printf("%q family not available", name)
        return
    }

    log.Fatalf("failed to query for family: %v", err)
}

// Ask nl80211 to dump a list of all WiFi interfaces.
req := genetlink.Message{
    Header: genetlink.Header{
        Command: nl80211CommandGetInterface,
        Version: family.Version,
    },
}

// Send request specifically to nl80211 instead of generic netlink
// controller (nlctrl).
flags := netlink.Request | netlink.Dump
msgs, err := c.Execute(req, family.ID, flags)
if err != nil {
    log.Fatalf("failed to execute: %v", err)
}

// ifInfo contains basic information about a WiFi interface.
type ifInfo struct {
    Index int
    Name  string
    MAC   net.HardwareAddr
}

var infos []ifInfo
for _, m := range msgs {
    // nl80211's response contains packed netlink attributes.
    ad, err := netlink.NewAttributeDecoder(m.Data)
    if err != nil {
        log.Fatalf("failed to create attribute decoder: %v", err)
    }

    // Gather data about interface from attributes.
    var info ifInfo
    for ad.Next() {
        switch ad.Type() {
        case nl80211AttributeInterfaceIndex:
            info.Index = int(ad.Uint32())
        case nl80211AttributeInterfaceName:
            info.Name = ad.String()
        case nl80211AttributeAttributeMAC:
            ad.Do(func(b []byte) error {
                if l := len(b); l != 6 {
                    return fmt.Errorf("unexpected MAC length: %d", l)
                }

                info.MAC = net.HardwareAddr(b)
                return nil
            })
        }
    }

    // Were any of the attributes malformed?
    if err := ad.Err(); err != nil {
        log.Fatalf("failed to decode attributes: %v", err)
    }

    infos = append(infos, info)
}

for i, info := range infos {
    log.Printf("#%02d: %+v", i, info)
}

func Dial Uses

func Dial(config *netlink.Config) (*Conn, error)

Dial dials a generic netlink connection. Config specifies optional configuration for the underlying netlink connection. If config is nil, a default configuration will be used.

func NewConn Uses

func NewConn(c *netlink.Conn) *Conn

NewConn creates a Conn that wraps an existing *netlink.Conn for generic netlink communications.

NewConn is primarily useful for tests. Most applications should use Dial instead.

func (*Conn) Close Uses

func (c *Conn) Close() error

Close closes the connection. Close will unblock any concurrent calls to Receive which are waiting on a response from the kernel.

func (*Conn) Execute Uses

func (c *Conn) Execute(m Message, family uint16, flags netlink.HeaderFlags) ([]Message, error)

Execute sends a single Message to netlink using Send, receives one or more replies using Receive, and then checks the validity of the replies against the request using netlink.Validate.

Execute acquires a lock for the duration of the function call which blocks concurrent calls to Send and Receive, in order to ensure consistency between generic netlink request/reply messages.

See the documentation of Send, Receive, and netlink.Validate for details about each function.

func (*Conn) GetFamily Uses

func (c *Conn) GetFamily(name string) (Family, error)

GetFamily retrieves a generic netlink family with the specified name.

If the family does not exist, the error value can be checked using netlink.IsNotExist.

func (*Conn) JoinGroup Uses

func (c *Conn) JoinGroup(group uint32) error

JoinGroup joins a netlink multicast group by its ID.

func (*Conn) LeaveGroup Uses

func (c *Conn) LeaveGroup(group uint32) error

LeaveGroup leaves a netlink multicast group by its ID.

func (*Conn) ListFamilies Uses

func (c *Conn) ListFamilies() ([]Family, error)

ListFamilies retrieves all registered generic netlink families.

func (*Conn) Receive Uses

func (c *Conn) Receive() ([]Message, []netlink.Message, error)

Receive receives one or more Messages from netlink. The netlink.Messages used to wrap each Message are available for later validation.

func (*Conn) RemoveBPF Uses

func (c *Conn) RemoveBPF() error

RemoveBPF removes a BPF filter from a Conn.

func (*Conn) Send Uses

func (c *Conn) Send(m Message, family uint16, flags netlink.HeaderFlags) (netlink.Message, error)

Send sends a single Message to netlink, wrapping it in a netlink.Message using the specified generic netlink family and flags. On success, Send returns a copy of the netlink.Message with all parameters populated, for later validation.

func (*Conn) SetBPF Uses

func (c *Conn) SetBPF(filter []bpf.RawInstruction) error

SetBPF attaches an assembled BPF program to a Conn.

func (*Conn) SetDeadline Uses

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error.

func (*Conn) SetOption Uses

func (c *Conn) SetOption(option netlink.ConnOption, enable bool) error

SetOption enables or disables a netlink socket option for the Conn.

func (*Conn) SetReadBuffer Uses

func (c *Conn) SetReadBuffer(bytes int) error

SetReadBuffer sets the size of the operating system's receive buffer associated with the Conn.

func (*Conn) SetReadDeadline Uses

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error.

func (*Conn) SetWriteBuffer Uses

func (c *Conn) SetWriteBuffer(bytes int) error

SetWriteBuffer sets the size of the operating system's transmit buffer associated with the Conn.

func (*Conn) SetWriteDeadline Uses

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline associated with the connection.

Deadline functionality is only supported on Go 1.12+. Calling this function on older versions of Go will result in an error.

func (*Conn) SyscallConn Uses

func (c *Conn) SyscallConn() (syscall.RawConn, error)

SyscallConn returns a raw network connection. This implements the syscall.Conn interface.

On Go 1.12+, all methods of the returned syscall.RawConn are supported and the Conn is integrated with the runtime network poller. On versions of Go prior to Go 1.12, only the Control method of the returned syscall.RawConn is implemented.

SyscallConn is intended for advanced use cases, such as getting and setting arbitrary socket options using the netlink socket's file descriptor.

Once invoked, it is the caller's responsibility to ensure that operations performed using Conn and the syscall.RawConn do not conflict with each other.

type Family Uses

type Family struct {
    ID      uint16
    Version uint8
    Name    string
    Groups  []MulticastGroup
}

A Family is a generic netlink family.

type Header struct {
    // Command specifies a command to issue to netlink.
    Command uint8

    // Version specifies the version of a command to use.
    Version uint8
}

A Header is a generic netlink header. A Header is sent and received with each generic netlink message to indicate metadata regarding a Message.

type Message Uses

type Message struct {
    Header Header
    Data   []byte
}

A Message is a generic netlink message. It contains a Header and an arbitrary byte payload, which may be decoded using information from the Header.

Data is encoded using the native endianness of the host system. Use the netlink.AttributeDecoder and netlink.AttributeEncoder types to decode and encode data.

func (Message) MarshalBinary Uses

func (m Message) MarshalBinary() ([]byte, error)

MarshalBinary marshals a Message into a byte slice.

func (*Message) UnmarshalBinary Uses

func (m *Message) UnmarshalBinary(b []byte) error

UnmarshalBinary unmarshals the contents of a byte slice into a Message.

type MulticastGroup Uses

type MulticastGroup struct {
    ID   uint32
    Name string
}

A MulticastGroup is a generic netlink multicast group, which can be joined for notifications from generic netlink families when specific events take place.

Directories

PathSynopsis
genltestPackage genltest provides utilities for generic netlink testing.

Package genetlink imports 9 packages (graph) and is imported by 17 packages. Updated 2019-06-18. Refresh now. Tools for package owners.