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

How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco.so and SAP_Vendor_Cluster_Connector Applies to: All SAP products controlled by sapstartsrv. For more information, visit the Application Management homepage. Summary Running SAP in a high availability cluster environment needs additional interfaces to communicate between the SAP program SAPSTARTSRV and the high availability cluster. At least it is essential to inform the cluster, if a SAP instance is started or shutdown. This article describes the reference interface implementation 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 products running on SUSE Linux Enterprise Server and the SUSE Linux Enterprise High Availability Extention. SAP COMMUNITY NETWORK © 2012 SAP AG SDN - sdn.sap.com | BPX - bpx.sap.com | BA - boc.sap.com | UAC - uac.sap.com 1 .......................................................................................... 7 Output Fields .............. 6 Params ................................................................com | BPX ...........................................................sap....................................................................................................................sdn.................................................................................................................................................................................................................................................................................................................................................................................... 10 Usage ............................... 12 SAP COMMUNITY NETWORK © 2012 SAP AG SDN ....................................................................................................................bpx............................................................................................................................................................. 6 Description ................................................................ 10 Prerequisites ................................................................................................................................................................................................ 7 Examples .................................. 10 Related Content .................................................................................................................... 7 Commands in Detail ................................................................... 10 Additional profile parameters: ..................................................................................................... 9 Usage and configuration of sapstartrsv with saphascriptco ...................................................... 3 The involved components ......................................so and SAP_Vendor_Cluster_Connector Table of Contents A Problem and its Solution ................ 9 Exit Status ................................................................................................................................com | UAC ......................................................................................................................................uac..... 5 Mapping sapstartsrv-Calls to Library functions and cluster connector commands .........................boc........................................................................ 6 Manual Page of the sap_suse_cluster_connector ..............................................com 2 .................... 11 Disclaimer and Liability Notice ................................................... 6 Commands ..................................................................................................................................................... 3 A typical call flow for SAP instance start ..................... 3 The Components of the Solution ............................................................................................................................................................................................................................ 6 Synopsis ..............................................................sap....sap..........................................com | BA ....... 4 A typical call flow for SAP instance stop ................How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco................................................................................................................... 10 Logging/Debugging: ............................................................................................................ 6 Name ....................sap........................................... uac.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.sap. In the cluster integrated scenario there are now five components working together:  Client (responsible: SAP) The client like sapcontrol.com | UAC .How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. architectures and responsibilities of the several cluster products is not in the scope of this document. This can result into very dangerous situations. There are a lot of detailed functions which can be called. The Components of the Solution To enable sapstartsrv to communicate with the cluster product the process needs an additional interface to ensure proper functionality.sap.sdn.com 3 .4. While sapstartsrv and sapscriptco.  Library (responsible: SAP) The new library saphascriptco.  Cluster connector (responsible: Cluster Vendor) The cluster connector like sap_suse_cluster_connector is called by the library saphascriptco. Discussing feature sets. will be enabled to communicate the state change (start/stop) to the cluster software. The cluster connector is responsible to answer questions like “is a SAP instance controlled by the cluster?” or “please stop cluster resource rsc_mySAP”. startsap. Sapstartsrv uses the library as a generic interface to a set of cluster products. All the clients must use the web-service interface of sapstartsrv. stopping SAP instances and also for getting information about the status of a SAP instance.sap. In other case the complete solution wold be broken. This program is also delivered by SAP. if the parameter service/sapha is used in the SAP instance profile.so takes the calls by sapstartsrv and matches them to calls to an external helper program the cluster connector.  Server (responsible: SAP) The server process sapstartsrv is providing web-service interfaces for starting.dll for Windows) is loaded by sapstartsrv. All those clients are typically part of the SAP delivery.so and SAP_Vendor_Cluster_Connector A Problem and its Solution One of the classical problems running SAP instances in a high available environment is that if a SAP administrator changes the status (start/stop) of a SAP instance without using the interfaces provided by the cluster software than the cluster framework will detect that as an error status and will bring the SAP instance into the old status by either starting or stopping the SAP instance. which controls SAP instances since SAP Kernel versions 6. SAP Management Console and others are the same as in the standard scenario.com | BA . The solution is that the central component SAPSTARTSRV.so for Unix (saphascriptco. 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.com | BPX . More details about the needed SAP parameters will follow in this article.sap. ACC. SAP COMMUNITY NETWORK © 2012 SAP AG SDN . For all mentioned client programs SAP is responsible. if the cluster changes the status of a SAP instance during some SAP maintenance tasks.so and is an abstraction layer between the SAP sapstartrv and the cluster product. The library saphascriptco.  Cluster product (responsible: Cluster Vendor) The last piece of the solution is the cluster product of course.bpx. No client is allowed to work around of this server process.boc. 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. You can use sapcontrol to get a list of available functions. so itself uses the cluster connector function lsr (details for lsr see call below) to answer that query.sap.sap.so.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco.  Now SAPSTARTSRV calls function SAP_HA_FindInstance in library saphascriptco. SAP COMMUNITY NETWORK © 2012 SAP AG SDN .sap. 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.com 4 .sap.so and SAP_Vendor_Cluster_Connector 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 first overview. SAP kindly provided this flow diagrams.sdn.bpx.com | BA .boc. if the cluster is responsible for this SAP instance.com | BPX . The library saphascriptco.com | UAC . The cluster connector is the external system command like sap_vendor_cluster_connector provided by the cluster vendor.uac. This request is sent via the SOAP based Start-WebService to SAPSTARTSRV. The library return will SAP_HA_OK.sap.  If the cluster is responsible for that SAP instance SAPSTARTSRV uses the library saphascriptco.boc. This means that SAP_HA_START_IN_PROGRESS is the return code to tell SAPSTARTRSV that its now ok to start the SAP instance.  If the cluster is responsible for that SAP instance SAPSTARTSRV uses the library saphascriptco. 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”.so to ask the cluster.com | BA .bpx. This query has to be answered by the external cluster connector using the function cpa. This query has to be answered by the external cluster connector using the function cpa.com | BPX . SAP COMMUNITY NETWORK © 2012 SAP AG SDN .com | UAC . if the requested cluster action (here start) is already in progress. This request is sent via the SOAP based Stop-WebService to SAPSTARTSRV. The library saphascriptco.  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. if the cluster connector has found the SAP instance.sap. The library saphascriptco.so takes the answer and returns SAP_HA_OK or SAP_HA_START_IN_PROGRESS back to SAPSTARTRV.uac.  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.so takes the answer and returns SAP_HA_OK or SAP_HA_START_IN_PROGRESS back to SAPSTARTRV.  Now SAPSTARTSRV calls function SAP_HA_FindInstance in library saphascriptco.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. The library will call the function fra (action stop) of the cluster connector. The library will call the function fra (action start) of the cluster connector.sdn.com 5 . if the cluster connector has found the SAP instance.  The administrator uses a client like SAP Management Console or sapcontrol to stop a SAP instance.sap.so and SAP_Vendor_Cluster_Connector The library return with SAP_HA_OK. If the cluster is not responsible SAPSTARTRV starts the SAPinstance using its own functionality.so itself uses the cluster connector function lsr (details for lsr see call below) to answer that query.so.sap. If the cluster is not responsible SAPSTARTRV stops the SAPinstance using its own functionality. if the cluster is responsible for this SAP instance.so to ask the cluster. This means that SAP_HA_START_IN_PROGRESS is the return code to tell SAPSTARTRSV that its now ok to stop the SAP instance. if the requested cluster action (here stop) is already in progress.  If SAPSTARTRV got the return code SAP_HA_START_IN_PROGRESS it will continue to stop the SAP instance by its own. The library saphascriptco.  If SAPSTARTRV got the return code SAP_HA_START_IN_PROGRESS it will continue to start the SAP instance by its own. com | UAC . Name sap_suse_cluster_connector.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. if a cluster actions is already in progress.uac. If not it sends a cluster command to stop the resource.sap.0 cpa resource stop fra resource stop Remark FindSAPInstance FindDB StopCluster Is used to find the cluster resource name for a specific SAP instance. SAP COMMUNITY NETWORK © 2012 SAP AG SDN .boc.com | BA . Fail Cluster is currently not called in sapstartsrv. Commands help or --help print help text and usage.0 of the sap_suse_cluster_connector and the mapping between the different layers is show in the following table: SAPSTARTSRV-Call Library function in saphascript. init check cluster installation and do some optional initialization. First the library checks. If not it sends a cluster command to start the resource.com | BPX .sdn.sap. 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. GetClusterNodes is currently not called in sapstartsrv.so SAP_HA_FindSAPInstance SAP_HA_FindDB SAP_HA_StopCluster sap_suse_cluster_connector command lsr SID NR Not implemented in version 1. Currently it needs to serve calls like queries about cluster status or to cluster resource actions.0 GetClusterNodes SAP_HA_GetClusterNodes lsn SID NR Manual Page of the sap_suse_cluster_connector This section includes the original manual page of the sap_suse_cluster_connector. StartCluster SAP_HA_StartCluster cpa resource start fra resource start MoveCluster FailCluster SAP_HA_MoveCluster SAP_HA_FailCluster not implemented fra resource move Not implemented in version 1. MoveCluster is currently not called in sapstartsrv.com 6 . First the library checks.bpx.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 SAP HA cluster library and the cluster software.sap.sap. if a cluster actions is already in progress.so and SAP_Vendor_Cluster_Connector Mapping sapstartsrv-Calls to Library functions and cluster connector commands The status of the implementation for version 1. Parameters: None.) 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 (initialization) Perform some basic tests.so and SAP_Vendor_Cluster_Connector cpa –res RES --act ACT check for specified pending/active actions in the cluster.maybe it does not fit for some cluster architectures.Cluster Resource Identifier NODE . if needed.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. lsr --out FILE --sid SID --ino INO list sap resources matching the search criteria.Cluster Node Name Output Fields All parameters identifiers like SID might also be referenced in output formats (see detailed command description). The command should only check. whether the cluster commands used are available.com 7 .Cluster action "start" or "stop" FILE .com | BPX . if the cluster software is installed and the cluster framework is stated. lsn --out FILE --res RES list sap nodes for specified resource. which are not used as parameters: GRP Cluster Group Identifier CLUSTER_NODES List of type NODE separated with comma (.sap.sap.com | BA .uac. Additionally there are some referenced output fields. Params SID .boc.SAP Instance Number (2 digits) ACT .Outputfile for result parsing RES . 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) SAP COMMUNITY NETWORK © 2012 SAP AG SDN .sap.bpx. fra --res RES --act ACT [ --nod NODE ] fire/start a cluster action like start/stop/migrate a resource. Optionally: This command could also implement some initializations. Return Codes 0: cluster software seams to be installed proper and cluster framework is stated on local node. The check “cluster framework started?” might be ignored .sap.sdn. This is not intended to do a cluster validation.SAP System Identifier (3 alphanum) INO .com | UAC . In that case the check only needs to test the availability of the external and needed cluster commands. [ --nod NODE ] For migrations this defines the destination node.com | BPX .com | UAC . Parameters . --ino INO SAP instance number to be queried.bpx. --res RES Cluster resource to be controlled.sap.uac. cpa (check for pending cluster actions) This cmd should check properly against the running cluster. It is not intended to wait till the cluster has processed the resource change. Parameters .only NODE is optional. --act ACT Action type (start/stop) to be queried.  Format: SID:INO:RES:GRP:CLUSTER_NODES fra (fire a resource action) This command fires a cluster change like “stop resource XX” or “start resource XX”. --sid SID SAP system identifier to be queried.  Each row / data set covers its values in a colon-separated (':') list.sap. lsr (list sap resources) This command is used to figure out the cluster resource and optionally resource group name for a specific SAP system and instance. 1: no success / internal error. Return Codes 0: success 1: no success / internal error 2: script notified bad parameters Output Formatted query answer to given FILE.com | BA .  Multiple rows (data sets) allowed even if typically there should only be one resource matching the query. if a given action on a SAP Instance is already running Parameters: All parameters are mandatory. --act ACT Cluster action (start/stop/migrate) to be "fired". --res RES Cluster resource to be queried. Return Codes 0: found pending action of queried type 1: did not found pending action of queried type 2: script notified bad parameters Output None.sdn.all parameters are mandatory --out FILE Output file to be used.com 8 . Return Codes 0: success.so and SAP_Vendor_Cluster_Connector Output None.sap. lsn (list sap nodes) SAP COMMUNITY NETWORK © 2012 SAP AG SDN . 2: script notified bad parameters Output None.sap. The SAP instance is specified by the cluster resource name.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco.boc. if the cluster action to start the SAP instance for system C11 and instance number 02 is already in progress.txt –sid C11 –ino 02 Look-up for the SAP instance number 02 of the SAP system C11 and return the cluster resource name.ls3199 sap_suse_cluster_connector fra –res rsc_sap_C11_D02 –act start Start the cluster resource rsc_sap_C11_D02. In this case the SAP instance is queried by the cluster resource name.sap.com | UAC .successful command termination or "yes" to a yes-no-query 1 . Parameters --out FILE Output file for results. sap_suse_cluster_connector lsn –out /tmp/myfile01.sdn.sap. 2: script notified bad parameters.com 9 .unsuccessful command termination or "no" to a yes-no-query 2 . 1: no success / internal error. C11:02:rsc_sap_C11_D02:grp_sap_C11_Dialog2:ls3198.txt –res rsc_sap_C11_D02 Look-up for the current cluster node and all possible cluster nodes to run the cluster resource named rsc_sap_C11_D02. In general: 0 . sap_suse_cluster_connector cpa –res rsc_sap_C11_D02 –act start Check.bpx.mostly bad parameters SAP COMMUNITY NETWORK © 2012 SAP AG SDN .sap.error occurred during command termination .com | BPX .  One single row (data set).so and SAP_Vendor_Cluster_Connector 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. --res RES Cluster resource to be queried.com | BA .  Format: RES:GRP:CURR_NODE:PRIO_NODES Examples sap_suse_cluster_connector init Do a minor check.uac. rsc_sap_C11_D02:grp_sap_C11_Dialog2:ls3198:ls3198. sap_suse_cluster_connector lsr –out /tmp/myfile00.boc. Return Codes 0: success.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. Output Formatted query answer to given FILE.sap.ls3199 Exit Status See detailed description of the command.  Values are separated by a colon (':'). While the lsr command returned the resource name rsc_sap_C11_D02 the matching SAP instance is C11. if the cluster framework command line interface is available. instance number 02 (see example before). /work/sapstartsrv.so service/halib_cluster_connector = /my/path/to/sap_<vendor>_cluster_connector The first parameter is already available with sapstartsrv distributed on SAP marketplace. If an old sapstartsrv is used.bpx. SAP COMMUNITY NETWORK © 2012 SAP AG SDN . it is possible to use the SAP HA Skript Connector Library with limited functionality mentioned in the next section. the required sapstartsrv is only available in the CGK/CGC and 720_COR branches (with access to SAP builds).boc. Usage Set following parameters in the SAP instance profile which is read by the sapstartrsv.3) enables more or less debug info in the sapstartsrv.sdn.sap.com | UAC .sap. used for script command 'lsr'). Default is 1.uac. 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: . With the parameter service/halib_tmp_prefix = /some_location/some_prefix you may set another location for temporary files (e. thus the script must available as /usr/local/bin/sap_cluster_connector.. This will be SAP HOST AGENT 7.20 patchlevel 96. service/halib = /my/sappath/to/saphascriptco.sap.com 10 . Until this is released. Additional profile parameters: There are two more profile parameters available with new sapstartsrv. To make full use of the SAP HA Skript Connector Library.so and SAP_Vendor_Cluster_Connector Usage and configuration of sapstartrsv with saphascriptco Prerequisites Status 2012-02-23 – Thanks to Holger Hopp for providing this information.com | BA . the second parameter is currently only available with the development sapstartsrv mentioned in section “Prerequisites”. Default is '/tmp/sapha-'.g.. Without this sapstartsrv..How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. passing profile parameters to the SAP HA Skript Connector Library is not available.com | BPX . a minimum patchlevel of sapstartsrv is required.log.log. that may be useful: The parameter service/halib_debug_level = <value> (value range 0.sap. sdn.com | BPX .sap.com 11 .uac.sap.boc.sap.com | UAC . visit the Application Management homepage.sap.bpx.so and SAP_Vendor_Cluster_Connector Related Content For more information.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. SAP COMMUNITY NETWORK © 2012 SAP AG SDN .com | BA . sap.boc.sdn. Changes made based on this information are not supported and can be overwritten during an upgrade. SAP COMMUNITY NETWORK © 2012 SAP AG SDN . SAP responsible or liable with respect to the content of this document.sap.sap. and anyone using these methods does so at his/her own risk. or seek to hold.sap.com | BPX . code or methods suggested in this document.so and SAP_Vendor_Cluster_Connector Disclaimer and Liability Notice This document may discuss sample coding or other information that does not include SAP official interfaces and therefore is not supported by SAP.com | BA .com | UAC .com 12 .uac.How to Connect SAPSTARSRV and Cluster Frameworks using the Components saphascriptco. You agree that you will not hold. SAP will not be held liable for any damages caused by using or misusing the information.bpx. 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 and services offered by SAP.