== Environment Variables ==

=== Logging ===

* CPM_LOG_FILE_SIZE
This variable defines the maximum size of the stdout (console) log. Use a number + K for kilobytes, M for megabytes and G for gigabytes.

Example:
<pre>
export CPM_LOG_FILE_SIZE=100K
</pre>

* CPM_LOG_FILE_ROTATIONS
This variable defines the number of log files (i.e) name1.log name2.log, etc to use before restarting the count.

Example:
<pre>
export CPM_LOG_FILE_ROTATIONS=100
</pre>

* ASP_STDOUT_LOGFILE (deprecates ASP_CPM_LOGFILE) [version 5.1+]
This variable overrides the log file name. Use either an absolute path (beginning with /) or a path relative to the ASP log directory.
The special name "console" will output to the console instead of a file. 
Note, setting this variable to "console" is equivalent starting with the command "etc/init.d/asp consolestart".

Example:
<pre>
export ASP_STDOUT_LOGFILE=/tmp/stdoutlog.txt
export ASP_STDOUT_LOGFILE=stdoutlog.txt
export ASP_STDOUT_LOGFILE=console
</pre>

* CL_LOG_CODE_LOCATION_ENABLE

Adds file/line to each log message, so logs can be tracked in the source code

Example:
<pre>
export CL_LOG_CODE_LOCATION_ENABLE=1
</pre>

* CL_LOG_TIME_ENABLE

Adds a timestamp to each log message (default is true)

Example:
<pre>
export CL_LOG_TIME_ENABLE=0
</pre>

=== Debugging ===

* ASP_NODE_REBOOT_DISABLE

Disable reboot of nodes, even if the AMF HA algorithm determines a reboot is necessary.

export ASP_NODE_REBOOT_DISABLE=1

* ASP_NODE_RESTART

Restart the SAFplus on node recovery, rather then wait for operator intervention.

export ASP_NODE_RESTART=1

* CL_LOG_TO_FILE

Sends all logs to a file or stdout. This environment variable is very helpful when debugging problems that occur before the SAFplus log server has started. For example:
export CL_LOG_TO_FILE=stdout
export CL_LOG_TO_FILE=/var/log/mylog.txt

Switch your model/image from TIPC to UDP

2016-05-09T13:08:45Z

Stone: /* FAQ / Troubleshooting */

UDP can be run in two modes -- local or cloud. In local mode, the UDP system uses multicast to find members of the cluster and auto-assigns non-routable IP addresses onto an alias of your chosen backplane network interface. The advantage of local mode is that no IP addresses need to be configured.

In cloud mode, it is assumed that the cluster is potentially running across the entire internet (no multicast) on machines with specified IP addresses. Since no initial discovery is possible, every node needs to be configured with the IP addresses of the two system controller nodes.

== Changing Your Model from TIPC to UDP ==
=== Step 1 ===
- If you have a pre-60 model you will need to upgrade it. Using the IDE open your model, every option will be grey except model->update. This update will generate a configuration file called <your model>/config/clTransport.xml that looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>TIPC</type>
<plugin>libClTIPC.so</plugin>
</xport>

</xports>

</multixport>
</version>
</openClovisAsp>

=== Step 2 ===
Edit the content clTransport.xml with the UDP configuration details, and remove the TIPC details:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<multicast address="226.0.1.1" port="9595" />
<heartbeat>
<interval>3000</interval>
<intervalLocal>3000</intervalLocal>
<retries>5</retries>
</heartbeat>
</multixport>
</version>
<openClovisAsp>

=== Step 3 (Local mode) ===
Add 2 environment variables into <model_dir>/src/target.env, or make sure these variables are defined before starting SAFplus:

export ASP_UDP_SUBNET=<IP Range>/Length
export ASP_UDP_LINK_NAME=<your interface>

*'''Example:'''

export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

=== Step 3 (Cloud mode) ===
To use the UDP transport without node discovery (multicast) or IP address assignment, you must:

1. Add these 2 environment variables into <model_dir>/src/target.env, or make sure these variables are defined before starting SAFplus:

ASP_UDP_USE_EXISTING_IP=true

ASP_UDP_LINK_NAME=<link name, for example 'eth0'>

2. Configure UDP peer addresses like this:
<code>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</code>

The following is a this complete example of a cloud mode configuration file:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<heartbeat>
<interval>1000</interval>
<intervalLocal>1000</intervalLocal>
<retries>4</retries>
</heartbeat>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</multixport>
</version>
</openClovisAsp>
</code>

=== Before or After "make images"? ===
clTransport.xml and target.env can be changed before the "make images" step so all generated images are UDP by default OR these files can be changed on every node after deployment.

== FAQ / Troubleshooting ==

=== Q: Is the SAFplus able to run in UDP local mode as a non-root user? ===
* A: Yes, but you must properly configure the interfaces since SAFplus cannot.
Configure interface name (ASP_UDP_LINK_NAME) with the IP address calculated from your subnet and node address (ASP_UDP_SUBNET.DEFAULT_NODEADDR). The node address is the DEFAULT_NODEADDR settings from etc/asp.conf file.

Example:
root:#ifconfig eth0 192.168.57.1
user:#export ASP_UDP_SUBNET=192.168.57.0/24
user:#export ASP_UDP_LINK_NAME=eth0
user:#./etc/init.d/safplus start

=== Q: In UDP LAN mode, nodes do not discover each other ===

You can determine this by running bin/safplus_info command "nodes" to see what nodes are alive.

* A: UDP broadcast packets are being dropped. This could be a router configuration, but is more likely a configuration in your Linux distribution's firewall software. Disable the firewall or add rules to allow UDP broadcast. How do to this depends on your distro:
Examples:
Centos 7: systemctl stop firewalld
Ubuntu: service iptables stop

=== Q: In UDP mode, the software still tries to load the TIPC kernel module ===

* A: TIPC is still specified as a backup communications protocol. Edit etc/clTransport.xml (on all nodes) and remove the <xport><type>TIPC ... </xport> block. Also edit etc/asp.conf and set "export BUILD_TIPC=0" (rather than =1).

Switch your model/image from TIPC to UDP

2016-05-09T13:02:50Z

Stone: /* FAQ */

Doc:latest/sdkguide/commandref

2014-10-29T01:09:25Z

Stone: undo spam

==SAFplus Platform Command Line and Environment Variable Reference==

===Environment Variables===

====Variables controlling automatic restart or reboot of SAFplus Platform or Node====
* '''ASP_RESTART_SAFplus''' -- If set to 1 will restart SAFplus Platform in case AMF crashed or SAFplus Platform was not able to come up for some reason, if set to 0 will not restart SAFplus Platform. Default value is 1.
* '''ASP_NODE_REBOOT_DISABLE''' --
* '''ASP_NODE_RESTART''' --

 
This table describes the interaction between the various SAFplus Platform restart and reboot variables:
{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| ASP_NODE_REBOOT_DISABLE
!style="color:#66b154; background:#09477c"| ASP_RESTART_SAFplus Platform
!style="color:#66b154; background:#09477c"| ASP_NODE_RESTART
!style="color:#66b154; background:#09477c"| Action taken
|- style="color:#ffffff; background:#549cc6"
| undefined
| undefined
| undefined
| reboot
|- style="color:#ffffff; background:#549cc6"
| 1
| undefined
| undefined
| Restart SAFplus Platform
|- style="color:#ffffff; background:#549cc6"
| 1
| 0
| undefined
| SAFplus Platform stopped
|- style="color:#ffffff; background:#549cc6"
| 1
| 0
| 1
| Restart SAFplus Platform
|}

====Cluster Membership Configuration (GMS)====
* '''CL_LEADER_NODE_ID''' --
* '''LINK_NAME''' -- This tells SAFplus Platform which Network Interface (ex. eth0, bind0, lo, etc.) to be used for communication with other SAFplus Platform's on same/other nodes.
* '''ASP_MULTINODE''' -- This environment variable must be used, when multiple SAFplus Platform's are to be run on single machine. Then user must export this environment variable before starting each of SAFplus Platform's.

====ValGrind====
* '''ASP_VALGRIND_FILTER''' --
* '''ASP_VALGRIND_CMD''' --

====Logging====

* '''ASP_LOG_FILTER_DIR''' -- place where log filter file should be present. It should be named logfilter.txt. Default value /tmp
* '''CL_LOG_SEVERITY''' -- Environment variable used to set the log filter. You can export this env variable to any log severity like DEBUG, INFO, NOTICE, ERROR, etc. Note that setting of this env variable has higher priority than the log filter file explained above.
* '''CL_LOG_CODE_LOCATION_ENABLE''' -- Environment variable if set to 1, will show the file name, function name and line number when displaying logs. Default value is 0.
* '''CL_LOG_TO_FILE'''
* '''CL_LOG_STREAM_ENABLE'''
* '''CL_LOG_TIME_ENABLE'''
* '''CL_LOG_DEBUG_LEVEL''' (clLogDebug.c)
* '''ASP_SAVE_PREV_LOGS''' -- if set to 1 will save logs in the sandbox from the previous run of SAFplus Platform (if any) during SAFplus Platform startup into location specified by the environment variable ASP_PREV_LOG_DIR or to /tmp/asp_saved_logs, creating the directory if necessary. If set to 0, the logs will deleted. Default value is 1.
* '''ASP_PREV_LOG_DIR''' -- place where logs of previous SAFplus Platform run will be stored. Default value is /tmp/asp_saved_logs
* '''AMS_DEBUG''' -- Enable special availability management framework console logging. This occurs outside of the normal log infrastructure since the AMF process manages the logging process.
* '''AMS_NOTIFICATION_DEBUG''' --
* '''CPM_LOG_FILE_SIZE''' --
* '''CPM_LOG_FILE_ROTATIONS''' --
* '''ASP_CPM_LOGFILE''' --

====Miscellaneous====
* '''ASP_RMD_METRIC''' --
* '''CL_TXN_DSBLE_CKPT''' --
* '''CL_HEAP_DEBUG''' --
* '''CL_MEM_TIME''' --
* '''ASP_WITHOUT_CPM''' --
* '''CL_NODE_REPRESENTATIVE''' --
* '''ASP_DB_SYNC''' --

====Debugging====
* '''CL_DEBUG_PAUSE''' --
* '''CL_DEBUG_PAUSE_CODE_ERROR''' --
* '''CL_DEBUG_COMP_NO_KILL''' --
* '''CL_DEBUG_COMP_TIMEOUT_OVERRIDE''' --
* '''CL_DEBUG_LOG_LEVEL''' --
* '''CL_DEBUG_RESOURCE_LOG_LEVEL''' --
* '''CL_DEBUG_REVERSE_TIMING''' --

====Intra-Cluster Message Traffic Shaping====
OpenClovis SAFplus Platform optionally uses a well known traffic shaping algorithm to modulate intracluster traffic. This is very useful if the internal communications between your applications can potentially overwhelm an application with requests. But if your application's inter-communication is designed to ensure that this cannot happen then the traffic shaping is not needed. By default (compile time) it is off.

These environment variables can be used to override the default leaky bucket intra-cluster message shaping parameters.
* '''CL_LEAKY_BUCKET_VOL''' -- Leaky bucket volume in bytes
* '''CL_LEAKY_BUCKET_LEAK_SIZE''' -- Leaky bucket removal in bytes
* '''CL_LEAKY_BUCKET_LEAK_INTERVAL''' -- How often the leak occurs in milliSeconds

===Environment Variables Set by OpenClovis SAFplus Platform===
These variables are available for use in your application:

====Locations====
Note these environment variables have equivalent "C" global variables (defined in clEoApi.h) which are recommended over using the environment variable directly.

* '''ASP_NODENAME''' -- The name of the node (as defined in the SAF AMF model)
* '''ASP_COMPNAME''' -- The name of this component (as defined in the SAF AMF model)
* '''ASP_RUNDIR''' -- The "current working directory" SAFplus Platform runs from
* '''ASP_LOGDIR''' -- The SAFplus Platform log directory
* '''ASP_BINDIR''' -- The location of SAFplus Platform binaries
* '''ASP_APP_BINDIR''' -- The location of the program binary. This is often, but not always the same as ASP_BINDIR.
* '''ASP_CONFIG''' -- Directory of the SAFplus Platform configuration files (normally <asp install dir>/etc)
* '''ASP_CPM_CWD''' -- The current working directory to use for SAFplus Platform and programs started by SAFplus Platform (defaults to var/run)
* '''ASP_DBDIR''' -- The location the SAFplus Platform stores its database files

