Modules in progress — pyroute2 0.3.18 documentation

### Navigation

- index
- modules |
- next |
- previous |
- pyroute2 0.3.18 documentation »

# Modules in progress

There are several modules in the very initial development state, and the help with them will be particularly valuable. You are more than just welcome to help with:

## IPSet module

The very basic ipset support.

Right now it is tested only for hash:ip and doesn’t support many useful options. But it can be easily extended, so you are welcome to help with that.

class `pyroute2.ipset.` `IPSet`(version=6, attr_revision=0, nfgen_family=2)

  NFNetlink socket (family=NETLINK_NETFILTER).

  Implements API to the ipset functionality.

  `add`(name, entry, family=2, exclusive=True)

    Add a member to the ipset

  `create`(name, stype='hash:ip', family=2, exclusive=True)

    Create an ipset name of type stype, by default hash:ip.

    Very simple and stupid method, should be extended to support ipset options.

  `delete`(name, entry, family=2, exclusive=True)

    Delete a member from the ipset

  `destroy`(name)

    Destroy an ipset

  `list`(name=None)

    List installed ipsets. If name is provided, list the named ipset or return an empty list.

    It looks like nfnetlink doesn’t return an error, when requested ipset doesn’t exist.

  `swap`(set_a, set_b)

    Swap two ipsets

## IW module

Experimental wireless module — nl80211 support.

### Disclaimer

Unlike IPRoute, which is mostly usable, though is far from complete yet, the IW module is in the very initial state. Neither the module itself, nor the message class cover the nl80211 functionality reasonably enough. So if you’re going to use it, brace yourself — debug is coming.

### Messages

nl80211 messages are defined here:

    pyroute2/netlink/nl80211/__init__.py

Pls notice NLAs of type hex. On the early development stage hex allows to inspect incoming data as a hex dump and, occasionally, even make requests with such NLAs. But it’s not a production way.

The type hex in the NLA definitions means that this particular NLA is not handled yet properly. If you want to use some NLA which is defined as hex yet, pls find out a specific type, patch the message class and submit your pull request on github.

If you’re not familiar with NLA types, take a look at RTNL definitions:

    pyroute2/netlink/rtnl/ndmsg.py

and so on.

### Communication with the kernel

There are several methods of the communication with the kernel.

> - sendto() — lowest possible, send a raw binary data
> - put() — send a netlink message
> - nlm_request() — send a message, return the response
> - get() — get a netlink message
> - recv() — get a raw binary data from the kernel

There are no errors on put() usually. Any permission denied, any invalid value errors are returned from the kernel with netlink also. So if you do put(), but don’t do get(), be prepared to miss errors.

The preferred method for the communication is nlm_request(). It tracks the message ID, returns the corresponding response. In the case of errors nlm_request() raises an exception. To get the response on any operation with nl80211, use flag NLM_F_ACK.

### Reverse it

If you’re too lazy to read the kernel sources, but still need something not implemented here, you can use reverse engineering on a reference implementation. E.g.:

    # strace -e trace=network -f -x -s 4096 \
            iw phy phy0 interface add test type monitor

Will dump all the netlink traffic between the program iw and the kernel. Three first packets are the generic netlink protocol discovery, you can ignore them. All that follows, is the nl80211 traffic:

    sendmsg(3, {msg_name(12)={sa_family=AF_NETLINK, ... },
        msg_iov(1)=[{"\x30\x00\x00\x00\x1b\x00\x05 ...", 48}],
        msg_controllen=0, msg_flags=0}, 0) = 48
    recvmsg(3, {msg_name(12)={sa_family=AF_NETLINK, ... },
        msg_iov(1)=[{"\x58\x00\x00\x00\x1b\x00\x00 ...", 16384}],
        msg_controllen=0, msg_flags=0}, 0) = 88
    ...

With -s 4096 you will get the full dump. Then copy the strings from msg_iov to a file, let’s say data, and run the decoder:

    $ pwd
    /home/user/Projects/pyroute2
    $ export PYTHONPATH=`pwd`
    $ python scripts/decoder.py pyroute2.netlink.nl80211.nl80211cmd data

You will get the session decoded:

    {'attrs': [['NL80211_ATTR_WIPHY', 0],
               ['NL80211_ATTR_IFNAME', 'test'],
               ['NL80211_ATTR_IFTYPE', 6]],
     'cmd': 7,
     'header': {'flags': 5,
                'length': 48,
                'pid': 3292542647,
                'sequence_number': 1430426434,
                'type': 27},
     'reserved': 0,
     'version': 0}
    {'attrs': [['NL80211_ATTR_IFINDEX', 23811],
               ['NL80211_ATTR_IFNAME', 'test'],
               ['NL80211_ATTR_WIPHY', 0],
               ['NL80211_ATTR_IFTYPE', 6],
               ['NL80211_ATTR_WDEV', 4],
               ['NL80211_ATTR_MAC', 'a4:4e:31:43:1c:7c'],
               ['NL80211_ATTR_GENERATION', '02:00:00:00']],
     'cmd': 7,
     'header': {'flags': 0,
                'length': 88,
                'pid': 3292542647,
                'sequence_number': 1430426434,
                'type': 27},
     'reserved': 0,
     'version': 1}

Now you know, how to do a request and what you will get as a response. Sample collected data is in the scripts directory.

### Submit changes

Please do not hesitate to submit the changes on github. Without your patches this module will not evolve.

## Network settings daemon – pyrouted

Pyrouted is a standalone project of a system service, that utilizes the pyroute2 library. It consists of a daemon controlled by systemd and a CLI utility that communicates with the daemon via UNIX socket.

- home: https://github.com/svinota/pyrouted
- bugs: https://github.com/svinota/pyrouted/issues
- pypi: https://pypi.python.org/pypi/pyrouted

It is an extremely simple and basic network interface setup tool.

### Navigation

- index
- modules |
- next |
- previous |
- pyroute2 0.3.18 documentation »