Netlink - Linux Netlink Socket Framing

pcapkit.protocols.link.netlink contains Netlink only, which implements the extractor for the struct nlmsghdr framing of Linux’s own kernel/user IPC transport, as seen on a LINKTYPE_LINUX_SLL/LINKTYPE_LINUX_SLL2 capture whose arphrd_type is ARPHRD_NETLINK (an nlmon interface). Its structure is described as below:

Octets	Bits	Name	Description
0	0	netlink.nlmsg_len	Message Length (header included)
4	32	netlink.nlmsg_type	Message Type
6	48	netlink.nlmsg_flags	Message Flags
8	64	netlink.nlmsg_seq	Sequence Number
12	96	netlink.nlmsg_pid	Sender Port ID

Only this fixed 16-octet header is dissected; per-family message payloads and multiple messages packed into one capture are out of scope for this first cut – see the module docstring’s Scope section. The byte order the header was written in is ambiguous (Netlink [*] is kernel/userspace IPC, not wire format) and is guessed by nlmsg_byteorder(); either way it is kept as netlink.byteorder.

class pcapkit.protocols.link.netlink.Netlink(file=None, length=None, **kwargs)

Bases: Link[Netlink, Netlink]

This class implements Linux Netlink socket framing.

Every message’s payload is kept as Raw unless its nlmsg_type is registered – see the module docstring’s Scope section for why. self.__proto__ ships empty, so that register() works the same way every other Link subclass’s does.

property name: Literal['Netlink']

Name of current protocol.

property alias: Literal['Netlink']

Acronym of corresponding protocol.

property length: Literal[16]

Header length of current protocol.

property protocol: int

Message type of the dissected nlmsghdr.

classmethod id()

Index ID of the protocol.

Return type:

tuple[Literal['Netlink']]

read(length=None, *, byteorder=None, **kwargs)

Read Linux Netlink socket framing.

Structure of the nlmsghdr this class dissects, the first message in the frame:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            nlmsg_len                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            nlmsg_type         |          nlmsg_flags          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            nlmsg_seq                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            nlmsg_pid                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

• length (int | None) – Length of packet data.

• byteorder (Literal['big', 'little'] | None) – Byte order to read the header in, ahead of guessing it from nlmsg_byteorder(). make() is handed the one info holds by from_data, and it reaches here too, so a rebuild reads the header as it was parsed rather than guessing again.

• **kwargs (Any) – Arbitrary keyword arguments.

Return type:

Netlink

Returns:

Parsed packet data.

Raises:

ProtocolError – If byteorder is neither 'big' nor 'little'.

make(nlmsg_type=0, nlmsg_flags=0, nlmsg_seq=0, nlmsg_pid=0, nlmsg_len=None, byteorder=sys.byteorder, payload=b'', **kwargs)

Make (construct) packet data.

Parameters:

• nlmsg_type (int) – Message type.

• nlmsg_flags (int) – Message flags.

• nlmsg_seq (int) – Sequence number.

• nlmsg_pid (int) – Sender port ID.

• nlmsg_len (int | None) – Message length, header included; computed from the header and payload when omitted.

• byteorder (Literal['big', 'little']) – Byte order to write the header in, by default this host’s, as a genuine capture is written in the capturing host’s own order.

• payload (bytes | ProtocolBase | Schema) – Payload data.

• **kwargs (Any) – Arbitrary keyword arguments.

Return type:

Netlink

Returns:

Constructed packet data.

Raises:

ProtocolError – If byteorder is neither 'big' nor 'little'; if nlmsg_type or nlmsg_flags is not an int (a bool included) or does not fit in 16 bits; if nlmsg_seq or nlmsg_pid is not an int (a bool included) or does not fit in 32 bits; or if nlmsg_len is given and does not fit in 32 bits.

classmethod register(code, protocol)

Register a new protocol class for a message type.

Notes

The fully qualified class name of the new protocol class should be {protocol.module}.{protocol.name}.

Parameters:

• code (int) – nlmsg_type of the dissected message