===Starting and Stopping SAFplus Platform: <aspDir>/etc/init.d/asp===
Usage : asp {start|stop|restart|console|status|zap|help} [options]

options can be one of the following : (these options only work with start command, e.g. etc/init.d/asp start -v etc.)

-v : Be verbose
--enforce-tipc-settings : Use etc/asp.conf's TIPC settings overriding the system TIPC settings
--ignore-tipc-settings : Use systems TIPC settings ignoring the etc/asp.conf's settings
--remove-persistent-db : Delete all of the SAFplus Platform persistent database files
--asp-log-level <level> : Start SAFplus Platform with particular log level. <level> is [trace|debug|info|notice|warning|error|critical]

===CLI===

====bin/asp_console====
SAFplus Platform console is a comprehensive CLI for examination and debugging of the SAFplus Platform system. SAFplus Platform console documentation is available as a separate document.

Start:
<aspDir>/etc/init.d/asp console
or
<aspDir>/bin/asp_console

====bin/asp_info====
The SAFplus Platform info CLI is a simple interface for display of SAFplus Platform status and basic control

<aspDir>/bin/asp_info

===Directly running a component: bin/asp_run===

Doc:latest/sdkguide/commandref

2014-10-29T01:07:37Z

Stone: Reverted edits by MediaWiki spam cleanup (talk) to last revision by 176.8.88.41

http://www.buyxanaxitem.com/ xanax to buy - xanax

Doc:latest/relnotes

2014-02-17T22:43:39Z

Stone: /* Porting Prior Models to 6.1 */

=='''Preface'''==

Welcome to ''OpenClovis Release Notes''. This document provides information about the details of the platforms on which OpenClovis SAFplus Availability/Scalability Platform (the SAFplus Platform for short) and Integrated Development Environment (IDE) have been tested and validated for SDK Release 6.0. It contains the additional features and enhancements of the product since the previous release. It also summarizes the known issues and limitations of the product and provides workaround wherever applicable.

===Key Topics===

''OpenClovis Release Notes'' covers the following topics in details:
*Tested Platforms
*What Is New
*Migration To Latest Version
*Known Issues
*Environment Related Observation
*Documentation Issues

===Audience===

''OpenClovis Release Notes'' addresses system integrators, designers, and system architects. To use SAFplus Platform, you must be aware of the fundamentals of operation, management, and configuration of telecom and networking domains. You must also be familiar with C programming, UML notations, and have 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" align="center" width="680"
|- 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 C 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 and 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 Documents===

For additional information about OpenClovis products, refer to the following guides:
* '''SAFplus Platform 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.
* '''SAFplus Platform Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''SAFplus Platform Sample Application Tutorial''' explains 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 SAFplus Platform offering.
* '''SAFplus Platform 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.
* '''SAFplus Platform SDK User Guide''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''SAFplus Platform IDE User Guide''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''SAFplus Platform 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.
* '''SAFplus Platform 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.
* '''SAFplus Platform Console Reference Guide''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===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. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

=='''Tested Platforms'''==

This chapter provides the details of the platforms on which OpenClovis SAFplus Platform have been tested and validated.

{| border="0" cellpadding="3" align="center" width="800"
|+ align="bottom" | '''Tested Platform Configurations'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c" width="150"| Platform
!style="color:#66b154; background:#09477c"| Configuration
|- style="color:#ffffff; background:#549cc6"
|
Hardware
|
* ATCA 5U Chassis - Schroff, ASIS
* ATCA 12U Chassis - Schroff, Sanmina, HP, Sun Netra, Radisys, Huawei Tecal Server
* Pigeon Point Systems ShMM300 and ShMM500 based Shelf Controllers
* Radisys Promentum 60x0 and its 2100 Switch/Shelf Controller blades
* CPU Blades:
** Intel Xeon based server cards
** Intel Pentium and Xeon based desktops and rack mount servers (RMS)
** Intel Itanium based RMS
** AMD Opteron based ATCA cards
** AMD Opteron and Athlon based desktops
** PowerPC based AMCs
** PowerPC based desktops
** Huawei Tecal BH23
** Sun 3020 and 3090
|- style="color:#ffffff; background:#549cc6"
|
Software
|
* Wind River PNE-LE 1.2 (2.6.10 kernel) on CPU blades
* Wind River PNE-LE 1.3 (2.6.14 kernel) on CPU blades
* Wind River PNE-LE 1.4 (2.6.14 kernel) on CPU blades
* Wind River PNE-LE 2.0 (2.6.21 kernel) on CPU blades
* MontaVista Linux Carrier Grade Edition 5.0 (2.6.21 kernel)on CPU Blades
* QNX Neutrino RTOS 6.3.2
* Pigeon Point Systems Shelf Manager version 2.2.1 on ShMM300, ShMM500
* SCM software version 1.7 on ATCA 2100 Shelf Manager
* OpenHPI 2.8.1 and 2.10.2
* Radisys HPI Client Library (HCL) version 1.1
|}

For more details on the hardware and software requirements and the steps to install OpenClovis SAFplus Platform and IDE, refer to ''OpenClovis Installation Guide''.

=='''What Is New'''==

This chapter outlines the new features and enhancements provided by OpenClovis SAFplus Platform and IDE for all releases.

===New In Release 6.1===

* Management Transformation: The SAFplus management is deprecated and replaced with an add-on product that supports NETCONF, SNMP, and CLI access.

* Multi-language code generation and support: Applications can generate C, C++, or Python code. Language-specific wrappers are provided for many SAFplus services.

* Support for gcc 4.8: Compilation errors/warnings fixed

* C++ compilation: SAFplus can compiled with the C or C++ (gcc or g++) compiler.

==== Porting Prior Models to 6.1 ====

The changes in 6.1 mean that 6.0 models will not compile without modification. However, the required changes are simple and so your model can be fixed in minutes.

* Problem: clCompCfg.c:39:1: error: too many initializers for ClEoConfigT

Remove the first initializer:
COMP_EO_NAME, /* EO Name */

* Problem: undefined symbol: ClNameT.

Convert all your references to SaNameT -- it is the exact same structure

* Problem: CL_DEBUG_XXXX was not declared in this scope.

Change the symbol to CL_LOG_SEV_XXXX.

===New In Release 6.0===

'''SAF Message Service'''
* Optimization: The SAF message service now operates using a peer-to-peer instead of client-server model, resulting in a 400% speedup and reduced network utilization.
* Additional features: Persistent message queues are always stored off-node and will not lose messages during application or node failures. The SAF standard allows node failures to lose messages in persistent queues.

'''Availability Management Framework'''
* 1+N system controller redundancy: More then 2 system controllers are now supported.
* Custom redundancy model: Our SAF-extension "Custom" redundancy model allows the application to chose Active/Standby pairing.

'''Platform Support Package'''
* HPI event filter plugin: A facility was created to intercept, analyze and modify or squelch HPI events before they are handled by the SAFplus Platform. Since it is implemented as a plug-in to our chassis manager, this feature does not affect the latency of our fast-path event handling.
* OpenHPI 3.0 is now the default HPI package
* The HPI dynamic simulator is fully supported, with OpenClovis extensions that generate HPI events if a threshold is changed so that the simulated sensor value falls outside of the nominal range.

'''Messaging Layer'''
* The messaging subsystem used by SAFplus Platform has been converted to a plug-in, allowing the user to implement different transport mechanisms.
* UDP and TIPC plugins are now supported with the default set to TIPC as before*.

'''Leader Election'''
* Cluster leader election is now based on results from the messaging layer (i.e. from TIPC) rather then running an independent algorithm.

'''*''' Note: This feature is not yet supported by the IDE, but can be enabled by changing configuration files.

==== Release 6.0 Patch 201212102041 Dec 10,2012 ====

* Changes to support Emerson HPI (along with the existing OpenHPI and Radisys) for users of the Platform Support Package

* Removed accidental inclusion of OpenHPI header files, even when HPI is not selected. Note: this will cause a compile error in the auto-generated file src/config/clCmResourceDeps.c. The fix is to add the following #ifdef near the top of the file (and #endif at the end):

<pre>
#include <clCmApi.h>
#ifdef CL_USE_CHASSIS_MANAGER
#include <SaHpi.h>
.
.
.
#endif
</pre>
Additionally, add the following line to the top of src/config/Makefile:
include $(CLOVIS_ROOT)/SAFplus/mk/preface.mk

This will ensure that CL_USE_CHASSIS_MANAGER is defined if required.

Theses file will be automatically corrected if you regenerate the code from within the IDE.

* Updated the "eval" (tutorial) model to work with the 6.0 release. It is located in src/examples/eval.

===New In Release 5.0===

====General Features====

* '''Support for Wind River PNELE 2.0''': OpenClovis SDK can seamlessly build SAFplus Platform and binaries for Wind River Platform for Network Equipment Linux Edition 2.0 on all supported SDK platforms, either using the build tool-chain of OpenClovis or of the development environment of Wind River.

====High Availability (HA)====

*'''ISSU - In Service Software Upgrade'''
Supports middleware upgrade in a rolling (in-service) or single-step mode.

'''Single-Step'''
For deployment of non-backwards compatible software, or rapid deployment of software. This method stops the relevant services on all nodes (causing an outage) and then upgrades that software and restarts. Note that services are stopped at various granularity levels depending on what is being upgraded. In other words, application A can be taken out-of-service and upgraded across the cluster without affecting application B running on the same nodes.

'''Inservice Rolling'''
This is the most commonly known telecom quality upgrade method. For deployment of backwards-compatible software across the cluster, this method stops service in one "upgrade unit" at a time, upgrades the software and restarts before stopping the next "upgrade unit". This process continues iteratively until the entire cluster is upgraded. Since the available redundant capacity takes over for the unit being upgraded service will be unaffected.

====Infrastructure and Communications====

====Group Membership Service (GMS) over TIPC====

By default GMS/openais is now compiled to run over TIPC.

====SAF Message Service====

SAF messaging data types and APIs supported by OpenClovis

*'''classes/types:'''

*SaMsgMessageT
*SaMsgHandleT
*SaMsgQueueStatusT
*SaMsgQueueHandleT
*SaMsgSenderIdT
*SaMsgQueueCreationAttributesT
*SaMsgQueueOpenFlagsT
*SaMsgQueueGroupPolicyT
*SaMsgQueueGroupNotificationBufferT
*SaMsgQueueGroupNotificationT
*SaMsgQueueUsageT
*SaMsgCallbacksT
*SaMsgMessageReceivedCallbackT

*'''APIs:'''

*saMsgMessageSend
*saMsgMessageSendAsync
*saMsgQueueOpen
*saMsgQueueClose
*saMsgQueueStatusGet
*saMsgMessageGet
*saMsgMessageDataFree
*saMsgQueueGroupCreate
*saMsgQueueGroupInsert
*saMsgQueueGroupTrack
*saMsgQueueGroupNotificationFree
*saMsgInitialize
*saMsgFinalize
*saMsgDispatch

====SAF Component cleanup script support====

5.0 introduces support to configure cleanup commands for SA-AWARE components using the Openclovis IDE. The cleanup command is invoked by AMF on component cleanup or abrupt terminations.

===System Management===

*Support of net-snmp 5.4.2.
*SNMP Traps in 64 Bit architectures.

===Platform Management===

OpenClovis SAFplus Platform provides pre-integrated support for commonly used ATCA platforms. All service affecting events reported by the shelf manager via HPI are intercepted and service on affected hardware is migrated to standby equipment, ensuring continuity of service.

This support is provided with the '''Platform Support Package (PSP)''' for Piegon Point Shelf manager 500ShMM via openHPI.

PSP is available as a separate product, please contact OpenClovis Sales for further information.

===Features of OpenClovis IDE===

* '''Running SAFplus Platform without manageability components''': IDE is having the support for enable/disable SAFplus Platform components. For more information refer to ''OpenClovis IDE User Guide''.
* '''AMF Clean-up script''': IDE is having support to specify the cleanup command in SAF Component. For more information refer to ''OpenClovis IDE User Guide''.
* '''Versioning the Configuration Files''': IDE is having support for versioning the configuration files.
* '''SAF Messaging''': IDE is having support to enable the SAF messaging. For more information refer to ''OpenClovis IDE User Guide''.

