Netlink debug howto

Dump data

Either run the required command via strace, or attach to the running process with strace -p. Use -s {int} argument to make sure that all the messages are dumped. The -x argument instructs strace to produce output in the hex format that can be passed to the pyroute2 decoder:

$ strace -e trace=network -x -s 16384 ip ro
socket(PF_NETLINK, SOCK_RAW|SOCK_CLOEXEC, NETLINK_ROUTE) = 3
setsockopt(3, SOL_SOCKET, SO_SNDBUF, [32768], 4) = 0
setsockopt(3, SOL_SOCKET, SO_RCVBUF, [1048576], 4) = 0
bind(3, {sa_family=AF_NETLINK, pid=0, groups=00000000}, 12) = 0
getsockname(3, {sa_family=AF_NETLINK, pid=28616, groups=00000000}, [12]) = 0
sendto(3, "\x28\x00\x00\x00\x1a\x00\x01\x03 [skip] ", 40, 0, NULL, 0) = 40
recvmsg(3, {msg_name(12)={sa_family=AF_NETLINK, pid=0, groups=00000000},
        msg_iov(1)=[{"\x3c\x00\x00\x00\x18 [skip]", 16384}],
        msg_controllen=0, msg_flags=0}, 0) = 480
socket(PF_LOCAL, SOCK_DGRAM|SOCK_CLOEXEC, 0) = 4
192.168.122.0/24 dev virbr0  proto kernel  scope link  src 192.168.122.1
recvmsg(3, {msg_name(12)={sa_family=AF_NETLINK, pid=0, groups=00000000},
        msg_iov(1)=[{"\x14\x00\x00\x00\x03 [skip]", 16384}],
        msg_controllen=0, msg_flags=0}, 0) = 20
+++ exited with 0 +++

Now you can copy send…() and recv…() buffer strings to a file.

Strace compatibility note

Starting with version 4.13, strace parses Netlink message headers and displays them in their parsed form instead of displaying the whole buffer in its raw form. The rest of the buffer is still shown, but due to it being incomplete, the method mentioned above doesn't work anymore.

For the time being, the easiest workaround is probably to use an older strace version as it only depends on libc6.

Decode data

The decoder is not provided with rpm or pip packages, so you should have a local git repo of the project:

$ git clone <url>
$ cd pyroute2

Now run the decoder:

$ export PYTHONPATH=`pwd`
$ python tests/decoder/decoder.py <message.class> <data>

E.g. for the route dump in the file rt.dump the command line should be:

$ python tests/decoder/decoder.py \
    pyroute2.netlink.rtnl.rtmsg.rtmsg \
    rt.dump

Why should I specify the message class? Why there is no marshalling in the decoder script? 'Cause it is intended to be used with different netlink protocols, not only RTNL, but also nl80211, nfnetlink etc. There is no common marshalling for all the netlink protocols.

How to specify the message class? All the netlink protocols are defined under pyroute2/netlink/, e.g. rtmsg module is pyroute2/netlink/rtnl/rtmsg.py. Thereafter you should specify the class inside the module, since there can be several classes. In the rtmsg case the line will be pyroute.netlink.rtnl.rtmsg.rtmsg or, more friendly to the bash autocomplete, pyroute2/netlink/rtnl/rtmsg.rtmsg. Notice, that the class you have to specify with dot anyways.

What is the data file format? Rules are as follows:

• The data dump should be in a hex format. Two possible variants are: \x00\x01\x02\x03 or 00:01:02:03.

• There can be several packets in the same file. They should be of the same type.

• Spaces and line ends are ignored, so you can format the dump as you want.

• The # symbol starts a comment until the end of the line.

• The #! symbols start a comment until the end of the file.

Example:

# ifinfmsg headers
#
# nlmsg header
\x84\x00\x00\x00  # length
\x10\x00          # type
\x05\x06          # flags
\x49\x61\x03\x55  # sequence number
\x00\x00\x00\x00  # pid
# RTNL header
\x00\x00          # ifi_family
\x00\x00          # ifi_type
\x00\x00\x00\x00  # ifi_index
\x00\x00\x00\x00  # ifi_flags
\x00\x00\x00\x00  # ifi_change
# ...

Compile data

Starting with 0.4.1, the library provides BatchSocket class, that only compiles and collects requests instead of sending them to the kernel. E.g., it is used by IPBatch, that combines BatchSocket with IPRouteMixin, providing RTNL compiler:

$ python3
Python 3.4.3 (default, Mar 31 2016, 20:42:37)
[GCC 5.3.1 20151207 (Red Hat 5.3.1-2)] on linux
Type "help", "copyright", "credits" or "license" for more information.
# import all the stuff
>>> from pyroute2 import IPBatch
>>> from pyroute2.common import hexdump
# create the compiler
>>> ipb = IPBatch()
# compile requests into one buffer
>>> ipb.link("add", index=550, kind="dummy", ifname="test")
>>> ipb.link("set", index=550, state="up")
>>> ipb.addr("add", index=550, address="10.0.0.2", mask=24)
# inspect the buffer
>>> hexdump(ipb.batch)
'3c:00:00:00:10:00:05:06:00:00:00:00:a2:7c:00:00:00:00:00:00:
 26:02:00:00:00:00:00:00:00:00:00:00:09:00:03:00:74:65:73:74:
 00:00:00:00:10:00:12:00:0a:00:01:00:64:75:6d:6d:79:00:00:00:
 20:00:00:00:13:00:05:06:00:00:00:00:a2:7c:00:00:00:00:00:00:
 26:02:00:00:01:00:00:00:01:00:00:00:28:00:00:00:14:00:05:06:
 00:00:00:00:a2:7c:00:00:02:18:00:00:26:02:00:00:08:00:01:00:
 0a:00:00:02:08:00:02:00:0a:00:00:02'
# reset the buffer
>>> ipb.reset()

Pls notice, that in Python2 you should use hexdump(str(ipb.batch)) instead of hexdump(ipb.batch).

The data, compiled by IPBatch can be used either to run batch requests, when one send() call sends several messages at once, or to produce binary buffers to test your own netlink parsers. Or just to dump some data to be sent later and probably even on another host:

>>> ipr = IPRoute()
>>> ipr.sendto(ipb.batch, (0, 0))

The compiler always produces requests with sequence_number == 0, so if there will be any responses, they can be handled as broadcasts.