Usher Plugins

Plugins allow an administrator to extend the functionality of Usher to take arbitrary action for nearly any event in the system. Plugins can interface with broader site infrastructure (e.g. authentication, storage, and host address and naming services) or express site-specific policies for the placement, scheduling, and use of VMs. As a result, Usher plugins allow administrators to decide how to configure their virtual machine environments and determine the appropriate management policies.

Available Plugins

Below is a list of currently available Usher plugins

• Usher Keyword Argument Filter (kwargfil) - a plugin for filtering keyword arguments for plugins and VM operations
• Usher DNS (udns) - a plugin for adding DNS A records to your nameserver for newly created VMs
• Usher IP Manager (uipmgr) - a plugin for managing IP addresses. Supports named ranges and access control. (beyond DHCP)
• Usher LDAP (uldap) - a plugin providing LDAP authentication for Usher and Usher users' clusters

Plugin Installation

Plugins can be placed in the controller's <path_to_usher_installation>/plugins directory, or any other directories listed in the plugin_dirs variable of the controller's configuration file. Any plugins found in these directories are automatically sourced at controller startup and added to a list of available plugins.

Plugin Registration

Plugins are registered to receive notification of events in the Usher system. Administrators register plugins for events using the controller's configuration file. Plugins found there are automatically registered for the events specified during controller startup. A plugin's documentation typically lists the events for which it was designed to be registered. A complete list of Usher events appears on the Usher Development page.

Below is a snippet of a controller's configuration file, providing an example of registering the 'sample' plugin for the 'request' and 'ctrl_start' events. Here, I assume you've read and understand the information in the Configuration Files section of the main Usher documentation.

# <snip>
# Don't forget to uncomment the following line
[plugins]
#########################################
# Begin sample plugin example
#########################################
#
# Here is an example of using the 'sample' plugin.  It's name is the title of
# a sub-section of 'plugins'.  Subsections are indicated by repeating square
# brackets in the section; nest levels by using more brackets.
# Use the 'sample' plugin
[[sample]]

sample_val = 909

[[[__allsecs__]]]
sample_option = ham
sample_value = ${sample_val}

# register it for the 'request' event 
[[[request]]]

order = 3.14159265359 
sample_string = Yes, I like green eggs and ham
# Here, sample_option will be 'ham' because it's defined in the __allsecs__
# section and not here.

# register it for the 'ctrl_start' event
[[[ctrl_start#1]]]

order = 0
sample_string = I am the first plugin for the ctrl_start event!
# Here, sample_option will be 'green' because it's defined here (i.e. it
# overrides sample_option from __allsecs__
sample_option = green

# register it a second time for the 'ctrl_start' event 
[[[ctrl_start#2]]]

order = 99
sample_string = I am the last plugin for the ctrl_start event!
sample_option = green

#########################################
# End sample plugin example
#########################################
# </snip>

For each plugin to be registered, you must create a subsection of the [plugin] section with the name of the plugin. As mentioned in the config file, subsections are indicated by repeating square brackets in the section. So, [[sample]] above is a subsection of [plugins] and [[[request]]] is a subsection of [[sample]].

Note the use of the [[[__allsecs__]]] subsubsection. Options here are added to all events for which our sample plugin is registered. Using this, there' often no need to even have additional options specified in event subsubsections.

Plugins can be registered for multiple events, or even multiple times for the same event. For each event for which the plugin is to be registered, you must create a subsection of the plugin's section with the name of the event. For plugins registered multiple times for the same event, place a hash '#' followed by a unique string after the event name to form the section title. For example, [request!#1] and [request!#2] could be used as section titles to register a plugin twice for the request event. Above, we registered the sample plugin once for the 'request' event and twice for the ctrl_start event.

Notice the order variable in the configuration file. By default, plugins for each event are simply called in the order in which they are registered. However, a plugin's configuration can optionally specify order which governs the order in which plugins are called on the event's callback list. This is a value (float) between 0 and 99 with a default of 50. Plugins with a higher order are called later.

Additional information on registering plugins can be found in the ctrl.config.orig file bundled with the distribution.

Plugin packages typically include a README file with a CONFIGURATION section which documents valid configuration options for the plugin. This file often contains a sample subsection which can be cut and pasted into the [plugins] section of the controller's configuration file and edited for your installation.

Writing Plugins

See the Writing Plugins section of the Development page.

---

Last Updated: 2007-10-10 by mmcnett
Report problems to: Marvin McNett