===SAFplus Platform Run-Time Director===

A new product, the SAFplus Platform Run-Time Director(ARD), provides cluster management of the SAFplus Platform via a web interface. This new product is available separately, please contact OpenClovis for demonstration and evaluation. The ARD has the following features:

* Software Distribution: Allows individual applications to be packaged in a "bundle" and be deployed to any set of nodes in the cluster.
* Inservice Software Upgrade: Supports application upgrade in a rolling (in-service) or single-step mode.
* WYSIWYG: Provides intuitive cluster management via an HTTP (web) interface.
* AJAX: Displays all SAF AMF entities and their current status -- uses asynchronous Javascript requests to dynamically update browser when changes occur.
* Dynamic AMF: Allows modification of AMF entity state and supports creation/deletion of AMF entities.
* High Availability: The ARD runs in unprotected or 2N redundancy mode.
* Python AMF API: Provides an easy-to-use CLI/programmatic API for cluster management
* Easy installation: The ARD can install itself into a running SAFplus Platform model, and therefore requires no changes to your existing model.
* Extensible: The ARD is built on top of TurboGears, a popular open source web mega-framework. Thus it provides a basis and example for your custom SaaS or EMS project.
* Integration of Platform Support Package (PSP), provides chassis configuration through OpenHPI.

===OpenClovis Documentation===

* OpenClovis Documentation is provided in two formats now, PDF and HTML. They both contain the same information.
* A new ''OpenClovis SA Forum Compliance'' document has been added
* As a courtesy, all relevant SA Forum specifications are supplied as part of our OpenClovis documentation package (only in PDF format).
* A new ''OpenClovis Sample Application Tutorial'' has been added, replacing the former Modeling Tutorial. The new document provides explanation for the various steps involved in creating and running a new application.
* The ''OpenClovis SDK User Guide'' has been extended to cover many additional topics, including:
** Communication infrastructure
** Hardware platform support
** How to debug SAFplus Platform based applications
** Build and deployment
* The ''OpenClovis API Reference Guide'' has been significantly revised:
** Numerous coding examples
** New reference pages for API error codes for easy lookup
** HTML version of API Refernce Guide is heavily cross-referenced, allowing easy navigation between the various programming construcs
* New, complete ''OpenClovis SAFplus Platform Console Reference Guide'' as a separate document

[[File:OpenClovis_Note.png]]From this release, the ''Debug CLI'' has been renamed to ''SAFplus Platform Console''.

=='''Migration To Latest Version'''==

Migration of a project or model from an earlier version of the OpenClovis IDE to the most recent version is performed automatically when the model it opened for the first time in the newer vesion. The IDE auto-detects the project's version and changes the internal files so that the information is in valid format and can be read by the current version. It also provides an option to create a backup of the project while performing the migration. For more information, refer to ''OpenClovis IDE User Guide'', Section ''Migrating Project''. IDE supports migration from R2.3 and above.

Any issues regarding migration from a previous version of the IDE are documented below.

===Change in Log File Locations===

As of release 3.0 all SAFplus Platform runtime log files are created in the <code>var/log</code> subdirectory of the SAFplus Platform install directory. It is recommended that you update existing models to also use this directory. To update an existing model edit the clLog.xml file in the model's src/config directory. Change all references of '''.:log''' in the <code><fileLocation></code> elements

<fileLocation>.:log</fileLocation>

to '''.:var/log'''

<fileLocation>.:var/log</fileLocation>

Once the model is rebuilt and deployed these new settings will take effect.

===gmsConfig.xml file===

Models of R2.3 may not contain the gmsConfig.xml file if GMS configuration is not done. If you migrate this project you will get error message saying that Migration was unable to create this file. But this is not going to affect further use of model. Model will be OK and user can make changes to it from IDE, generate source, build it, etc without any problem.

Although this error is not going to affect the functionality of the model, there is a work around for this. Before migrating your model, just open up the model in your old IDE setup. Launch "SAFplus Platform Component Configuration" dialog from the Clovis menu. Press OK. Now just migrate the model with new IDE setup, you will not get this error. Bug has been raised for this and it will be fixed in next release.

=='''Known Issues'''==

This chapter describes the known issues in the current release and provides the associated workarounds. These issues arise due to deviation from the normal functioning of the system or as a result of an unexpected behavior of a component or a service.

===Known Issues of OpenClovis SAFplus Platform===

Following are the known issues for OpenClovis SAFplus Platform:

*'''Infrastructure and Communications'''
** '''TIPC address:''' TIPC with 1.5.12 versions was found to give problems (link unstable) when you have 2 different TIPC netids configured for the same TIPC address. This issue is not seen with the 1.7.x TIPC releases, but in general we recommend you to keep the TIPC addresses unique and not collide with the same addresses on nodes configured with different TIPC netids. One of the symptoms of this is that the TIPC link between 2 machine starts going UP and DOWN continuously when there is another machine in the network, whose TIPC address is conflicting with address of one of those 2 machines. The behavior can be observed through continuous execution of command "tipc-config -l" or through "dmesg".
** In general, TIPC 1.5.XX has been found to be unstable, especially under high multicast load, and should not be used in production environments.

** '''Bug ID #7269''' A cluster having a mixture of 32bit little endian, 32bit big endian and 64 bit little endian machines/nodes may find that the GMS service in inadvertently terminates.
*** '''Workaround''' - None
** '''aspinfo known issues:''' (1) On some systems, especially systems with Python version 2.3, aspinfo can be slow to respond. (2) Some corner cases may not be properly handled and aspinfo may prematurely exit, dumping its Python stack.

* '''System Management'''
** '''Bug ID #7313''' If an Alarm Server is restarted after it published an alarm, it won't allow to clear/publish that alarm again.
*** '''Workaround''' - Currently there is no workaround.

* '''SAF Compliance'''
** '''Deviation from SAF in Event Service:''' Event Service does not yet support Event Retention as specified in SAF specification. The retention time specified in the clEventPublish() API would have no effect.
** '''Bug in SAF specificaion B11:''' The clEventDataGet() API of Event Service is in compliance with the SAF specification B11. This allows the user to either allocate memory for the event payload or obtain it from the API by passing a pointer. The latter is not possible with this API as the argument needs to be a pointer to a pointer which is not the case. As per the new specification and the recommended way the user is always required to allocate and free the memory.

===Known Issues of OpenClovis IDE===

<ul>
<li>'''Bug ID # 6543: X Error in Ubuntu Installation.''' Starting the IDE in '''Ubuntu''' installation may result some X errors in the console. This is not an IDE issue, this will not affect any of the IDE functionalities.
<ul>
<li>'''Workaround''' - See the ''Limitations'' section of the ''OpenClovis IDE User Guide''.
</ul>
<li>'''SNMP MIB Enumerated Integer Construct Limitations''': During SNMP code generation all enumerated integer labels are converted to <code>#define</code> statements. The constant names used in these statements are the enumerated integer labels converted to upper case. Because of this the all labels used within an enumerated integer construct must be unique regardless of case.

<li>'''SNMP MIB V1 TRAP-TYPE Construct Not Supported''': Due to an issue in the Net-SNMP mib2c compiler code generation for MIBs using the V1 TRAP-TYPE construct does not work properly.
<ul>
<li>'''Workaround''' - To generate trap code from an SNMP MIB use the SNMP V2 NOTIFICATION-TYPE construct.
</ul>
</ul>

===Known Issues of Install Package===

* '''Bug ID # 6749: Potential conflict with net-snmp package on local system''': In certain rare instances, building OpenHPI from the included third-party packages during SDK installation fails owing to a conflict with an already-installed version of NetSNMP on the system. In these instances, it is recommended that NetSNMP be removed from the local system before installing OpenClovis SDK, and that it be reinstalled after completing the SDK installation.

* '''Installation on Red Hat Enterprise 4''': On a Red Hat Enterprise Linux 4 system, the 'Development Tools' subset of packages must be installed to cover the requirements for installing OpenClovis SDK. In general, an installation with the default package set contains all requirements for installation.

* '''Installation on Fedora Core 6''': On a Fedora Core 6 system, installation of OpenClovis SAFplus Platform automatically builds and installs the TIPC opensource package. To build TIPC, the kernel headers must be present and so these are automatically installed (by our ./preinstall-fedora-core.sh script) using the "yum install kernel-devel" command. On rare configurations, this command does not work correctly. It is supposed to install headers so that the symbolic link located at "/lib/modules/`uname -r`/build" points to a valid directory of Linux header files. However, on some systems this symbolic link points to "/usr/src/kernels/2.6.22.14-72.fc6-i586" but the headers are actually installed in "/usr/src/kernels/2.6.22.14-72.fc6-i686" (note 'i586' vs 'i686'). To resolve this problem, change the symbolic link to point to the correct directory name, and then restart the OpenClovis SAFplus Platform installation.

* '''Configuring TIPC and assigning the SAFplus Platform node address''' to an OpenClovis SAFplus Platform is done by SAFplus Platform start up script. But if manual configuration of TIPC is allowed. Misconfiguration (such as assigning 2 nodes the same TIPC address) will result in an unstable system. When this happens the whole system (all the SAFplus Platform nodes including the ones which are already up and running properly) have to be brought down, the TIPC kernel driver unloaded (to remove its configuration) and the system restarted.

* '''Installation of SQLite using Preinstall script''': The Preinstall script installs SQLite by default as database engine. It locates SQLite - if it is already installed - without verifying version number. If its version is older than 3.3.13, then SAFplus Platform will fail to start.
** '''Workaround''' - Use SQLite 3.3.13 or newer. The source code can be downloaded from http://www.sqlite.org/download.html. The user can install the latest version of SQLite if its not present in the repository.

* '''Installation on Solaris 10/SPARC (beta)''': Installation of OpenClovis SAFplus Platform requires the following third party packages installed via either installation media or using pkgadd with packages obtained from http://www.sunfreeware.com/. Missing third-party packages may cause unpredictable behavior during installation and SDK use.
** db-4.2.52
** fileutils
** flex
** gcc-3.4.2
** gdbm-1.8.3
** glib-2.14.1
** gmake
** gtar
** libintl
** libiconv
** ncurses
** openssl
** pkgconfig
** python-2.5.1
** readline
** snprintf
** tipc-solaris-1.7.5 or SUNWtipc
** SUNWbtool
** SUNWsprot
** SUNWhea
** wget

=='''Environment Related Observation'''==

* '''Bug ID #7549''' When SAFplus Platform is running in non simulation mode, if SAFplus Platform is started from one sandbox, then it can be stopped/zapped from another sandbox.

===Enabled Firewall Can Cause SAFplus Platform to Shutdown===
The enablement of a firewall on a system running a deployed SAFplus Platform image can cause the software to shutdown. An indication that you may be running into this problem is if you see an entry similar to the following in your log file (in the log file it is one line):
<code><pre>
Wed Sep 26 15:06:54 2007 (SCNodeI0.10499 : GMS.---.---.00036 : ERROR)
[clGmsEngine.c:448] No nodes in the cluster view to run leader
electionLeader Election Aborted
</pre></code>
To resolve this problem disable all filtering in the Netfilter framework by issuing the following command.
<code><pre>
iptables -F
</pre></code>

===Reusing A Project Area With New Version of OpenClovis SDK===
Every Project Area is associated with an installation of OpenClovis SDK at a given location. If one elects to reinstall the SDK at a different location or install a newer version at a different location, the project area will stay associated with the original SDK location. This allows one to work with multiple versions of the SDK simultaneously.
In order to use an existing project area with a different or moved installation of OpenClovis SDK, remove the <code>.config</code> file from your project area directory and re-run <code>configure</code> as you normally would to work with a model.

===Running Multiple SAFplus Platform Clusters in the same Subnet===
If you are running multiple SAFplus Platform clusters within the same subnet, please ensure that the <code>TIPC network ID</code> selected for each cluster is unique.

=='''Documentation Issues'''==

This chapter describes the known issues with the OpenClovis Documentation shipped along with the product.

