NDB objects

Structure and API

The NDB objects are dictionary-like structures that represent network objects – interfaces, routes, addresses etc. In addition to the usual dictionary API they have some NDB-specific methods, see the RTNL_Object class description below.

The dictionary fields represent RTNL messages fields and NLA names, and the objects are used as argument dictionaries to normal IPRoute methods like link() or route(). Thus everything described for the IPRoute methods is valid here as well.

See also: IPRoute module

E.g.:

# create a vlan interface with IPRoute
with IPRoute() as ipr:
    ipr.link("add",
             ifname="vlan1108",
             kind="vlan",
             link=ipr.link_lookup(ifname="eth0"),
             vlan_id=1108)

# same with NDB:
with NDB(log="stderr") as ndb:
    (ndb
     .interfaces
     .add(ifname="vlan1108",
          kind="vlan",
          link="eth0",
          vlan_id=1108)
     .commit())

Slightly simplifying, if a network object doesn’t exist, NDB will run an RTNL method with “add” argument, if exists – “set”, and to remove an object NDB will call the method with “del” argument.

Accessing objects

NDB objects are grouped into “views”:

  • interfaces

  • addresses

  • routes

  • neighbours

  • rules

  • netns

Views are dictionary-like objects that accept strings or dict selectors:

# access eth0
ndb.interfaces["eth0"]

# access eth0 in the netns test01
ndb.sources.add(netns="test01")
ndb.interfaces[{"target": "test01", "ifname": "eth0"}]

# access a route to 10.4.0.0/24
ndb.routes["10.4.0.0/24"]

# same with a dict selector
ndb.routes[{"dst": "10.4.0.0", "dst_len": 24}]

Objects cache

NDB create objects on demand, it doesn’t create thousands of route objects for thousands of routes by default. The object is being created only when accessed for the first time, and stays in the cache as long as it has any not committed changes. To inspect cached objects, use views’ .cache:

>>> ndb.interfaces.cache.keys()
[(('target', u'localhost'), ('tflags', 0), ('index', 1)),  # lo
 (('target', u'localhost'), ('tflags', 0), ('index', 5))]  # eth3

There is no asynchronous cache invalidation, the cache is being cleaned up every time when an object is accessed.

class pyroute2.ndb.objects.RTNL_Object(view, key, iclass, ctxid=None, match_src=None, match_pairs=None)

Base RTNL object class.

property table

The main reference table for the object. The SQL schema of the table is used to build the key and to verify the fields.

property etable

The table where the object actually fetches the data from. It is not always equal self.table, e.g. snapshot objects fetch the data from snapshot tables.

Read-only property.

property key

The key of the object, used to fetch it from the DB.

show(**kwarg)

Return the object in a specified format. The format may be specified with the keyword argument format or in the ndb.config[‘show_format’].

TODO: document different formats

set(key, value)

Set a field specified by key to value, and return self. The method is useful to write call chains like that:

(ndb
 .interfaces["eth0"]
 .set('mtu', 1200)
 .set('state', 'up')
 .set('address', '00:11:22:33:44:55')
 .commit())
snapshot(ctxid=None)

Create and return a snapshot of the object. The method creates corresponding SQL tables for the object itself and for detected dependencies.

The snapshot tables will be removed as soon as the snapshot gets collected by the GC.

complete_key(key)

Try to complete the object key based on the provided fields. E.g.:

>>> ndb.interfaces['eth0'].complete_key({"ifname": "eth0"})
{'ifname': 'eth0',
 'index': 2,
 'target': u'localhost',
 'tflags': 0}

It is an internal method and is not supposed to be used externally.

rollback(snapshot=None)

Try to rollback the object state using the snapshot provided as an argument or using self.last_save.

commit()

Try to commit the pending changes. If the commit fails, automatically revert the state.

apply(rollback=False)

Create a snapshot and apply pending changes. Do not revert the changes in the case of an exception.

load_value(key, value)

Load a value and clean up the self.changed set if the loaded value matches the expectation.

load_sql(table=None, ctxid=None, set_state=True)

Load the data from the database.

load_rtnlmsg(target, event)

Check if the RTNL event matches the object and load the data from the database if it does.