RTNL objects

General structure

The NDB objects are dictionary-like structures that represent network objects -- interfaces, routes, addresses etc. They support the common dict API, like item getting, setting, iteration through key and values. In addition to that, NDB object add specific calls, see the API section below.

Most of the NDB object types store all attributes in a flat one level dictionary. Some, like multihop routes, implement nested structures. In addition to that, some objects like Interface provide views on the DB that list only related objects -- addresses, routes and neighbours. More on these topic see in the corresponding sections.

NDB objects and RTNL API

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

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

# same with NDB:
with NDB(log="stderr") as ndb:
    vlan = ndb.interfaces.create(
        ifname="vlan1108",
        kind="vlan",
        link="eth0",
        vlan_id=1108,
    )
    vlan.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.

API

class pyroute2.ndb.objects.RTNL_Object

The common base class for NDB objects -- interfaces, routes, rules addresses etc. Implements common logic for all the classes, like item setting, commit/rollback, RTNL event filters, loading values from the DB backend etc.

property table

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

Read-write property.

property etable

Effective 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

Key of the object, used to build SQL requests to fetch the data from the DB.

Read-write property.

apply(*argv, **kwarg)

Apply the pending changes. If an exception is raised during apply(), no rollback() is called. No automatic snapshots are madre.

In order to properly revert the changes, you have to run:

obj.save_context()
try:
    obj.apply()
except Exception:
    obj.rollback()
commit(*argv, **kwarg)

Commit the pending changes. If an exception is raised during commit(), automatically rollback() to the latest saved snapshot.

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.

create(**spec)

Create an RTNL object of the same type, and add it to the commit chain. The spec format depends on the object.

The method allows to chain creation of multiple objects sharing the same context.

(
    ndb.interfaces['eth0']                     # 1.
    .set(state="up")                           # 2.
    .ipaddr                                    # 3.
    .create(address='10.0.0.1', prefixlen=24)  # 4. <- create()
    .create(address='10.0.0.2', prefixlen=24)  # 5. <- create()
    .commit()                                  # 6.
)

Here:

  1. returns an interface object eth0

  2. sets state="up" and returns the object itself

  3. returns an address view, that uses eth0 as the context

  4. creates an IP address, the interface lookup is done via context

  5. creates another IP address -- same type, same context

  6. commits the changes in the order: (interface state="up"; address 10.0.0.1/24; address 10.0.0.2/24)

exists(key)

Check if the object exists in the DB

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

Load the data from the database.

load_value(key, value)

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

set(key, value)

Call formats:

  • set(key, value)

  • set(key=value)

  • set(key1=value1, key2=value2)

with ndb.interfaces["eth0"] as eth0:
    eth0.set(
        mtu=1200,
        state='up',
        address='00:11:22:33:44:55',
    )
show(fmt)

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

snapshot(*argv, **kwarg)

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.

rollback(*argv, **kwarg)

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