Configuring Plugins

When a service station starts up, it reads three configuration files to determine which plugins should be started initially. The files are located in the config directory. They are used to store the default configuration, site-specific configuration, and host-specific configuration. Specifically, the files loaded are:

config/plugins: Default configuration. There should be no reason to change this file.
config/plugins.local: Site-specific configuration. This file can be used to add or change information needed for all or most KSSs running on a single local area network. The expectation is that many hosts will share this file.
config/plugins.<KERNEL>: Host-specific configuration, where <KERNEL>is the name of the KOS kernel of the machine running the KSS; by default this is the short host name of the host. This should be used to configure aspects of the KSS which depend on the individual host running the KSS.

Plugins Configuration File Format

Each of the plugin configuration files loaded by the KSS has the same format. Each file is divided into sections, which have specified by lines that look a lot like RFC 822 headers. The RFC 822 quoting rules for the header values do not apply, but continuation lines are supported. Lines which start with a hash character "#" are comments and are ignored. Blank lines are also ignored. Section and value names are case-sensitive.

Sections are marked by lines containing a label in brackets; for example, the DEFAULTS section starts with the line:

[DEFAULTS]

Lines following the mark contain named values which are set for that section, until a new section is started or the end of the file.

Each section corresponds to a plugin. The DEFAULTS section provides default values for all sections.

Each section may contain variable definitions. See below for a list of variable with defined meanings. Some variables represent path or file names. Values may refer to other variables by name using the Python formatting operation `string % dictionary'. For example, to refer to the `name' value in the specification for `args', refer to it using the formatting syntax:

args:    -n %(name)s more args...

See ``Fancier Output Formatting'' in the Python Tutorial for more information on the formatting operator.

Name Resolution

When the plugin starter needs to find the value of a particular variable for a particular plugin, there are six places it can look. In order, they are:

The plugin-specific section of plugins.<KERNEL>
The plugin-specific section of plugins.local
The plugin-specific section of plugins
The DEFAULTS section of plugins.<KERNEL>
The DEFAULTS section of plugins.local
The DEFAULTS section of plugins

Though only a small number of names are used to launch plugins when a KSS starts, those values may refer to values not among those used directly by the KSS. This allows additional values to be defined for use & override in the site- and host-specific files.

Defined Names

The following names are defined by the system and should not be overridden.

name: The name of the section for which a name is being resolved.
kosroot: The value of $KOSROOT (the location of the KOE source tree).
root: The value of %(kosroot)s/plugins. This is the directory below which plugin implementations are stored.
kosname: The name of the KSS running the plugin. The plugins distributed with the KOE all accept the option -n which is used to specify the KSS name.
run-at-boot: A boolean indicator which specifies whether the plugin should be started when the KSS starts. The value must be an integer. If the value is not 0, the plugin specified by that section is started when the KSS is started.
executor: The name of the program which will execute the plugin script. For plugins written in Python, this is the name and path to the Python interpreter. If the name specified is not on the $PATH of the KSS kernel process, then it needs to be an absolute path and filename for the interpreter.
dir: The name of the directory where the plugin implementation is located. This will be the current directory for the plugin when it is started. It should be an absolute path.
file: The name of the script file to execute. The name is passed as the initial paramter to executor.
args: Command line parameters passed to the script named by file. Use simple quoting of individual parameters using single- and double-quote characters to include space, tab, and quote characters in parameters.