Vnx-plugins

VNX Extension Plugins

VNX Extension Plugins provide a way to develop new functionality to interact with virtual machines by copying files and executing commands inside them.

Basically, VNX provides three main actions when dealing with a virtual scenario: creating it, when called with "-t|--create" mode; executing commands, when called with "-x|--exe" mode; and releasing it, when called with "-d|shutdown" mode). VNX plugins architecture provides a way to define new actions to take place on virtual machines whenever VNX is executed in one of these modes.

A VNX plugin exports four basic functions:

• initPlugin, which is called whenever vnx is executed using create, execute or shutdown modes and it is used by the plugin to do initialization tasks.
• getFiles, which is called for each virtual machine in the scenario to get the files that have to be copied to that virtual machine. The main parameter passed to this function is the command sequence identifier, which tells the plugin the mode VNX has been invoked, and, in the case of execute mode, the sequence identifier the user has selected.
• getCommands, which is called for each virtual machine in the scenario to get the commands that have to be executed on that virtual machine. As in getFiles, the sequence identifier is passed to allow the plugin know the mode.
• finalizePlugin, which is called just before exiting VNX and it is used to do finalization plugin tasks.

To include a plugin in a virtual scenario, you just have to include the <extension> tag in the global section, just after the vm_defaults:

<global>
   ...
   <vm_defaults>
     ...
   </vm_defaults>
   <extension plugin="plugin-name"/>
</global>

Among other uses, VNX plugins can be utilized to simplify the user the configuration of services running over virtual machines (see, for example, the OSPF and DHCP plugins). Instead of requiring the user to know all the internal details of the configuration files and commands to manage a service, these plugins provide the user with a simplified configuration language based on XML.

This language allows to specify the service configuration for each virtual machine scenario. Although the language can be freely designed by plugin developers, typically it has the following format:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dhcp_conf SYSTEM "/usr/share/xml/vnx/plugin-name.dtd">

<plugin-name_conf>

  <vm name="r1">
     <service_tag1/>
     <service_tag2>
        <service_subtag1>value1</service_subtag1>
        <service_subtag2>value2</service_subtag2>
     </service_tag2>	
  </vm>

  <vm name="r2">
     <service_tag1/>
     <service_tag2>
        <service_subtag1>value1</service_subtag1>
        <service_subtag2>value2</service_subtag2>
     </service_tag2>	
  </vm>

</plugin-name_conf>

The plugin code is in charge of processing this simplified Plugin Configuration File (PCF) and translate it into the files and commands needed to configure and manage the services.

One of tasks the plugin has to do is to validate the PCF. This can be done in several ways, for example, using a DTD or an XML schema (XSD) which has to be specified by the plugin developer.

To include a PCF in a virtual scenario the "conf" attribute of <extension> tag has to be used. For example:

<extension plugin="ospf" conf="example_ospf-plugin-conf.xml" />

includes the ospf pluginn in an scenario and passes it the example_ospf-plugin-conf.xml file as the configuration file.

VNX API version 1.1

The plugins API version 1.1 includes the following methods:

initPlugin

• Parameters:
• mode: the mode in which VNX is executed. Possible values: create, execute, shutdown.
• pcf: the plugin configuration file (pfc) name (empty if configuration file has not been defined in the scenario).
• Returns:
• error: an empty string if successful initialization, or a string describing the error in other cases.
• Description: initPlugin function is called at the very beginning of VNX code for every plugin declared with an <extension> tag. It is aimed to do plugin specific initialization tasks, for example, the validation of the plugin configuration file (PCF) if it is used. If an error is returned, VNX dies showing the plugin error description returned by this function.

getFiles

• Parameters:
• vm_name: the name of the virtual machine for which getFiles is being called
• seq: the command sequence identifier. The value passed is: on_boot, when VNX invoked in create mode; on_shutdown when shutdown mode; and the value defined in "-x" option when invoked in execute mode.
• files_dir: the directory where the files to be copied to the virtual machine have to be located.
• Returns:
• files: an associative array (hash) containing the files to be copied to the virtual machine, the location where they have to be copied and (only for UNIX like operating systems) the owner, group and permissions.
• Description: getFiles function is called once for each virtual machine defined in the scenario when VNX is executed without using "-M" option, or for each virtual machine specified in "-M" parameter when VNX is invoked with this option. The plugin has to return to VNX the files that wants to be copied to that virtual machine for the command sequence identifier passed. For example:

my %files;
...
$files{"/etc/quagga/ospfd.conf,quagga,quagga,644"} = "ospfd.conf;
return %files;

returns the ospf.conf files (previously copied to $files_dir location) and instructs VNX to copy it to /etc/quagga directory in virtual machine with owner quagga.quagga and permissions 644. Remember that the destination value (the key of the hash) has to be an absolute filename or directory in the virtual machine and the source has to be a relative filename or directory to the $files_dir passed to the function. In case of directories, they have to be ended by a "/".

In case of error, the error description is returned in "ERROR" key. For example:

$files{"ERROR"} = "Unknown type value $type in vm $vm\n";

getCommands

• Parameters:
• vm_name: the name of the virtual machine for which getCommands is being called.
• seq: the command sequence identifier. The value passed is: 'on_boot', when VNX invoked in create mode; 'on_shutdown' when shutdown mode; and the value defined in "-x" option when invoked in execute mode.
• Returns:
• commands: an array containing the commands to be executed on the virtual machine. The first position of the array has to be empty if no error occurs, or contain a string describing the error in other cases.
• Description: getCommands function is called once for each virtual machine in the scenario when VNX is executed without using "-M" option, or for each virtual machine specified in "-M" parameter when VNX is invoked with this option. The plugin has to provide VNX the list of commands that have to be executed on that virtual machine for the command sequence identifier passed. For example:

my @commands;

unshift( @commands, "" );
push( @commands, "/etc/init.d/dhcp3-server start" );

tells VNX to execute '/etc/init.d/dhcp3-server start' command inside the virtual machine.

getSeqDescriptions

• Parameters:
• vm_name: the name of the virtual machine (optional).
• seq: the command sequence identifier (optional).
• Returns: an associative array (hash) whose keys are command sequences and the associated values the description of the actions made for that sequence. The value for special key '_VMLIST' is a comma separated list of the virtual machine names involved in a command sequence when 'seq' parameter is used.
• seq_desc: .
• Description: getSeqDescriptions returns a description of the command sequences offered by the plugin.

finalizePlugin

• Parameters:
• none
• Returns:
• error: an empty string if successful initialization, or a string describing the error
• Description: finalizePlugin function is called before sending the shutdown signal to the virtual machines. Note: finalizePlugin is not called when "-P|destroy" option is used, as that mode deletes any changes made to the virtual machines.

Creating a VNX Plugin

Recommended steps to create a VNX plugin:

• Create a virtual scenario and experiment over it manually with the application or services you want to control until you have a clear view of the files you need to copy and the commands you need to execute on each virtual machine.

• Specify that file copies and commands using <filetree> and <exec> tags.

• Design the language to specify the PCF. We recommend to use XML and the format used in plugin examples, but you can use whatever you want (for example, a not XML based language). In case of using XML, it is recommended to describe the language using a DTD or XML schema (XSD) and validate the PCFs in initPlugin function.

• Create the plugin code starting from the dummy plugin or one of the examples provided.