pyroute2-minimal 0.9.6

Supported systems

Pyroute2 runs natively on Linux and emulates some limited subset of RTNL netlink API on BSD systems on top of PF_ROUTE notifications and standard system tools.

Other platforms are not supported.

IPRoute – synchronous RTNL API

Low-level IPRoute utility — Linux network configuration, this class is almost a 1-to-1 RTNL mapping. There are no implicit interface lookups and so on.

Get notifications about network settings changes:

from pyroute2 import IPRoute

with IPRoute() as ipr:
    ipr.bind()  # <--- start listening for RTNL broadcasts
    for message in ipr.get():  # receive the broadcasts
        print(message)

More examples:

from socket import AF_INET
from pyroute2 import IPRoute

# get access to the netlink socket
ipr = IPRoute()
# no monitoring here -- thus no bind()

# print interfaces
for link in ipr.get_links():
    print(link)

# create VETH pair and move v0p1 to netns 'test'
ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')
# wait for the devices:
peer, veth = ipr.poll(
    ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
)
ipr.link('set', index=peer['index'], net_ns_fd='test')

# bring v0p0 up and add an address
ipr.link('set', index=veth['index'], state='up')
ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)

# release Netlink socket
ipr.close()

AsyncIPRoute – asynchronous RTNL API

While IPRoute provides a synchronous RTNL API, it is actually build around the asyncio-based core.

The same example as above can look like that:

import asyncio

from pyroute2 import AsyncIPRoute

async def main():
    # get access to the netlink socket
    ipr = AsyncIPRoute()

    # print interfaces
    async for link in await ipr.get_links():
        print(link)

    # create VETH pair and move v0p1 to netns 'test'
    await ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')

    # wait for the devices:
    peer, veth = await ipr.poll(
        ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
    )
    await ipr.link('set', index=peer['index'], net_ns_fd='test')
    ...
    ipr.close()

 asyncio.run(main())

Please notice that .close() is synchronous in any case.

Network namespace management

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 IPRoute

with IPRoute() as ipr:

    # create interface pair
    ipr.link('add', ifname='v0p0', kind='veth',  peer='v0p1')

    # wait for the peer
    (peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname='v0p1')

    # move the peer to the 'test' netns:
    ipr.link('set', index=peer['index'], net_ns_fd='test')

List interfaces in some netns:

from pyroute2 import IPRoute

with IPRoute(netns='test') as ipr:
    for link in ipr.get_links():
        print(link)

More details and samples see in the documentation.

NDB – high level RTNL API

Key features:

• Data integrity

• Transactions with commit/rollback changes

• State synchronization

• Multiple sources, including netns and remote systems

A “Hello world” example:

from pyroute2 import NDB

with NDB() as ndb:
    with ndb.interfaces['eth0'] as eth0:
        # set one parameter
        eth0.set(state='down')
        eth0.commit()  # make sure that the interface is down
        # or multiple parameters at once
        eth0.set(ifname='hello_world!', state='up')
        eth0.commit()  # rename, bring up and wait for success
    # --> <-- here you can be sure that the interface is up & renamed

Installation

Using pypi:

pip install pyroute2

Using git:

pip install git+https://github.com/svinota/pyroute2.git

Using source, requires make and nox

git clone https://github.com/svinota/pyroute2.git
cd pyroute2
make install

Requirements

Python >= 3.10

Links

• home: https://pyroute2.org/

• source: https://github.com/svinota/pyroute2

• bugs: https://github.com/svinota/pyroute2/issues

• pypi: https://pypi.python.org/pypi/pyroute2

• docs: http://docs.pyroute2.org/