Page Comparison

The sipXsupervisor manages all other sipXecs processes.  To give the supervisor the information about a process that it needs to manage the process correctly, the installer for the process must install a process definition into the directory {{$\{prefix\}/share/sipXecs/process.d}}, whose file name is {{_name_-process.xml}} (where _name_ is unique to the process).

The XML schema for the process definition is at {{[sipXsupervisor/meta/sipXecs-process.xsd.in|http://sipxecs.sipfoundry.org/rep/sipXecs/main/sipXsupervisor/meta/sipXecs-process.xsd.in]}}. This page explains the elements and attributes defined by that schema, and to use them to ensure proper management of any sipXecs component.

The top level element of the process definition document is *{{sipXecs-process}}*.  The contents of {{sipXecs-process}} are:

Exactly one of each of:
* *{{name}}*: the name of the process - this is used to identify this process in control operations and alarms.
* *{{version}}*: the version number of the process (see [#Versions])
* *{{commands}}*: commands used to control the process (see [#Commands])
* *{{status}}*: status files for the process (see [#Status])
and optionally one:
* *{{resources}}*: list of resources used by the process (see [#Resources])

{note}
The process definition file is read-only - it is only read by the sipXsupervisor, and is never modified by anything (except when being replaced by the new version when the component is upgraded).
{note}

h1. Process Management State Machine

In order to understand how the various elements of the process definition are used, it helps to understand the sipXsupervisor process management state machine (this diagram is slightly simplified from the actual state machine for clarity). {color:darkgreen}The dark green states and paths are the normal successful sequence of states and events{color}. The Enabled and Disabled states are the permanent states of a process, established by start and stop commands from sipXconfig; the start and stop commands are persistent - each sets the desired state of the process, and that desired state is saved by the supervisor (there is also a restart command which causes the process to stop and restart without ever changing the persistent desired state).

{graphviz}
digraph {

node [shape=oval];

subgraph cluster_states {
style=invis;
node  [shape=rectangle];

ShutDown [label="Enabled / Shut Down"];
Disabled;
}

subgraph {
node [shape=oval, color=darkgreen, fontcolor=darkgreen];
edge [color=darkgreen, fontcolor=darkgreen];


Disabled -> ConfigurationMismatch [label="start command"];

ConfigurationMismatch [label="Compare Process and Config Versions", URL="#SupervisorProcessDefinitions-Versions"];
ResourceRequired      [label="Check Resources"];
Testing               [label="Run Configuration Test"];
Starting;
Running;
ShuttingDown          [label="Shutting Down"];

ShutDown -> ConfigurationMismatch [label="system start"];
ConfigurationMismatch -> ResourceRequired [label="versions matched"];
ResourceRequired -> Testing  [label="resources ready"];
Testing -> Starting          [label="passed"];
Starting -> Running          [label="started"];

Running -> ShuttingDown      [label="shutdown command"];
ShuttingDown -> ShutDown     [label="stopped"];

}

subgraph errors {

node [color=red, fontcolor=red];
edge [color=red, fontcolor=red];

Failed;

ConfigTestFailed      [label="Invalid Configuration"];
Testing -> ConfigTestFailed  [label="failed"];
Starting -> Failed           [label="failed"];
Running -> Failed            [label="failed"];
}

ConfigurationMismatch -> ConfigurationMismatch [label="version set"];
ResourceRequired -> ResourceRequired  [label="configuration change"];
ConfigTestFailed -> Testing  [label="configuration change"];
Failed -> ConfigurationMismatch [label="retry timeout"];

Running -> ConfigurationMismatch [label="restart command"];
Stopping;
Running -> Stopping          [label="stop command"];
Stopping -> Disabled         [label="stopped"];


}
{graphviz}

h2. Versions

The first check that the supervisor does before starting a process is that the version number in the process definition matches the version of the configuration data; this ensures that sipXconfig has a chance to update configuration data to the correct format and content following an upgrade before the process is started.  The contents of the sipXecs-process/version element are compared with a value written by sipXconfig through an XML-RPC interface that establishes the version number for any configuration data.  The values are compared as strings, and must match exactly: if they do not, and alarm is generated by the supervisor, and the state machine waits until the configuration version is updated.

h2. Commands

The commands element contain three elements that define operations on the process by the supervisor: [#Configuration Test], [#Start], and [#Stop].  All of these elements are the same schema data type (analogous to a class): {{Command}}.  They have:

* An optional *{{defaultdir}}* element whose content is the directory that should be set as the current working directory before the command is executed (defaults to the sipXecs log directory).
* An optionsl *{{user}}* element whose content specifies the user id that the command be executed by (not yet implemented, I believe).
* An *{{execute}}* element whose content is the full path to the command to be exectuted.
* Zero or more *{{parameter}}* elements, each of which is a fixed string argument to be passed to the command.

h3. Configuration Test

The *{{configtest}}* element specifies the command to be run to validate the configuration of the process.  The exit status is used to determine the results of the test (a return status of zero indicates that the test passed - any other value is a failure).

h3. Start

The *{{start}}* element specifies the command to be run to start running the process after all configuration checks are complete.

h3. Stop

The *{{stop}}* element specifies the commmand to be run to stop a running instance of the process.

h2. Status

h3. Log files

h3. Process Id files

h2. Resources