* Formatting issues
** Following cross-references pointing to a heading, the PDF viewer will jump to the end of the previous page if the heading is on the top of a page.
** Firefox web browsers sometimes do not correctly jump to intra-page anchors when the user clicks on a reference. This is a known issue with Firefox. The workaround is to click on Back button and then on the reference again. The browser jumps to the correct position for the 2nd time.

2013-10-18T13:35:14Z

Stone: Blanked the page

Doc:latest/evalguide/cmPlugin

2013-10-08T14:01:02Z

Stone: /* Building the CM-Plugin model and controlling Events in run-time */

== CM Plug-in Guide==

===Objective===

CM-Plugin is an event controlling policy in Platform-Support-Package(PSP) to allow, restrict, or modify the events received from HPI and forwarded to the Application during run-time. The policy is defined by the Application programmer and is loaded into the Chassis Manager and called whenever a hardware event is received.

The purpose of this plugin is to allow the application programmer to intercept events that may be miscategorized by the hardware and transform them. For example, if a voltage loss event is reported as MAJOR in a dual power supply system, this even should not cause system shutdown so can be reduced to a MINOR level event.

===What you can learn===

How to define a policy to control the events in the CM, so that only interested events are forwarded to the Application and unintended events are discarded.

===Building the CM-Plugin model and controlling Events in run-time===

The example code containing Application and CM-Policy is available in
'''[https://github.com/OpenClovis/SAFplus-Platform-Support-Package/tree/6.0/src/example/cmplugin PSP/src/example]'''

====Usage of CM-Plugin====

The policy to control the events is defined in cmPolicy.c and is available in the location: ...\CmPlugin\src\app\common\plugins\cmPolicy.c in specified example.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| cmPolicy.c
|-
|<code><pre>

ClRcT HpiEventFilter(SaHpiSessionIdT session, SaHpiEventT* event, SaHpiRdrT* rdr, SaHpiRptEntryT* rpt)
{
/* Define the policy to Allow, Block or Change the events here */
if ( /* For Specific condition of Event Ex: event->Severity==SAHPI_MAJOR */)
{
/* Change the event to required form */
/* event->Severity=SAHPI_MINOR; */
}

return CL_OK;
}
</pre></code>
|}

* HpiEventFilter() will be contain the details of specific event to be handled and specific modification for that event.

===How to Run cmPlugin model===

Copy the image to required location (/root/asp/).

<ol>

<li>Start the SAFplus Platform on deployed node <code><pre>
# cd /root/asp/
# ./etc/init.d/asp start</pre></code>

<li>Generate event using HPI Event Simulator OR through actual hardware <code><pre>
# cd /root/asp/bin
# ./hpithres</pre></code>
The logs are available in var/log/sys.latest and application_name.latest

Doc:latest/evalguide/cmPlugin

2013-10-08T13:58:20Z

Stone: /* CM Plug-in Guide */

== CM Plug-in Guide==

===Objective===

CM-Plugin is an event controlling policy in Platform-Support-Package(PSP) to allow, restrict, or modify the events received from HPI and forwarded to the Application during run-time. The policy is defined by the Application programmer and is loaded into the Chassis Manager and called whenever a hardware event is received.

The purpose of this plugin is to allow the application programmer to intercept events that may be miscategorized by the hardware and transform them. For example, if a voltage loss event is reported as MAJOR in a dual power supply system, this even should not cause system shutdown so can be reduced to a MINOR level event.

===What you can learn===

How to define a policy to control the events in the CM, so that only interested events are forwarded to the Application and unintended events are discarded.

===Building the CM-Plugin model and controlling Events in run-time===

The example code containing Application and CM-Policy is available in
'''[https://github.com/OpenClovis/SAFplus-Platform-Support-Package/tree/6.0/src/example/cmplugin PSP/src/example]'''

====Usage of CM-Plugin====

The policy to control the events are defined in cmPolicy.c and is available in location: \CmPlugin\src\app\common\plugins\cmPolicy.c in specified example.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| cmPolicy.c
|-
|<code><pre>

ClRcT HpiEventFilter(SaHpiSessionIdT session, SaHpiEventT* event, SaHpiRdrT* rdr, SaHpiRptEntryT* rpt)
{
/* Define the policy to Allow, Block or Change the events here */
if ( /* For Specific condition of Event Ex: event->Severity==SAHPI_MAJOR */)
{
/* Change the event to required form */
/* event->Severity=SAHPI_MINOR; */
}

return CL_OK;
}
</pre></code>
|}

* HpiEventFilter() will be contain the details of specific event to be handled and specific modification for that event.

===How to Run cmPlugin model===

Copy the image to required location (/root/asp/).

<ol>

<li>Start the SAFplus Platform on deployed node <code><pre>
# cd /root/asp/
# ./etc/init.d/asp start</pre></code>

<li>Generate event using HPI Event Simulator OR through actual hardware <code><pre>
# cd /root/asp/bin
# ./hpithres</pre></code>
The logs are available in var/log/sys.latest and application_name.latest

Switch your model/image from TIPC to UDP

2013-10-07T16:01:49Z

Stone:

UDP can be run in two modes -- local or cloud. In local mode, the UDP system uses multicast to find members of the cluster and auto-assigns non-routable IP addresses onto an alias of your chosen backplane network interface. The advantage of local mode is that no IP addresses need to be configured.

In cloud mode, it is assumed that the cluster is potentially running across the entire internet (no multicast) on machines with specified IP addresses. Since no initial discovery is possible, every node needs to be configured with the IP addresses of the two system controller nodes.

== Changing Your Model from TIPC to UDP ==
=== Step 1 ===
- If you have a pre-60 model you will need to upgrade it. Using the IDE open your model, every option will be grey except model->update. This update will generate a configuration file called <your model>/config/clTransport.xml that looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>TIPC</type>
<plugin>libClTIPC.so</plugin>
</xport>

</xports>

</multixport>
</version>
</openClovisAsp>

=== Step 2 ===
Edit the content clTransport.xml with the UDP configuration details, and remove the TIPC details:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<multicast address="226.0.1.1" port="9595" />
<heartbeat>
<interval>3000</interval>
<intervalLocal>3000</intervalLocal>
<retries>5</retries>
</heartbeat>
</multixport>
</version>
<openClovisAsp>

=== Step 3 (Local mode) ===
Add 2 environment variables into <model_dir>/src/target.env, or make sure these variables are defined before starting SAFplus:

export ASP_UDP_SUBNET=<IP Range>/Length
export ASP_UDP_LINK_NAME=<your interface>

*'''Example:'''

export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

=== Step 3 (Cloud mode) ===
To use the UDP transport without node discovery (multicast) or IP address assignment, you must:

1. Add these 2 environment variables into <model_dir>/src/target.env, or make sure these variables are defined before starting SAFplus:

ASP_UDP_USE_EXISTING_IP=true
ASP_UDP_LINK_NAME=<link name, for example 'eth0'>

2. Configure UDP peer addresses like this:
<code>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</code>

The following is a this complete example of a cloud mode configuration file:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<heartbeat>
<interval>1000</interval>
<intervalLocal>1000</intervalLocal>
<retries>4</retries>
</heartbeat>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</multixport>
</version>
</openClovisAsp>
</code>

=== Before or After "make images"? ===
clTransport.xml and target.env can be changed before the "make images" step so all generated images are UDP by default OR these files can be changed on every node after deployment.

== FAQ ==

* Q: Is the SAFplus able to run in UDP local mode as a non-root user?
* A: Yes, but you must properly configure the interfaces since SAFplus cannot.
Configure interface name (ASP_UDP_LINK_NAME) with the IP address calculated from your subnet and node address (ASP_UDP_SUBNET.DEFAULT_NODEADDR). The node address is the DEFAULT_NODEADDR settings from etc/asp.conf file.

Example:
root:#ifconfig eth0 192.168.57.1
user:#export ASP_UDP_SUBNET=192.168.57.0/24
user:#export ASP_UDP_LINK_NAME=eth0
user:#./etc/init.d/safplus start

Switch your model/image from TIPC to UDP

2013-10-07T15:40:22Z

Stone: /* Step 2 */

== From Model ==
=== Step 1 ===
- If you have a pre-60 model you will need to upgrade it. Using IDE open your model, it will require an upgrade before it can be used. This will generate a configuration file in <your model>/config/clTransport.xml.

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>TIPC</type>
<plugin>libClTIPC.so</plugin>
</xport>

</xports>

</multixport>
</version>
</openClovisAsp>

=== Step 2 ===
Edit the content clTransport.xml with some UDP configuration details:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<multicast address="226.0.1.1" port="9595" />
<heartbeat>
<interval>3000</interval>
<intervalLocal>3000</intervalLocal>
<retries>5</retries>
</heartbeat>
</multixport>
</version>
<openClovisAsp>

=== Step 3 ===
Add 2 env variables into <model_dir>/src/target.env:

export ASP_UDP_SUBNET=<IP Range>/Length
export ASP_UDP_LINK_NAME=<your interface>

*'''Example:'''

export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

=== Step 4 ===
Before running ASP, should export/setenv 2 below variables:
export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

== UDP without Auto IP address assignment ==

To use the UDP transport with the IP address, 'already configured' on a link, set these variables in your environment before starting SAFplus:

ASP_UDP_USE_EXISTING_IP=true
ASP_UDP_LINK_NAME=<link name, for example 'eth0'>

'''clTransport.xml''' should add static IP addresses for cluster:

<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>

== UDP without Node Discovery (Multicast) ==

To use the UDP transport without node discovery, you must explicitly configure the static addresses and define variable environments ASP_UDP_USE_EXISTING_IP=true and ASP_UDP_LINK_NAME for getting ip addresses below.

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<heartbeat>
<interval>1000</interval>
<intervalLocal>1000</intervalLocal>
<retries>4</retries>
</heartbeat>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</multixport>
</version>
</openClovisAsp>

== From Image ==
Create a clTransport.xml like step 2 & 3 above and retarball your images.

== Q&A ==
* Q: Is the SAFplus able to run as a user other than root?
* A: Only pre-requisites, configure interface name (ASP_UDP_LINK_NAME) with IP address (ASP_UDP_SUBNET.DEFAULT_NODEADDR) (Use DEFAULT_NODEADDR settings from asp.conf file)

Example:
root:#ifconfig eth0 192.168.57.1
user:#export ASP_UDP_SUBNET=192.168.57.0/24
user:#export ASP_UDP_LINK_NAME=eth0
user:#./etc/init.d/safplus start

Switch your model/image from TIPC to UDP

2013-10-07T15:37:18Z

Stone: /* Step 1 */

== From Model ==
=== Step 1 ===
- If you have a pre-60 model you will need to upgrade it. Using IDE open your model, it will require an upgrade before it can be used. This will generate a configuration file in <your model>/config/clTransport.xml.

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>TIPC</type>
<plugin>libClTIPC.so</plugin>
</xport>

</xports>

</multixport>
</version>
</openClovisAsp>

=== Step 2 ===
Edit content clTransport.xml with UDP default:

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<multicast address="226.0.1.1" port="9595" />
<heartbeat>
<interval>3000</interval>
<intervalLocal>3000</intervalLocal>
<retries>5</retries>
</heartbeat>
</multixport>
</version>
<openClovisAsp>

UDP use multicast to notification component arrival and departure.

=== Step 3 ===
Add 2 env variables into <model_dir>/src/target.env:

export ASP_UDP_SUBNET=<IP Range>/Length
export ASP_UDP_LINK_NAME=<your interface>

*'''Example:'''

export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

=== Step 4 ===
Before running ASP, should export/setenv 2 below variables:
export ASP_UDP_SUBNET=192.168.57.0/24
export ASP_UDP_LINK_NAME=eth0

== UDP without Auto IP address assignment ==

To use the UDP transport with the IP address, 'already configured' on a link, set these variables in your environment before starting SAFplus:

ASP_UDP_USE_EXISTING_IP=true
ASP_UDP_LINK_NAME=<link name, for example 'eth0'>

'''clTransport.xml''' should add static IP addresses for cluster:

<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>

== UDP without Node Discovery (Multicast) ==

To use the UDP transport without node discovery, you must explicitly configure the static addresses and define variable environments ASP_UDP_USE_EXISTING_IP=true and ASP_UDP_LINK_NAME for getting ip addresses below.

