Creating and testing substrate handlers

Handlers can invoke tasks directly on the substrate or do so via Node Agent (NA) deployed in the substrate.

To test handlers, tools/cmdline project is used. It creates an instance of ORCA that is running outside a container and allows to execute handler tasks from the commandline. It is possible to do so either with or without emulation mode turned on.

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 $ORCA_SRC/handlers for various handler examples. Note that handler scripts are tied both to policies and to specific substrate, so if you plan to use your handler with your own controller policy you must create your own handler script.

NOTE: some useful notes on configuring specific handlers can be found here.

NOTE: all handler code has been consolidated under $ORCA_SRC/handlers from the various places under controllers.

Testing handlers without NA component

  1. Mysql should be running (this step does not apply to ORCA 5.0 and beyond).
  2. Build ORCA
    $ mvn clean install
    
  3. You should have tools/cmdline/config/orca.properties file present (at least in sample form)
  4. You should have already created an admin security configuration (this step does not apply to ORCA 5.0 and beyond):
    $ cd $ORCA_SRC/tools/config
    $ ant security.create.admin.config
    
  5. A new directory is created ($ORCA_SRC/tools/config/runtime) in the previous step. This directory contains keys etc. This runtime/ directory needs to be sym-linked under tools/cmdline (this step does not apply to ORCA 5.0 and beyond).
    $ cd $ORCA_ROOT/tools/cmdline
    $ ln -s $ORCA_ROOT/tools/config/runtime runtime
    
  6. Prepare handlers for execution in the commandline project. Note that because this command attempts to start ORCA instance, you must have mysql with valid schema and dataset running on the localhost. Note that ORCA deployment tree is created under tools/cmdline (including all plugins and handlers, and that is where they are executed from).
    $ cd tools/cmdline
    $ ant test.handler.prepare
    
  7. Test handler
    $ ant test.handler -Dtarget=<join|leave> <-Demulation=true|false> -Dhandler=<path to handler xml file in tools/cmdline subtree> <-DsomeProperty=any other properties>
    

NOTE: Many handlers (BEN, LEARN, NLR, Euca-net) require credentials for logging into the equipment to perform actions. You should define a properties file containing credentials (typically containing properties like 'router.username', 'router.password' etc, although the exact property names depend on the handler) and pass its name as the credentials property to the handler by adding -D<provider>.credentials=<absolute path to the properties file>. More information on names of properties that specify filenames with credentials can be found here.

Testing handlers with NA components (Obsolete)

  1. Let $ORCA_ROOT be the root of your orca source tree. Edit build.properties in the appropriate handler directory to reflect the correct IP address of the node agent and the substrate locations. For example, look at the build.properties for BEN gec7 demo handler in $ORCA_ROOT/controllers/ben/resources/handlers/controllers/ben/gec7 . master.service.location needs to contain the correct IP address for the node agent machine.
  2. Build ORCA from $ORCA_ROOT
    $ mvn install
    
  1. Make sure that the node agent (NA) is up and running. The NA actually controls the substrate. Also, the drivers need to be installed there. See documentation on how to set up node agents and install drivers on them - https://geni-orca.renci.org/trac/wiki/DeployNodeAgent . Make sure that the 'ant drivers.install' step goes smoothly. That should verify whether the security setup is correct so that you can talk to the node agent.
  2. As a part of the node agent setup process, a runtime/ directory would be created inside tools/config. This directory contains keys etc. required to talk to node agent. This runtime/ directory needs to be sym-linked under tools/cmdline.
    $ cd $ORCA_ROOT/tools/cmdline
    $ ln -s $ORCA_ROOT/tools/config/runtime runtime
    

4. Prepare handlers for execution in tools/cmdline. Note that because this command attempts to start ORCA instance, you must have mysql with valid schema and dataset running on the localhost. Note that ORCA deployment tree is created under tools/cmdline (including all plugins and handlers, and that is where they are executed from).

$ cd tools/cmdline
$ ant test.handler.prepare

This will create the handlers/ tree and packages/ tree inside tools/cmdline

  1. Disable emulation in $ORCA_ROOT/tools/cmdline/config/container.properties so that actual substrates are touched. Make emulation=false in container.properties.
  2. Go to tools/cmdline directory.
    $ cd $ORCA_ROOT/tools/cmdline
    
  3. Test handler
    $ ant test.handler -Dtarget=<join|leave> -Demulation=false -Dhandler=<path to handler xml file in tools/cmdline subtree> -Dactor.id=admin -Dorca.home=. -Dsecure.communication=true <-DsomeProperty=any other optional properties>
    

Example command to test the ben gec7 demo handler :

$ ant test.handler -Dhandler=handlers/controllers/ben/gec7/ben.xml -Dtarget=join -Demulation=false -Dactor.id=admin -Dorca.home=. -Dsecure.communication=true

Example command to test the NLR handler :

$ ant test.handler -Dhandler=handlers/network/nlr/handler.xml -Dtarget=join -Demulation=false -Dactor.id=admin -Dorca.home=. -Dsecure.communication=true -Dnlr.site.properties=/home/orca/orca-2.0/tools/cmdline/config/nlr.properties

Example command to test euca handler :

$ ant test.handler -Dhandler=handlers/ec2/handler.xml -Dtarget=join -Demulation=false -Dorca.home=/home/orca/orca-2.0/tools/cmdline -Dunit.data.subnet=255.255.0.0 -Dunit.manage.ip=192.168.206.3 -Dunit.manage.subnet=255.255.255.0 -Dunit.manage.gateway=192.168.206.1 -DleaseLength=600 -Dunit.vlan.tag=12