...
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
...
.
...
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). |
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). The dark green states and paths are the normal successful sequence of states and events. 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).
| Wiki Markup |
|---|
{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", URL="#SupervisorProcessDefinitions-Resources"];
Testing [label="Run Configuration Test", URL="#SupervisorProcessDefinitions-ConfigurationTest"];
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"];
Failed;
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
h2. Commands
h3. Configuration Test
h3. Start
h3. Stop
h2. Status
h3. Log files
h3. Process Id files
h2. Resources
|
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.
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
defaultdirelement 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
userelement whose content specifies the user id that the command be executed by (not yet implemented, I believe). - An
executeelement whose content is the full path to the command to be exectuted. - Zero or more
parameterelements, each of which is a fixed string argument to be passed to the command.
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, and any other value is a failure.
The specified command should attempt to validate as much of the process configuraiton as possible.
Start
The start element specifies the command to be run to start running the process after all configuration checks are complete.
Stop
The stop element specifies the commmand to be run to stop a running instance of the process.
Status
The status element has either zero or one pid element (see #Process Id files),
and any number of log elements (see #Log files)
Process Id files
The content of the pid element, if present, is the full path to a file containing the process id of this process when it is running.
Log files
Each log element contains the full path to a log file written by the process. A logfile declaration implicitly creates a read-only file resource for the specified path (see #Resources).
Resources
The elements within the resources container element declare resources that may be needed by the process, and the rules for what a management interface is allowed to do with each resource.
There are a number of resource types, detailed below, but they all have the same attributes allowed:
- required is a boolean (values
trueorfalse) that declares whether the resource must exist before the process is started. The supervisor enforces this in the Check Resources step in xecsdev:the state machine above.
- configAccess controls the access allowed to the resource through mangement interfaces; it may take any of the values
read-write,read-only,write-only, orno-access. These rules specify what the supervisor will allow through its management interfaces - they do not control the filesystem or system access attributes of the resource. If different definitions of the same resource specify different access rules, the more permissive rule apples, except thatno-accessand any other value causes a runtime error that invalidates the resource definition.
File Resources
A file or osconfig resource declares the full path to a specific file.
At present, there is no practical difference between these two types - the osconfig resource is differentiated because it declares files that use a specific syntax (the OsConfigDb class in sipXportLib).
IMDB Resources
An imdb resouce declares a table name in the In-Memory-Database.
Process Resources
A process resouce declares a dependency between two processes: the content is the name of another process that must be in the Running state before this process can be started.
SQL Database Resources
An sqldb resouce describes an external database.
Directory Resources
A directory resource describes a directory, and optionally file patterns for files within the directory. The configAccess attribute of the directory is the default access rule for any file in the directory, but a file pattern can override this value. The required attribute of the directory only specifies that the directory itself is or is not required to start the process.
There must be exactly one path element as the first child of the directory; it's contents are the full path name of the directory.
There may be any number of filePattern elements. Each filePattern specifies a simple pattern for file names in which any '{}' character may be replaced by any number of characters that are not '/' - any other characters must appear in the file name for it to match thie pattern. Patterns are checked in the order in which the *filePattern elements appear. If the same path value is used in multiple directory elements, the search order of the patterns within any declaration is maintained, but the order of the declarations is undefined. A filePattern element may override the configAccess specified by its containing directory, but may not have a required attribute.