Version 3 (modified by ibaldin, 9 years ago)

--

Creating a simple driver without Node Agent

Many types of substrate allow for RPC-like access (examples are XML-RPC, CGI, proprietary RPC protocols). These types of substrate can use a simplified version of the driver that executes tasks on the substrate directly without the need for Node Agent and associated security setup. This document briefly describes how to do it. You can look at drivers/network/NLRSherpa driver as an example. This document is geared towards creating networking drivers. To use it for other types of drivers substitute

  • Package paths orca.drivers.network for orca.drivers or orca.drivers.<other>
  • Directory paths orca/drivers/network for orca/drivers or orca/drivers/<other>

Creating directory structure

  1. Locate appropriate place for your driver (e.g. all network substrate drivers go under $ORCA_ROOT/drivers/network)
    $ cd drivers/network
    
  2. Execute the following maven command that will create the directory structure. The following parameters must be specified:
    • <Device Driver name> name of the device driver (e.g. Cisco65xx or Arista or NEC)
      $ mvn archetype:create -DgroupId=orca.drivers.network -DartifactId=<Device Driver Name>
      
  3. This will automatically update the pom file of the parent directory (drivers/ or drivers/network)
  4. Note that ORCA frequently uses additional directories (ant/ for storing additional ant scripts, resources/ for storing properties)
    $ cd <Device Driver Name>
    $ mkdir -p ant src/main/resources/orca/drivers/network/<Device Driver Name> 
    
  5. If you open your IDE (Beans or Eclipse) you should see the new module in the directory structure (in Eclipse it sometimes requires doubleclicking the pom.xml file in the parent directory).
  6. You should add to the build path
    • drivers/network/<Device Driver name>/src/main/java
    • drivers/network/<Device Driver name>/src/main/resources
    • drivers/network/<Device Driver name>/src/test/java
  7. You will need at least two packages created in the source (src/main/java) directory (e.g. using Eclipse):
    • orca.drivers.network.<Device Driver name>
    • orca.drivers.network.<Device Driver name>.tasks
  8. To facilitate unit tests you should also create the orca.drivers.network.<Device Driver name> package in src/test/java folder

Developing the driver

Now you are ready to develop the driver. This involves identifying 'tasks'- operations on the substrate it will perform. For a networking device these may be e.g. 'Enable vlan tag T on a set of ports S' or 'Translate vlan tag T1 to T2 on port P' (each operation should have a concomitant 'undo/disable/unmap' operation). These operations must be coded as individual tasks, children of AntBaseTask? class (see NLRSherpa example).

Helper classes should go into orca.drivers.network.<Device Driver name> package, while specific tasks will go into orca.drivers.network.<Device Driver name>.tasks package.

Testing the driver

Once you have coded all the tasks, it is time to test them. Testing drivers is a multi-layered process that includes:

  1. Running unit-tests built into the code. This is strongly recommended. Please familiarize yourself with JUnit framework. These tests are run as part of Maven build process. Look at driver tests in other drivers for ideas.
  2. Running simple ant-based tests. Create drivers/network/<Device Driver name>/test.xml ant script to invoke individual tasks. Look at similar scripts in other drivers for ideas. They can be invoked as simply as
    $ ant -f test.xml -Dproperty1=property1Value -Dproperty2=property2Value targetName
    
  3. Creating and invoking a handler script to invoke the tasks and pass appropriate parameters to them. This begins the process of integration of the driver with policies and is described in the next section

Creating a handler script

A handler script is executed by site authority or service manager and presents a simple abstraction of performing parameterized actions for joining a slice, leaving a slice and modifying a slice. In its current implementation, handlers are ant scripts with the three targets: join, leave and modify that pass Java properties to driver tasks.

There are a number of examples of handler scripts in the codebase. You can look at