How to Connect SAPSTARSRV and Cluster Frameworks Using the Components Saphascriptco.so and SAP_Vendor_Cluster_Connector

7/22/2019 How to Connect SAPSTARSRV and Cluster Frameworks Using the Components Saphascriptco.so and SAP_Vendor_C…

http://slidepdf.com/reader/full/how-to-connect-sapstarsrv-and-cluster-frameworks-using-the-components-saphascriptcoso 1/12

SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com | BA - boc.sap.com | UAC - uac.sap.com

© 2012 SAP AG 1

How to Connect SAPSTARSRV andCluster Frameworks using theComponents saphascriptco.so andSAP_Vendor_Cluster_Connector

Applies to:

All SAP products controlled by sapstartsrv. For more information, visit the Application Managementhomepage.

Summary

Running SAP in a high availability cluster environment needs additional interfaces to communicate betweenthe SAP program SAPSTARTSRV and the high availability cluster. At least it is essential to inform thecluster, if a SAP instance is started or shutdown. This article describes the reference interfaceimplementation sap_suse_cluster_connector.

Author: Fabian Herschel

Company: SUSE Linux Products GmbH

Created on: April 3, 2012

Version: 1.0

Author Bio

Fabian Herschel is SAP architect and employee of SUSE Linux Products GmbH in Nuremberg,Germany. He is currently working directly at the SAP LinuxLab in Rot and is leading, together with

his colleague Markus Gürtler, the creation of the architectures of HA solutions for SAP productsrunning on SUSE Linux Enterprise Server and the SUSE Linux Enterprise High Availability

Extention.

https://www.sdn.sap.com/irj/sdn/applicationmanagement








How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco.so and SAP_Vendor_Cluster_Connector


© 2012 SAP AG 2

Table of Contents

A Problem and its Solution ................................................................................................................................. 3 The Components of the Solution ........................................................................................................................ 3

The involved components ............................................................................................................................... 3 A typical call flow for SAP instance start ......................................................................................................... 4 A typical call flow for SAP instance stop ......................................................................................................... 5

Mapping sapstartsrv-Calls to Library functions and cluster connector commands ............................................ 6 Manual Page of the sap_suse_cluster_connector ............................................................................................. 6

Name ............................................................................................................................................................... 6 Synopsis .......................................................................................................................................................... 6 Description ...................................................................................................................................................... 6 Commands ...................................................................................................................................................... 6 Params ............................................................................................................................................................ 7 Output Fields ................................................................................................................................................... 7 Commands in Detail ........................................................................................................................................ 7 Examples ........................................................................................................................................................ 9 Exit Status ....................................................................................................................................................... 9

Usage and configuration of sapstartrsv with saphascriptco ............................................................................. 10 Prerequisites ................................................................................................................................................. 10 Usage ............................................................................................................................................................ 10 Logging/Debugging: ...................................................................................................................................... 10 Additional profile parameters: ....................................................................................................................... 10

Related Content ................................................................................................................................................ 11 Disclaimer and Liability Notice .......................................................................................................................... 12





© 2012 SAP AG 3

A Problem and its Solution

One of the classical problems running SAP instances in a high available environment is that if a SAPadministrator changes the status (start/stop) of a SAP instance without using the interfaces provided by thecluster software than the cluster framework will detect that as an error status and will bring the SAP instanceinto the old status by either starting or stopping the SAP instance. This can result into very dangeroussituations, if the cluster changes the status of a SAP instance during some SAP maintenance tasks.

The solution is that the central component SAPSTARTSRV, which controls SAP instances since SAP Kernel

versions 6.4, will be enabled to communicate the state change (start/stop) to the cluster software.

The Components of the Solution

To enable sapstartsrv to communicate with the cluster product the process needs an additional interface

to ensure proper functionality.

The involved components

For a standard start or stop of a SAP instance two major components are needed a client program

requesting the start or stop and sapstartsrv to process the request.

In the cluster integrated scenario there are now five components working together:

Client (responsible: SAP)

The client like sapcontrol, startsap, ACC, SAP Management Console and others are the same

as in the standard scenario. For all mentioned client programs SAP is responsible. All those clients

are typically part of the SAP delivery. All the clients must use the web-service interface of

sapstartsrv. No client is allowed to work around of this server process. In other case the

complete solution wold be broken.

Server (responsible: SAP)

The server process sapstartsrv is providing web-service interfaces for starting, stopping SAP

instances and also for getting information about the status of a SAP instance. There are a lot of

detailed functions which can be called. You can use sapcontrol to get a list of available functions.

This program is also delivered by SAP.

Library (responsible: SAP)

The new library saphascriptco.so for Unix (saphascriptco.dll for Windows) is loaded by

sapstartsrv, if the parameter service/sapha is used in the SAP instance profile. More details

