OpenClovis Product Documentation - User contributions [en]

Doc:Sdk 4.1/awdguide/apiexamples

2009-07-27T17:26:57Z

Suraj:

==API Examples==
API documentation is included in this documentation package. Additionally, there are several examples located in the "bin" directory of the distribution. These examples provide a basic overview of the APIs and how to use them and also show some simple client/server implementations.

===Basic API Use Example: apiexample.py===

This is intended to be an interactive example (i.e. cut-and-paste the lines into a Python shell running under SAFplus Platform). It presents an overview of the highest layer of APIs and shows how cluster information can be retrieved, software can be installed, and an upgrade started.

It can be run in any SAFplus-connected python shell. To get to an SAFplus-connected Python shell, either use the shell embedded in the SAFplus Platform web server (browse to /shell), or run one from the command line. To run from the command line (recommended because you get a full-featured standard python shell) do the following:

Set up paths to get ARD libraries:
$ export PYTHONPATH={ardDir}/lib:{ardDir}/bin
$ export PATH={ardDir}/bin:$PATH

Run Python. Make SURE to specify ARD's embedded Python, and not your distribution's installed version!
$ {ASP_Dir}/bin/asp_run {ardDir}/bin/python2.5

Now at the Python prompt, run this line FIRST to hook into the SAFplus Platform AMF:
>> import amfpy; amfpy.initializeAmf()

At this point you can use all ARD Python services, as shown in the following script:

====apiexample.py====

# Standard Python modules
import os
import time

# ARD Python API example code, including deployment and upgrade:
import upgrade; import clusterinfo; import aspApp; import aspAmf; import appdeploy

# Hook into the various services
ci = clusterinfo.ci # The clusterinfo.ci objects reflect the entire state of the cluster
amf = aspAmf.Session() # The aspAmf.Session class lets you modify the cluster state

# Example of getting the node names
print [x.name for x in ci.nodeList]

# Get the name of the node in slot 1
print ci.nodes[1].name

# Example of getting the sg started/stopped status
print "Running Service Groups:"
for x in clusterinfo.ci.sgList:
if x.isRunning():
print x.name

# Example of getting SU status and of traversing the entity hierarchy
print "Active Service Units:"
for x in clusterinfo.ci.suList:
if x.isActive():
print "%s is active for service group %s and is running on node %s (slot: %d)" % (x.name,x.sg.name,x.node.name,x.node.slot)

# Example of stopping and restarting an entity
su = ci.suList[0]
print "Stopping %s" % su.name
amf.Shutdown(su)
# Now we must reload the clusterinfo to reflect changes.
ci.load()
su = ci.entities[su.name] # and reload our temporary. Its best to access your entities by name in case the list order changes
if su.isRunning():
print "SU %s is still running" % su.name
else:
print "SU %s is stopped" % su.name
amf.Startup(su)
ci.load()
su = ci.entities[su.name] # its best to access your entities by name in case the list order changes
if su.isRunning():
print "SU %s is running" % su.name
else:
print "SU %s is still stopped" % su.name

# Initialize the Application bundle DB & pass the bundle repository directory. Note that you should only create 1 of these per bundle repository directory or you will have 2 entities managing the same data.
appDb = aspApp.AppDb(os.getenv("ASP_DIR","/tmp") + "/apps")
ci.setAppDb(appDb) # Hook them up (so clusterinfo knows about application versions)
myNode = "ctrlI0"

# Set additional data that SAFplus Platform may not know into the node
# This info is necessary to deploy software
# (it also can be entered via the GUI, or via etc/clustercfg.xml file)
# You need to change these values to correctly reflect your setup
if ci.entities[myNode].localUser == 'unknown':
ci.entities[myNode].setIntraclusterAccess("192.168.66.130","root","clovis","/root/ocmsdemo7")
# The above example sets 1 node. For the application deployment example
# below to work, you must set all of the nodes to the correct values.

# Add 2 bundle files into the system. Of course you must modify the path to
# point to valid bundle files.
appDb.NewAppFile("/code/vipapp1.4.0.0.tgz")
appDb.NewAppFile("/code/vipapp1.4.0.1.tgz")
# Note that if you want AppDb to automatically find them again,
# you must copy them into the repository (the directory you specified
# when creating "appDb").

# Show all bundles and versions
print [(x.name,x.version) for x in appDb.AppList()]

# Find all "live" nodes
# Of course, you can't deploy to nodes that aren't powered up!
liveNodes = filter(lambda x: x.isRunning(),ci.nodeList)
print [x.name for x in liveNodes]

# Get an application
appFile = appDb.apps['virtualIp'].version['1.4.0.0']
print "Name: ", appFile.name, "Located At: ", appFile.dir, "Version: ", appFile.version

Deploy the application:

# Tweak the configuration for just this deployment
# If I didn't copy the configuration, I would be modifying it in RAM
# which would affect other deployments I do within this Python session.
import copy
newCfg = copy.deepcopy(appFile.cfg)
# For example, set failback parameter to True:
newCfg.virtualIp.modifiers.failBack = True

# Really Deploy
import appdeploy
(sgList,(errors,notes)) = appdeploy.deploy(appFile.dir,newCfg,liveNodes,abortIfCantAccess=True,copy=True,deploy=True)
# Did you get a pexpect exception? You probably forgot to specify the node
# intracluster access data as shown above. Or you may have specified
# incorrect information.
myNewSg = sgList[0]
mySgName = myNewSg.name
print "Deployed application and created SG %s" % mySgName
# Reload the AMF information model
ci.load()

# Reaccess via ci global to get refreshed data.
mySg = ci.entities[mySgName]
# Let's start it up
amf.Startup(mySg)
# Give it time to come up
# I reaccess through ci each time to get refreshed data.
while not ci.entities[mySgName].isRunning():
time.sleep(5)
ci.refresh()
print "It is running"

Let's do an upgrade!

# Start the upgrade manager...
umgr = upgrade.UpgradeMgr()
umgr.add(mySg) # Add my Service Group to it.
upSg = umgr.entities[mySgName] # Get my sg's upgrade entity
upSg.upMethod = upgrade.RollingUpgrade
print mySg.appVer.version

# Start the upgrade...
upSg.Upgrade(appDb.apps['virtualIp'].version['1.4.0.1'])
ci.load() # Reload the database.
mySg = ci.entities[mySg.name] # Get the new SG object
print mySg.appVer.version

===XML client/server example===

This example is located in the "bin" directory and consists of 2 files "xmlclientexample.py" and "xmlserverexample.py". It implements a simple XML-RPC client server application that demonstrates how the ARD can interface with 3rd party off-box element management systems. Please look at these files to see how it works.

===HTTP client/server example===

This example is located in the "bin" directory and consists of 2 files "httpclientexample.py" and "httpserverexample.py". It implements a simple http server application that demonstrates how the ARD can interface with 3rd party off-box element management systems. The intention behind this example is to show a client-server application communicating via http not a human browseable web site (the main ARD GUI application demonstrates how a web-based EMS can be constructed).

Doc:Sdk 4.1/awdguide/deploymentdetails

2009-07-27T17:24:57Z

Suraj:

{{AwdDocHeader}}
==AWD Deployments (Service Groups) Page==

This page shows the details of the selected Application (SAF Service Group). To properly understand this page it is best to understand the SAF entity hierarchy documented in the SAF AMF specification.

The top table describes the Service Group in detail. In this case the "Version" field is yellow, which indicates that a new version of this application is available in the bundle manager ([[Doc:sdk_4.1/awdguide/applications | Applications ]] page) and so this application can be upgraded.

The second table describes all the programs that make up this application. In this case, 2 programs are running on different nodes, in an active/standby relationship.

The third table describes all work assigned to this applications (SAF Service Instances). In this case there is just one work item called "virtualIpSIi0_firstIp". If you click on the name, you will be sent to the work details page, where you can modify the Name/Value pairs that define this work. You man also click the "New" button to create a new work item. Doing so will create a new row in the table. You can then fill in any relevant details. You may create as many new work items as desired. When finished, click the "Commit Changes" button to actually submit your changes to the SAFplus Platform Web Director.

As with all pages, you may select any table row by clicking the select box in that row and then click on a button to operate on the selected rows. In this page, you may start, stop, idle, or delete entities. If the deployment's version field is yellow, you may also upgrade the deployment by selecting the deployment (select the only row in the top table) and then clicking on the "Upgrade button". You may only upgrade at a deployment granularity, so selecting a component program or work item and then clicking upgrade will give an error.

[[File:awdSg.png|frame|center|'''OpenClovis SAFplus Platform Web Director Service Group Page''']]

You may also extend this deployment onto more nodes by typing the node name into the text box located near the "extend" button and then clicking on the button. For example, in this model, I could "extend" onto the node in slot 1 by typing "ctrlI0" into the box. You may also extend the deployment onto other nodes (or reduce it) by typing a new redundancy model designation into the "Change redundancy type" box and then clicking "Migrate". This is a very powerful one shot button, but it has some drawbacks; for example the system will automatically choose nodes to extend or delete. Of course, you can do the same functionality by hand by explicitly "extending" onto desired nodes (to add nodes) or by selecting rows and clicking "delete" (to remove them).

Of course, to successfully use the extend or migrate functionality, you must install the software to the appropriate nodes yourself. This can be done via the [[Doc:sdk_4.1/awdguide/applications | Applications (SAF Software Bundles) Page ]]. If you forget to do so, the extend or migrate will work, but you will not be able to actually start the software on that node (until you install it)!

Advanced Configuration can be accessed by clicking on the "+ Advanced Configuration" title. Once opened, the advanced configuration looks like:

[[File:awdSgAdvCfg.png|frame|center|'''OpenClovis SAFplus Platform Web Director Applications Page''']]

Documentation for each field is beyond the scope of this document. It exists on the page itself, in the SAF AMF spec, and within the OpenClovis documentation.

You may change any field by clicking on it (it will dynamically create a edit box), making the change, and then (when all desired fields are changed) clicking the "Commit Changes" button.

Doc:Sdk 4.1/awdguide/si

2009-07-27T17:23:20Z

Suraj:

{{AwdDocHeader}}
===Application Provisioning Page===

This page allows you to change the SAF CSI name/value pairs before the SAFplus Platform assigns the CSI to a component. For more details about SAF CSI please see the SAF AMF specification located at www.saforum.org.

The name/value pairs that appear application initial deployment are defaults specified in the application bundle file. To change the defaults, delete the items that should be changed (by checking them and clicking delete) and then recreate them by clicking "new" to add a new line, filling in the name and value (you can do this multiple times) and finally clicking on "commit changes".

Note that the SAFplus Platform and the SAFplus Platform Runtime Director simply passes these provisioned values to the component; therefore it cannot do any validation on the fields. It is important to get them right to ensure correct operation of your component.

[[File:awdsi.png|frame|center|'''OpenClovis SAFplus Platform Web Director Work Details Page''']]

Doc:Sdk 4.1/awdguide/upgrade

2009-07-27T17:12:22Z

Suraj:

{{AwdDocHeader}}
==Application Upgrade==

After an application deployment is scheduled for an upgrade (by selecting it and clicking on the "upgrade" button in various places in the GUI). It appears in this upgrade page. Multiple upgradeable deployments can appear here simultaneously and you may run the upgrades simultaneously or sequentially as you wish.

Select the application deployments to be upgraded by clicking on the left checkbox. Next choose "rolling" or "single-step" upgrade on the right. "Rolling" upgrade executes an in-service algorithm in which the application is upgraded on each node sequentially ensuring that some nodes always remain to provide the application service. To use this method, applications must be capable of having different versions run simultaneously on the cluster. "Single-step" upgrade upgrades the application on every node simultaneously, causing a short interruption in service. However, this method does not require that application versions interoperate. These upgrade algorithms are explained in detail in the SAF SMF (Software Manageability Framework) specification.

Leave "automatic" as "yes" since manual upgrades are not yet supported.

When ready, click "Start". This page will be updated dynamically so you will see the upgrade's progress.

[[File:awdUpgrade.png|frame|center|'''OpenClovis SAFplus Platform Web Director Upgrade Page''']]

This is a view of an in-progress rolling upgrade. Note that the payloadI0 node is no longer running the application (its status is "down") and that it is being upgraded. Also note that the "payloadI1" node is up, and active -- it is providing the service during the upgrade of the "payloadI0" node.

[[File:awdMidUpgrade.png|frame|center|'''OpenClovis SAFplus Platform Web Director Mid-Upgrade Page''']]

When the upgrade is complete and you are satisfied with the correct operation, click "Commit" to remove it from the upgrade page.

Doc:Sdk 4.1/awdguide/programs

2009-07-27T17:09:31Z

Suraj:

{{AwdDocHeader}}
==Programs (SAF Components)==
This page shows information about every SAFplus-aware process running in the cluster. You may modify the running state of these processes using the standard "select-rows and click button" method that exists throughout the GUI.

[[File:awdComponents.png|frame|center|'''OpenClovis SAFplus Platform Web Director Nodes Page''']]

Doc:Sdk 4.1/awdguide/deployments

2009-07-27T17:06:04Z

Suraj:

{{AwdDocHeader}}
==AWD Deployments (Service Groups) Page==
This page shows the applications deployed (SAF Service Groups) on the cluster.
The table contains one row per deployment. In this case the only applications running are the SAFplus Platform Web Director itself (ClusterMgrSGI0) and a single application called "virtualIpSGi0". Note that some fields are not populated for the ClusterMgrSGI0 deployment because the ClusterMgr was not dynamically deployed into this model. Also note that the "Version" field for the "virtualIp" deployment is yellow, which indicates that a new version of this application is available in the bundle manager ([[Doc:sdk_4.1/awdguide/applications | Applications ]] page) and so this application deployment can be upgraded.

[[File:awdSgs.png|frame|center|'''OpenClovis SAFplus Platform Web Director Deployments (Service Groups) Page''']]

Doc:Sdk 4.1/awdguide/deploy

2009-07-27T17:00:56Z

Suraj:

{{AwdDocHeader}}
===Application Installation and/or Deployment===
To install and run software bundles on the cluster, use the application deployment page. On the top, select the nodes on which you want the application to be installed/deployed. Next choose the "Operation" (just install -- copy the software, just deploy -- create the application in AMF with the assumption that it is already installed, or do both). If the software is already installed it will not be installed again, so the "Install and Deploy" option is the most commonly used option. Next change the deployment name, if desired.

Next, change any High Availability parameters. Note that the parameters shown are selected by the application. It is possible that the application will not work for a particular combination of parameters so only modify these if you know the application intimately.

Finally click the "Deploy" button to make it happen. Be patient! Since the system may be installing the application on remote nodes it can take some time.

[[File:awdDeploy.png|frame|center|'''OpenClovis SAFplus Platform Web Director New Application Deployment Page''']]

Doc:Sdk 4.1/awdguide/nodedetails

2009-07-27T16:57:37Z

Suraj:

{{AwdDocHeader}}
==Node Details==

This page describes the node details. Shown are the state of the node, the applications running on the node, and the exact programs running on the node. At the bottom is a form showing the information required to do a software installation onto the node. See the "New Node" screen for more details about these fields.

[[File:awdNode.png|frame|center|'''OpenClovis SAFplus Platform Web Director Node Details Page''']]

Doc:Sdk 4.1/awdguide/applications

2009-07-27T16:56:08Z

Suraj:

{{AwdDocHeader}}
==Applications (SAF Software Bundles) Page==

Application bundles can be uploaded to the cluster, where they are stored in an application repository. Applications in the repository are not actually installed or deployed in the cluster -- they are simply available for installation and deployment. This page shows the uploaded applications and versions. In this case 2 versions of the "virtualIp" application have been uploaded 1.4.0.0 and 1.4.0.1.

Applications can be uploaded using the "upload new application" box at the bottom of the main window. Next applications can be installed and/or deployed through the "Deploy" button (first check the desired application version). It is also possible to schedule applications to be upgraded here (check the OLD version and click upgrade) or to delete application versions from the repository.

[[File:awdapp.png|frame|center|'''OpenClovis SAFplus Platform Web Director Applications Page''']]

Doc:Sdk 4.1/awdguide/newnode

2009-07-27T16:45:00Z

Suraj:

{{AwdDocHeader}}
===New Node===
The "New Node" page allows the user to provision a new node in the cluster. It remains the user's responsibility to install and start SAFplus Platform on the new node.

The "Name" and "Slot" are required fields; although the slot will only be used if the node is not in an ATCA chassis. Otherwise the node's actual slot will be used. These values also must be defined in the asp/etc/asp.conf file on the new node (this is the mechanism used to "connect" the provisioned node with a real node.

The IP Address, Admin username, Admin password, and SAFplus Platform directory fields are needed for application software deployment. Application deployment uses the "scp" protocol, and so if the cluster is configured with ssh private/public keys then it is not necessary to fill out these fields. There are many tutorials online describing this configuration so it will not be discussed here. For security reasons, using ssh keys is recommended for deployment.

[[File:awdNewNode.png|frame|center|'''OpenClovis SAFplus Platform Web Director New Node Page''']]

Doc:Sdk 4.1/awdguide/nodes

2009-07-27T16:37:50Z

Suraj:

{{AwdDocHeader}}
==AWD Nodes Page==

[[File:awdNodes.png|frame|center|'''OpenClovis SAFplus Platform Web Director Nodes Page''']]

The AWD Nodes table describes details about the state of each node in the system. The node's name, IP address, administrative (i.e. desired) state, actual state, redundancy role, and what SAFplus Platform applications and processes are running on it are all available. By checking one or multiple rows, you may press the "start", "idle", "stop", "switchover", or "delete" buttons to execute that operation on one or more nodes. To create a new node, click the "New node" menu item in the left-hand sidebar.

The node's IP address must be correct for the SAFplus Platform web director to correctly deploy software onto the node. To set the node's IP Address, and other details, click the node's name in the left-hand sidebar. This will bring you to the [[Doc:sdk_4.1/awdguide/nodedetails | Node Details Page ]].

Doc:Sdk 4.1/awdguide/frame

2009-07-27T16:32:14Z

Suraj:

{{AwdDocHeader}}
==AWD Frame and Common Elements==

This is the AWD “Nodes” page. It displays the state of all nodes/blades/computers (pick your terminology) in the OpenClovis SAFplus Platform cluster and is used as the "home" page of the AWD. Let us examine the surrounding frame before we take a look at the table itself. This frame will be the same in most AWD pages.

[[File:awdNodes.png|frame|center|'''OpenClovis SAFplus Platform Web Director Nodes Page''']]

On top is the AWD title bar. At the upper left is the OpenClovis logo (rebrandable) and just below that (in brown) is the last time this page was refreshed. On the right side is the title of this page, “Nodes”, and below that is a menu of major functionality (note if this instance of AWD was running on a chassis, we would also see a “chassis” menu item on this bar). On the far right is a small “logout” link for when you are done using the AWD.

On the left side is the AWD sidebar. This sidebar contains links to dynamic content pages. In this case every node, and application is listed. There are also 2 shortcut menu choices to create a new application deployment “New deployment” and to create a new node “New node”. If an application has extended AWD with custom content, you would also see a link to this customization in this sidebar.

On the bottom is the AWD footer. On the left are two buttons. The first demonstrates internationalization by allowing you to dynamically switch the entire web site between displaying SA Forum and “human” readable text. For example, if SA Forum terminology was turned on, the “Start” button would instead be labeled “Unlock”, the “Idle” button “lock assignment”, and the “Stop” button “lock instantiation”. The next button selects how often the web page should be reloaded. By selecting a different time, you can choose your desired compromise between network traffic and data accuracy. Finally on the far right is the OpenClovis Copyright notice (rebrandable).

In the nodes page shown above, you can see that the name of each node (displayed in a column of the main table) is colored. Entity names are color-coded based on the current status of the entity.

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Color
!style="color:#66b154; background:#09477c"| Meaning
|- style="color:#ffffff; background:#549cc6"
| style="color:green" | Green
| Entity is OK
|- style="color:#ffffff; background:#549cc6"
| style="color:yellow" | Yellow
| Entity is OK but idle/unused. This may happen administratively or because there is nothing for the entity to do.
|- style="color:#ffffff; background:#549cc6"
| style="color:orange" | Orange
| Entity is unprotected (i.e. it is configured for redundancy but is currently running without redundancy)
|- style="color:#ffffff; background:#549cc6"
| style="color:red" | Red
| Entity is down
|- style="color:#ffffff; background:#549cc6"
| style="color:gray" | Gray
| Entity is off or does not exist
|}

Doc:Sdk 4.1/awdguide/login

2009-07-27T16:15:40Z

Suraj:

{{AwdDocHeader}}
==Login==
To access AWD functionality, you must log in first. By default the AWD is running on port 8080 on both system controller nodes.

[[File:awdLogin.png|frame|center|'''OpenClovis SAFplus Platform Web Director Login Screen''']]

This is the SAFplus Platform Web Director login page. Three user groups are supported, read, read/write, and administrator. Users in the read-only group can look at pages, users in the read/write group can look at pages AND make changes. Finally, the administrator group can manage AWD web site settings. The default administrator username/password is "root"/"clovis" and this account will be automatically created upon startup if accidentally deleted. Note: to setup users, etc, or to change the administrator password please use the TurboGears-supplied Catwalk web site management toolbox accessible from your browser at “//{AWD node}/catwalk”. Documentation for this tool is located in the turbogears project (http://www.turbogears.org/).

Doc:Sdk 4.1/awdguide/screens

2009-07-27T15:28:26Z

Suraj:

{{AwdDocHeader}}
==Screens==
The following pages describe the GUI screens that constitute the SAFplus Platform Web director.

* [[Doc:sdk_4.1/awdguide/login | Login ]]
* [[Doc:sdk_4.1/awdguide/frame | AWD Frame and Common Elements ]]
* [[Doc:sdk_4.1/awdguide/nodes | Nodes Page ]]
** [[Doc:sdk_4.1/awdguide/newnode | New Node Page ]]
* [[Doc:sdk_4.1/awdguide/applications | Applications (SAF Software Bundles) Page ]]
** [[Doc:sdk_4.1/awdguide/deploy | Application Deployment Page ]]
* [[Doc:sdk_4.1/awdguide/deployments | Deployments (SAF Service Groups) Page ]]
* [[Doc:sdk_4.1/awdguide/programs | Programs (SAF Components) Page ]]
* [[Doc:sdk_4.1/awdguide/upgrade | Upgrade Page ]]
* [[Doc:sdk_4.1/awdguide/nodedetails | Node Details Page ]]
* [[Doc:sdk_4.1/awdguide/deploymentdetails | Deployment Details (Service Group) Page ]]
** [[Doc:sdk_4.1/awdguide/si | Application Work Details (SAF Service Instance) Page ]]

Doc:Sdk 4.1/awdguide/upgradedirector

2009-07-27T15:24:39Z

Suraj:

{{AwdDocHeader}}
==Upgrade Director==

The Upgrade Director is a separate entity that controls the upgrade of the SAFplus Platform middleware and optionally the OS. To upgrade applications, please see the "Software Management" subsection.

The core of the Upgrade Director consists of a python program that is run on both system controllers that upgrades a cluster using an in-service (rolling) algorithm. This is difficult because the node that the upgrade director's themselves are running on may need to be rebooted. However, since the upgrade director is run redundantly (on both system controllers) there is always one live node to direct operations.

===Delivery===

The Upgrade Director requires an "upgrade bundle" file to run. This file contains the Upgrade Director itself and all files necessary to do an upgrade. New upgrade bundle file formats can be used by deriving new classes from the "UpgradeBundle" and "UpgradeRemote" classes.

The Upgrade Director provides a default, self-executing, linux-distribution-neutral bundle file format based on gzipped tar files. A script is also provided that will create this bundle given a compiled SAFplus Platform tree and an xml configuration file.

===XML File Format===

The following is an example XML file.

<code>
<pre>
<bundle_config ver="1.0.0.0">

<asp>
<image version="4.1.0" arch="i686" os="ubuntu" osVersion="9.04" files='i686-linux-2.6.22.tgz'/>
</asp>

<app>
<virtualIp version="1.4.0.1" arch="i686" os="linux" files='vipapp1.4.0.1.tgz' />
</app>

<upgradeDirector>
<default fromAspVersion="4.0" aspVersion="4.1" files='/code/svn/clustermgt/clustermgt/root/ocms/src/app/asppybinding /code/svn/clustermgt/clustermgt/root/ocms/src/app/upgradeDirector /code/svn/clustermgt/clustermgt/root/ocms/target/i686/linux-2.6.22/lib/' />
</upgradeDirector>

<os>
<Ubuntu fromVersion="8.04" version="9.10" files='fakeubuntu9.10.tgz' />
</os>

</bundle_config>
</pre>
</code>

This XML file is included in the upgrade bundle for use when upgrading the cluster. Any unknown tag or attribute is simply ignored, so this file format may be extended to supply additional functionality. If the entity is applicable to all possibilities (such as what operating system the code runs on, or what version must be running on the system before the upgrade) then the specifying attribute may be removed.

In this release, only a single entry in each major section is allowed -- for example, the software does not determine which SAFplus Platform image or OS image should be used in the upgrade. There should be only one image specified.

==== Description of tags ====

* <bundle_config> This tag defines the start and end of the config file. It contains as single attribute which is the version of this XML config file format. Currently "ver" which must be "1.0.0.0".
* <asp> This tag contains the SAFplus Platform images available within this bundle. Currently only a single SAFplus Platform image is supported per bundle.
* <image> This tag defines the SAFplus Platform image. Its attributes are:
** version The SAFplus Platform version
** arch The architecture this SAFplus Platform is compiled for
** os The OS this image was compiled on
** osVersion The OS version this image was compiled on
** files The SAFplus Platform image file. This is the output of "make images" executed in an SAFplus Platform model, with your target.conf set to generate a single binary image, and separate .conf files.
* <app> Simultaneous application upgrade is not supported in this release
* <upgradeDirector> This section specifies the upgrade director software available in this bundle
** fromAspVersion Specifies what version of SAFplus Platform the upgrade director can upgrade from.
** aspVersion Specifies what version of SAFplus Platform the upgrade director can upgrade to.
** files A space-separated list of files and directories that must contain the upgrade director application and all required libraries. These file will be copied into the bundle.
* <os> What operating system upgrades are contained in this bundle
** fromVersion The node must be running this version for this file to be applicable
** version The version of the os in this file
** files A space-separated list of files and directories that contain the operating system. These files/directories will be copied into the bundle.

