genetlink

Documentation

Overview

Package genetlink implements the Linux Kernel Generic Netlink protocol, for interacting with the systems network stack and related subsystems.

This package contains a low-level implementation of the protocol, you should use a higher-level abstraction contained within a subpackage.

References:

• linux/include/uapi/linux/netlink.h
• linux/include/uapi/linux/genetlink.h
• https://www.kernel.org/doc/html/latest/netlink/specs/nlctrl.html

Index

• Variables
• type Client
  • func NewClient(family string, version uint8, opts ...netlink.ConnOption) (Client, error)
• type Controller
  • func NewController() (*Controller, error)
  • func (c *Controller) Close() error
  • func (c *Controller) GetFamily(name string) (*Family, error)
  • func (c *Controller) ListFamilies() (Families, error)
• type Families
  • func (fs *Families) UnmarshalNetlink(msg netlink.MessageDecoder) error
• type Family
  • func GetFamily(nl netlink.Client, name string) (*Family, error)
  • func (f *Family) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error
  • func (f *Family) UnmarshalNetlink(msg netlink.MessageDecoder) error
• type Group
  • func (g *Group) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error
• type Header
  • func (h Header) AppendBinary(b []byte) ([]byte, error)
  • func (Header) Len() int
  • func (h Header) MarshalBinary() ([]byte, error)
  • func (h Header) String() string
  • func (h *Header) UnmarshalBinary(b []byte) error
• type Op
  • func (o *Op) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error
• type OpFlags
  • func (o OpFlags) String() string

Variables

var ErrFamilyNotFound = errors.New("family not found")

ErrFamilyNotFound is returned by Controller.GetFamily when the requested Generic Netlink family does not exist.

Types

type Client

type Client interface {
	// Close the client, underlying socket, and prevent further client
	// exchanges.
	Close() error

	// Seq returns the last sequence number used by the client.
	Seq() uint32

	// Family returns the id of the Generic Netlink family resolved for the
	// family name this client was opened with.
	Family() uint16

	// FamilyName returns the name of the Generic Netlink family this client
	// was opened with.
	FamilyName() string

	// Version returns the Generic Netlink version this client was opened with.
	Version() uint8

	// Do executes a Generic Netlink request, marshaling the request from an
	// [Marshaler], and does not expect a response other than an ERROR
	// message type or an acknowledgement.
	//
	// The message will automatically have the Generic Netlink header added
	// with the given command, and have the REQUEST, ACK and any additional
	// flags set.
	//
	// On non-zero ERROR message types, the error will be unmarshaled
	// automatically and returned as an [Error] type.
	Do(cmd uint8, flags uint16, src netlink.Marshaler) error

	// Dump executes a Generic Netlink request, marshaling the request from a
	// [Marshaler], which may be nil, and unmarshaling the response(s) to an
	// [Unmarshaler].
	//
	// The message will automatically have the Generic Netlink header added
	// with the given command, and have the REQUEST, DUMP and any additional
	// flags set.
	//
	// If the response contains multiple messages, dst will be unmarshaled to
	// repeatedly until all messages have been consumed, not including the
	// DONE message type.
	//
	// On non-zero ERROR message types, the error will be unmarshaled
	// automatically and returned as an [Error] type.
	Dump(cmd uint8, flags uint16, src netlink.Marshaler, dst netlink.Unmarshaler) error

	// Get executes a Generic Netlink request, marshaling the request from a
	// [Marshaler], which may be nil, and unmarshaling the response to an
	// [Unmarshaler].
	//
	// The message will automatically have the Generic Netlink header added
	// with the given command, and have the REQUEST, ACK and any additional
	// flags set.
	//
	// On non-zero ERROR message types, the error will be unmarshaled
	// automatically and returned as an [Error] type.
	Get(cmd uint8, flags uint16, src netlink.Marshaler, dst netlink.Unmarshaler) error
}

Client is a wrapper around a netlink.Client for exchanging client requests and responses using Generic Netlink, where all messages will automatically be configured for the Generic Netlink header.

It is safe for concurrent use, the client will only ever have one request and response exchange in-flight at once.

func NewClient

func NewClient(family string, version uint8, opts ...netlink.ConnOption) (Client, error)

NewClient establishes a Netlink socket connection, configured for the given Generic Netlink family and version, and creates a Client for exchanging messages with request-response semantics.

It may optionally be given [ConnOption] to configure the underlying socket.