about the needed SAP parameters will follow in this article. Sapstartsrv uses the library as a

generic interface to a set of cluster products. The library saphascriptco.so takes the calls by

sapstartsrv and matches them to calls to an external helper program the cluster connector.

Cluster connector (responsible: Cluster Vendor)

The cluster connector like sap_suse_cluster_connector is called by the library

saphascriptco.so and is an abstraction layer between the SAP sapstartrv and the cluster

product. The cluster connector is responsible to answer questions like “is a SAP instance controlled

by the cluster?” or “ please stop cluster resource rsc_mySAP ”. While sapstartsrv andsapscriptco.so does not need anything to know about the cluster product the cluster connector

needs to answer all queries or to “fire” cluster commands to change the status of cluster resources.

Cluster product (responsible: Cluster Vendor)

The last piece of the solution is the cluster product of course. Discussing feature sets, architectures

and responsibilities of the several cluster products is not in the scope of this document. In the scope

of this solution the cluster product must be able to answer the queries of the cluster connector and to

process the “fired” changes of cluster resources.





© 2012 SAP AG 4

A typical call flow for SAP instance start

To understand the flow of a SAP instance start in a cluster context the following diagram gives you a firstoverview. SAP kindly provided this flow diagrams.

Abbildung 1: Flow diagram of a SAP instance start request

Description of the work flow including the cluster connector:

The administrator uses a client like SAP Management Console or sapcontrol to start a SAP

instance. This request is sent via the SOAP based Start -WebService to SAPSTARTSRV.

Now SAPSTARTSRV calls function SAP_HA_FindInstance in library saphascriptco.so, if the

cluster is responsible for this SAP instance. The library saphascriptco.so itself uses the cluster

connector function lsr (details for lsr see call below) to answer that query. The cluster connector is

the external system command like sap_vendor_cluster_connector provided by the cluster vendor.





© 2012 SAP AG 5

The library return with SAP_HA_OK , if the cluster connector has found the SAP instance. If the

cluster is not responsible SAPSTARTRV starts the SAPinstance using its own functionality.

If the cluster is responsible for that SAP instance SAPSTARTSRV uses the library

saphascriptco.so to ask the cluster, if the requested cluster action (here start) is already in

progress. This query has to be answered by the external cluster connector using the function cpa.

The library saphascriptco.so takes the answer and returns SAP_HA_OK or

SAP_HA_START_IN_PROGRESS back to SAPSTARTRV.

Depending on the return code SAPSTARTSRV decides to either request the cluster to start the

SAPinstance or to do the start action by its own:

If SAPSTARTRV got the return code SAP_HA_OK it uses the library to tell the cluster to change

the resource status. The library will call the function fra (action start) of the cluster connector.

If SAPSTARTRV got the return code SAP_HA_START_IN_PROGRESS it will continue to start the

SAP instance by its own. This means that SAP_HA_START_IN_PROGRESS is the return code

to tell SAPSTARTRSV that its now ok to start the SAP instance.

A typical call flow for SAP instance stop

For the stop of a SAP instance the flow is nearly the same of course with action “Stop” instead of “Start”.

The administrator uses a client like SAP Management Console or sapcontrol to stop a SAP

instance. This request is sent via the SOAP based Stop-WebService to SAPSTARTSRV.

Now SAPSTARTSRV calls function SAP_HA_FindInstance in library saphascriptco.so, if the

cluster is responsible for this SAP instance. The library saphascriptco.so itself uses the cluster

connector function lsr (details for lsr see call below) to answer that query. The library return will

SAP_HA_OK , if the cluster connector has found the SAP instance. If the cluster is not responsible

SAPSTARTRV stops the SAPinstance using its own functionality.

If the cluster is responsible for that SAP instance SAPSTARTSRV uses the library

saphascriptco.so to ask the cluster, if the requested cluster action (here stop) is already inprogress. This query has to be answered by the external cluster connector using the function cpa.

The library saphascriptco.so takes the answer and returns SAP_HA_OK or

SAP_HA_START_IN_PROGRESS back to SAPSTARTRV.

Depending on the return code SAPSTARTSRV decides to either request the cluster to stop the

SAPinstance or to do the stop action by its own:

If SAPSTARTRV got the return code SAP_HA_OK it uses the library to tell the cluster to change

the resource status. The library will call the function fra (action stop) of the cluster connector.

If SAPSTARTRV got the return code SAP_HA_START_IN_PROGRESS it will continue to stop the

SAP instance by its own. This means that SAP_HA_START_IN_PROGRESS is the return code

to tell SAPSTARTRSV that its now ok to stop the SAP instance.





© 2012 SAP AG 6

Mapping sapstartsrv-Calls to Library functions and cluster connector commands

The status of the implementation for version 1.0 of the sap_suse_cluster_connector and the mappingbetween the different layers is show in the following table:

