pymnl.message Module — pymnl 0.6 documentation

# pymnl 0.6 documentation

## 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.