Creating drivers with Node Agent component


Drivers with Node Agent components require two parts - the part that is executed on the substrate by the Node Agent and the part residing in site authority that instructs the Node Agent to perform actions on the substrate. The part residing with the site authority is generally referred to as 'driver client'.

Fully testing drivers with node agent components requires setting up a Node Agent and creating a security association with it, described in Handler-Testing.

You can use the sample driver template to get started on writing a new Orca driver. The driver template consists of 3 projects:

  • core
    • specifies the API for all drivers of the given family, e.g., drivers for creating virtual machines
    • provides ANT tasks that invoke the driver API
  • specific device driver implementation
    • contains the implementation of a specific driver from the device family, e.g, a driver that creates Xen virtual machines
  • tests
    • contains tests for the driver and its ant taske

Setting up directory structure and generating driver GUID

To use the template to generate a working skeleton for your driver do the following:

1. Make a work directory

mkdir scratch

2. Download the template

cd scratch
svn export template
mv template/ .

3. Edit the conversion script.

The following variables must be changed:

FAMILY_NAME='Orca Test Device'
INSTANCE_NAME='Orca Test Device Driver'
TESTS_NAME='Orca Test Device Driver Tests'
  • DEST - top level directory for your driver, e.g., mydriver
  • DEVICE_FAMILY - package name for the driver family. The full package name will become: orca.drivers.${DEVICE_FAMILY}, e.g, mydriver
  • DEVICE_FAMILY_PREFIX - prefix to use for class file names for the driver family, e.g., MyDriver?
  • VERSION - you can leave it as it is
  • FAMILY_NAME - name you want to use in the pom for the driver family
  • DEVICE_INSTANCE - package name for the specific device. The full package name will become: orca.drivers.${DEVICE_FAMILY}.${DEVICE_INSTANCE}, e.g, mydevice
  • DEVICE_INSTANCE_PREFIX - prefix to use for class file names for the specific device, e.g., MyDevice?
  • DEVICE_INSTANCE_GUID - guid for your device driver. NOTE: you must generate a new one.
  • INSTANCE_NAME - name you want to use in the pom for the specific device
  • TESTS_NAME - name you want to use in the pom for the device family tests

4. After you modify the template settings, invoke the script


5. The script will generate a new directory ($DEST). You can compile the generate code by doing:

cd ${DEST}
mvn install

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.
  2. 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. See handler testing for more information.

Running unit tests on drivers

Each driver should contain a number of unit tests. Please familiarize yourself with JUnit and create a number of tests for your new driver.

To run unit tests on the driver you need to install it on in a node-agent service. Orca provides two helper projects to simplify this process:

  • orca/tools/config/trunk - contains tools to install and configure a node agent service
  • orca/tools/drivers/trunk - contains tools to simplify the installation of drivers

You will need to check out orca/tools/config/trunk and follow the instructions listed on this page. Once you have installed your node agent, you will need to check out orca/tools/drivers/trunk and add a link to the runtime directory from the config project, e.g.:

ln -s -f ORCA_TOOLS_CONFIG_DIR/runtime

Finally, you will need to add a link to the driver tools project in the top-level directory of your newly generated driver:

cd ${DEST}

The template assumes that your node agent is running on the localhost on port 6. If this is not the case with your setup you will need to do the following:


Edit and specify the location and port of your node agent service. Place a copy of the resulting file in ${DEST}/tests/ant

Once you have successfully run mvn install in ${DEST}. You can install the driver by:

ant install

To run the unit tests for the driver:

cd tests
ant copy.local   (do this to make sure log4j will log to a file)
ant tests.device

To test the ant tasks:

cd tests
ant -f test.xml clean
ant -f test.xml greet