SAPSTARTSRV-Call Library funct ion in

saphascr ipt .so sap_suse_cluster_connector

command Remark

FindSAPInstance SAP_HA_FindSAPInstance lsr SID NR Is used to find the cluster resource

name for a specific SAP instance.

FindDB SAP_HA_FindDB Not implemented in version 1.0

StopCluster SAP_HA_StopCluster cpa resource stop

fra resource stop

First the library checks, if a cluster

actions is already in progress. If not it

sends a cluster command to stop the

resource.

StartCluster SAP_HA_StartCluster cpa resource start

fra resource start

First the library checks, if a cluster

actions is already in progress. If not it

sends a cluster command to start the

resource.

MoveCluster SAP_HA_MoveCluster fra resource move MoveCluster is currently not called in

sapstartsrv.

FailCluster SAP_HA_FailCluster

not implemented

Not implemented in version 1.0 Fail Cluster is currently not called in

sapstartsrv.

GetClusterNodes SAP_HA_GetClusterNodes lsn SID NR GetClusterNodes is currently not called

in sapstartsrv.

Manual Page of the sap_suse_cluster_connector

This section includes the original manual page of the sap_suse_cluster_connector . All other

sap_vendor_cluster_connector implementations should be able to accept the same commands and

parameters and have to be designed to provide the same return codes and output.

Name

sap_suse_cluster_connector- handle sapstartsrv cluster calls

Synopsis

sap_suse_cluster_connector cmd options-and-params

sap_vendor_cluster_connector cmd options-and-params

Description

sap_suse_cluster_connector (or in general sap_vendor_cluster_connector) is the interface between the SAPHA cluster library and the cluster software. Currently it needs to serve calls like queries about cluster statusor to cluster resource actions.

Commands

help or --help

print help text and usage.

init

check cluster installation and do some optional initialization.





© 2012 SAP AG 7

cpa –res RES --act ACT

check for specified pending/active actions in the cluster.

fra --res RES --act ACT [ --nod NODE ]

fire/start a cluster action like start/stop/migrate a resource.

lsn --out FILE --res RES

list sap nodes for specified resource.

lsr --out FILE --sid SID --ino INO

list sap resources matching the search criteria.

Params

SID - SAP System Identifier (3 alphanum)

INO - SAP Instance Number (2 digits)

ACT - Cluster action "start" or "stop"

FILE - Outputfile for result parsing

RES - Cluster Resource Identifier

NODE - Cluster Node Name

Output Fields

All parameters identifiers like SID might also be referenced in output formats (see detailed commanddescription). Additionally there are some referenced output fields, which are not used as parameters:

GRP Cluster Group Identifier

CLUSTER_NODES List of type NODE separated with comma (,) within the cluster that could

run the resource

CURR_NODE NODE which is currently running the resource

PRIO_NODES Priorized list of type NODE (separated with comma (,)) within the cluster that

could run the resource

Commands in Detail

Init (init ialization)

Perform some basic tests, if the cluster software is installed and the cluster framework is stated. This is notintended to do a cluster validation. The command should only check, whether the cluster commands usedare available. The check “cluster framework started?” might be ignored - maybe it does not fit for somecluster architectures. In that case the check only needs to test the availability of the external and neededcluster commands.

Optionally: This command could also implement some initializations, if needed.

Parameters: None.

Return Codes

0: cluster software seams to be installed proper and cluster framework is stated

on local node.

1: error during detection of cluster status

2: script notified bad parameters

3: cluster commands are not installed correctly (missing commands)

4: cluster commands are installed correctly but cluster framework is not running

(optional)





© 2012 SAP AG 8

Output None.

cpa (c heck for p ending cluster a ctions)

This cmd should check properly against the running cluster, if a given action on a

SAP Instance is already running

Parameters: All parameters are mandatory.

--res RES Cluster resource to be queried.

--act ACT Action type (start/stop) to be queried.

Return Codes

0: found pending action of queried type

1: did not found pending action of queried type


Output None.

lsr (list s ap r esources)

This command is used to figure out the cluster resource and optionally resource group

name for a specific SAP system and instance.

Parameters - all parameters are mandatory

--out FILE Output file to be used.

--sid SID SAP system identifier to be queried.

--ino INO SAP instance number to be queried.

Return Codes

0: success

1: no success / internal error


Output Formatted query answer to given FILE.

Multiple rows (data sets) allowed even if typically there should only be one

resource matching the query. Each row / data set covers its values in a colon-separated (':') list.

Format: SID:INO:RES:GRP:CLUSTER_NODES

fra (f ire a r esource a ction)

This command fires a cluster change like “stop resource XX” or “start resource XX”.

It is not intended to wait till the cluster has processed the resource change. The

SAP instance is specified by the cluster resource name.

Parameters - only NODE is optional.

