pymnl.message Module

Message type:

Flag Meaning
NLM_F_REQUEST It is a request message
NLM_F_MULTI Multipart message, terminated by NLMSG_DONE
NLM_F_ACK Reply with ack, with zero or error code
NLM_F_ECHO Echo this request

Modifiers to GET request:

Modifier Meaning
NLM_F_ROOT specify tree root
NLM_F_MATCH return all matching
NLM_F_ATOMIC atomic GET
NLM_F_DUMP NLM_F_ROOT | NLM_F_MATCH

Modifiers to NEW request:

Modifier Meaning
NLM_F_REPLACE Override existing
NLM_F_EXCL Do not touch, if it exists
NLM_F_CREATE Create, if it does not exist
NLM_F_APPEND Add to end of list

Response message types:

Flag Meaning
NLMSG_NOOP Nothing.
NLMSG_ERROR Error
NLMSG_DONE End of a dump
NLMSG_OVERRUN Data lost
pymnl.message.NLMSG_ALIGNTO

The size to which netlink messages should be aligned.

pymnl.message.NLMSG_ALIGN(x)

A function that returns the size of x aligned to the size of NLMSG_ALIGNTO.

pymnl.message.MSG_HDRLEN

The aligned size of a message header.

class pymnl.message.Message(buffer=None)

A netlink message.

Netlink message:

|<----------------- 4 bytes ------------------->|
|<----- 2 bytes ------>|<------- 2 bytes ------>|
|-----------------------------------------------|
|      Message length (including header)        |
|-----------------------------------------------|
|     Message type     |     Message flags      |
|-----------------------------------------------|
|           Message sequence number             |
|-----------------------------------------------|
|                 Netlink PortID                |
|-----------------------------------------------|
|                                               |
.                   Payload                     .
|_______________________________________________|

There is usually an extra header after the the Netlink header (at the beginning of the payload). This extra header is specific of the Netlink subsystem. After this extra header, comes the sequence of attributes that are expressed in Length-Type-Value (LTV) format.

__init__(buffer=None)

buffer - A string of bytes to interpret as a Message.

__len__()

Get the unaligned length of the message (in bytes).

__weakref__

list of weak references to the object (if defined)

add_payload(data)

Add payload to the message.

data - Payload or string

get_binary()

Return a packed struct suitable for sending through a netlink socket.

get_errno()

Return the errno reported by Netlink.

get_errstr()

Return the errno reported by Netlink as interpretted by os.strerror.

get_flags()

Returns the 2-byte flag.

get_payload()

Return the payload object contained in the message.

get_portid()

Returns the 4-byte port id.

get_seq()

Returns the 4-byte sequence number.

get_type()

Returns the 2-byte type.

ok()

Check that Message is internally consistent. (i.e. verify that a netlink message is not malformed nor truncated.

portid_ok(portid)

Perform portID origin check.

portid - netlink portid that we want to check

This method returns true if the origin is fulfilled, otherwise false is returned. We skip the tracking for netlink message whose portID is zero since it is reserved for event-based kernel notifications. On the other hand, if portid is set but the message PortID is not (i.e. this is an event message coming from kernel-space), then we also skip the tracking. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track).

printf(extra_header_size=0)

This method prints the full netlink message to stdout. It may be useful for debugging purposes.

It calls Message.printf_header() and Payload.printf() to do the real work.

printf_header()

This method prints the netlink message header to stdout. It may be useful for debugging purposes. Use Message.printf() to print out a full message.

One example of the output is the following:

----------------        ------------------
|  0000000040  |        | message length |
| 00016 | R-A- |        |  type | flags  |
|  1289148991  |        | sequence number|
|  0000000000  |        |     port ID    |
----------------        ------------------

This example shows the header of the netlink message that is sent to kernel-space to set up the link interface eth0. The netlink header data is displayed in base 10. The possible flags in the netlink header are:

  • R, that indicates that NLM_F_REQUEST is set.
  • M, that indicates that NLM_F_MULTI is set.
  • A, that indicates that NLM_F_ACK is set.
  • E, that indicates that NLM_F_ECHO is set.

The lack of one flag is displayed with '-'.

put_extra_header(header)

Add a protocol-specific header to the Payload.

Simply appends the header object to the message payload. Users must finish building their list of extra headers before continuing with constructing the message payload. Otherwise, the next extra header will be after the payload contents. This is the same behavior as libmnl.

header - The object which contains the extra header. This
object must provide a get_binary() method which returns a binary string/bytes with the netlink data, like Payload or GenlMessageHeader.
seq_ok(seq)

Perform sequence tracking.

seq - last sequence number used to send a message

This method returns true if the sequence tracking is fulfilled, otherwise false is returned. We skip the tracking for netlink messages whose sequence number is zero since it is usually reserved for event-based kernel notifications. On the other hand, if seq is set but the message sequence number is not set (i.e. this is an event message coming from kernel-space), then we also skip the tracking. This approach is good if we use the same socket to send commands to kernel-space (that we want to track) and to listen to events (that we do not track).

set_flags(flags)

Sets the message flags.

flags - 2-byte integer

set_portid(pid)

Sets the message port id.

pid - 4-byte integer

set_seq(seq)

Sets the message sequence number.

seq - 4-byte integer

set_type(msg_type)

Sets the message type.

msg_type - 2-byte integer

class pymnl.message.MessageList(msg)

Holds the Message objects making up a multipart message.

__init__(msg)

msg - A Message object.

__weakref__

list of weak references to the object (if defined)

size()

Return the length (in bytes) of the total MessageList.

split(msg)

Split multipart message into its component messages.

class pymnl.message.Payload(contents=None)

The payload of a netlink message.

__init__(contents=None)

contents - string or object representing the payload When passing an object, it must implement the get_binary() method.

__len__()

Get the length of the payload (in bytes).

__weakref__

list of weak references to the object (if defined)

add_attr(attribute)

Add an Attr object to the payload.

attribute - an Attr object

get_binary()

Return a packed struct suitable for sending through a netlink socket.

get_data()

Return the non-header data string. This is the non-aligned version of get_binary().

printf(msg_type, extra_header_size)

This method prints the netlink message payload to stdout. It may be useful for debugging purposes. Use Message.printf() to print out a full message.

One example of the output is the following:

| 00 00 00 00  |        |  extra header  |
| 00 00 00 00  |        |  extra header  |
| 01 00 00 00  |        |  extra header  |
| 01 00 00 00  |        |  extra header  |
|00008|--|00003|        |len |flags| type|
| 65 74 68 30  |        |      data      |       e t h 0
----------------        ------------------

This example shows the payload for the netlink message that is send to kernel-space to set up the link interface eth0. The extra header and the attribute payloads are expressed in base 16.

The attribute header is shown in base 10. The possible flags in the attribute header are:

  • N, that indicates that NLA_F_NESTED is set.
  • B, that indicates that NLA_F_NET_BYTEORDER is set.

The lack of one flag is displayed with '-'.

set(contents)

Set the payload contents.

contents - string or object representing the payload
When passing an object, it must implement the get_binary() method.