[[TracGuideToc]] [[PageOutline(2-5,Page Contents)]] = 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 * [wiki:UsherPlugins/Kwargfil Usher Keyword Argument Filter (kwargfil)] - a plugin for filtering keyword arguments for plugins and VM operations * [wiki:UsherPlugins/UDNS Usher DNS (udns)] - a plugin for adding DNS A records to your nameserver for newly created VMs * [wiki:UsherPlugins/UIPMgr Usher IP Manager (uipmgr)] - a plugin for managing IP addresses. Supports named ranges and access control. (beyond DHCP) * [wiki:UsherPlugins/ULDAP Usher LDAP (uldap)] - a plugin providing LDAP authentication for Usher and Usher users' clusters == Plugin Installation == Plugins can be placed in the controller's `/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 [wiki:UsherDevelopment 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 [http://usher.ucsd.edu/trac/wiki/UsherDocumentation#ConfigurationFiles Configuration Files] section of the main Usher documentation. {{{ # # 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 ######################################### # }}} 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 [wiki:UsherDevelopment#WritingPlugins Writing Plugins] section of the [wiki:UsherDevelopment Development] page. ---- Last Updated: [[LastModified]][[BR]] Report problems to: [mailto:mmcnett@cs.ucsd.edu?subject=Usher_Issue Marvin McNett]