--res RES Cluster resource to be controlled.

--act ACT Cluster action (start/stop/migrate) to be "fired".

[ --nod NODE ] For migrations this defines the destination node.

Return Codes

0: success;

1: no success / internal error;


Output None.

lsn (list s ap n odes)





© 2012 SAP AG 9

This command should list the current node running a specific SAP resource and a

prioritized list of possible cluster nodes for a specific SAP instance. In this case

the SAP instance is queried by the cluster resource name.

Parameters

--out FILE Output file for results.

--res RES Cluster resource to be queried.

Return Codes

0: success;

1: no success / internal error;

2: script notified bad parameters;

Output Formatted query answer to given FILE.

One single row (data set).

Values are separated by a colon (':').

Format: RES:GRP:CURR_NODE:PRIO_NODES

Examples

sap_suse_cluster_connector init

Do a minor check, if the cluster framework command line interface is available.

sap_suse_cluster_connector lsr –out /tmp/myfile00.txt –sid C11 –ino 02

Look-up for the SAP instance number 02 of the SAP system C11 and return the cluster resource name.

C11:02:rsc_sap_C11_D02:grp_sap_C11_Dialog2:ls3198,ls3199

sap_suse_cluster_connector fra –res rsc_sap_C11_D02 –act start

Start the cluster resource rsc_sap_C11_D02. While the lsr command returned the resource namersc_sap_C11_D02 the matching SAP instance is C11, instance number 02 (see example before).

sap_suse_cluster_connector cpa –res rsc_sap_C11_D02 –act start

Check, if the cluster action to start the SAP instance for system C11 and instance number 02 is already inprogress.

sap_suse_cluster_connector lsn –out /tmp/myfile01.txt –res rsc_sap_C11_D02

Look-up for the current cluster node and all possible cluster nodes to run the cluster resource namedrsc_sap_C11_D02.

rsc_sap_C11_D02:grp_sap_C11_Dialog2:ls3198:ls3198,ls3199

Exit Status

See detailed description of the command. In general:

0 - successful command termination or "yes" to a yes-no-query

1 - unsuccessful command termination or "no" to a yes-no-query

2 - error occurred during command termination - mostly bad parameters





© 2012 SAP AG 10

Usage and configuration of sapstartrsv with saphascriptco

Prerequisites

Status 2012-02-23 – Thanks to Holger Hopp for providing this information.

To make full use of the SAP HA Skript Connector Library, a minimum patchlevel of sapstartsrv is required.This will be SAP HOST AGENT 7.20 patchlevel 96. Until this is released, the required sapstartsrv is onlyavailable in the CGK/CGC and 720_COR branches (with access to SAP builds). Without this sapstartsrv, it ispossible to use the SAP HA Skript Connector Library with limited functionality mentioned in the next section.

Usage

Set following parameters in the SAP instance profile which is read by the sapstartrsv.

service/halib = /my/sappath/to/saphascriptco.so

service/halib_cluster_connector = /my/path/to/sap_<vendor>_cluster_connector

The first parameter is already available with sapstartsrv distributed on SAP marketplace, the secondparameter is currently only available with the development sapstartsrv mentioned in section “Prerequisites”.If an old sapstartsrv is used, passing profile parameters to the SAP HA Skript Connector Library is not

available, thus the script must available as /usr/local/bin/sap_cluster_connector .

Logging/Debugging:

All Logging and Debugging information of sapstartsrv and also of the saphascriptco library could be found at

the standard place – the work directory of the SAP instance: .../work/sapstartsrv.log.

Additional profile parameters:

There are two more profile parameters available with new sapstartsrv, that may be useful:

The parameter

service/halib_debug_level = <value> (value range 0..3)

enables more or less debug info in the sapstartsrv.log. Default is 1.

With the parameter

service/halib_tmp_prefix = /some_location/some_prefix

you may set another location for temporary files (e.g. used for script command 'lsr').

Default is '/tmp/sapha-'.





© 2012 SAP AG 11

Related Content

For more information, visit the Application Management homepage.









Disclaimer and Liability Notice

This document may discuss sample coding or other information that does not include SAP official interfaces and therefore is notsupported by SAP. Changes made based on this information are not supported and can be overwritten during an upgrade.

SAP will not be held liable for any damages caused by using or misusing the information, code or methods suggested in this document,and anyone using these methods does so at his/her own risk.

SAP offers no guarantees and assumes no responsibility or liability of any type with respect to the content of this technical article or

code sample, including any liability resulting from incompatibility between the content within this document and the materials andservices offered by SAP. You agree that you will not hold, or seek to hold, SAP responsible or liable with respect to the content of thisdocument.

Documents

How to Connect SAPSTARSRV and Cluster Frameworks Using the Components Saphascriptco.so and SAP_Vendor_Cluster_Connector