Application Bundle Format
An application bundle is a gzipped tar file (.tgz, open via the "tar xvfz <file>" command). This format was chosen because it is distribution-neutral. However, it is a small customization to use a .rpm (Red-Hat family) or .deb (Debian, Ubuntu, etc) instead.
The file contains at a minimum the following layout:
appcfg.xml
deploy (a directory)
bin (a directory)
<application binary files>
etc
<application configuration files>
The appcfg.xml file describes the contents of the application bundle. It is an xml V1.1 document with a simple layout. As a simplification to standard XML, attributes and child tags are considered equivalent and the special attribute "value" is equivalent to child content. The purpose is to allow the xml author to use whichever form is more convenient. This concept is most easily understood by noting that all of the following are equivalent config files:
Classic XML
<foo> <bar>1</bar> </foo>
Compact XML
<foo bar="1" />
Partially compacted XML
<foo> <bar value="1"></bar> </foo>
Example configuration file
The following is a typical appcfg.xml configuration file. This file is used in the SAFplus Platform virtualIp example provided with your SAFplus Platform source distribution:
<virtualIp ver="1.4.0.0"> <programNames prog0="vip" /> <redundancyModel value="3+1" /> <totalNodes value="4" /> <modifiers> <failBack value="false" /> <autoRepair value="true" /> <restartsBeforeFailure value='0' /> <activeStandbyRatio value='50' /> </modifiers> <messages> <newDeployment>Virtual IP application deployed. Please edit the work assignment (SAF SI) to customize your virtual IP address and interface before starting it.</newDeployment> </messages> <work> <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" /> </work> </virtualIp>
The tags are described as follows:
Root Tag
The root tag (in this case "virtualIp") is the name of the application (SAF Service Group).
Attribute: ver
It has a single attribute "ver" that specifies the version of the software in a 4 dotted digit format.
ProgramNames
ProgramNames specifies the names of every SAF component to be run in the application (SAF Service Group). A single SAF Service Unit will be created on each node that this Service Group is deployed onto, and this SU will contain 1 component for every specified attribute to this tag.
Attribute: progN
This tag takes any number of attributes, labelled prog0...progN. Each attribute specifies the name of a Component to be created, and also the name of a binary located in "deploy/bin" that the component will run.
Example:
<programNames prog0="vip" prog1='myProg' />
RedundancyModel
Specify what type of redundancy this Service Group requires
Attribute: value
This specifies the redundancy model. Possible values are:
- "2N": 1 Active/1 standby redundancy
- "N+M": N Active/N standby redundancy
- "custom": The application will explicitly assign redundancy
Example:
<redundancyModel value="3+1" />
totalNodes
Recommend the optimal number of nodes to run this application on.
Attribute: value
A number specifying the number of nodes
Example:
<totalNodes value="4" />
modifiers
To override the default configuration for any Service Group configuration parameter, specify the parameter and value as a child tag of this tag. The possible child tags are standard SAF and are also documented in the AWD GUI's deployment page under "Advanced Configuration", or in the SAF AMF, SAFplus Platform SDK or IDE documentation.
Example:
<modifiers> <failBack value="false" /> <autoRepair value="true" /> <restartsBeforeFailure value='0' /> <activeStandbyRatio value='50' /> </modifiers>
failback
Should work be automatically moved back to the original location after a failure?
autoRepair
After a failure, should a node be put directly back into service, or should an adminstrative reset be required.
instantiateDuration (Instantiation delay)
How long to wait after system startup before starting this application.
numPrefActiveSUs (Preferred number of active nodes)
Active nodes are executing your application.
numPrefStandbySUs (Preferred number of standby nodes)
These nodes act as redundant backups for the active nodes.
numPrefIdleSUs (Preferred number of idle nodes)
Idle nodes have the application running but no work assignments. For example, if this number is 0 the application will not be started on any nodes until it is needed. If 1 it will be started on 1 additional node (assuming that the app is deployed to enough nodes).
maxActiveSIsPerSU (Maximum active work)
Maximum active work assignments on one program.
maxStandbySIsPerSU (Maximum standby work)
Maximum standby work assignments on one program.
compRestartDuration (Process validation period)
If a process fails X times within this duration the failure is escalated. X is the 'Maximum process failure count' below.
compRestartCountMax (Maximum process failure count)
How many times to restart a failed component before giving up and escalating to all processes on this node in this deployment.
suRestartDuration (Service Unit restart duration)
If all processes in this deployment on one node take longer than this time to start up, the deployment is considered failed.
suRestartCountMax (Maximum service unit failure count)
How many times to restart all the processes in this deployment before giving up and moving work to another node.
isCollocationAllowed (Collocation)
Allow multiple instances to run on the same node. WARNING: doing so may mean that work is assigned active and standby on the same node, which means you will not have physical redundancy! This flag simply means that you CAN collocate SUs on a node in a SG, however to direct the system to collocate SUs during deployment use the 'instancesPerNode' modifier.
instancesPerNode (Collocated deployments)
During deployment, create this many SUs on each node.
alpha (Redundancy degradation ratio)
Percent of active nodes vs standby nodes when the preferred configuration can not be met
autoAdjust (Automatic work adjustment)
Automatically move work assignments between blades to match as closely as possible the configured work->node preferences.
autoAdjustProbation (Work adjustment interval)
How long between checks to see if work adjustments need to be made
reductionProcedure (Automatic active assignment )
As nodes are removed, standby work assignments are automatically removed to make room for active work assignments
messages
The messages section allows you to provide a message to the user during certain actions.
newDeployment
The new deployment tag specifies the message to print after a successful deployment of this application.
Example:
<messages> <newdeployment>This application is deployed onto the selected nodes.</newdeployment> </messages>
work
The work tag is used to specify the work assignments (SAF Service Instance and Component Service Instances) for this application. Each item of work is defined by a child tag, and the tag name will become the name of the SAF Service Instance. Attributes become the name/value pairs in each CSI. This specification is simpler than the full SAF definition and so covers a subset of the full SAF expressibility. In particular, every component defined in the "ProgramNames" tag will have a CSI created for it, and each CSI will contain every name/value pair.
Example:
<work> <firstIp VirtualIpAddress="192.168.1.250" VirtualNetMask="255.255.255.0" VirtualDevice="eth0:10" /> </work>