Version 22 (modified by ibaldin, 9 years ago)


Network driver development HOWTO


As of Bella 2.1, network substrate drivers have been reorganized from a number of separate projects (one project per device family) into a single simple project that covers all network elements. Node Agent code has been removed, such that new network drivers and handlers no longer require the use of Node Agent and are invoked directly by the Site Authority.

The drivers are located under $ORCA_SRC/handlers/network and are organized into a number of packages: - contains interfaces and classes common to multiple network element types (routers, DWDM platforms etc) - implementation of the Polatis optical switch driver - implementation of the Infinera DTN driver - implementations for routers/switches (currently contains Cisco6509 and Juniper EX3200) - common interfaces and classes for handler tasks that invoke driver actions. Also tasks for DTN and Polatis. - handler tasks for Cisco 6509 - handler tasks for Juniper EX3200

These packages are spread over multiple directories under $ORCA_SRC/handlers/network/src/main/java and $ORCA_SRC/handlers/network/src/main/resources. The resources/ subtree contains XML and TXT scripts used by different device drivers that encode the commands that need to be sent.

The attached figure shows the UML diagram of the classes and interfaces that implement router drivers (not DTN or OS).

Implementing a new router driver


A basic router driver must either implement the basic IRouterDevice interface (if the device supports basic VLAN operations) or the IMappingRouterDevice (if the device supports VLAN tag remapping):


public interface IRouterDevice extends INetworkDevice {
    // create VLAN with QoS
    public void createVLAN(String vlanTag, String qos) throws CommandException;

    // delete VLAN
    public void deleteVLAN(String vlanTag) throws CommandException;
    // add trunk ports to a VLAN
    public void addTrunkPortsToVLAN(String vlanTag, String ports) throws CommandException;
    // add access ports to a VLAN
    public void addAccessPortsToVLAN(String vlanTag, String ports) throws CommandException;

    // remove trunk ports from a VLAN
    public void removeTrunkPortsFromVLAN(String vlanTag, String ports) throws CommandException;
    // remove access ports from a VLAN
    public void removeAccessPortsFromVLAN(String vlanTag, String ports) throws CommandException;


public interface IMappingRouterDevice extends IRouterDevice {
    public void mapVLANs(String sourceTag, String destinationTag, String port) throws CommandException;

    public void unmapVLANs(String sourceTag, String destinationTag, String port) throws CommandException; 


The parameters are passed in as strings and their interpretation is left to the driver implementation. For example, the port ranges are passed in to the Cisco devices in IOS CLI syntax as e.g.

gigabitethernet 1/25-27, gigabitethernet 1/12-14

On the other hand, Juniper device takes port ranges as

ge-0/0/[1-5], xe-0/0/1


Once the interface is implemented, the next step is to implement a set of tasks (a class per task) corresponding to driver actions. A common way to implement them is to define a device-specific base task that is a child of NetworkBaseTask and subclass further tasks from it (see the or as an example).

Juniper EX3200 driver UML


You can compile the network drivers project standalone by issuing

mvn install 

in the $ORCA_SRC/handlers/network directory.

NOTE: you still need to run 'mvn install' on the entire trunk at least once prior to doing this.


Once the tasks are implemented, you must create a mapping between Java properties used by Ant handlers and tasks and declare the driver as available. Targets must be created in the test handler to facilitate testing. This is done by editing files:

$ORCA_SRC/handlers/network/src/main/resources/orca/handlers/network/ - driver declaration

$ORCA_SRC/handlers/network/src/main/resources/orca/handlers/network/network.tasks - Java properties to task classname mapping

$ORCA_SRC/handlers/network/test.xml - test handler where targets need to be added for each declared task and properties can be passed in as parameters to tasks

Unit tests

Developers are strongly encouraged to implement unit tests under handlers/network/src/test/java in the package See existing tests for inspiration.

Task tests

Once unit tests work and tasks and associated meta-information is defined, you can test your driver by invoking the test handler. You should update handlers/network/ant/ file to add necessary property definitions (like vlan tags, device IP addresses or DNS names although they can be passed as command-line parameters to ant as well. You should create a handlers/network/ant/ file where you can re-declare login properties (usernames and passwords). There properties are declared in handlers/network/ant/ file, however they have empty values. This is done because ant/ file is under Subversion control and you should avoid checking in live passwords and logins (and other credentials) into subversion. Any properties declared in ant/ take precedence of properties declared in ant/, however the ant/ file is NOT and should NEVER be checked into subversion.

  ant -f test.xml -D<property name>=<property value> <target name>