pyroute2 ======== Pyroute2 is a pure Python **netlink** library. It requires only Python stdlib, no 3rd party libraries. The library was started as an RTNL protocol implementation, so the name is **pyroute2**, but now it supports many netlink protocols. Some supported netlink families and protocols: * **rtnl**, network settings --- addresses, routes, traffic controls * **nfnetlink** --- netfilter API: **ipset**, **nftables**, ... * **ipq** --- simplest userspace packet filtering, iptables QUEUE target * **devlink** --- manage and monitor devlink-enabled hardware * **generic** --- generic netlink families * **nl80211** --- wireless functions API (basic support) * **taskstats** --- extended process statistics * **acpi_events** --- ACPI events monitoring * **thermal_events** --- thermal events monitoring * **VFS_DQUOT** --- disk quota events monitoring the simplest usecase -------------------- The socket objects, provided by the library, are actual socket objects with a little bit extended API. The additional functionality aims to: * Help to open/bind netlink sockets * Discover generic netlink protocols and multicast groups * Construct, encode and decode netlink messages Maybe the simplest usecase is to monitor events. Disk quota events:: from pyroute2 import DQuotSocket # DQuotSocket automatically performs discovery and binding, # since it has no other functionality beside of the monitoring with DQuotSocket() as ds: for message in ds.get(): print(message) Or IPRoute:: from pyroute2 import IPRoute with IPRoute() as ipr: # With IPRoute objects you have to call bind() manually ipr.bind() for message in ipr.get(): print(message) rtnetlink sample ---------------- More samples you can read in the project documentation. Low-level **IPRoute** utility --- Linux network configuration. The **IPRoute** class is a 1-to-1 RTNL mapping. There are no implicit interface lookups and so on. Some examples:: from socket import AF_INET from pyroute2 import IPRoute # get access to the netlink socket ip = IPRoute() # no monitoring here -- thus no bind() # print interfaces print(ip.get_links()) # create VETH pair and move v0p1 to netns 'test' ip.link_create(ifname='v0p0', peer='v0p1', kind='veth') idx = ip.link_lookup(ifname='v0p1')[0] ip.link('set', index=idx, net_ns_fd='test') # bring v0p0 up and add an address idx = ip.link_lookup(ifname='v0p0')[0] ip.link('set', index=idx, state='up') ip.addr('add', index=idx, address='10.0.0.1', broadcast='10.0.0.255', prefixlen=24) # create a route with metrics ip.route('add', dst='172.16.0.0/24', gateway='10.0.0.10', metrics={'mtu': 1400, 'hoplimit': 16}) # create MPLS lwtunnel # $ sudo modprobe mpls_iptunnel ip.route('add', dst='172.16.0.0/24', oif=idx, encap={'type': 'mpls', 'labels': '200/300'}) # create MPLS route: push label # $ sudo modprobe mpls_router # $ sudo sysctl net.mpls.platform_labels=1024 ip.route('add', family=AF_MPLS, oif=idx, dst=0x200, newdst=[0x200, 0x300]) # release Netlink socket ip.close() High-level transactional interface, **IPDB**, a network settings DB:: from pyroute2 import IPDB # # The `with` statement automatically calls `IPDB.release()` # in the case of an exception. with IPDB() as ip: # # Create bridge and add ports and addresses. # # Transaction will be started by `with` statement # and will be committed at the end of the block with ip.create(kind='bridge', ifname='rhev') as i: i.add_port('em1') i.add_port('em2') i.add_ip('10.0.0.2/24') # --> <-- Here the system state is as described in # the transaction, if no error occurs. If # there is an error, all the changes will be # rolled back. The IPDB arch allows to use it transparently with network namespaces:: from pyroute2 import IPDB from pyroute2 import NetNS # Create IPDB to work with the 'test' ip netns. # # Pls notice, that IPDB itself will work in the # main netns, only the netlink transport is # working in the namespace `test`. ip = IPDB(nl=NetNS('test')) # Wait until someone will set up ipaddr 127.0.0.1 # in the netns on the loopback device ip.interfaces.lo.wait_ip('127.0.0.1') # The IPDB object must be released before exit to # sync all the possible changes that are in progress. ip.release() The project contains several modules for different types of netlink messages, not only RTNL. network namespace samples ------------------------- Network namespace manipulation:: from pyroute2 import netns # create netns netns.create('test') # list print(netns.listnetns()) # remove netns netns.remove('test') Create **veth** interfaces pair and move to **netns**:: from pyroute2 import IPDB ip = IPDB() # create interface pair ip.create(ifname='v0p0', kind='veth', peer='v0p1').commit() # move peer to netns with ip.interfaces.v0p1 as veth: veth.net_ns_fd = 'test' # don't forget to release before exit ip.release() List interfaces in some **netns**:: from pyroute2 import NetNS from pprint import pprint ns = NetNS('test') pprint(ns.get_links()) ns.close() More details and samples see in the documentation. installation ------------ `make install` or `pip install pyroute2` requires -------- Python >= 2.7 The pyroute2 testing framework requires **flake8**, **coverage**, **nosetests**. links ----- * home: https://github.com/svinota/pyroute2 * bugs: https://github.com/svinota/pyroute2/issues * pypi: https://pypi.python.org/pypi/pyroute2 * docs: http://docs.pyroute2.org/ * list: https://groups.google.com/d/forum/pyroute2-dev