IPDB module

Experimental IP database module. Provides high-level interface to the IPRoute functionality.

Basically, IPDB is a transactional database, containing records, representing network stack objects. Any change in the database is not reflected immediately in OS (unless you ask for that explicitly), but waits until commit() is called.

Quick start:

from pyroute2 import IPDB
# several IPDB instances are supported within on process
ip = IPDB()

# commit is called automatically upon the exit from `with`
# statement
with ip.interfaces.eth0 as i:
    i.address = '00:11:22:33:44:55'
    i.ifname = 'bala'
    i.txqlen = 2000

# basic routing support
ip.routes.add({'dst': 'default', 'gateway': '10.0.0.1'}).commit()

class pyroute2.netlink.ipdb.IPDB(nl=None, host=None, mode='implicit', key=None, cert=None, ca=None, iclass=<class 'pyroute2.netlink.ipdb.Interface'>, fork=False)

The class that maintains information about network setup of the host. Monitoring netlink events allows it to react immediately. It uses no polling.

create(kind, ifname, **kwarg)

Create an interface. Arguments ‘kind’ and ‘ifname’ are required.

• kind – interface type, can be of: * bridge * bond * vlan * tun * dummy
• ifname – interface name

Different interface kinds can require different arguments for creation.

FIXME: this should be documented.

register_callback(callback, mode='post')

IPDB callbacks are routines executed on a RT netlink message arrival. There are two types of callbacks: “post” and “pre” callbacks.

...

“Post” callbacks are executed after the message is processed by IPDB and all corresponding objects are created or deleted. Using ipdb reference in “post” callbacks you will access the most up-to-date state of the IP database.

“Post” callbacks are executed asynchronously in separate threads. These threads can work as long as you want them to. Callback threads are joined occasionally, so for a short time there can exist stopped threads.

...

“Pre” callbacks are synchronous routines, executed before the message gets processed by IPDB. It gives you the way to patch arriving messages, but also places a restriction: until the callback exits, the main event IPDB loop is blocked.

Normally, only “post” callbacks are required. But in some specific cases “pre” also can be useful.

...

The routine, register_callback(), takes two arguments: 1. callback function 2. mode (optional, default=”post”)

The callback should be a routine, that accepts three arguments:

cb(ipdb, msg, action)

1. ipdb is a reference to IPDB instance, that invokes the callback.
2. msg is a message arrived
3. action is just a msg[‘event’] field

E.g., to work on a new interface, you should catch action == ‘RTM_NEWLINK’ and with the interface index (arrived in msg[‘index’]) get it from IPDB:

index = msg['index']
interface = ipdb.interfaces[index]

release()

Shutdown monitoring thread and release iproute.

serve_forever()

Main monitoring cycle. It gets messages from the default iproute queue and updates objects in the database.

Note

Should not be called manually.

class pyroute2.netlink.ipdb.Interface(ipdb, mode=None)

Objects of this class represent network interface and all related objects: * addresses * (todo) neighbors * (todo) routes

Interfaces provide transactional model and can act as context managers. Any attribute change implicitly starts a transaction. The transaction can be managed with three methods: * review() – review changes * rollback() – drop all the changes * commit() – try to apply changes

If anything will go wrong during transaction commit, it will be rolled back authomatically and an exception will be raised. Failed transaction review will be attached to the exception.

add_ip(*argv, **kwarg)

Add IP address to an interface

add_port(*argv, **kwarg)

Add a slave port to a bridge or bonding

commit(tid=None, transaction=None, rollback=False)

Commit transaction. In the case of exception all changes applied during commit will be reverted.

del_ip(*argv, **kwarg)

Delete IP address from an interface

del_port(*argv, **kwarg)

Remove a slave port from a bridge or bonding

down()

Shortcut: change the interface state to ‘down’.

if_master

[property] Link to the parent interface – if it exists

load(dev)

Update the interface info from RTM_NEWLINK message.

This call always bypasses open transactions, loading changes directly into the interface data.

reload()

Reload interface information

remove()

Shortcut: marks the interface for removal

up()

Shortcut: change the interface state to ‘up’.

class pyroute2.netlink.ipdb.TrafficControl(ipdb, mode=None)

class pyroute2.netlink.ipdb.Transactional(ipdb, mode=None)

An utility class that implements common transactional logic.

begin()

Start new transaction

drop()

Drop all not applied changes and rollback transaction.

last()

Return last open transaction

pick(detached=True)

Get a snapshot of the object. Can be of two types: * detached=True – (default) “true” snapshot * detached=False – keep ip addr set updated from OS

Please note, that “updated” doesn’t mean “in sync”. The reason behind this logic is that snapshots can be used as transactions.

review()

Review last open transaction

pyroute2.netlink.ipdb.get_addr_nla(msg)

Incosistency in Linux IP addressing scheme is that IPv4 uses IFA_LOCAL to store interface’s ip address, and IPv6 uses for the same IFA_ADDRESS.

IPv4 sets IFA_ADDRESS to == IFA_LOCAL or to a tunneling endpoint.

pyroute2.netlink.ipdb.get_interface_type(name)

Utility function to get interface type