=== Bundle Creation ===

A bundle is created by running the "createUpgradeBundle.py" script located in the upgradeDirector directory. It is run like this:

<code>
<pre>
export UPGRADE_IMAGE_PATH=<colon separated list of directories>
python createUpgradeBundle.py <xmlConfigFile>
</pre></code>

The UPGRADE_IMAGE_PATH directory allows you to specify the set of search directories when looking for files referenced in the xml config file. The purpose of the UPGRADE_IMAGE_PATH variable twofold: First, to allow the script to handle changes in the directory hierarchy without requiring the config file to be changed. This is useful for multiple-developer source-controlled environments since different "checkouts" may use different root trees. Second, to allow the config file to be copied into the bundle itself and still have applicable file names.

=== Bundle Execution ===
The created bundle is a gzipped tar file which is wrapped in a simple self-extracting script (selfextractor.sh). This script can either extract all files in the archive (i.e. detar them) or extract and start the runtime director. This latter is the rolling upgrade operation.

For example:

To extract all files in the archive:
<code>
<pre>
<bundle> extract
specifically:
./asp4.1.0.bdl extract
</pre>
</code>

To start the upgrade director:

<code>
<pre>
<bundle> <current SAFplus Platform dir>
specifically:
./asp4.1.0.bdl /root/asp40
</pre>
</code>

Note that this command should only be run on a single controller node in your cluster. It will automatically identify the other controller node and run the upgrade director redundantly on it.

Please see the "selfextractor.sh" script for more details and for customization.

===Software Overview===

Please see the API documentation for details on the software.

Doc:Sdk 4.1/awdguide/appbundle

2009-07-27T15:21:25Z

Suraj:

{{AwdDocHeader}}
==Application Bundle Format==

An application bundle is a gzipped tar file (.tgz, open via the "tar xvfz <file>" command) that 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====
<pre>
<foo bar="1" />
</pre>

====Partially compacted XML====
<pre>
<foo>
<bar value="1"></bar>
</foo>
</pre>

===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!

====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:
<pre>
<messages>
<newdeployment>This application is deployed onto the selected nodes.</newdeployment>
</messages>
</pre>

===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>

Doc:Sdk 4.1/awdguide/swmgmt

2009-07-27T15:18:36Z

Suraj:

{{AwdDocHeader}}
==Software Management==

Software Management consists of the creation and management of software bundles, software version tracking, deployment, removal, and upgrade. The software management functionality is available as a set of Python APIs delivered as part of the AWD API. Individual function documentation is available in the AWD API reference guide.

===Software Lifecycle===

This section describes the application software lifecycle from the perspective of the AWD GUI for clarity. However, understand that AWD APIs exist to access every stage of this process independently of the GUI and of other stages. Therefore an independently written EMS can selectively modify or override any or all of these stages.

[[File:awdsoftwarelifecycle.png|frame|right|'''Software Lifecycle''']]

1. Upload: Application Software is delivered in the form of a "bundle", which is a tarred, gzipped (.tgz) archive file containing the application. The application author generates this bundle as part of the application "build" process. This bundle file is uploaded to the ARD server (controller nodes) and is stored in the AWD's software repository.

2. Deployment: Once the application software is in the AWD bundle manager, it can be deployed to nodes. In this step the software is automatically copied to each node and the appropriate SAF AMF Entities are created to model the application

3. New Version: A new version (bugfix or major change) of the application is delivered as another bundle in the same manner as the original upload.

4. Upgrade: An upgrade can occur when a newer version of application software exists in the bundle manager then is running on the nodes. The user initiates an upgrade, and can do so selectively -- that is, for particular deployments (service groups) and not others. Multiple upgrades can be ongoing at the same time.

5. Removal: When no deployments are currently using a particular version of application software, that software can be deleted from the bundle manager.

===Software Library Overview===

====AspApp====
Software can be provided to the AWD in a single bundle file, which is essentially a Linux .tgz (gzipped tar archive) that contains specific files and a well-defined directory layout. Most importantly, at the top level there exists an XML file called "appcfg.xml". This file describes the application contained in the bundle file, and includes details such as its current version and required redundancy model (see [[Doc:sdk_4.1/awdguide/appbundle | Application Bundle Format ]]).

The "aspApp" module manages bundles in the system. It is notified of a bundle file via and API call that simply takes the name of the file as a parameter (AppDb.NewAppFile()). The module then opens the file, parses the appcfg.xml file and creates an "AppFile" object that corresponds to this software bundle. This object contains data members and methods that make it easy for an application to access all information about the bundle. The module also places this "AppFile" object into a global database of all application bundles, so that it is easy to understand its relationship to other bundles that are also in the system (such as to prior versions of the same application). It also connects this application bundle to the existing SAFplus Platform state, so you can easily determine whether this application bundle has already been deployed on the system and exactly which Service Groups are running it.

[[File:awdAspApp.png|frame|center|'''OpenClovis SAFplus Platform Web Director Application Management Object Hierarchy''']]

====AppDeploy====

The "appDeploy" module handles software deployment. It contains a single API called "deploy" that takes some data members from an AppFile object (basically the bundle extraction location and the deployment configuration), a list of nodes to deploy to, and some flags controlling various aspects of the operation. The function does not take the AppFile directly for two reasons:
* It is usable on software that is not part of the software bundle management.
* You may want to modify the software's deployment configuration.

Using this function, you may either copy the software onto all specified nodes, create the required SAF AMF entities in the information model, or do both simultaneously (depending on the flags passed).

You may also select whether you want an exception raised upon error (such as inability to deploy the software to a node), or whether you want to continue, returning all issues at the end of the operation.

All together, this results in an incredibly powerful but simple deployment facility!

====Application Removal====

Applicaton removal is extremely simple. You simple choose the SAF entities to be deleted, and call the "DeleteEntities" member of the aspAmf module. The system makes sure that applications are shut down before deletion, etc. And to make the process even simpler, there is a helper function in the clusterinfo module called "getDependentEntities" that will return a list of all entities that are wholly dependent on the entity passed in. These two functions can be used in conjunction to create a very powerful application or entity removal system. For example, to delete a Service Group named "mySg" the following code could be used:

<code><pre>
entities = ci.getDependentEntities(ci.entities["mySg"])
amf.DeleteEntities(entities)
</pre></code>

[In the code above, "ci" is the global clusterinfo database located at "clusterinfo.ci" and "amf" is an instance of an aspAmf session (aspAmf.Session())].

This will delete the Service Group and all Service Units, Components, Service Instances, and Component Service Instances within that Service Group.

This idiom works for all SAF entities. For example, to delete a node named "myNode" the exact same code could be used (other then the entity name):

<code><pre>
entities = ci.getDependentEntities(ci.entities["myNode"])
amf.DeleteEntities(entities)
</pre></code>

This will delete the node and all Service Units and Components running on that node. If a Service Group is running on several nodes including the deleted node, only the Service Unit and Components on the node will be affected -- the Service Group does not need to be taken out of service, and work (SAF SIs) will automatically be transferred to Service Units that are not being deleted!

====Application Upgrade====

Application Upgrade is implemented in the "upgrade" module. This module contains an upgrade manager (UpgradeMgr) that is essentially a container for objects that describe the upgrade state of individual Service Groups (UpgradeSg).

To initiate an upgrade one first must provide the software bundle file containing the new version to the bundle manager (aspApp, described above). Next, one simply adds the service group to the upgrade manager by calling the UpgradeMgr.add() member function with the service group entity (accessed via clusterinfo). At this point an UpgradeSg object is created but not yest started. It is now possible to configure the specifics of the upgrade operation by calling UpgradeSg member functions and modifying member variables. For the upgrade algorithm (single step or rolling) can be selected by modifying the "upMethod" member variable.

Finally, an upgrade can be initiated by calling the UpgradeSg.Upgrade() member function. This function accepts as a parameter an AppFile (see above for a description of AppFile) object that describes exactly what target software to upgrade to. The upgrade system takes care of automatically deploying the software to the required nodes, shutting down Service Units, and deleting and recreating SAF AMF entities.

Its THAT simple!

=====Additional Upgrade APIs=====