type Controller

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

Controller implements the API for the Generic Netlink Controller, used to register and discover Generic Netlink families available on a system.

References:

• https://www.kernel.org/doc/html/latest/netlink/specs/nlctrl.html

func NewController

func NewController() (*Controller, error)

NewController establishes a Netlink socket connection for the netlink.GENERIC family, and returns a Controller client.

func (*Controller) Close

func (c *Controller) Close() error

Close the Netlink socket to the Controller client.

func (*Controller) GetFamily

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

GetFamily returns details of the named Generic Netlink family.

If the family does not exist, ErrFamilyNotFound is returned.

func (*Controller) ListFamilies

func (c *Controller) ListFamilies() (Families, error)

ListFamilies lists the available Generic Netlink families.

type Families

type Families []*Family

Families contains the Generic Netlink families available on the system.

References:

• https://www.kernel.org/doc/html/latest/netlink/specs/nlctrl.html#ctrl-attrs

func (*Families) UnmarshalNetlink

func (fs *Families) UnmarshalNetlink(msg netlink.MessageDecoder) error

UnmarshalNetlink unmarshals a Generic Netlink family dump from a message.

type Family

type Family struct {
	ID      uint16
	Name    string
	Version uint32
	HdrSize uint32
	MaxAttr uint32
	Ops     []*Op
	Groups  []*Group
}

Family contains information about a registered Generic Netlink family.

References:

• https://www.kernel.org/doc/html/latest/netlink/specs/nlctrl.html#ctrl-attrs

func GetFamily

func GetFamily(nl netlink.Client, name string) (*Family, error)

GetFamily is a helper to resolve the the named Family with an established netlink.Client without initializing a whole Controller.

The client MUST be configured for the netlink.GENERIC family.

If the family does not exist, ErrFamilyNotFound is returned.

func (*Family) UnmarshalAttributes

func (f *Family) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error

UnmarshalAttributes unmarshals the attributes for a Generic Netlink family.

func (*Family) UnmarshalNetlink

func (f *Family) UnmarshalNetlink(msg netlink.MessageDecoder) error

UnmarshalNetlink unmarshals a Generic Netlink family from a message.

type Group

type Group struct {
	ID   uint32
	Name string
}

Group is one of the multicast groups a Family has defined.

References:

• https://www.kernel.org/doc/html/latest/netlink/specs/nlctrl.html#mcast-group-attrs

func (*Group) UnmarshalAttributes

func (g *Group) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error

UnmarshalAttributes unmarshals a multicast group contained within Family.

type Header

type Header struct {
	netlink.MessageHeader

	Cmd      uint8
	Version  uint8
	Reserved uint16
}

Header is the fixed-length preamble before each Generic Netlink message that describes the command.

References:

• linux/include/uapi/linux/genetlink.h

func (Header) AppendBinary

func (h Header) AppendBinary(b []byte) ([]byte, error)

AppendBinary appends a Generic Netlink header to bytes, in the host byteorder.

func (Header) Len

func (Header) Len() int

Len returns the fixed-length of the Generic Netlink header.

func (Header) MarshalBinary

func (h Header) MarshalBinary() ([]byte, error)

MarshalBinary marshals a Generic Netlink header to bytes, in the host byteorder.

func (Header) String

func (h Header) String() string

String returns a string representation of the attribute header for debugging.

func (*Header) UnmarshalBinary

func (h *Header) UnmarshalBinary(b []byte) error

UnmarshalBinary unmarshals a Generic Netlink header from bytes using the host byteorder.

It will ignore any additional bytes it is given.

type Op

type Op struct {
	ID    uint32
	Flags OpFlags
}

Op is one of the Generic Netlink operations a Family has defined.

References:

• linux/include/uapi/linux/genetlink.h

func (*Op) UnmarshalAttributes

func (o *Op) UnmarshalAttributes(attrs *netlink.AttributeDecoder) error

UnmarshalAttributes unmarshals a single Op for a Family.

type OpFlags

type OpFlags uint32

OpFlags defines the permissions required for an Op.

References:

• linux/include/uapi/linux/genetlink.h

const (
	ADMIN_PERM OpFlags = 1 << iota
	CMD_CAP_DO
	CMD_CAP_DUMP
	CMD_CAP_HASPOL
	UNS_ADMIN_PERM
)

Constants for Op.

func (OpFlags) String

func (o OpFlags) String() string