• protocol (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module descriptor or a ProtocolBase subclass

Important

This overrides Link.register because self.__proto__ is keyed by nlmsg_type rather than by EtherType.

Raises:

pcapkit.utilities.exceptions.RegistryError – If protocol is not a class, or not a ProtocolBase subclass.

Warns:

pcapkit.utilities.warnings.RegistryWarning – If this message type is already registered and the incumbent differs from the replacement; see Protocol.register for the guard.

__length_hint__()

Return an estimated length for the object.

Return type:

Literal[16]

classmethod __index__()

Numeral registry index of the protocol.

Return type:

ARPHRD

Returns:

Numeral registry index of the protocol in Linux ARP hardware types, the arphrd_type that LinuxSLL.__proto__ dispatches here.

classmethod _make_data(data)

Create key-value pairs from data for protocol construction.

Parameters:

data (Netlink) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

__proto__: DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]

Protocol index mapping for decoding next layer, keyed by nlmsg_type. Deliberately empty – see the class docstring – so every unregistered key resolves through the defaultdict fallback to Raw.

pcapkit.protocols.link.netlink.nlmsg_byteorder(nlmsg_len, length)

Guess the byte order a Netlink message header was written in.

Parameters:

• nlmsg_len (bytes) – The 4 raw octets of nlmsg_len.

• length (int) – Octets available from the start of this header to the end of the frame – nlmsg_len counts the header itself (RFC 3549 Section 2.3.2: “the length of the message in bytes, including the header”), so this is the quantity to compare against, not the payload alone.

Return type:

Literal['big', 'little']

Returns:

'big' or 'little', whichever reading of nlmsg_len comes closer to length; ties favour 'little', the overwhelmingly common case (x86/ARM hosts).

Note

This is the heuristic Wireshark’s own netlink dissector uses (packet-netlink.c, dissect_netlink()): a genuine message length is normally well under the size either misreading of 4 arbitrary octets would imply, so the reading closer to the octets actually on hand is overwhelmingly likely to be the real one.

Header Schemas

class pcapkit.protocols.schema.link.netlink.Netlink(nlmsg_len=NO_VALUE, nlmsg_type=NO_VALUE, nlmsg_flags=NO_VALUE, nlmsg_seq=NO_VALUE, nlmsg_pid=NO_VALUE, payload=NO_VALUE, *, __packet__=None, **kwargs)

Bases: Schema

Header schema for Linux Netlink socket framing (nlmsghdr).

nlmsg_len: bytes = <BytesField nlmsg_len>

Message length, including this header; 4 octets, byte order ambiguous.

nlmsg_type: bytes = <BytesField nlmsg_type>

Message type; 2 octets, byte order ambiguous.

nlmsg_flags: bytes = <BytesField nlmsg_flags>

Message flags; 2 octets, byte order ambiguous.

nlmsg_seq: bytes = <BytesField nlmsg_seq>

Sequence number; 4 octets, byte order ambiguous.

nlmsg_pid: bytes = <BytesField nlmsg_pid>

Sender port ID; 4 octets, byte order ambiguous.

payload: bytes = <PayloadField payload>

Payload.

Data Models

class pcapkit.protocols.data.link.netlink.Netlink(nlmsg_len, nlmsg_type, nlmsg_flags, nlmsg_seq, nlmsg_pid, byteorder)

Bases: Protocol

Data model for Linux Netlink socket framing (nlmsghdr).

nlmsg_len: int

Message length, in octets, including this 16-octet header – as written, in whichever byte order byteorder records.

nlmsg_type: int

Message type; 1-4 are the generic control values (NLMSG_NOOP/NLMSG_ERROR/NLMSG_DONE/NLMSG_OVERRUN) shared by every Netlink family, 16 and above are family-specific and not interpreted by this class.

nlmsg_flags: int

Message flags; their bit meanings depend on nlmsg_type and on whether the message is a request, so they are not decoded further.

nlmsg_seq: int

Sequence number.

nlmsg_pid: int

Sender port ID; 0 when sent by the kernel.

byteorder: Literal['big', 'little']

Byte order the header was written in.

Footnotes

[*]

netlink(7); RFC 3549 Section 2.3.2