<?xml version="1.0" encoding="UTF-8"?>
<openClovisAsp>
<version v0="4.0.0">
<multixport xmlns="multixport.ecore">
<xports>
<xport>
<type>UDP</type>
<plugin>libClUDP.so</plugin>
</xport>
</xports>
<protocol default="UDP"/>
<heartbeat>
<interval>1000</interval>
<intervalLocal>1000</intervalLocal>
<retries>4</retries>
</heartbeat>
<peerAddresses port="6789">
<peer addr="192.168.56.101"/>
<peer addr="192.168.56.102"/>
</peerAddresses>
</multixport>
</version>
</openClovisAsp>

== From Image ==
Create a clTransport.xml like step 2 & 3 above and retarball your images.

== Q&A ==
* Q: Is the SAFplus able to run as a user other than root?
* A: Only pre-requisites, configure interface name (ASP_UDP_LINK_NAME) with IP address (ASP_UDP_SUBNET.DEFAULT_NODEADDR) (Use DEFAULT_NODEADDR settings from asp.conf file)

Example:
root:#ifconfig eth0 192.168.57.1
user:#export ASP_UDP_SUBNET=192.168.57.0/24
user:#export ASP_UDP_LINK_NAME=eth0
user:#./etc/init.d/safplus start

Doc:Latest/SAFplus Availability/Scalability Platform Documentation

2013-09-30T15:25:22Z

Stone: /* SAFplus Platform Runtime Director Documentation */