There are also additional APIs that allow a programmer to have more control over the upgrade process. The "Upgrade" member function is actually a thin wrapper around a "generator" function (http://docs.python.org/tutorial/classes.html#generators) that "returns" each time a single step in the upgrade is complete. So you can directly call the generator function if you need to execute some code at each step in the upgrade process. The AWD GUI uses this feature to implement step-by-step guided upgrade.

The upgrade objects are also derived from a single class called ChangeTracker. The ChangeTracker class has an API that allows threads to block until a state change has occurred (ChangeTracker.changeWait). As the upgrade proceeds, waiting threads are unblocked each time the upgrade changes the state of the cluster, allowing application code to be written to observe these state changes. For example, the AWD GUI uses this technique to report the upgrade state changes to the web browser as they occur, allowing the user to watch the upgrade's progress.

Doc:Sdk 4.1/awdguide/swmgmt

2009-07-27T15:15:10Z

Suraj:

{{AwdDocHeader}}
==Software Management==

Software Management consists of the creation and management of software bundles, software version tracking, deployment, removal, and upgrade. The software management functionality is available as a set of Python APIs delivered as part of the AWD API. Individual function documentation is available in the AWD API reference guide.

===Software Lifecycle===

This section describes the application software lifecycle from the perspective of the AWD GUI for clarity. However, understand that AWD APIs exist to access every stage of this process independently of the GUI and of other stages. Therefore an independently written EMS can selectively modify or override any or all of these stages.

[[File:awdsoftwarelifecycle.png|frame|right|'''Software Lifecycle''']]

1. Upload: Application Software is delivered in the form of a "bundle", which is a tarred, gzipped (.tgz) archive file containing the application. The application author generates this bundle as part of the application "build" process. This bundle file is uploaded to the ARD server (controller nodes) and is stored in the AWD's software repository.

2. Deployment: Once the application software is in the AWD bundle manager, it can be deployed to nodes. In this step the software is automatically copied to each node and the appropriate SAF AMF Entities are created to model the application

3. New Version: A new version (bugfix or major change) of the application is delivered as another bundle in the same manner as the original upload.

4. Upgrade: An upgrade can occur when a newer version of application software exists in the bundle manager then is running on the nodes. The user initiates an upgrade, and can do so selectively -- that is, for particular deployments (service groups) and not others. Multiple upgrades can be ongoing at the same time.

5. Removal: When no deployments are currently using a particular version of application software, that software can be deleted from the bundle manager.

===Software Library Overview===

====AspApp====
Software can be provided to the AWD in a single bundle file, which is essentially a Linux .tgz (gzipped tar archive) that contains specific files and a well-defined directory layout. Most importantly, at the top level there exists an XML file called "appcfg.xml". This file describes the application contained in the bundle file, and includes details such as its current version and required redundancy model (see [[Doc:sdk_4.0/awdguide/appbundle | Application Bundle Format ]]).

The "aspApp" module manages bundles in the system. It is notified of a bundle file via and API call that simply takes the name of the file as a parameter (AppDb.NewAppFile()). The module then opens the file, parses the appcfg.xml file and creates an "AppFile" object that corresponds to this software bundle. This object contains data members and methods that make it easy for an application to access all information about the bundle. The module also places this "AppFile" object into a global database of all application bundles, so that it is easy to understand its relationship to other bundles that are also in the system (such as to prior versions of the same application). It also connects this application bundle to the existing SAFplus Platform state, so you can easily determine whether this application bundle has already been deployed on the system and exactly which Service Groups are running it.

[[File:awdAspApp.png|frame|center|'''OpenClovis SAFplus Platform Web Director Application Management Object Hierarchy''']]

====AppDeploy====

The "appDeploy" module handles software deployment. It contains a single API called "deploy" that takes some data members from an AppFile object (basically the bundle extraction location and the deployment configuration), a list of nodes to deploy to, and some flags controlling various aspects of the operation. The function does not take the AppFile directly for two reasons:
* It is usable on software that is not part of the software bundle management.
* You may want to modify the software's deployment configuration.

Using this function, you may either copy the software onto all specified nodes, create the required SAF AMF entities in the information model, or do both simultaneously (depending on the flags passed).

You may also select whether you want an exception raised upon error (such as inability to deploy the software to a node), or whether you want to continue, returning all issues at the end of the operation.

All together, this results in an incredibly powerful but simple deployment facility!

====Application Removal====

Applicaton removal is extremely simple. You simple choose the SAF entities to be deleted, and call the "DeleteEntities" member of the aspAmf module. The system makes sure that applications are shut down before deletion, etc. And to make the process even simpler, there is a helper function in the clusterinfo module called "getDependentEntities" that will return a list of all entities that are wholly dependent on the entity passed in. These two functions can be used in conjunction to create a very powerful application or entity removal system. For example, to delete a Service Group named "mySg" the following code could be used:

<code><pre>
entities = ci.getDependentEntities(ci.entities["mySg"])
amf.DeleteEntities(entities)
</pre></code>

[In the code above, "ci" is the global clusterinfo database located at "clusterinfo.ci" and "amf" is an instance of an aspAmf session (aspAmf.Session())].

This will delete the Service Group and all Service Units, Components, Service Instances, and Component Service Instances within that Service Group.

This idiom works for all SAF entities. For example, to delete a node named "myNode" the exact same code could be used (other then the entity name):

<code><pre>
entities = ci.getDependentEntities(ci.entities["myNode"])
amf.DeleteEntities(entities)
</pre></code>

This will delete the node and all Service Units and Components running on that node. If a Service Group is running on several nodes including the deleted node, only the Service Unit and Components on the node will be affected -- the Service Group does not need to be taken out of service, and work (SAF SIs) will automatically be transferred to Service Units that are not being deleted!

====Application Upgrade====

Application Upgrade is implemented in the "upgrade" module. This module contains an upgrade manager (UpgradeMgr) that is essentially a container for objects that describe the upgrade state of individual Service Groups (UpgradeSg).

To initiate an upgrade one first must provide the software bundle file containing the new version to the bundle manager (aspApp, described above). Next, one simply adds the service group to the upgrade manager by calling the UpgradeMgr.add() member function with the service group entity (accessed via clusterinfo). At this point an UpgradeSg object is created but not yest started. It is now possible to configure the specifics of the upgrade operation by calling UpgradeSg member functions and modifying member variables. For the upgrade algorithm (single step or rolling) can be selected by modifying the "upMethod" member variable.

Finally, an upgrade can be initiated by calling the UpgradeSg.Upgrade() member function. This function accepts as a parameter an AppFile (see above for a description of AppFile) object that describes exactly what target software to upgrade to. The upgrade system takes care of automatically deploying the software to the required nodes, shutting down Service Units, and deleting and recreating SAF AMF entities.

Its THAT simple!

=====Additional Upgrade APIs=====

There are also additional APIs that allow a programmer to have more control over the upgrade process. The "Upgrade" member function is actually a thin wrapper around a "generator" function (http://docs.python.org/tutorial/classes.html#generators) that "returns" each time a single step in the upgrade is complete. So you can directly call the generator function if you need to execute some code at each step in the upgrade process. The AWD GUI uses this feature to implement step-by-step guided upgrade.

The upgrade objects are also derived from a single class called ChangeTracker. The ChangeTracker class has an API that allows threads to block until a state change has occurred (ChangeTracker.changeWait). As the upgrade proceeds, waiting threads are unblocked each time the upgrade changes the state of the cluster, allowing application code to be written to observe these state changes. For example, the AWD GUI uses this technique to report the upgrade state changes to the web browser as they occur, allowing the user to watch the upgrade's progress.

Doc:Sdk 4.1/awdguide/deppkg

2009-07-27T15:11:58Z

Suraj:

{{AwdDocHeader}}
==Deployment and Packaging==
The SAFplus Platform Web Director GUI is provided in the form of a gzipped tar file (.tgz). You should open this file (tar xvfz {filename}) in the SAFplus Platform user's (generally "root") home directory or the SAFplus Platform base directory. It will create a directory called aspwebdirector-{version}-{OS}-{arch}. The rest of this document will refer to this directory using the symbol {AWDBASE}.

===Integration within your IDE model===
The SAFplus Platform Web Director GUI can be integrated within your IDE-based model by creating a 1+1 Service group with 1 component on 1 or 2 SAFplus Platform nodes. The component executable should reference a script that simply executes the AWD binary ({AWDBASE}/bin/aspwebdirector). Before running your model, you must run the {AWDBASE}/install script to ensure that all of the AWD requirements are installed.

===Dynamic Installation===
Additionally, the SAFplus Platform Web Director GUI can be dynamically installed into a running SAFplus Platform chassis. To do so, detar the package and run the ./install and then the ./start scripts. These scripts do not need to be run again (even after an cluster reboot) unless you remove the SAFplus Platform configuration (located in the "var" directory of your SAFplus Platform installation). If the SAFplus Platform configuration is deleted, you will need to run the "./start" script again to insert the AWD service group into the SAFplus Platform Application Management Framework (AMF).

===Library Integration===
The SAFplus Platform Web Director Libraries can be deployed within your management application by running your management application (or agent) on an SAFplus Platform node and running a Python interpreter within it. Embedding a Python interpreter in this manner is very simple. You may use the AWD GUI as an example of how to do so, or you may read the "Extending and Embedding Python" chapter of the python documentation located at http://www.python.org.

===Standalone Python===
Additionally, you may run the SAFplus Platform Web Director Libraries stand-alone in its own Python shell. To do so, first start SAFplus Platform and then add the AWD "bin" directory to your "PYTHONPATH" environment variable (see Python documentation for more details) so you can "import" the AWD libraries. Next, from the SAFplus Platform base directory run "bin/asp_run python". You should see the python prompt. Next run:

>>> import asppy
>>> asppy.initializeAmf()

At this point, you should be able to access the API. For example:

>>> import clusterinfo
>>> print [x.name for x in clusterinfo.ci.nodes]

Additionally, if you choose to not run the GUI, you do not need most of the applications that are installed as part of the {AWDBASE}/install script (although it does not hurt to install them). All that is needed is "pexpect" which is used for deployment (to automate the "scp" command). You may see how to install this by hand by looking at the {AWDBASE}/3rdparty/Makefile file. If you are not using the GUI or the deployment features, you do not need to install any prerequisites.

Doc:Sdk 4.1/awdguide/overview

2009-07-27T15:08:31Z

Suraj:

{{AwdDocHeader}}
==Overview==

The following diagram show the major functional blocks provided by the SAFplus Platform Web Director.

[[File:awdHLD.png|frame|center|'''SAFplus Platform Web Director High Level Architecture Diagram''']]

The complete AWD package includes everything above the red curve that denotes the Python/C boundary. Above the red curve, blue boxes denote software created by OpenClovis while brown boxes show the free open source software that the AWD utilizes.

For explanatory purposes, the fundamental components of your cluster are shown below the red curve. These include the OpenClovis SAFplus Platform (required), HPI (optional and it is bundled with SAFplus Platform), a SQL database, and Linux (or other OS supported by SAFplus Platform).

===Architecture Block Descriptions===

====SAFplus Platform Web Director====

The SAFplus Platform Web Director itself is a thin layer that simply implements the GUI look and feel and calls the underlying APIs. It uses the TurboGears web application framework and templating system to serve particular web pages. To facilitate rebranding, customization, and extensibility, this layer is carefully constructed to contain only the web logic, and not any SAFplus Platform functionality.

All subsequent sections describe the APIs available to any application. These APIs are described in detail in the SAFplus Platform Web Director API document.

====Software Management====

The software management layer consists of APIs that handle software deployment onto any node, software bundle and version management, and in-service software upgrade (ISSU). This layer uses the Object Access Layer to access the SAFplus Platform middleware and Linux services to deploy software.

====Object Access Layer====

This set of APIs presents the cluster Information Model as a set of objects and methods, instead of presenting it functionally as occurs in the lower layers.

=====ClusterInfo=====

The ClusterInfo library presents the AMF Information Model (both configuration and current state) as a set of objects. Since the Information Model naturally consists of objects (Service Groups, Service Units, and Components for example) this abstraction greatly simplifies the effort required to access the data.

Also included are routines that create internally consistent groups of Information Model entities. For example, a single function call will return a complete SAF Service Group hierarchy (Service Group, Service Unit, Components, Service Instances, and Component Service Instances) for a new application that is both internally consistent and consistent with the existing Information Model. This set of objects is not yet installed into the system, allowing you to tweak and modify their configuration before "committing" the group.

=====AspAmf=====

The AspAmf library contains all functions that modify the AMF Information Model. These functions are tightly integrated with the ClusterInfo entities and encapsulate a tremendous amount of functionality as compared to the underlying functional interface. For example, modifying the Information Model to implement common operations such as adding or removing a Service Group can require hundreds of function calls at the AMF layer. However this can be done in a single AspAmf API call called "InstallApp". This single call takes as a parameter a list of AMF entities, and (from the user's perspective) it simply adds them into the AMF Information Model. But actually doing so is not so simple! The function ensures that the entities are created if they do not exist, or modified to match a new configuration if they already exist. It also ensures that the entities are created in the proper order and that they correctly reference each other and existing objects within the Information Model. The end result is a very simple API to accomplish a complex task.

The AspAmf library also contains APIs to query entity state and start and stop them.

=====AmfPy=====

The amfpy library allows a Python program to register itself as an AMF component and therefore receive AMF component control callbacks (start, stop, CSI assignment, etc). Both extending and embedding is supported -- that is Python can either be embedded as a small interpreter into an SAFplus-aware C program, or it can be run standalone and the amfpy functionality can be "import"ed. Python programs can either be spawned automatically by the AMF's component manager, or can be run from the command line (using the asp_run tool provided by the SAFplus Platform) and register with the AMF dynamically.

=====SWIG Interfaces=====

Most OpenClovis SAFplus Platform functions are directly available at the Python interpreter using an automatically generated Python-to-C translation layer. However, it is often inconvenient to use these functions since they correspond one-to-one with equivalent C functions. Additionally if the function uses complex pointer or object relationships (such as forced casting of pointers) it is sometimes very difficult or even impossible to express the parameters in a type-safe language like Python. Therefore it is recommended that this layer only be used if the functionality does not exist in the higher layers.

Doc:Sdk 4.1/awdguide/preface

2009-07-27T15:04:06Z

Suraj:

=='''Preface'''==

''OpenClovis SAFplus Platform Web Director (AWD) User Guide'' provides information about the usage of OpenClovis Web Director, a web-based cluster and chassis management system from OpenClovis Inc. that complements the OpenClovis SAFplus Platform (Application Service Platform). This guide helps you to utilise the OpenClovis Web Director in your own environment.

OpenClovis SAFplus Platform Web Director is designed to simplify and accelerate the development of Telecom application software over OpenClovis platform. It provides a simple and powerful mechanism to examine and modify an online SAFplus Platform cluster, to share critical chassis resources, install and manage new applications, and dynamically modify the SAFplus Platform Information Model.

The OpenClovis SAFplus Platform Web Director is also a "living" case study for customers to use when creating a web-based EMS (element management system) or network management glue layer. It can be easily rebranded to provide essentially an off-the-shelf EMS for SAFplus Platform deployments, customized to provide enhanced EMS functionality, or used as a reference when integrating OpenClovis SAFplus Platform into an existing EMS framework.

===Audience===

OpenClovis SAFplus Platform Web Director (AWD) User Guide is designed for system integrators, designers, and system architects. To use this OpenClovis product, you must be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You must also be familiar with Python programming, the OpenClovis SAFplus Platform product, and have a basic knowledge of Linux.

===Documentation Conventions===

This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table:

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Notation
!style="color:#66b154; background:#09477c"| Description
|- style="color:#ffffff; background:#549cc6"
| style="color:black" | <code><pre>Code</pre></code>
| This font denotes the source code provided in various examples.
|- style="color:#ffffff; background:#549cc6"
|
Cross reference
|
This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the User Guide or a URL link.
A cross reference refers to a section name accesses the first page of that section.
|- style="color:#ffffff; background:#549cc6"
|
'''Bold Text'''
|
Menu items and button names.
|- style="color:#ffffff; background:#549cc6"
|
''Italic Text''
|
Variables for which you enter values.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Related Documentation===

For additional information about OpenClovis products, refer to the following guides:
* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.
* '''OpenClovis Evaluation System User Guide''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''OpenClovis SDK User Guide''' provides information about OpenClovis Application Service Platform (SAFplus Platform) architecture, various OpenClovis SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the OpenClovis SAFplus Platform code to build your custom application.
* '''OpenClovis Log Tool User Guide''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

For additional information about TurboGears, the web application mega-framework used by the OpenClovis SAFplus Platform Web Director please refer to:
* Turbogears web site at http://www.turbogears.org.

===OpenClovis Online Technical Support===

OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum.

===Documentation Feedback===

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Post your feedback on documentation at: http://www.openclovis.org/forum.

Doc:latest/taeguide/testcases

2009-07-01T12:14:48Z

Suraj:

This page contains the list of all test cases which are being run and reported to the report server. It also shows total number of a test case run reported to the report server and success/failure rate per test case.
[[File:TAE_testcases.png|frame|center|'''OpenClovis TAE report server Testcases Page''']]

Doc:latest/taeguide/fixtures

2009-07-01T12:13:56Z

Suraj:

[[File:TAE_fixtures.png|frame|center|'''OpenClovis TAE report server Fixtures Page''']]

Doc:latest/taeguide/models

2009-07-01T12:11:51Z

Suraj:

[[File:TAE_models.png|frame|center|'''OpenClovis TAE report server Models Page''']]

Doc:latest/taeguide/logfiles

2009-07-01T12:10:37Z

Suraj:

*TAE log files and Node postmortem files

[[File:TAE_log_files.png|frame|center|'''OpenClovis TAE Report server Test log files Page''']]

Doc:latest/taeguide/testreport

2009-07-01T12:07:38Z

Suraj:

This page displays the detailed report of test cases run for a particular model. You can reach this page by clicking Go to Report link on project report page.

[[File:Test_report.png|frame|center|'''OpenClovis TAE report server Test Report Page''']]

Doc:latest/taeguide/reports

2009-07-01T12:05:59Z

Suraj:

This page contains the test report of all models with SAFplus Platform revision on which it was run. On this page we have filter based on different parameters like model name, SAFplus Platform revision, model revision, start date and end date. You can use this filter to check the desired report.

[[File:List reports.png|frame|center|'''OpenClovis TAE Report server Reports Page''']]

Doc:latest/taeguide/projectSummary

2009-07-01T12:03:24Z

Suraj:

*This page displays the report of TAE test runs for a particular project. It contains the test run report of all models which are run using TAE. This page a two kind of summary:
** '''Bar Chart:''' It gives the number of reports generated in last 20 days.
** '''Pie Chart:''' It shows two types of test reports for models based on date and revision. It also shows the percentage of test cases which are passed e.g. 79% means 79 % of total test cases are passing, rest are failing or erroring out. If you place the cursor on pie chart It will pop up information of no. of test cases, no. of passes etc. If you click on pie chart it will guide you to full report of the test cases run in that model.

[[File:Project_summary4.0.png|frame|center|'''OpenClovis TAE report server Project Summary''']]

[[File:Project_summary4.0_2.png|frame|center|'''OpenClovis TAE report server Project Summary''']]

Doc:Sdk 4.1/taeguide/projects

2009-07-01T12:00:38Z

Suraj:

This page displays the list of all SAFplus Platform projects for which TAE tests are run. You can click on project name to get the TAE test report.

[[File:TaereportMain.png|frame|center|'''OpenClovis TAE Report server Projects Page''']]

Doc:Sdk 4.1/taeguide/screens

2009-07-01T11:58:48Z

Suraj:

==Screens==

Below is a list of some of the screen shots of various tabs present on OpenClovis Test Automation Environment page:

* [[Doc:sdk_4.1/taeguide/projects | Projects ]]
* [[Doc:sdk_4.1/taeguide/projectSummary | Project Summary ]]
* [[Doc:sdk_4.1/taeguide/reports | Test Reports ]]
* [[Doc:sdk_4.1/taeguide/testreport | Test Report in Detail ]]
* [[Doc:sdk_4.1/taeguide/logfiles | TAE log files and Node postmortem files ]]
* [[Doc:sdk_4.1/taeguide/models | Models ]]
* [[Doc:sdk_4.1/taeguide/fixtures | TAE Fixtures ]]
* [[Doc:sdk_4.1/taeguide/testcases | Testcases ]]

Doc:Sdk 4.1/taeguide/reportserver

2009-07-01T11:57:59Z

Suraj:

TAE report server configuration and monitoring

===Start taereport server ===
<pre>
# cd <TAEBASE>/tae/taereport
# python start-taereport.py
</pre>
You should preferably start this server as a background job.

once TAE report server is started, the interface can be accessed through a browser using URL "http://localhost:5000".

===Server Configuration files and parameters===

*dev.cfg (present in directory <TAEBASE>/tae/taereport) 
It contains several configurations but the configuration which user would be interested is "server port". By default this value is set to 5000

===Report directory===
All TAE reports should be submitted to the directory "<TAEBASE>/tae/taereport/import". taereport server continuously polls for report(s) and if present it processes the report(s) and uploads the processed result(s) to the report server. These reports could be accessed through a browser by opening report server interface using "http://localhost:5000" and then browsing to the correct project and the reports.

* [[Doc:sdk_4.1/taeguide/screens | Screens ]]
** [[Doc:sdk_4.1/taeguide/projects | Projects ]]
** [[Doc:sdk_4.1/taeguide/projectSummary | Project Summary ]]
** [[Doc:sdk_4.1/taeguide/reports | Test Reports ]]
** [[Doc:sdk_4.1/taeguide/testreport | Test Report in Detail ]]
** [[Doc:sdk_4.1/taeguide/logfiles | TAE log files and Node postmortem files ]]
** [[Doc:sdk_4.1/taeguide/models | Models ]]
** [[Doc:sdk_4.1/taeguide/fixtures | TAE Fixtures ]]
** [[Doc:sdk_4.1/taeguide/testcases | Testcases ]]

Doc:Sdk 4.1/taeguide/reportserver

2009-07-01T11:56:49Z

Suraj:

TAE report server configuration and monitoring

===Start taereport server ===
<pre>
# cd <TAEBASE>/tae/taereport
# python start-taereport.py
</pre>
You should preferably start this server as a background job.

once TAE report server is started, the interface can be accessed through a browser using URL "http://localhost:5000".

===Server Configuration files and parameters===

*dev.cfg (present in directory <TAEBASE>/tae/taereport) 
It contains several configurations but the configuration which user would be interested is "server port". By default this value is set to 5000

===Report directory===
All TAE reports should be submitted to the directory "<TAEBASE>/tae/taereport/import". taereport server continuously polls for report(s) and if present it processes the report(s) and uploads the processed result(s) to the report server. These reports could be accessed through a browser by opening report server interface using "http://localhost:5000" and then browsing to the correct project and the reports.

* [[Doc:sdk_4.0/taeguide/screens | Screens ]]
** [[Doc:sdk_4.0/taeguide/projects | Projects ]]
** [[Doc:sdk_4.0/taeguide/projectSummary | Project Summary ]]
** [[Doc:sdk_4.0/taeguide/reports | Test Reports ]]
** [[Doc:sdk_4.0/taeguide/testreport | Test Report in Detail ]]
** [[Doc:sdk_4.0/taeguide/logfiles | TAE log files and Node postmortem files ]]
** [[Doc:sdk_4.0/taeguide/models | Models ]]
** [[Doc:sdk_4.0/taeguide/fixtures | TAE Fixtures ]]
** [[Doc:sdk_4.0/taeguide/testcases | Testcases ]]

Doc:Sdk 4.1/taeguide/runtae

2009-07-01T11:27:20Z

Suraj:

===TAE help===

To know about various TAE options, you can use "tae --help". This provides detailed information about all the TAE options and their usage.
<pre>
# <TAEBASE>/tae/tae --help
</pre>

<pre>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~ OpenClovis Test Automation Environment (TAE) - Version 0.8 ~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Usage:
tae [options] [command]
Options:
-h, --help This help page
fetch
-f, --force Force action despite stamp shows it has been completed in
previous session, but executing unfinished prerequisites
-i, --ignore Ignore prerequisites. Same as -f (--force), but it does not
check for prerequisites. This should be used only if you
specifically want to skip prerequisites.
-q, --quiet Be more quiet (can be issued multiple times)
-v, --verbose Be more verbose (can be issued multiple times)
-s, --suppress
Do not show testcase error details on TAE console output
-u, --unload-tipc
Unload the tipc kernel module before starting SAFplus Platform during the
start stage
-b, --no-nodeinfo
Do not show nodeinfo/bladeinfo for each fixture node. By
default this information is requested and printed for each node
-w <cols>, --width=<cols>
Use this width instead of the actual width of the terminal
when printing results to output
-c, --clean Run a 'make clean' before configure
-r, --revert Run an 'svn revert' on any SVN-based images before running
'svn update' on the tree
--show-config Shows all the config attributes parsed from the config files
and then quits
-o <variable>=[<value>]
Allow manual override of a config attribute
-d Start tae in debug mode. Any Python error will launch a JIT
Python debug (pdb) session, allowing quick code analyzis.
This applies to Python errors in testcases too, which would
otherwise let TAE to continue
-n, --netid Manual override of the TIPC netid that will be used on the
target
-p <port>, --gms-port=<port>
Manual override of the GMS port number used on the target
-m <mcast-ip>, --gms-mcast=<mcast-ip>
Manual override of the GMS multicast IP address
-L, --list List test cases in model
-l <file>, --log=<file>
Put detailed tae log here (default is log/tae.log)
-t <filter>, --testcase-filter=<filter>
Execute test cases matching this filter expression only (by
default all testcases in model are executed). A filter
expression is a testcase identifier, with wildcard characters
also allowed. Examples:
TAE-TST-ACC.TC001
TAE-TST-ACC.TC0??
*-ACC*
*TC001
-T <file>, --testcase-file=<file>
Execute test cases specified in this file. The first word of
each line is treated as a filter expression which will be
matched against testcase ids. Lines started with a comment
character (#) are ignored.
-C <config-file>, --config=<file>
Config file to define the model, fixture, mapping, and other
operational parameters. This information can be provided in
one single file, or can be separated into multiple config
files. To read more than one config file this option can be
used repeatedly. If the same configuration attribute is defined
in more than one file, the last read file takes precedence.
If no config file is specified, tae will attempt to
read all local files with '*.cfg' extensions in alphabetical
order.

Deprecated config file options:
The following four options are still allowed, but their use is deprecated.
Use the -C option instead to read any and all config files.
-E <file>, --environment=<file>
Environment definition config file.
-F <file>, --fixture=<file>
Test fixture config file.
-M <file>, --model=<file>
Model definition config file.
-P <file>, --mapping=<file>
Model node name to fixture node mapping config.

Command:

Command describes what needs to be done in terms of the sequential stages
of a full test run. The following stages are defined (in the order of
progression):

fetch, populate, configure, build, package, deploy, start, test, stop

The following forms are allowed as command:

<stage> Run up to this stage, doing all prerequisites (any previous
stages that were not done yet)

When no command is specified, the last stage (report) is assumed to be the
target stage.

When combined with the -f (--force) option, the command can be in either of
the following forms:

<stage> Redo this stage even if it has been done before. Also do all
prerequisite stages if they have not been completed yet
<stage> Redo all stages from fetch to the named stage, even if all or
some have been done previously.
<stage>: Starting from named stage, redo everything
<st1>:<st2> Redo everything from stage st1 through stage st2

When the -i (--ignore) option used, TAE does not check for prerequisites,
but attempt to run the specified stage or stages. It implies the -f (--force)
option.

The meanings of these stages are:

fetch Fetch model for purpose of test case extract
populate Grab the images and populate working dirs for build
configure Configure the project for target fixture
build Build project for target fixture
package Package project for target fixture deployment
deploy Deploy images to target fixture
start Bring up SAFplus Platform on target fixture
test Run all or selected tests
stop Shut down SAFplus Platform on target fixture

</pre>

===TAE configuration files===
To run TAE with your model, you need to create a directory (rest of the document will refer to this directory using the symbol <TAECFGDIR>). It is generally a good idea to create separate <TAECFGDIR> for testing different models. A <TAECFGDIR> should contain at least following configuration files (these are just sample files, you need to change the configuration according to your requirement):

====mapping.cfg====

<pre>

<map_config ver="1.0.0.0">
<mapping>
<SCNode0 node="node1" role="controller" order="1" asp_dir="/root/simulation/asp1"/>
<SCNode1 node="node2" role="controller" order="2" asp_dir="/root/simulation/asp2"/>
<WorkerNode0 node="node3" role="worker" order="3" asp_dir="/root/simulation/asp3"/>
<WorkerNode1 node="node4" role="worker" order="4" asp_dir="/root/simulation/asp4"/>
<WorkerNode2 node="node5" role="worker" order="5" asp_dir="/root/simulation/asp5"/>
<WorkerNode3 node="node6" role="worker" order="6" asp_dir="/root/simulation/asp6"/>
<WorkerNode4 node="node7" role="worker" order="7" asp_dir="/root/simulation/asp7"/>
<WorkerNode5 node="node8" role="worker" order="8" asp_dir="/root/simulation/asp8"/>
</mapping>
<gms mcast_port="8788" />
<tipc netid="8239" />
</map_config>
</pre>

*Where SCNode0, SCNode1, WorkerNode0, etc are the node instances of the model. You also need to mention the role of the node instance. The "order" field is used to set the order of SAFplus Platform bring up on the nodes. "mcast_port" in gms tag can be used to override the value of "GMS_MCAST_PORT" present in "<model>/src/target.conf" Similarly "netid" in tipc tag can be used to override the value of "TIPC_NETID" (these values will be overridden in the "package" stage of TAE)
*asp_dir attribute is required only when TAE has to run in simulation setup(It deploys the asp images to specified directory), otherwise this attribute has to be removed.

====fixture.cfg====

<pre>
<fixture_config ver="1.0.0.0">
<build_server ip='localhost' os='kubuntu' user='build_user' password='password' />
<nodes>
<node1 ip='10.10.3.10' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node2 ip='10.10.3.20' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node3 ip='10.10.3.30' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node4 ip='10.10.3.40' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node5 ip='10.10.3.50' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node6 ip='10.10.3.60' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node7 ip='10.10.3.90' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node8 ip='10.10.3.100' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
</nodes>
<description>
HP 14-slot chassis with MPCBL0001 cards
</description>
<lockfile value="/home/build_user/run_tae/test_on_hp/hp_chassis.lock" />

</fixture_config>
</pre>

*Normally the build server (where the SAFplus Platform code along with the model is compiled) is localhost (the same machine from where TAE is being run). One can use any other machine on the network for this purpose by specifying the ip, username and password of that machine. <nodes> tag contains the information about the machines where SAFplus Platform will be running during the test run.
*"crossbuild" attribute in node<number> tag is used for the purpose of building the SAFplus Platform binaries for the machine which is architecturally different than the build machine. The value of "crossbuild" attribute should be the name of the toolchain present for that kind of achitecture (located in <sdk-dir>/buildtools/"). If architecture of build and target machine are same, then "crossbuild" field has to be removed.
*lockfile tag can be used to maintain the integrity of the test. Once specified it doesn't allow any other test to use the same fixture. This way you can avoid interrupting an already running test on the same fixture.
*simulation value is used only when tae has to be run in simulation mode i.e. more than one node on same machine.

====model.cfg====

<pre>
<model_config ver="1.0.0.0">
<project value="CLASP3.1" />
<models>
<amsTestGeneric>
<image_source value="dir:~/run_tae/test_on_hp/asptest3.1/" />

<make_options value="AMS_PERF_TEST=1" />
</amsTestGeneric>
</models>

<asp>
<image_source value="dir:~/run_tae/test_on_hp/clasp3.1/" />


</asp>

<testcase_dir value="~/run_tae/test_on_hp/asptest3.1" />

<buildserver>
<sdk_root_dir value="/opt/clovis" />
<asp_dir value="~/run_tae/test_on_hp/clasp3.1" />
<project_dir value="~/run_tae/test_on_hp/asptest3.1" />
</buildserver>


</model_config>
</pre>

* This file contains the model specific configurations like model name, make options, source code directory etc. In the above sample file "amsTestGeneric" is the model name.

* Below are the description of all the tags in the model.cfg file:
** <image_source>: In this attribute, we have to specify the location of SAFplus Platform source code and model directory. This can be any directory on build server (In the example it is ~/run_tae/test_on_hp/clasp3.1/ directory on build server) or it can be the path from where we have to checkout from SVN or any other repository or it can be any link on internet or ftp details.
** <make_options>: In this tag we provide all the flags with which we have to compile the code. In the example above it is AMS_PERF_TEST=1. So, code will be compiled with "make AMS_PERF_TEST=1".
** <testcase_dir>: It is the directory where all test cases of the model will be present.
** <sdk_root_dir>: In this we specify the directory where sdk is installed.
** <asp_dir>: In this we specify the directory where SAFplus Platform is checked out.
** <project_dir>: In this we specify the directory where model is checked out.
** <skip_stages>: By specifying this we can skip some of the steps of complete tae run.

*There are many ways to specify the location of SAFplus Platform source code. "dir:" can be used to specify the local directory as the source code directory for SAFplus Platform in the <asp> <image_source> tag and <model-name><image_source> tag for the model directory.

====env.cfg====

<pre>
<env_config ver="1.0.0.0">
<svn>
<timeout>
<checkout value='10000' />
<update value='10000' />
<revert value='3000' />
<status value='6000' />
</timeout>
</svn>
<report_url value="scp://<user>:<password>@<ip>/<taereport-dir>/import" />

</env_config>
</pre>

*This file contains the timeout values for various TAE operations. After the test run TAE will send the report tarball to the machine specified in <report_url>. Below are the list of all tags used in this config file:
** checkout: It is time in seconds for which tae will wait for checkout to happen before timing out.
** update: It is time in seconds for which tae will wait for svn update to complete before timing out.
** revert: It is time in seconds for which tae will wait for svn revert before timing out.
** status: It is time in seconds for which tae will wait for svn status before timing out.
** report_url: In this we specify the command (to copy) and location where tae report has to be copied.

===Selecting and running the tests===

If following command is issued from the <TAECFGDIR> directory, it lists all the test cases present in the model.
<pre>
# <TAEBASE>/tae/tae -L
</pre>

<pre>
#----------------------------------------------------------------------
# ID State Brief description
#----------------------------------------------------------------------
AMF-CMP-KIL.TC001 E Active Comp Kill Test : Verify SI/CSI assignments after fail-over
AMF-CSI-DEP.TC001 E CSI Dependency Test : Verify CSI assignments order after switch-over
AMF-HA-TST.TC001 E SI Swap Test : Verify SI/CSI assignments after switch-over
AMF-HA-TST.TC002 E SU Lock Test : Verify SI/CSI assignments after switch-over
AMF-NOD-LCK.TC001 E Node Lock Test : Verify SI/CSI assignments after switch-over
AMF-RDN-PRC.TC001 E AMF Reduction Procedure Test : Verify SI/CSI assignments in the reduced mode
AMF-SU-SDN.TC001 E SU Shutdown Test : Verify SI/CSI assignments after switch-over

</pre>

you can then put some of the test cases in a file (say tests.lst) and specify the test-case-filter-file name while running tae using -T switch

<pre>
# <TAEBASE>/tae/tae -T tests.lst -f fetch:stop
</pre>

*Note that the above command should be issued from <TAECFGDIR> directory for the model

*It will execute all the steps from fetch to stop (fetch, populate, configure, build, package, deploy, start, test, stop).

*Some of the steps can be skipped by specifying the stage-name in <skip_stages value="" /> tag present in "model.cfg" file. Alternatively, you can also specify something like "-f build:test" if the requirement is to build the model from already existing code base and then run the test cases.

*If neither of "-t" or "-T" switch is specified, then TAE runs all the test cases present in the "<model>/src/test" directory. One can also use "-t *" to run all the test cases. Remember, the regular expression syntax is supported while specifying the filter for testcases, which can be very handy sometime.

===TAE logs===
TAE log files will be present in "log" directory of your model <TAECFGDIR>. Following log files are created by TAE for various different purposes:

*tae.log : contains detailed log of all the commands executed by the TAE while performing the test.
*bash_127.0.0.1_build_server.log : Contains the logs of commands executed during the SAFplus Platform and model build. It also contains the "make" output in case of build error.
*bash_local.log : Contains the commands performed on the local machine like scp the tarball to the remote nodes etc.
*Node level postmortem files (e.g. SysCtrlI0.postmortem.tgz) : Contains the node level logs as well as the runtime files of the node.

Doc:Sdk 4.1/taeguide/testintg

2009-07-01T11:19:44Z

Suraj:

=== Integration ===

After you have created the model using IDE and generated the source, add a "test" directory just below the model's root (as a peer to "app") and make subdirectories below "test" for your major functional blocks.

==== Python TAE Interface ====
The python testcase files should be present in "<model>/src/test" directory. Since you are probably already programming your test cases in Python using our testcase framework, nothing further need be done.

==== C TAE Interface ====
The Python "layer" for an exclusively "C" implementation is simple :

<pre>
import openclovis.test.testcase as testcase

class test(testcase.TestGroup):

def test_sg006(self):
r"""
\testcase BIC-UTL-BIT.TG001
\brief Test group based on SG "tcSg005Bitmap"
"""
# List of service groups to unlock, Maximum time (in seconds) that the test takes to run
self.run_sg_based_test(['tcSg005Bitmap'], 60)

</pre>

This python file should be present in "<model>/src/test" directory.

You also need to add some test initialization code in clCompAppMain.c of the component. Here is an example of what all you need to initialize/register :

===== Stub1 =====
In the global context of the file clCompAppMain.c, you need to add following code with BEGIN/END block :
<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

int
clTestBitmapRun(ClTcParamListT *param_list)
{
clTestBitmapMain();
return 0;
}

void*
clTcRunThread(void *param)
{
clTcRun();
return NULL;
}

/*
* ---END_APPLICATION_CODE---
*/
</pre>

*Where, clTestBitmapMain() is the main test function (where all the test cases will start their execution). The example code for this function is present in "Testcase Implementation" section.

===== Stub2 =====
In main() function, TC initialize should be done in following way :
<pre>
/*
* Do the application specific initialization here.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
rc = clTcInitialize("Bitmap Utility", "BIT", clTestBitmapRun);
if(CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR, "clTcInitialize() failed, rc : 0x%x", rc);
return rc;
}

/*
* ---END_APPLICATION_CODE---
*/
</pre>

===== Stub3 =====
Before blocking on AMF file descriptor for callbacks, in main() function a thread should be created to run the test in the thread context. Alternatively, you can block on the AMF file descriptor in another thread and let the test run in main thread.

<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
rc = clOsalTaskCreateDetached(NULL, CL_OSAL_SCHED_OTHER,
CL_OSAL_THREAD_PRI_NOT_APPLICABLE,
CL_OSAL_MIN_STACK_SIZE,
clTcRunThread, NULL);

/*
* ---END_APPLICATION_CODE---
*/

/*
* Block on AMF dispatch file descriptor for callbacks
*/
</pre>

===== Stub4 =====
In clCompAppTerminate() finalize the TC in following way :

<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clTcFinalize();

/*
* ---END_APPLICATION_CODE---
*/
</pre>

===== Stub5 =====
In clCompAppAMFCSISet(), call TC activate in SA_AMF_HA_ACTIVE context :

<pre>
switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clTcActivate((ClAmsCSIDescriptorT*)&csiDescriptor, haState);

/*
* ---END_APPLICATION_CODE---
*/

</pre>

Doc:Sdk 4.1/taeguide/testimpl

2009-06-26T12:09:30Z

Suraj:

=== Create your model ===

Create a model using the OpenClovis IDE. Your model can use any redundancy model and contain any number of components and/or service groups. It can expect any number of blades. However, the most common configuration will be 2 system controllers and 0 or more payload blades. It would be best if your model supports this configuration (or fewer) and is capable of utilizing extra blades if they exist.

=== Add your tests ===

There are various ways/options to implement SAFplus Platform testcases:
# Write testcase in C as part of an SAFplus-based component. Such testcases should use the C TAE Interface, see below.
#* Such testcases should be triggered by unlocking AMF entities, typically Service Groups.
#* Such testcases should use the TAE C interface to start and end of testcases, and the result of the testcases.
#* Such testcases will be activated from the TAE robot, using a special 1-line wrapper (explained in "Testcase Integration" section).
# Write testcases purely in Python at the TAE robot side.
#* Such testcase is implemented as a test*.py file.
#* Such testcases can typically do anything that can be done using normal shell access to the target blades and debug CLI access to SAFplus Platform.
#* In the near future, direct access to HPI actions will also be supported.
#* '''It is also possible to invoke C functions in your (test) application from the Python test script, provided that the function is exposed using the SOAP RPC method described with a code snippet below.'''
#* Such testcases may not use the TAE C interface at all.
# The 3rd type of testcase is a mixture of the two extremes above, and implement tests using the C interface, but also have more than just one line code in the Python layer (robot side).

==== When to Use What Approach? ====
When you try to decide what is the best approach for a given testcase, think from a application perspective. Some guidelines:
* If the scenario you want to test is representative of what applications would do, lean more on the C-level implementation. Example:
** An application uses the checkpoint service to save some data, and a standby component is trying to read that data.
* If the scenario has to emulate some artificial external events, use the Python layer to induce the event. Example:
** You need to reset a blade or emulate a kernel crash by invoking some command line commands. Would this code ever be done in a user application? NO! So, you should not (need to) implement this in C, but rather figure out a simple way of doing this from the Python testcase code.
* If the scenario involves artificial sequencing of otherwise randomly occurring events across multiple nodes, the sequencing is better to be left for the Python layer. Example:
** You need to bring some components up, and then crash them in a certain order. Again, you should ask: does the code that crashes the component have a natural place in the application? Would a customer ever write such code as natural part of his application? Hardly. Also, would the sequencing be controlled in C from some other application? No. So, in that case implementing the sequencing and the crash is better to be left to the Python (robot) layer.

==== Python TAE Interface ====
If you plan to implement your tests in a combination of C and Python by invoking some C functions from Python testcase, you must now add the TAE SOAP server and remotely callable functions to your model. For an example of how to do this, please look at the "sysctrlcomp" component in the "bicTests" model in the "asptest" project [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/clCompAppMain.c?root=asptest&rev=946&view=markup here]. This component is untouched except for the addition of 2 remotely callable functions. You must also add the "tae" subdirectory, as seen [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/?root=asptest here]. This is where you define and implement your RPC calls. Finally, you must hook up the Makefiles, so that the "tae" subdirectory is build, as seen [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/Makefile?root=asptest&rev=1270&view=markup here].

Next you must implement your tests in Python, and have them call down to the C layer. This information is best shown by example [[Doc:Sdk_4.0/taeguide/testimpl#Python_test_case | test_lint.py]]

==== C TAE Interface ====
* Any service group instances that run tests MUST be called tcSg<number>[Name]
* For example:
* tcSg001MessagingTest, tcSg034,
** To run 2 service group instances simultaneously use tcSg<same number>[different name]
** For example:
** tcSg001a and tcSg001b, or tcSg005MsgClient and tcSg005MsgServer

=====Include and Library=====

#include <clTestApi.h>

Code is located in the SAFplus Platform utils library (SAFplus/components/utils/...).

=====Summary=====

The module provides a set of functions that are useful while implementing regression tests.

The module creates a hierarchy of tests; a test, a test case, and a test point. The "test" is started/stopped by clTestInitialize/clTestFinalize (clTestStart/End deprecated) and should precede and succeed all other clTest function calls. In general, you'll call these functions once each in your program. Next, within a "test", you are allowed to implement any number of "test cases". A test case is whatever you want it to be, but generally think of it as a grouping based on configuration, load, or strategy. To start/end a test case, use clTestCaseStart/End. You can also use "clTestCase" if your test is a single line (like a function call) -- it's just syntactic sugar.

Finally, individual predicates are called "test points". Use the clTestXXX for these. The basic function is clTest. You essentially pass it a predicate (an expression that evaluates to a boolean) and it checks the truth of that predicate. There is also a similar function that lets you also execute code if the test failed. This is mostly used to skip subsequent test points in a setup where each point requires that the prior succeed. Finally, you can claim that a test succeeded, failed or malfunctioned, without checking any predicate.

Malfunctioned? What's that? A "malfunction" occurs when initial conditions necessary to run the test were not met. For example, let's say you are running a messaging test. The test checks that messaging works between 2 processes on the same blade, and then checks between 2 blades. But what if it is run on a chassis with a single blade? In this case, the test could call TestMalfunction.

=====Context=====

These functions will act differently depending on the context in which they are executed.

* If run independent of a Test Automation Environment (TAE) they will print out consistently formatted messages that can be analysed by scripts. '''To stop the deluge of data, there is a mode that does not print test point successes'''

* If run within a TAE, they will communicate state to the TAE.

Note, some functions ask for formatted strings. Please refrain from using newline or line feeds "\n" or "\l" since these functions will do formatting for you. Also, do not use success or failure words, for example "Failed", "Pass", "Success", or "Ok", since the functions will also add this annotation.

=====Functions=====

<TBD> Available C Test APIs (library : libClTcUtils.a, header file : clTestApi.h, clTcUtilsApi.h)

==== Failover support ====

The Python TAE interface can be used to trigger various failures in the chassis. Organise your tests to use the Python layer.

==== Multi-blade coordination ====

If your test must coordinate the activity of multiple blades then you must use the Python layer. There are rich set of APIs provided by TAE for this purpose.

=== Debug ===

==== Python TAE Interface ====
You can call your Python-to-C functions outside of the TAE with some very simple code. In this example, assume that your RPC function is called "Log", and that you have set the MyPort variable to the TCP port of your TAE server (initialized in your component). Your function will be magically created as a member of the WSDL.Proxy class, so in the example below it will be called in the line "soap.Log(...)".

<pre>
import pdb
from SOAPpy import *
from SOAPpy import WSDL
Config.simplify_objects = 1

MyPort = 8100
soap = WSDL.Proxy("http://localhost:%d/wsdl" % MyPort)

# Call your function. NOTE you MUST use the keyword=value argument format!
print soap.Log(severity=1, area="TST", context="RPC", log="Test the RPC")

</pre>

==== C TAE Interface ====
You can debug your own test by unlocking it as you would a normal application through the debug CLI (asp_console). The output of your test (i.e calls to clTestXXX functions) will be stored in /var/log/testresults.txt.

==Examples==
===Python test case===

*test_lint.py

<pre>

import pdb
import openclovis.test.testcase as testcase

class arbitraryname(testcase.TestCase): # The name of the class does not matter

# This function is executed before each test_xxxx member function is called
def set_up(self):

# self.fixture is a large data structure that models the whole
# chassis or cluster (i.e. all of the machines SAFplus Platform runs on).
fix = self.fixture
# pdb.set_trace()

# Get to the right node in the chassis.
node = fix.nodes["SysCtrl0"]

# Connect to a process on the system controller blade so RPC calls can
# be made. Note that the port 8100 is "well known" for that application.
self.rpc = node.get_rpc("sysctrl", 8100)

# This function is executed after each test_xxxx member function is called
def tear_down(self):
del self.rpc # Clean up my RPC client

def test_doesnotmattername(self): # methods with 'test' prefix are testcases
r"""
\testcase SQA-TAE-REG.TC001
\brief TAE regression test and demo testcase (LINT)
\description
This is a "veterinary horse" kind of a testcase, demonstrating the
various features of the test environment and testing these
features in the same time.
"""

##----------------------------------------------------------------
##
## Logging
##
## .log object
## .log.debug() method
## .log.info() method
## .log.warning() method
## .log.error() method
## .log.critical() method
##
##----------------------------------------------------------------

self.log.debug('This is a sample debug message')
self.log.info('This is a sample info message')
self.log.warning('A sample warning')
self.log.error('A sample error that is recoverable')
self.log.critical('A sample critical error')

##----------------------------------------------------------------
## Local bash access
##
## .tae_host object
## .tae_host.run() method
## .tae_host.run_cmd() method
##
##----------------------------------------------------------------

#
# Running Unix commands on the local host that the tae robot is
# running (this is not part of the fixture), using the pre-opened
# bash session 'tae_host':
#

# Just need output of command. In case of error, an exception is thrown.
# Before using 'run' check for a member function that already implements
# your command. If it exists it will parse the output and return
# 'Pythonized' data (like a list of filenames for 'ls').

# If the member function does not exist, consider writing one!
res = self.tae_host.run('wc -l /etc/passwd')

# res includes the trailing newline; to ignore it, use rstrip()
self.log.debug('Output: %s' % res.rstrip())

# Need both return code and output (does not throw an exception)
rc, out = self.tae_host.run_cmd('wc -l /etc/passwd')
self.log.debug('Return values: rc=[%d] out=[%s]' % (rc, out.rstrip()))

##----------------------------------------------------------------
##
## Build server features
##
## .fixture object
## .fixture.build_server object
## .fixture.build_server.run() method
## .fixture.build_server.run_cmd() method
## .fixture.build_server.scp() method
##
##----------------------------------------------------------------

# Running Unix commands on the build server of the fixture

res = self.fixture.build_server.run('hostname')
self.log.debug('The buildserver is [%s]' % res.rstrip())

# Miscellaneous info about the build server

self.log.debug('Build server IP : [%s]' % self.fixture.build_server.ip)
self.log.debug('Build server login : [%s]' % self.fixture.build_server.user)
self.log.debug('Build server passwd: [%s]' % self.fixture.build_server.password)

# Run scp on the build server to copy in or out something
# Syntax: scp(frm, to, pw) where either frm or to can also include
# a username.
self.log.info('Checking accessibility by ping before attempting scp...')
if not self.fixture.build_server.run_cmd('ping -c 1 10.10.6.1')[0]:
self.fixture.build_server.scp('root@10.10.6.1:.bashrc', '.', 'clovis')

##----------------------------------------------------------------
##
## Fixture target node features
##
## .fixture.nodes object, works as dictionary
## .fixture.nodes.keys() method
## .fixture.nodes.values() method
## .fixture.nodes.items() method
## .fixture.nodes[name].name str
## .fixture.nodes[name].ip str
## .fixture.nodes[name].user str
## .fixture.nodes[name].password str
## .fixture.nodes[name].ping method
##
##----------------------------------------------------------------

# Target node access, based on the model mapping
# Key: self.fixture.nodes is a Python dictionary indexed by the node
# names. Each element is a Node class with a few useful info and
# methods.

# List of node names in the fixture:
node_names = self.fixture.nodes.keys()
self.log.debug('Model node names: %s' % str(node_names))

# To access a given node:
node = self.fixture.nodes['SysCtrl0']

# A few useful values in node:
self.log.debug('Fixture node name : [%s]' % node.name)
self.log.debug('Fixture node ip : [%s]' % node.ip)
self.log.debug('Fixture node login : [%s]' % node.user)
self.log.debug('Fixture node passwd: [%s]' % node.password)

# A few useful methods:
if node.ping(): # ping node from tae server and check if accessible
self.log.debug('Fixture [%s] at [%s] is accessible' %
(node.name, node.ip))
else:
self.log.error('Fixture [%s] at [%s] is not accessible' %
(node.name, node.ip))

##----------------------------------------------------------------
##
## Unix commands on fixture node
##
## .fixture.nodes[name].bash object (session)
## .fixture.nodes[name].bash.run() method
## .fixture.nodes[name].bash.run_cmd() method
##
##----------------------------------------------------------------

# To run a Unix command line command on the fixture node using a
# preinstantiated bash session (this works in the same way as the
# build_server bash session above):
res = self.fixture.nodes['SysCtrl0'].bash.run('df -h . | tail -n 1')
self.log.debug('Disk on fixture node [%s] is [%s] percent full ([%s] available)' %
(node.name, res.split()[4], res.split()[3]))

# Note you must leave this bash session at the Unix prompt!
# For example, do not do .bash.run("tail -f /var/log/asp")
# For this, you can create your own bash session.

shell = self.fixture.nodes['SysCtrl0'].create_bash()
# To start a command that you don't expect to complete:
# expect = shell.start("tail -f /var/log/messages")
# Returned is a pexpect object

##----------------------------------------------------------------
##
## Other generic fixture node methods (also available as methods
## of any bash session)
##
## .fixture.nodes[name].get_pid() method
## .fixture.nodes[name].kill() method
## .fixture.nodes[name].killall() method
##
##----------------------------------------------------------------

# To get list of pids for any running process by given name
pids = self.fixture.nodes['SysCtrl0'].get_pid('bash') # returns a list
self.log.debug('Number of bash sessions: [%d]' % len(pids))
self.log.debug('PID of first bash session: [%s]' %
(len(pids) and pids[0] or 'N/A'))

# To kill a process by pid or process name
node = self.fixture.nodes['SysCtrl0']
node.bash.run('ping localhost > /dev/null & ' * 4) # starting 4 pings
pids = node.get_pid('ping')
self.log.debug('Number of ping sessions: [%d]' % len(pids))

node.kill(pids[0])
node.kill(pids[1], signal=9)
self.log.debug('Number of ping sessions: [%d]' % len(node.get_pid('ping')))

node.killall('ping')
self.log.debug('Number of ping sessions: [%d]' % len(node.get_pid('ping')))

##----------------------------------------------------------------
##
## SAFplus Platform specific fixture node methods
##
## .fixture.nodes[name].asp_running() method
## .fixture.nodes[name].start_asp() method
## .fixture.nodes[name].stop_asp() method
## .fixture.nodes[name].restart_asp() method
##
##----------------------------------------------------------------

# Check if SAFplus Platform is running and start it if not

# Note, the framework starts the SAFplus Platform before running your test case,
# so you can assume that the SAFplus Platform is running. That is, you don't
# need to call this function, unless your test shuts down SAFplus Platform.

if self.fixture.nodes['Worker0'].asp_running():
self.log.debug('SAFplus Platform is running on the node already')
else:
self.fixture.nodes['Worker0'].start_asp()

# Bring down SAFplus Platform and then back
if self.fixture.nodes['Worker0'].asp_running():
self.log.debug('Stopping SAFplus')
self.fixture.nodes['Worker0'].stop_asp()
self.fixture.nodes['Worker0'].start_asp()

# Restart SAFplus Platform in a single command
self.fixture.nodes['Worker0'].restart_asp()

##----------------------------------------------------------------
##
## Fixture-wide methods
## Note that all fixture-wide methods have node equivalents that
## have the same name but are members of the 'node' object.
##
## .fixture.start_asp() method
## .fixture.stop_asp() method
## .fixture.restart_asp() method
##
##----------------------------------------------------------------

# Stopping SAFplus Platform on all nodes
### self.fixture.stop_asp()

# Starting up SAFplus Platform on all nodes
### self.fixture.start_asp()

# Restarting SAFplus Platform on all nodes
# Does it wait?
### self.fixture.restart_asp()

# self.fixture.wait_until_asp_up(50) # TBD,

##----------------------------------------------------------------
##
## Test case python script debugging
##
## pdb.set_trace() method
##
##----------------------------------------------------------------
##
## To get the python debugger break during test execution, issue the
## pdb.set_trace() call ANYWHERE IN YOUR TESTCASE code. To check this
## feature out, uncomment the two lines below
##

#import pdb
#pdb.set_trace()

##----------------------------------------------------------------
##
## Debug CLI access
##
## .fixture.has_debug_cli() method
## .fixture.start_debug_cli() method
## .fixture.debug_cli.root() method
## .fixture.debug_cli.run() method
##
##----------------------------------------------------------------

# All "get_xxx" functions return a cached version if it exists or create
# if it does not.
# All "create_xxx" functions create a new one and pass it back to you.

# In the case of the debug CLI, there can be only 1 instance, so there
# is no "create" function.
dbgcli = self.fixture.get_debug_cli()

# Run some native debug cli commands:
dbgcli.run('setc 1')
dbgcli.run('setc cpm')

# You may also use the fixture variable debug_cli, if you are sure
# that it is valid.
res = self.fixture.debug_cli.run('compList')
self.log.debug('First 20 partial lines of component list:')
for line in res.splitlines()[:20]:
self.log.debug('>> %-65s ...' % line[:60])

##----------------------------------------------------------------
##
## Determining test result
##
## Test ERROR is not the same as a FAIL-ed test
##
## The former means the test is not conclusive because the test
## procedure itself could not be completed dur to some errors.
## The latter means the test subject failed the test.
##
## Test errors: any unhandled Python exception that occurs during
## running the testcase will be regarded by the test
## framework as a test error and the failure of the
## Test failure: test failures are generated when an explicit
## verification of some result produces a negative
## result. These types of check are done using one of
## the following method calls:
##
## .assert_true(condition [, failure info])
## .assert_false(condition [, failure info])
## .assert_equal(value1, value2 [, failure info])
## .assert_not_equal(value1, value2 [, failure info])
## .assert_almost_equal(value1, value2 [, failure info])
## .assert_not_almost_equal(value1, value2 [, failure info])
## .assert_raises(exception [, failure info])
##
## These are demonstrated in separate testcases below not as part
## of this LINT testcase
##
##----------------------------------------------------------------

def test_always_errors1(self):
r"""
\testcase SQA-TAE-REG.TC002
\brief This testcase should always produce an ERROR
"""
l = [0, 1]
print l[100] # index is out of range, will generate a python exception

def test_always_fails(self):
r"""
\testcase SQA-TAE-REG.TC003
\brief This testcase should always produce a FAIL
"""
self.assert_equal(1, 10, 'This test is failed purposely')

def test_well_documented(self):
r"""
\testcase SQA-TAE-REG.TC004

\brief This is a well documented testcase example

\description
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

\state enabled

\prerequisites
* SC0 is accessible
* OS booted on system controller
* Python test environment (with PyOpenHPI) is available on SC0
* IP address to shelf manager is know as SHMGR_IP environment variable

\steps
1 start test application which will attempt to setup HPI session and
wait till its output is printed

\criteria
\li HPI session open returns with success
"""
pass # always passes

def test_unimplemented(self):
r"""
\testcase SQA-TAE-REG.TC005

\brief Unimplemented testcase (always errors out)
"""
self.log.debug('This is an unimplemented testcase')
raise testcase.TestcaseNotImplemented

def test_with_measurement(self):
r"""
\testcase SQA-TAE-REG.TC006

\brief Testcase example with measurements

\description
This measures two attributes, as described below.

\measured
\data FREE_DISK_SPACE [MB] Free disk space on first node
\data RANDOM_NUMBERS [] Random numbers in [0, 1) interval
\data ASP_STARTUP_TIME [ms] Ping latency between two nodes

"""
##----------------------------------------------------------------
##
## Measurements related stuff
##
## openclovis.test.bin module
## openclovis.test.bin.Bin() class
## openclovis.test.bin.Bin.record() method
## .report_data() method
##
##----------------------------------------------------------------

import openclovis.test.bin as bin

# Free disk space example
raw_data = self.fixture.nodes['SysCtrl0'].bash.run('df -m . | tail -n 1')
free_space = int(raw_data.split()[3])
self.report_data(bin.Bin('FREE_DISK_SPACE', free_space, unit='MB'))

# Random number measurement
import random
array = [random.random() for foo in range(10000)]
self.report_data(bin.Bin('RANDOM_NUMBERS', array, fmt='%6.4f'))

# Step-by-step data collection
data = bin.Bin('ASP_STARTUP_TIME', unit='s')
import time
self.log.info('Measuring SAFplus Platform startup time, using 5 runs')
if self.fixture.nodes['Worker0'].asp_running():
self.fixture.nodes['Worker0'].stop_asp()
for i in range(5):
start_time = time.time()
self.fixture.nodes['Worker0'].start_asp()
stop_time = time.time()
data.record(stop_time - start_time)
self.fixture.nodes['Worker0'].stop_asp()
self.log.debug('- Iteration %d done' % (i+1))
self.report_data(data)

def test_with_rpc(self):
r"""
\testcase SQA-TAE-REG.TC007
\brief Testcase example with RPC calls

\description
This runs 2 functions on the target within a particular process.
To see the server side implementation, look at:
SAFplus/models/unitTests/app/sysctrlcomp/tae

\measured
\data Length of a task delay.
"""
# This example shows passing strings.
self.rpc.Log(severity=1,area="TST",context="LNT", log="Testing the RPC mechanism. This log actually originated from the test_lint.py script running on the TAE.")

# This example shows how a complex data structure can be returned.
ret = self.rpc.TaskSleep(sec=3,msec=0)
self.log.info("Raw data received from RPC call: %s" % str(ret))
self.log.info('Sleep of 3 seconds was measured (on the node) as taking %d ms' % ((int(ret["sec"]) * 1000) + int(ret["msec"])))

def test_disabled(self):
r"""
\testcase SQA-TAE-REG.TC008
\brief Disabled testcase
\state disabled
"""
self.log.critical('You should never see this testcase executed by TAE')

</pre>

===C testcase (SG based)===

*testBitmap.c

<pre>

void TC2_BitMap(void)
{
ClBitmapHandleT bitHdl = CL_BM_INVALID_BITMAP_HANDLE;
ClRcT rc = CL_OK;
ClRcT retVal = CL_OK;
ClUint32T bitCount= 0;
ClUint32T bitNum = 0;

for(bitCount = 3, bitNum = 1; bitCount <= 100; bitCount += 2, bitNum++)
{
clTestCaseMalfunction(
("Bitmap create"),
(rc = clBitmapCreate(&bitHdl, bitCount)) == CL_OK,
return);

clTest(("Bitmap set bit [%d]", bitNum),
(rc = clBitmapBitSet(bitHdl, bitNum)) == CL_OK,
("Error: rc[0x %x]", rc));

clTest(("Bitmap is bit[%d] set?", bitNum),
(((clBitmapIsBitSet(bitHdl, bitNum, &retVal))
== CL_BM_BIT_SET) && CL_OK == retVal),
("Error: rc[0x %x]", retVal));

clTest(("Bitmap set bit [%d]", (bitNum + 2)),
(rc = clBitmapBitSet(bitHdl, (bitNum + 2))) == CL_OK,
("Error: rc[0x %x]", rc));

clTest(("Bitmap is bit[%d] set?", (bitNum + 2)),
(((clBitmapIsBitSet(bitHdl, (bitNum + 2), &retVal))
== CL_BM_BIT_SET) && CL_OK == retVal),
("Error: rc[0x %x]", retVal));

clTest(("Bitmap destroy"),
(rc = clBitmapDestroy(bitHdl)) == CL_OK,
("Error: rc[0x %x]", rc));

}

}

void
clTestBitmapMain(void)
{

clTestGroupInitialize(("Test of Bitmap utility"));

clTestCase(("BIC-UTL-BIT.TC003 Set Bits in a bitmap and Verify whether the bits are set"),
TC2_BitMap());

(void) clTestGroupFinalize();

}

</pre>

* This example shows just one test case of many that can appear in a single service group. To make this example a "fully" runnable standalone test, you would have to call clTestGroupInitialize and clTestGroupFinalize functions before and after calling a set of clTestCase().

*When a service group is assigned work (a CSI) this should trigger your test to run. When your test is complete it should simply wait until the work is unassigned. Also, the service group should be modeled to be in lock assigned mode.

* Your tests must call the functions in the Test API defined in "clTestApi.h". You can also use the Test Lifecycle APIs defined in "clTcUtilsApi.h" to facilitate starting test cases with different parameters.

Doc:Sdk 4.1/taeguide/deppkg

2009-06-26T12:08:30Z

Suraj:

==Deployment and Packaging==
The OpenClovis TAE is provided in the form of a gzipped tar file (.tar.gz). You can open this file (tar xvfz <filename>) in directory (as "root" user). It will create a directory called openclovis-tae-<version>. The rest of this document will refer to this directory using the symbol <TAEBASE>. This directory should contain following files/directories :
*README.txt
*Python-2.5.2.tgz
*setuptools-0.6c9.tar.gz
*TG_setup_files.tgz
*tae (directory)

==Steps to install TAE==

* Install Python-2.5.2
# tar zxvf Python-2.5.2.tgz
# cd Python-2.5.2
# ./configure
# make
# make install

* Install setuptools (required for easy_install used in next step)

# tar zxvf setuptools-0.6c9.tar.gz
# cd setuptools-0.6c9
# python setup.py install

* Install Turbougear and tae-report server dependent packages

# tar zxvf TG_setup_files.tgz
# cd TG_setup_files
# easy_install -Hlocalhost *.egg

* Install tae 3rdparty packages

# cd tae/3rdparty/
# make install

* Build initial database

# cd taereport
# rm devdata.sqlite*
# tg-admin sql create

* Run

# iptables -F # Turn off firewall needed on some linux distributions (or you can edit your firewall settings to let TAE through)
# python start-taereport.py

* Set up database

#Open browser, and go to <taeserver>:5000/catwalk
#Click project->Add project
#Status: 1
#Description: <anything>
#Created: <leave>
#Brief: <anything>
#Label: <specify the project name that appears throughout the rest of the TAE reports>
#anonymous_view: <specify 1 to allow anonymous users>

* All Done!

#Use TAE report server: Open browser, and go to <taeserver>:5000

* Next steps:

# Read and follow the OpenClovis TAE user/programming guide
# Start running tests and upload them to <taeserver>/<taedirectory>/taereport/import

Doc:Sdk 4.1/taeguide/overview

2009-06-26T12:06:42Z

Suraj:

== Organization ==

The TAE is organized following the [http://en.wikipedia.org/wiki/Matryoshka_doll Matryoshka principle] in that each facility requires all "smaller" facilities, yet any particular facility and all "smaller" facilities comprises a working automation environment (albeit missing the features provided by the "larger" facilities) and is useful in certain circumstances.

The purpose of this organization is most importantly to create an incremental development schedule that will yield a usable test framework rapidly and a fully-featured one when those features are required.

Another extremely important purpose is to allow the automation environment to be run in a variety of different situations and by a variety of different users. For example, it could be run by an automated nightly verification system (layer 3), or by a developer fixing a bug (layer 1,2). It could be run by an OpenClovis engineer (layer 1,2 or 3), or by a customer who is verifying compatibility with his hardware (layer 3).

Lastly, it is designed to allow programs written for a variety of purposes -- test, demo, eval, and real systems -- to be run. Traditionally automated test frameworks are so encompassing that the only software that can be run are test suites designed from the bottom-up to fit within the automated test framework. This framework allows software that was not written for the express purpose of testing to be annotated with compile-time optional tests (similar to assert()) that can be used to verify the correct execution of that software.

Each layer is summarized in this document and contains a link to a detailed design.

=== Layer 1: C program API (Clovis Test API) ===

The smallest layer is the API used in a program to run tests. This layer consists of a set of C macros that group and run tests. When not testing, these macros can be compiled out. This is very similar to unit testing packages found for many languages.

If this layer is run alone, it will simply print test successes and failures to the screen.

When run within the layer 3 framework, test successes and failures will be posted to the TAE report server.

=== Layer 2: Python based testing (using APIs provided by TAE)===

This is another layer to write test programs in python and run tests. Here the test program uses the rich set of APIs (written in python) present in the TAE infrastructure. This layer provides multiple utilities to run tests in a distributed environment.

If this layer is run alone, it will simply print test successes and failures to the screen.

When run within the layer 3 framework, test successes and failures will be posted to the TAE report server.
=== Layer 3: Test Execution Management and Event Simulation ===

The Test Execution Management and Event Simulation (TEMES) layer consists of a separate machine (test driver) that controls the test "fixture" (the set of machines that constitute a test environment). It is capable of taking software from either a local directory, a ftp site, an http site or from subversion repository, unpacking it (if needed), installing it on the fixture, compiling it, and running a series of tests.

These tests primarily constitute executable programs that use the Layer 1 and 2 APIs, and conform to a loose modeling format.

Additionally, a test-specific scripts may be run on the TEMES that can "drive" the progress of the test and cause events such as process, network, and machine failures.

If this layer is run alone, it will run through a complete test suite and report successes and failures.

=== Layer 4: Automated Run and Longitudinal Reports ===

The Automated Run and Longitudinal Reporting (ARLR) layer consists of a single globally accessible server (ARLR server) and a source repository (subversion etc). The ARLR server contains a web site that allows users to see which source code branches are failing which tests on what hardware and it keeps a history of this information. It also will communicate with unused (or layer 3 dedicated) test drivers to schedule runs of a set of test suites against a set of branches and receive results from these drivers.

Doc:Sdk 4.1/taeguide/preface

2009-06-26T12:04:59Z

Suraj:

=='''Preface'''==

''OpenClovis Test Automation Environment (TAE) User Guide'' provides information about the usage of OpenClovis TAE. TAE provides an infrastructure to allow comprehensive system and unit tests to be written and executed easily. It also contains a web-based test report server for permanent storage and retrieval of test reports. This guide helps you to utilize the OpenClovis TAE in your own environment.

OpenClovis TAE is designed to simplify and accelerate the testing of Telecom application software over OpenClovis platform. It also provides a simple and powerful mechanism to coordinate the activities of multiple blades of a chassis or multiple systems in a network.

===Audience===

OpenClovis TAE User Guide is designed for system integrators, developers, and testers. To use this OpenClovis product, you must be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You must also be familiar with Python programming, the OpenClovis SAFplus Platform product, and have a basic knowledge of Linux.

===Documentation Conventions===

This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table:

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Notation
!style="color:#66b154; background:#09477c"| Description
|- style="color:#ffffff; background:#549cc6"
| style="color:black" | <code><pre>Code</pre></code>
| This font denotes the source code provided in various examples.
|- style="color:#ffffff; background:#549cc6"
|
Cross reference
|
This font denotes a hyper link. You can click on the hyper link text to access the reference location, which can be either a section within the User Guide or a URL link.
A cross reference refers to a section name accesses the first page of that section.
|- style="color:#ffffff; background:#549cc6"
|
'''Bold Text'''
|
Menu items and button names.
|- style="color:#ffffff; background:#549cc6"
|
''Italic Text''
|
Variables for which you enter values.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Related Documentation===

For additional information about OpenClovis products, refer to the following guides:
* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.
* '''OpenClovis Evaluation System User Guide''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''OpenClovis SDK User Guide''' provides information about OpenClovis Application Service Platform (SAFplus Platform) architecture, various OpenClovis SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the OpenClovis SAFplus Platform code to build your custom application.
* '''OpenClovis Log Tool User Guide''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

For additional information about TurboGears, the web application mega-framework used by the OpenClovis SAFplus Platform Web Director please refer to:
* Turbogears web site at http://www.turbogears.org.

===OpenClovis Online Technical Support===

OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum.

===Documentation Feedback===

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Post your feedback on documentation at: http://www.openclovis.org/forum.