.. debug: 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 $ cd pyroute2 Now run the decoder:: $ export PYTHONPATH=`pwd` $ python tests/decoder/decoder.py 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.