==SAFplus Availability/Scalability Platform==
:[[Doc:latest/relnotes | Release Notes ]]
:[[Doc:latest/installguide | Installation Guide]]
:[[Doc:latest/tutorial | Sample Application Tutorial]]
:[[Doc:latest/evalguide | Evaluation System User's Guide]]
:[[Doc:latest/ideguide | IDE User Guide]]
:[[Doc:latest/sdkguide | SDK User Guide]]
:[[Doc:latest/safcompliance | SAF Compliance]]
:[[Doc:latest/logtoolguide | LogTool User's Guide]]


===API Documentation===

==== SA-Forum Compliant Services ====
:Many SAFplus Platform services are SAF (Service Availability Forum) compliant. The full SAF API documentation is available from [http://www.saforum.org the Service Availability Forum]. Selected documents are available here:
*[http://help.openclovis.com/saf/SAI-AIS-AMF-B.04.01.AL Availability Management Framework]
*[http://help.openclovis.com/saf/SAI-AIS-CKPT-B.02.02.AL Checkpoint Service]
*[http://help.openclovis.com/saf/SAI-AIS-MSG-B.03.01.AL Message Service]
*[http://help.openclovis.com/saf/SAI-AIS-EVT-B.03.01.AL Event Service]

*[http://help.openclovis.com/saf/SAI-AIS-CPROG-B.05.02.AL C Programming Model]

==== SAFplus Platform Additional APIs ====
: Documentation of SAFplus Platform APIs is located here [[http://help.openclovis.com/api/SAFplus/index.html SAFplus API Documentation]]. This API documentation is also located within the SAFplus Platform header files.

=== 3rdparty Services and Tools Documentation ===

* [http://tipc.sourceforge.net/doc/tipc_2.0_users_guide.html TIPC] is a Linux kernel module that provides fast, low latency cluster based messaging and is a network transport option under SAFplus.

 

==SAFplus Platform Runtime Director Documentation==

:[[Doc:latest/awdguide | Runtime Director User's Guide]]
: SAFplus Runtime Director API Reference [[http://help.openclovis.com/api/srd/index.html SRD API Documentation]].

==[[Test Automation Environment]]==
:[[Doc:latest/taeguide | TAE Users Guide]] : Installation, configuration, discussion and examples
:[http://help.openclovis.com/static/taeApiDoc TAE Python APIs] : API documentation for the Python system test case layer
:[http://help.openclovis.com/static/apirefs/a00447.html TAE C APIs]: API documentation for the C unit test case layer
 

==SAFplus Platform Plugins==

====[[SAFplus Management Framework]] EXPERIMENTAL====
:The [[SAFplus Management Framework]] provides a powerful element management framework.
====[[PostgreSQL Database Integration]] EXPERIMENTAL====
:The [[PostgreSQL Database Integration]] provides an easy way to deploy a highly available SQL database for use by applications in your cluster.
====[[CouchDB Integration]] EXPERIMENTAL ====
:The [[CouchDB Integration]] provides an integration between CouchDB and SAFplus, providing a highly available nosql database solution.

Doc:Latest/SAFplus Availability/Scalability Platform Documentation

2013-09-30T15:24:49Z

Stone: /* SAFplus Platform Runtime Director Documentation */

==SAFplus Availability/Scalability Platform==
:[[Doc:latest/relnotes | Release Notes ]]
:[[Doc:latest/installguide | Installation Guide]]
:[[Doc:latest/tutorial | Sample Application Tutorial]]
:[[Doc:latest/evalguide | Evaluation System User's Guide]]
:[[Doc:latest/ideguide | IDE User Guide]]
:[[Doc:latest/sdkguide | SDK User Guide]]
:[[Doc:latest/safcompliance | SAF Compliance]]
:[[Doc:latest/logtoolguide | LogTool User's Guide]]


===API Documentation===

==== SA-Forum Compliant Services ====
:Many SAFplus Platform services are SAF (Service Availability Forum) compliant. The full SAF API documentation is available from [http://www.saforum.org the Service Availability Forum]. Selected documents are available here:
*[http://help.openclovis.com/saf/SAI-AIS-AMF-B.04.01.AL Availability Management Framework]
*[http://help.openclovis.com/saf/SAI-AIS-CKPT-B.02.02.AL Checkpoint Service]
*[http://help.openclovis.com/saf/SAI-AIS-MSG-B.03.01.AL Message Service]
*[http://help.openclovis.com/saf/SAI-AIS-EVT-B.03.01.AL Event Service]

*[http://help.openclovis.com/saf/SAI-AIS-CPROG-B.05.02.AL C Programming Model]

==== SAFplus Platform Additional APIs ====
: Documentation of SAFplus Platform APIs is located here [[http://help.openclovis.com/api/SAFplus/index.html SAFplus API Documentation]]. This API documentation is also located within the SAFplus Platform header files.

=== 3rdparty Services and Tools Documentation ===

* [http://tipc.sourceforge.net/doc/tipc_2.0_users_guide.html TIPC] is a Linux kernel module that provides fast, low latency cluster based messaging and is a network transport option under SAFplus.

 

==SAFplus Platform Runtime Director Documentation==

:[[Doc:latest/awdguide | Runtime Director User's Guide]]
 
: SAFplus Runtime Director API Reference [[http://help.openclovis.com/api/srd/index.html SAFplus API Documentation]].

==[[Test Automation Environment]]==
:[[Doc:latest/taeguide | TAE Users Guide]] : Installation, configuration, discussion and examples
:[http://help.openclovis.com/static/taeApiDoc TAE Python APIs] : API documentation for the Python system test case layer
:[http://help.openclovis.com/static/apirefs/a00447.html TAE C APIs]: API documentation for the C unit test case layer
 

==SAFplus Platform Plugins==

====[[SAFplus Management Framework]] EXPERIMENTAL====
:The [[SAFplus Management Framework]] provides a powerful element management framework.
====[[PostgreSQL Database Integration]] EXPERIMENTAL====
:The [[PostgreSQL Database Integration]] provides an easy way to deploy a highly available SQL database for use by applications in your cluster.
====[[CouchDB Integration]] EXPERIMENTAL ====
:The [[CouchDB Integration]] provides an integration between CouchDB and SAFplus, providing a highly available nosql database solution.

Doc:Latest/SAFplus Availability/Scalability Platform Documentation

2013-09-30T15:23:48Z

Stone: /* SAFplus Platform Additional APIs */

==SAFplus Availability/Scalability Platform==
:[[Doc:latest/relnotes | Release Notes ]]
:[[Doc:latest/installguide | Installation Guide]]
:[[Doc:latest/tutorial | Sample Application Tutorial]]
:[[Doc:latest/evalguide | Evaluation System User's Guide]]
:[[Doc:latest/ideguide | IDE User Guide]]
:[[Doc:latest/sdkguide | SDK User Guide]]
:[[Doc:latest/safcompliance | SAF Compliance]]
:[[Doc:latest/logtoolguide | LogTool User's Guide]]


===API Documentation===

==== SA-Forum Compliant Services ====
:Many SAFplus Platform services are SAF (Service Availability Forum) compliant. The full SAF API documentation is available from [http://www.saforum.org the Service Availability Forum]. Selected documents are available here:
*[http://help.openclovis.com/saf/SAI-AIS-AMF-B.04.01.AL Availability Management Framework]
*[http://help.openclovis.com/saf/SAI-AIS-CKPT-B.02.02.AL Checkpoint Service]
*[http://help.openclovis.com/saf/SAI-AIS-MSG-B.03.01.AL Message Service]
*[http://help.openclovis.com/saf/SAI-AIS-EVT-B.03.01.AL Event Service]

*[http://help.openclovis.com/saf/SAI-AIS-CPROG-B.05.02.AL C Programming Model]

==== SAFplus Platform Additional APIs ====
: Documentation of SAFplus Platform APIs is located here [[http://help.openclovis.com/api/SAFplus/index.html SAFplus API Documentation]]. This API documentation is also located within the SAFplus Platform header files.

=== 3rdparty Services and Tools Documentation ===

* [http://tipc.sourceforge.net/doc/tipc_2.0_users_guide.html TIPC] is a Linux kernel module that provides fast, low latency cluster based messaging and is a network transport option under SAFplus.

 

==SAFplus Platform Runtime Director Documentation==

:[[Doc:latest/awdguide | Runtime Director User's Guide]]
 
==[[Test Automation Environment]]==
:[[Doc:latest/taeguide | TAE Users Guide]] : Installation, configuration, discussion and examples
:[http://help.openclovis.com/static/taeApiDoc TAE Python APIs] : API documentation for the Python system test case layer
:[http://help.openclovis.com/static/apirefs/a00447.html TAE C APIs]: API documentation for the C unit test case layer
 

==SAFplus Platform Plugins==

====[[SAFplus Management Framework]] EXPERIMENTAL====
:The [[SAFplus Management Framework]] provides a powerful element management framework.
====[[PostgreSQL Database Integration]] EXPERIMENTAL====
:The [[PostgreSQL Database Integration]] provides an easy way to deploy a highly available SQL database for use by applications in your cluster.
====[[CouchDB Integration]] EXPERIMENTAL ====
:The [[CouchDB Integration]] provides an integration between CouchDB and SAFplus, providing a highly available nosql database solution.

Doc:Sdk 4.1/awdguide/upgradedirector

2013-09-12T01:20:50Z

Stone: /* Bundle Creation */

{{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.

Care was taken during the design of the Upgrade Director to ensure that it continues to operate in adverse conditions and does not leave the cluster in an untenable state. In particular:

* All required software is deployed on-cluster on both system controllers before the upgrade starts this ensures that a network outage will not affect the upgrade.
* Once started, the upgrade is driven by software running on the cluster rather then at the management station. This ensures that an outage between the NOC and the cluster will not affect the upgrade.
* The Upgrade Director executable is delivered within the upgrade package, ensuring that it can be upgraded itself before executing an upgrade.
* The Upgrade Director uses the SAFplus Platform middleware as little as possible. Essentially, it only uses it to query the state of the cluster, not to store its own state. This reduces the possibility that a bug in the middleware will cause the upgrade director to fail.

===Extensibility===

The Upgrade Director is made to be operating system distribution-neutral. To upgrade operating system packages or the operating system itself, you must overload certain virtual functions that actually install the packages on disk. This allows you to control how the packages are organized on disk: "rpm", "dpkg", an A/B disk partitioning system, or something custom to your system.

But the upgrade director simplifies the process dramatically by scheduling when your operations occur relative to the ongoing upgrade in the rest of the cluster.

===Operational Walkthrough===

This operational walkthrough is written based on the OpenClovis supplied bundle that uses tar files. If you add another bundle file format, some steps may be different.

====Development====
# The engineer first creates an SAFplus Platform model with the IDE, compiles it, makes images, tests it, etc as is normally done.
## The SAFplus Platform image should be made with the "INSTANTIATE_IMAGES=NO" flag in target.conf so a single SAFplus Platform tarball is created for all nodes.
# The engineer implements upgrade manager customization including optional callouts to upgrade the operating system and application data.
# The engineer must create a bundle definition xml file, as defined below.
# The "createUpgradeBundle.py" script is run to generate an "asp.bundle" file.

This file is copied to a system controller node on the target chassis

====Upgrade====
Prerequisites: The SAFplus Platform middleware bundle should be copied to one system controller node.

# The user executes the bundle with a single argument that is the path to the running asp
## for example: chmod a+x asp.bundle; ./asp.bundle /root/asp
# The upgrade does its work (see "UpgradeDirector algorithm walkthrough" below).
# Now the user has the option to either commit the upgrade, or revert it.
## /root/asp.newver/bin /tmp/udtmp1/upgradeDirector/upgradeDirector/upgradeDirector.py --commit
## /root/asp.newver/bin /tmp/udtmp1/upgradeDirector/upgradeDirector/upgradeDirector.py --revert

====UpgradeDirector "Upgrade" Algorithm Walkthrough====
Prerequisites: The SAFplus Platform middleware bundle is executed on one system controller node.

# The bundle contains a shell script executes:
## It detars itself into /tmp/udtmp1
## It starts upgradeDirector.py running under "asp_run"
# upgradeDirector.py first verifies that the cluster is healthy
# Then it installs itself onto the second system controller, and starts up.
# It establishes communications with the second upgrade director and synchronizes state.
# It chooses a "master".
# The master starts upgrading the secondary system controller:
## Installs the new SAFplus Platform
## Stops the secondary upgrade director
## Stops SAFplus Platform
## Copies and upgrades the runtime data from the old SAFplus Platform location to the new.
## Calls customer implemented callbacks to upgrade the OS, and reboot the system (if required for OS kernal upgrade -- otherwise a reboot is not required) at this time.
## Restarts SAFplus Platform
## Verify that SAFplus Platform came up successfully.
## Restarts the secondary upgrade director.
## Resynchronizes with the secondary
## Gives up "master" status
# The new master now upgrades the other controller node in the same manner described above
# At this point both controllers are upgraded, but no payload nodes are upgraded. So software written for the payload nodes can rely on the fact that the controllers are running the latest software, but controllers cannot assume that for payload nodes or for other controller nodes.
# The master now upgrades each payload node one at a time following the following algorithm
## Copy the bundle to the node
## Installs the new SAFplus Platform
## Stops SAFplus Platform
## Copies and upgrades the runtime data from the old SAFplus Platform location to the new.
## Calls customer implemented callbacks to upgrade the OS, and reboot the system at this time.
## Restarts SAFplus Platform
## Verify that SAFplus Platform came up successfully.

# Both upgrade director applications exit.

At this point all nodes are upgraded, but the old SAFplus Platform still remains on disk. The user may now operate in this mode for as long as desired (but may not run another upgrade). When there is confidence in the successful operation of the system, the user may commit or revert the upgrade.

Committing the upgrade is simply a matter of deleting the old SAFplus Platform files and deleting the upgrade bundle out of /tmp. There is no effect on the running SAFplus Platform.

Reverting an upgrade is also made as simple as possible, since it occurs after user confidence in the system is lost. The revert operation simply stops the currently running SAFplus Platform on all payload nodes and starts the old version. Then it does the same for the controller nodes. In fact in the worst case of upgrade software failure, the operator can do this revert manually on each node (essentially just "<newver>/etc/init.d/asp stop; <oldver>/etc/init.d/asp start". This makes the revert operation resilient even to failures in the upgrade software itself!

The reversion order ensures that all payload nodes are downgraded before controller nodes.

===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. But the first step is to "make images" your model with the "INSTANTIATE_IMAGES=NO" flag set in your model's target.conf file. Setting this flag to NO will create a single archive containing the compiled model rather than individual archives for each node.

createUpgradeBundle.py 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.

=== Upgrade Director Command Line ===

Once the bundle has been extracted it automatically runs the upgrade director. But you can also run it explicitly like this:

* --resume
To continue an upgrade if it stopped for any reason, use the --resume option
<aspDir>/bin/asp_run python /tmp/udtmp/upgradeDirector/upgradeDirector.py --resume

* --commit
To commit an upgrade, run the upgrade director under asp_run with the --commit option:
<aspDir>/bin/asp_run python /tmp/udtmp/upgradeDirector/upgradeDirector.py --commit

* --revert
To revert an upgrade, run the upgrade director under asp_run with the --revert option:
<aspDir>/bin/asp_run python /tmp/udtmp/upgradeDirector/upgradeDirector.py --revert

* --restart
To restart the upgrade (losing current state), run with the --restart option.
<aspDir>/bin/asp_run python /tmp/udtmp/upgradeDirector/upgradeDirector.py --restart <aspdir>

* --nocopy
To skip the step that pushes the upgrade director to the other controller and starts it, use "--nocopy" along with one of the other flags above.

* --display=<ip>
If you would like it to open progress and debugging windows, use "--display=<ip address>". Note your X server on "display" machine must be configured to accept incoming x client requests (xhost +) on the default "X" port.

===Software Overview===

Please see the API documentation for details on the software.

Doc:latest/statsguide

2013-08-15T16:34:13Z

Stone: /* StressTest */

=='''Preface'''==

''SAFplus Performance and Test Guide'' guide provides information about how the SAFplus system performs under load and how we test the product.

===Audience===

This guide is designed for system integrators, designers, and system architects. To use the product, you must be aware of the fundamentals of design, development, operation, management and configuration of telecommunication and networking systems. You must also be familiar with C programming, UML notations, and have the 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 C 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 and 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 Documents===

For additional information about OpenClovis products, refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform 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 summarizes 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.
* '''[[Doc:latest/safcompliance | SAFplus Platform 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.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains 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 SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform 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.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform 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.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' 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.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===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. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

=='''Performance'''==

=='''Test'''==

===StressTest===
[describe what the test tests]
====Required Cluster Configuration====
[what cluster configuration is required. If there are multiple possible configurations, please describe the minimum configuration and the complete configuration. Describe what additional tests you get by running the complete vs the minimum.]

====Running====
[how can the test be run by hand? what configuration tweaks are there? What SGs need to be unlocked, etc? Am I expected to do some kills, pull links or stop nodes for HA]

====What to Observe====
[ How to prove that the test is testing?
Post interesting logs generated, if "top", "tipc-config xxx", etc are informative then talk about them]

===Test Document Template===
[describe what this test tests]
====Required Cluster Configuration====
[what cluster configuration is required. If there are multiple possible configurations, please describe the minimum configuration and the complete configuration. Describe what additional tests you get by running the complete vs the minimum.]

====Running====
[how can the test be run by hand? what configuration tweaks are there? What SGs need to be unlocked, etc? Am I expected to do some kills, pull links or stop nodes for HA]

====What to Observe====
[ How to prove that the test is testing?
Post interesting logs generated, if "top", "tipc-config xxx", etc are informative then talk about them]

Doc:Latest/SAFplus Availability/Scalability Platform Documentation

2013-08-15T16:26:59Z

Stone: /* SAFplus Availability/Scalability Platform */

==SAFplus Availability/Scalability Platform==
:[[Doc:latest/relnotes | Release Notes ]]
:[[Doc:latest/installguide | Installation Guide]]
:[[Doc:latest/tutorial | Sample Application Tutorial]]
:[[Doc:latest/evalguide | Evaluation System User's Guide]]
:[[Doc:latest/ideguide | IDE User Guide]]
:[[Doc:latest/sdkguide | SDK User Guide]]
:[[Doc:latest/safcompliance | SAF Compliance]]
:[[Doc:latest/logtoolguide | LogTool User's Guide]]


===API Documentation===

==== SA-Forum Compliant Services ====
:Many SAFplus Platform services are SAF (Service Availability Forum) compliant. The full SAF API documentation is available from [http://www.saforum.org the Service Availability Forum]. Selected documents are available here:
*[http://help.openclovis.com/saf/SAI-AIS-AMF-B.04.01.AL Availability Management Framework]
*[http://help.openclovis.com/saf/SAI-AIS-CKPT-B.02.02.AL Checkpoint Service]
*[http://help.openclovis.com/saf/SAI-AIS-MSG-B.03.01.AL Message Service]
*[http://help.openclovis.com/saf/SAI-AIS-EVT-B.03.01.AL Event Service]

*[http://help.openclovis.com/saf/SAI-AIS-CPROG-B.05.02.AL C Programming Model]

==== SAFplus Platform Additional APIs ====
: Documentation of SAFplus Platform APIs is located here [[http://help.openclovis.com/api/index.html SAFplus API Documentation]]. This API documentation is also located within the SAFplus Platform header files.

=== 3rdparty Services and Tools Documentation ===

* [http://tipc.sourceforge.net/doc/tipc_2.0_users_guide.html TIPC] is a Linux kernel module that provides fast, low latency cluster based messaging and is a network transport option under SAFplus.

 

==SAFplus Platform Runtime Director Documentation==

:[[Doc:latest/awdguide | Runtime Director User's Guide]]
 
==[[Test Automation Environment]]==
:[[Doc:latest/taeguide | TAE Users Guide]] : Installation, configuration, discussion and examples
:[http://help.openclovis.com/static/taeApiDoc TAE Python APIs] : API documentation for the Python system test case layer
:[http://help.openclovis.com/static/apirefs/a00447.html TAE C APIs]: API documentation for the C unit test case layer
 

==SAFplus Platform Plugins==

====[[SAFplus Management Framework]] EXPERIMENTAL====
:The [[SAFplus Management Framework]] provides a powerful element management framework.
====[[PostgreSQL Database Integration]] EXPERIMENTAL====
:The [[PostgreSQL Database Integration]] provides an easy way to deploy a highly available SQL database for use by applications in your cluster.
====[[CouchDB Integration]] EXPERIMENTAL ====
:The [[CouchDB Integration]] provides an integration between CouchDB and SAFplus, providing a highly available nosql database solution.

Doc:latest/statsguide

2013-08-15T16:23:13Z

Stone: Created page with "=='''Preface'''== ''SAFplus Performance and Test Guide'' guide provides information about how the SAFplus system performs under load and how we test the product. ===Audienc..."

=='''Preface'''==

''SAFplus Performance and Test Guide'' guide provides information about how the SAFplus system performs under load and how we test the product.

===Audience===

This guide is designed for system integrators, designers, and system architects. To use the product, you must be aware of the fundamentals of design, development, operation, management and configuration of telecommunication and networking systems. You must also be familiar with C programming, UML notations, and have the 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 C 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 and 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 Documents===

For additional information about OpenClovis products, refer to the following guides:
* '''[[Doc:latest/relnotes | SAFplus Platform 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 summarizes 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.
* '''[[Doc:latest/safcompliance | SAFplus Platform 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.
* '''[[Doc:latest/installguide | SAFplus Platform Installation Guide]]''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''[[Doc:latest/tutorial | SAFplus Platform Sample Application Tutorial]]''' explains 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 SAFplus Platform offering.
* '''[[Doc:latest/evalguide | SAFplus Platform 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.
* '''[[Doc:latest/sdkguide | SAFplus Platform SDK User Guide]]''' provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
* '''[[Doc:latest/ideguide | SAFplus Platform IDE User Guide]]''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''[[Doc:latest/logtoolguide | SAFplus Platform 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.
* '''SAFplus Platform API Reference Guide [http://www.openclovis.org/doc/latest/apirefs/index.html]''' 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.
* '''[[SAFplus Platform Console Reference Guide]]''' provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===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. Or even better, edit (or comment in) the page on our documentation wiki located at [http://help.openclovis.com http://help.openclovis.com].

=='''Performance'''==

=='''Test'''==

===StressTest===

====Required Cluster Configuration====

====Running====

====What to Observe====

2013-06-10T13:58:25Z

Stone:

Doc:latest/evalguide/csa102

2013-06-07T15:22:08Z

Stone: /* Launching the SAFplus Platform IDE */

==csa102 Redundancy and Failover==

===Objective===

This sample demonstrates basic HA (High Availability) and SU (Service Unit) fail-over functionality. The application has two components, both processing the same workload as csa101, that is, repeatedly printing "Hello World". The difference, however, is that in this case there is now an active component and a standby component, with only the active component performing the printing function.

csa102 is quite similar to csa101, and this section will discuss the areas in which they deviate.

===What you will learn===

*Keeping track of HA states and how to respond to callbacks requesting HA state changes.

===How to create new Project Model csa102===
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. This is same as created for ''csa101''.

Create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE as follows:</li>
<code><pre>
# cl-ide
</pre></code>
<li>Start cl-ide by specifying the full path</li>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code. Select the workspace and click '''OK''' to launch SAFplus Platform IDE.

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model '''csa102''' for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.This step is similar compared to ''csa101''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

Enter the following information (These steps are similar compared to ''csa101''):

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''SDK Location''': Enter the location where the SAFplus Platform SDK was installed. For e.g. if the SDK was installed at location /opt/clovis, then the SDK location is /opt/clovis/sdk-<version>.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 is installed on your system. If Python 2.5.0 was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Tutorial_csa102_AddBlade.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Tutorial_csa102_AddNode.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:Tutorial_csa102_DefineProgramNames.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa102 continuously prints "Hello World!" '''redundantly''').

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa102' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_csa102_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our redundant model (which only has one node with one Active component and another standby component used for redundancy) change the '''Redundancy Model''' to '2N Redundancy' as shown.

 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa102 application will not yet start printing "Hello World!".

<li>The third change that we want to make is to the '''Auto repair'''. The '''Auto repair''' defines the state of the component to be achieved after failure of the component. So our csa102 application will not yet start printing "Hello World!".
<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa102'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_csa102_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

To make the model to recover from failure by Stand-by component, the field '''Recovery action on error''' needs to be changed to ''Component fail over''.

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' window will be displayed. If you now completely expand the AMF Configuration branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_csa102_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

===Code===

The code can be geneteted using the same steps as mentioned for csa101. The genetated code can be found within the following directory
<project-area_dir>/eval/src/app/csa102Comp

This sample component is implemented in a few C modules that are quite similar to the csa101 module. We will discuss the additions in detail.

We change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10, CL_LOG_AREA_UNSPECIFIED, CL_LOG_CONTEXT_UNSPECIFIED, __VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;
</pre></code>
|}

Next, the log stream is initialized in the application's "main" function:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
/*
* Initialize the log stream
*/
clEvalAppLogStreamOpen((ClCharT*)appName.value, &gEvalLogStream);
</pre></code>
|}

This function is implemented in the src/app/ev.c file.

As with csa101, the <code>clCompAppAMFCSISet()</code> function is called to set the component's HA state, and the following block of code assigns this requested state to the component, while verbosely detailing this process:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
void clCompAppAMFCSISet(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

clCompAppAMFPrintCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/
pthread_t thr;

clprintf(CL_LOG_SEV_INFO,"csa102: ACTIVE state requested; activating service");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Standby state requested");
running = 0;
saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Acknowledging new state quiesced");
running = 0;

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Signaling completion of QUIESCING");
running = 0;

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
...
</pre></code>
|}

In this case the application spawns a thread when it is assigned active which is a very common strategy for threaded applications. It also sets a global variable "running" to true. When the application is "quesced" -- that is when the active work assignment is taken away -- the application sets this global variable back to 0 to trigger the active thread to quit itself. The thread is simply defined as:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO,"csa102: Threaded Hello World! %s", show_progress());
sleep(2);
}
return NULL;
}

static char* show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}
</pre></code>
|}

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds)) saAmfDispatch(amfHandle, SA_DISPATCH_ALL);

if (running) clprintf(CL_LOG_SEV_INFO,"csa102: Unthreaded Hello World! %s", show_progress()); // Run the "active" code
else clprintf(CL_LOG_SEV_INFO,"csa102: idle");
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===How to Run csa102 and What to Observe===

As with the csa101 example we will use the SAFplus Platform Console to manipulate the administrative state of the csa102 service group.

<ol>
<li>Start the SAFplus Platform Console<code><pre>
# cd /root/asp/bin
# ./asp_console</pre></code>

<li>Then put the csa102SGI0 service group into lock assignment state using the following commands.<code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
</pre></code>

Because example 102 has two components there will be two application log files to view. These are <code>/root/asp/var/log/csa102CompI0Log.latest</code> and <code>/root/asp/var/log/csa102CompI1Log.latest</code>. Viewing these application logs using the <code>tail -f</code>, you should see the following.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00029 : INFO)
Component [csa102CompI0] : PID [13418]. Initializing

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00030 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00031 : INFO)
IOC Port : 0x80

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00032 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00033 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| //root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00028 : INFO)
Component [csa102CompI1] : PID [13422]. Initializing

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00029 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00030 : INFO)
IOC Port : 0x81

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00031 : INFO)
csa102: Instantiated as component instance csa102CompI1.

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00032 : INFO)
csa102CompI1: Waiting for CSI assignment...
</pre></code>
|}

<li>Next, unlock the service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa102SGI0
</pre></code>
and in the /var/log/csa102CompI*.log files we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! .
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:43:00 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00043 : INFO)
csa102: New state is not the ACTIVE; deactivating service
</pre></code>
|}

These can be watched in a separate terminal window using <code>tail -f</code>. csa102CompI0 is the active component in this case, and csa102CompI1 is the standby. Consequently, the "Hello world!" lines appear in csa102CompI0.log and not in csa102CompI1.log. They will continue to be logged to that file until the HA state of that component changes, for example, when the process logging those lines is killed. In the mean time the standby component: csa102CompI1 just waits until it is told that it should take over the workload.
</ol>

'''Changing the HA state of the Client/Server'''

The easiest way to test component fail-over is to kill the process associated with the active component using the <code>kill</code> command. For this you need to know the process ID of the active component. To find the process ID issue the following command from a bash shell.
# ps -eaf | grep csa102
This should produce an output that looks similar to the following.
root 15872 15663 0 13:49 ? 00:00:01 csa102Comp -p
root 16328 15663 0 13:56 ? 00:00:00 csa102Comp -p
root 17304 16145 0 14:11 pts/4 00:00:00 grep csa102
Notice the two entries that end with <code>csa102Comp -p</code>. These are our two component processes. The first one is usually the active process. This is the one that we will kill. In this case the process ID is 15872. So to kill the active component you issue the command:
# kill -9 15872
[[File:OpenClovis_Note.png]]If this step does not result in the active component being killed then it is likely that the standby component was killed. In this case simply try killing the other process.

After executing the <code>kill</code> command you can see in the csa102CompI1 application that the standby component is now active.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! . .
</pre></code>
|}

This indicates that the standby component has taken over for the failed active component.

Looking in the csa102CompI0 application log you can see that this component was killed and has been restarted. Since csa102CompI1 took over as the active component this component now goes into the standby state.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00040 : INFO)
Component [csa102CompI0] : PID [13712]. Initializing

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00041 : INFO)
IOC Address : 0x1

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00042 : INFO)
IOC Port : 0x80

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00043 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00044 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

You can continue to observe this failover by alternately killing the active component.

To stop csa102 using the SAFplus Platform Console.
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
Successfully changed state of csa102SGI0 to LockAssignment
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa102SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
Successfully changed state of csa102SGI0 to LockInstantiation and exit.

===Summary===

This Sample Application has covered basic HA and failover, with changing the state of a component to active and standby.

Doc:latest/evalguide/csa102

2013-06-07T15:21:42Z

Stone: /* Launching the SAFplus Platform IDE */

==csa102 Redundancy and Failover==

===Objective===

This sample demonstrates basic HA (High Availability) and SU (Service Unit) fail-over functionality. The application has two components, both processing the same workload as csa101, that is, repeatedly printing "Hello World". The difference, however, is that in this case there is now an active component and a standby component, with only the active component performing the printing function.

csa102 is quite similar to csa101, and this section will discuss the areas in which they deviate.

===What you will learn===

*Keeping track of HA states and how to respond to callbacks requesting HA state changes.

===How to create new Project Model csa102===
The first step in setting up our example is to create a model which represents the system that we will eventually deploy. This is done through the '''SAFplus Platform IDE'''. In this chapter we will step through the following tasks:
* Create a project area
* Launch the '''SAFplus Platform IDE'''
* Create the IDE project
* Specify the Resource model (the types of physical hardware in our system)
* Specify the Component model (the types of components or applications in our system)
* Specify which Components run on which Resources
* Specify important build and boot parameters

===Creating a New Project Area===
A project area is a directory on your system where you can develop SAFplus Platform models and generate the code corresponding to those models. This is same as created for ''csa101''.

Create a project area using a script from the command line. To create a project area named '''projectarea1''' in the '''/home/clovis''' directory you should execute the following command:
<code><pre>
# cl-create-project-area /home/clovis/projectarea1
</pre></code>

===Launching the SAFplus Platform IDE===
You can launch the '''SAFplus Platform IDE''' from the command line. If you chose to create symbolic links during installation you can simply enter <code>'''cl-ide'''</code> from any directory. If you did not create symbolic links during installation you can either:

<ul>
<li>Add the installation directory to the shells search path and then launch the IDE.</li>
<code><pre>
# cl-ide
</pre></code>
<li>Start cl-ide by specifying the full path</li>
</ul>

The splash screen for SAFplus Platform IDE is displayed as illustrated in Figure [[#SAFplus Platform IDE Opening Screen | SAFplus Platform IDE Opening Screen]].

[[File:Tutorial_GettingStartedIDE_OpeningScreen.png|frame|center| '''SAFplus Platform IDE Opening Screen''' ]]

You will then be prompted to select a workspace in which to do your work as illustrated in Figure [[#SAFplus Platform IDE Workspace Launcher | SAFplus Platform IDE Workspace Launcher]].

The workspace you select should correspond to the project area that you created in the previous section (in this case "/home/clovis/projectarea1"). Note that the workspace includes a subdirectory of "/ide_workspace". This is done strictly for organizational purposes. It keeps the IDE models separate from the generated SAFplus Platform models and code. Select the workspace and click '''OK''' to launch SAFplus Platform IDE.

The '''SAFplus Platform''' IDE is launched and you are now looking at the main work area. For more information about the components of this main work area including the SAFplus Platform IDE menu and toolbar, see ''SAFplus Platform IDE User Guide''.

===Creating the Sample Project===
We will now create a project within the '''SAFplus Platform IDE'''. This project will hold both the resource model and the component model '''csa102''' for our example system. The resource model is a physical view of the resources (the chassis, the blade types, etc.) in our system. The component model is a logical view of the components (applications, etc.) in our system.

We will be using the '''New Project Wizard''' to create our project. The wizard captures some high-level information about the system that we are building and performs a lot of the basic setup for us.

[[File:OpenClovis_Note.png]]The same model that we are building through the wizard could also be created manually through the Resource and Component Editors. For more information on the Resource and Component Editors see ''SAFplus Platform IDE User Guide''.This step is similar compared to ''csa101''.

To launch the '''New Project Wizard''' select '''File''' > '''New''' > '''Project''' from the IDE menu bar.

The '''New Project Wizard''' is displayed and '''Clovis System Project''' is selected by default as illustrated in Figure [[#New Project Wizard | New Project Wizard]].

Click '''Next'''. The '''Clovis System Project''' window is displayed as illustrated in Figure [[#Clovis System Project | Clovis System Project]].

Enter the following information (These steps are similar compared to ''csa101''):

<ul>
<li>'''Project Name''' : Enter the name of your new project as '''SampleModel'''.
 Do not use spaces or special characters for the project name. The project name can be alphanumeric, but cannot start with a number or have only numbers.
 Select '''Use default''' to use the same directory mentioned in the '''Directory''' field.

<li>'''SDK Location''': Enter the location where the SAFplus Platform SDK was installed. For e.g. if the SDK was installed at location /opt/clovis, then the SDK location is /opt/clovis/sdk-<version>.

<li>'''Project Area Location''': Enter the location where the generated source code for the model should be stored.
 This can be any existing directory but is usually the project area that was created in the previous section.

<li>'''Python Location''': Enter the location where Python 2.5.0 is installed on your system. If Python 2.5.0 was installed by SAFplus Platform SDK, the directory is <code>'''<installation_directory>/buildtools/local/bin'''</code>.
</ul>

Click '''Next'''. The '''Add New Blade Type''' window is displayed. This dialog is used to define the blade types that are in our system.

[[File:Tutorial_csa102_AddBlade.png|frame|center| '''Add New Blade Type''' ]]

Remember that the system we are modelling has only one blade type...a System Controller.
<ul>
<li>Use the '''Add''' button to add a new blade type to the list. Name this blade type 'SysBlade' (for System Controller blade).
</ul>

Click '''Next'''. The '''Add New SAF Node Type''' window is displayed. This dialog is used to define the type of logical node that will be run on the corresponding blade type defined in the previous dialog.

[[File:Tutorial_csa102_AddNode.png|frame|center| '''Add New SAF Node Type''' ]]

Node types represent groups of software. They are classified as either a System Controller class or a Payload class. This distinction gives the node type certain characteristics which cause it to behave in a well-defined manner. Since we have only a System Controller in our system we will add a node type of class System Controller.

<ul>
<li>Use the '''Add''' button to add a new node type to the list. Name the node type 'SCNode' and ensure that its node class is 'System Controller (SAF Class B)'.
</ul>

Click '''Next'''. The '''Specify Program Names''' window is displayed. This dialog is used to create programs or SAF Service Types and associate them with the SAF Node Types specified in the previous dialog.

[[File:Tutorial_csa102_DefineProgramNames.png|frame|center| '''Specify Program Names''' ]]

In our system we need one SAF Service Type which represents our high availability software (csa102 continuously prints "Hello World!" '''redundantly''').

<ul>
<li>Use the '''Add''' button to add a program name to the list. Change the program name to 'csa102' and associate the program with the 'SCNode' node type.
</ul>

Click '''Finish'''. This will create the sample model using the blade type, node type, and program name information collected through the 'New Project Wizard' dialogs.

====Configuring the Service Group====
To make changes to the Service Group double-click on the box titled '''csa101SG'''. The '''Service Group Details''' dialog is displayed.

[[File:Tutorial_csa102_ServiceGroupDetails.png|frame|center| '''Service Group Details''' ]]

<ul>
<li>The first change we want to make is to the '''Redundancy Model'''. The '''Redundancy Model''' is the strategy that is used by the SAFplus Platform system to recover from a node failure. For our redundant model (which only has one node with one Active component and another standby component used for redundancy) change the '''Redundancy Model''' to '2N Redundancy' as shown.

 [[File:OpenClovis_Note.png]]You will notice that when you change the redundancy model some of the other fields are modified automatically and become read-only. This is to ensure integrity of the redundancy models.

<li>The second change that we want to make is to the '''Admin State'''. The '''Admin State''' defines the state of the component when the system is first brought up. In our case we want to change the '''Admin State''' to be 'Locked Initialized'. This means that when the system first starts up this '''Service Group''' (and its subcomponents) will be initialized but not yet put into a running state. So our csa102 application will not yet start printing "Hello World!".

<li>The third change that we want to make is to the '''Auto repair'''. The '''Auto repair''' defines the state of the component to be achieved after failure of the component. So our csa102 application will not yet start printing "Hello World!".
<li>When you are finished making the changes click the '''OK''' button to commit the changes.
</ul>

====Configuring the SAF Component====
To make changes to the SAF Component double-click on the box titled '''csa102'''. The '''SAF Component Details''' dialog is displayed.

[[File:Tutorial_csa102_SAFComponentDetails.png|frame|center| '''SAF Component Details''' ]]

To make the model to recover from failure by Stand-by component, the field '''Recovery action on error''' needs to be changed to ''Component fail over''.

The SAF Component represents our high availabilty program or executable. We need to pass a command line argument to this executable. The reason for this argument is to force the program to print the 'Hello World!' output to a special log file for our viewing. We will look at this more closely when we customize our code.

===Configuring Physical Instances===
The configuration of our logical models is complete. During this process we have defined all of the 'types' of objects in our system. Now it is time to configure actual instances of those objects so that they can be built and deployed.

Object instance configuration is done through the Availability Management Framework (AMF) via the '''AMF Configuration''' dialog.

<ul>
<li>To launch this dialog go to the the '''Clovis''' menu and select '''AMF Configuration...'''
</ul>

The '''AMF Configuration''' window will be displayed. If you now completely expand the AMF Configuration branch of the tree in the left-hand pane you will see the following.

[[File:Tutorial_csa102_AMFConfig.png|frame|center| '''AMF Configuration Dialog''' ]]

===Code===

The code can be geneteted using the same steps as mentioned for csa101. The genetated code can be found within the following directory
<project-area_dir>/eval/src/app/csa102Comp

This sample component is implemented in a few C modules that are quite similar to the csa101 module. We will discuss the additions in detail.

We change the logging from the default "application" stream to a custom stream. To do this, we include the header that defines our config routines, change the default "clLogApp" macro to use a different stream, and define that stream as a global variable:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
#include "../ev/ev.h"
...
#define clprintf(severity, ...) clAppLog(gEvalLogStream, severity, 10, CL_LOG_AREA_UNSPECIFIED, CL_LOG_CONTEXT_UNSPECIFIED, __VA_ARGS__)
...
ClLogStreamHandleT gEvalLogStream = CL_HANDLE_INVALID_VALUE;
</pre></code>
|}

Next, the log stream is initialized in the application's "main" function:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
/*
* Initialize the log stream
*/
clEvalAppLogStreamOpen((ClCharT*)appName.value, &gEvalLogStream);
</pre></code>
|}

This function is implemented in the src/app/ev.c file.

As with csa101, the <code>clCompAppAMFCSISet()</code> function is called to set the component's HA state, and the following block of code assigns this requested state to the component, while verbosely detailing this process:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
void clCompAppAMFCSISet(SaInvocationT invocation,
const SaNameT *compName,
SaAmfHAStateT haState,
SaAmfCSIDescriptorT csiDescriptor)
{
/*
* Print information about the CSI Set
*/

clprintf (CL_LOG_SEV_INFO, "Component [%.*s] : PID [%d]. CSI Set Received\n",
compName->length, compName->value, mypid);

clCompAppAMFPrintCSI(csiDescriptor, haState);

/*
* Take appropriate action based on state
*/

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/
pthread_t thr;

clprintf(CL_LOG_SEV_INFO,"csa102: ACTIVE state requested; activating service");
running = 1;
pthread_create(&thr,NULL,activeLoop,NULL);

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Standby state requested");
running = 0;
saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Acknowledging new state quiesced");
running = 0;

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

case SA_AMF_HA_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/
clprintf(CL_LOG_SEV_INFO,"csa102: Signaling completion of QUIESCING");
running = 0;

saAmfCSIQuiescingComplete(amfHandle, invocation, SA_AIS_OK);
break;
}
...
</pre></code>
|}

In this case the application spawns a thread when it is assigned active which is a very common strategy for threaded applications. It also sets a global variable "running" to true. When the application is "quesced" -- that is when the active work assignment is taken away -- the application sets this global variable back to 0 to trigger the active thread to quit itself. The thread is simply defined as:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
void* activeLoop(void* p)
{
while (running)
{
clprintf(CL_LOG_SEV_INFO,"csa102: Threaded Hello World! %s", show_progress());
sleep(2);
}
return NULL;
}

static char* show_progress(void)
{
static char bar[] = " .";
static int progress = 0;

/* Show a little progress bar */
return &bar[sizeof(bar)-2-(progress++)%(sizeof(bar)-2)];
}
</pre></code>
|}

The example also demonstrates a non-threaded approach. But first, some background: for both threaded and non-threaded applications, the main must have a "dispatch" loop that handles incoming AMF notifications and calls the relevant callback. So to implement a single threaded SAF aware application, the programmer must modify this dispatch loop adding active (and potentially standby) functionality:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
main(...)

do
{
struct timeval timeout;
timeout.tv_sec = 2; timeout.tv_usec = 0;

FD_ZERO(&read_fds);
FD_SET(dispatch_fd, &read_fds);

if( select(dispatch_fd + 1, &read_fds, NULL, NULL, &timeout) < 0)
{
if (EINTR == errno)
{
continue;
}
clprintf (CL_LOG_SEV_ERROR, "Error in select()");
perror("");
break;
}
if (FD_ISSET(dispatch_fd,&read_fds)) saAmfDispatch(amfHandle, SA_DISPATCH_ALL);

if (running) clprintf(CL_LOG_SEV_INFO,"csa102: Unthreaded Hello World! %s", show_progress()); // Run the "active" code
else clprintf(CL_LOG_SEV_INFO,"csa102: idle");
}while(!unblockNow);

</pre></code>
|}

This code should be very familiar to anyone who has written single threaded "event loop" style code. As can be seen in the code snippet above, the select is given an idle timeout (in a real application the timeout would be much smaller) and the application only calls <code>saAmfDispatch</code> if the select actually indicates that the there is data in the FD. Then it falls down into an "if" statement that checks if we are active "if (running)..." and outputs a log if that is the case.

===How to Run csa102 and What to Observe===

As with the csa101 example we will use the SAFplus Platform Console to manipulate the administrative state of the csa102 service group.

<ol>
<li>Start the SAFplus Platform Console<code><pre>
# cd /root/asp/bin
# ./asp_console</pre></code>

<li>Then put the csa102SGI0 service group into lock assignment state using the following commands.<code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
</pre></code>

Because example 102 has two components there will be two application log files to view. These are <code>/root/asp/var/log/csa102CompI0Log.latest</code> and <code>/root/asp/var/log/csa102CompI1Log.latest</code>. Viewing these application logs using the <code>tail -f</code>, you should see the following.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00029 : INFO)
Component [csa102CompI0] : PID [13418]. Initializing

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00030 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00031 : INFO)
IOC Port : 0x80

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00032 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00033 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| //root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00028 : INFO)
Component [csa102CompI1] : PID [13422]. Initializing

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00029 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00030 : INFO)
IOC Port : 0x81

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00031 : INFO)
csa102: Instantiated as component instance csa102CompI1.

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00032 : INFO)
csa102CompI1: Waiting for CSI assignment...
</pre></code>
|}

<li>Next, unlock the service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa102SGI0
</pre></code>
and in the /var/log/csa102CompI*.log files we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! .
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:43:00 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00043 : INFO)
csa102: New state is not the ACTIVE; deactivating service
</pre></code>
|}

These can be watched in a separate terminal window using <code>tail -f</code>. csa102CompI0 is the active component in this case, and csa102CompI1 is the standby. Consequently, the "Hello world!" lines appear in csa102CompI0.log and not in csa102CompI1.log. They will continue to be logged to that file until the HA state of that component changes, for example, when the process logging those lines is killed. In the mean time the standby component: csa102CompI1 just waits until it is told that it should take over the workload.
</ol>

'''Changing the HA state of the Client/Server'''

The easiest way to test component fail-over is to kill the process associated with the active component using the <code>kill</code> command. For this you need to know the process ID of the active component. To find the process ID issue the following command from a bash shell.
# ps -eaf | grep csa102
This should produce an output that looks similar to the following.
root 15872 15663 0 13:49 ? 00:00:01 csa102Comp -p
root 16328 15663 0 13:56 ? 00:00:00 csa102Comp -p
root 17304 16145 0 14:11 pts/4 00:00:00 grep csa102
Notice the two entries that end with <code>csa102Comp -p</code>. These are our two component processes. The first one is usually the active process. This is the one that we will kill. In this case the process ID is 15872. So to kill the active component you issue the command:
# kill -9 15872
[[File:OpenClovis_Note.png]]If this step does not result in the active component being killed then it is likely that the standby component was killed. In this case simply try killing the other process.

After executing the <code>kill</code> command you can see in the csa102CompI1 application that the standby component is now active.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! . .
</pre></code>
|}

This indicates that the standby component has taken over for the failed active component.

Looking in the csa102CompI0 application log you can see that this component was killed and has been restarted. Since csa102CompI1 took over as the active component this component now goes into the standby state.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00040 : INFO)
Component [csa102CompI0] : PID [13712]. Initializing

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00041 : INFO)
IOC Address : 0x1

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00042 : INFO)
IOC Port : 0x80

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00043 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00044 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

You can continue to observe this failover by alternately killing the active component.

To stop csa102 using the SAFplus Platform Console.
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
Successfully changed state of csa102SGI0 to LockAssignment
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa102SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
Successfully changed state of csa102SGI0 to LockInstantiation and exit.

===Summary===

This Sample Application has covered basic HA and failover, with changing the state of a component to active and standby.