SAPHanaSrMultiTarget.py(7)

NAME
SAPHanaSrMultiTarget.py - Provider for multi-target aware SAP HANA srHook method srConnectionChanged().

DESCRIPTION
SAPHanaSrMultitarget.py can be used to provide a script for the SAP HANA srHook method srConnectionChanged(). The SAP HANA nameserver provides a Python-based API ("HA/DR providers"), which is called at important points of the host auto-failover and system replication takeover process. These so called hooks can be used for arbitrary operations that need to be executed. The method srConnectionChanged() is called on the master nameserver as soon as one of the replicating services loses or establishes the system replication connection. This method is called only once. SAPHanaSR srHook script and resource agent need to use same cluster attributes. Therefor beginning with package SAPHanaSR-ScaleOut version 0.180 a generation attribute is used.

SUPPORTED PARAMETERS
* The "HA/DR providers" API accepts the following parameters for the ha_dr_provider_saphanasrmultitarget section:

[ha_dr_provider_saphanasrmultitarget]

provider = SAPHanaSrMultiTarget

path = /usr/share/SAPHanaSR-ScaleOut/

execution_order = 1

The "HA/DR providers" API accepts the following parameter for the system_replication section:

[system_replication]

register_secondaries_on_takeover = [ true | false ]

The "HA/DR providers" API accepts the following parameter for the trace section:

[trace]

ha_dr_saphanasrmultitarget = [ info | debug ]

* The SAPHanaController and SAPHana RA recognize the effecting system replication status via attributes in the CIB properties section. The SAP System Indentifier (sid) is given in lower case. See REQUIREMENTS section below for supported API versions and scenarios. For new SAPHanaSR-ScaleOut the SAPHanaSrMultiTarget.py provides site-specific attributes among the SAPHanaSR properties:

hana_<sid>_site_srHook_<site> = [ SOK | SFAIL | SWAIT | SREG | SCOPY | PRIM ]

Note: See SAPHanaSR.py(7) for old-style SAPHanaSR-ScaleOut with one global attribute instead of site-specific attributes.

* The SAPHanaSR-manageAttr tool recognizes the scale-out multi-target capability via host attribute. The SAP System Indentifier (sid) is given in lower case. See REQUIREMENTS section below for supported API versions and scenarios. For new SAPHanaSR-ScaleOut the SAPHanaSrMultiTarget.py reports its generation:

hana_<sid>_gsh = [ generation ]

RETURN CODES
0 Successful program execution.
>0 Usage, syntax or execution errors.

EXAMPLES

* Simple example for permission in /etc/sudoers, SID is SLE.
All needed attributes (..._srHook, ..._gsh, ..._mts) are covered.

    # SAPHanaSR needs for srHook
    sleadm ALL=(ALL) NOPASSWD: /usr/sbin/crm_attribute -n hana_sle_site_*

* Example for looking up the sudo permission for the srHook script.
All related files (/etc/sudoers and /etc/sudoers.d/*) are scanned. Example SID is HA1.

    # sudo -U ha1adm -l | grep "NOPASSWD.*crm_attribute.*hana_"

* Example for entry in SAP HANA 2.0 global configuration /hana/shared/$SID/global/hdb/custom/config/global.ini with multi-target aware, site-specific attributes.
This entry is needed at both sites that are managed by the Linux cluster. The HANA has to be stopped before the files can be edited. Do not copy the file between nodes. Please check SAP HANA documentation for details. Do not forget to adapt the sudoers permission, see examples above.

    [ha_dr_provider_saphanasrmultitarget]
    provider = SAPHanaSrMultiTarget
    path = /usr/share/SAPHanaSR-ScaleOut/
    execution_order = 1
    [trace]
    ha_dr_saphanasrmultitarget = info

* Example for entry in SAP HANA 2.0 global configuration /hana/shared/$SID/global/hdb/custom/config/global.ini to enable multi-target aware third site.
This entry is needed to allow ocf_suse_SAPHanaController(7) parameter AUTOMATED_REGISTER=true in multi-target environments. The HANA has to be stopped before the files can be edited. Do not copy the file between nodes. Please check SAP HANA documentation for details.

    [system_replication]
     ...
    register_secondaries_on_takeover = true
     ...

* Example for entry in SAP HANA 2.0 nameserver configuration /hana/shared/$SID/global/hdb/custom/config/nameserver.ini for two-node scale-out HANA without standby nodes.
This entry is needed at both sites that are managed by the Linux cluster. The HANA has to be stopped before the files can be edited. Do not copy the file between nodes. Please check SAP HANA documentation for details. In this example the master node is suse11, the worker is suse12.

    [landscape]
     ...
    master = suse11:31001
    worker = suse11 suse12
    active_master = suse11:31001
    roles_suse11 = worker
    roles_suse12 = worker
     ...

* Example for creating the optional SAPHanaSrMultiTarget.pyc python object file manually. SID is SLE.

    # mkdir -p /hana/shared/srhook
    # chown sleadm.sapsys /hana/shared/srhook
    # su - sleadm
    # cd /hana/shared/srhook
    # python -m py_compile /usr/share/SAPHanaSR-ScaleOut/SAPHanaSrMultiTarget.py
    # chmod 755 SAPHanaSrMultiTarget.pyc
    # ls -l SAPHanaSrMultiTarget.pyc

* Example for checking the system log for srHook setting HANA system replication status in the CIB properties section. To be executed on respective HANA primary site's master nameserver.

    # grep "sudo.*crm_attribute.*srHook" /var/log/messages

* Example for checking the HANA tracefiles for srConnectionChanged() events. To be executed on respective HANA primary site's master nameserver.

    # su - sleadm
    ~> cdtrace
    ~> grep SAPHanaSR.srConnectionChanged.*called nameserver_*.trc
    ~> grep crm_attribute.*SAPHanaSR nameserver_*.trc
    # exit

* Example for checking the HANA tracefiles for when the hook script has been loaded. To be executed on both site's master nameservers.

    # su - sleadm
    ~> cdtrace
    ~> grep HADR.*load.*SAPHanaS nameserver_*.trc

* Example for comparing Linux cluster srHook attribute with current HANA SR state. SID is HA1. To be executed on current HANA primary site.

    # SAPHanaSR-showAttr | grep -A4 srHook
    # su - ha1adm -c "HDBSettings.sh systemReplicationStatus.py"

* Potentially dangerous example for manually changing Linux cluster srHook attribute according to current HANA SR state. This might be desired if the HANA SR state has changed while the Linux cluster was completely down. SID is ICE, site is BERG, current HANA SR state is SFAIL.
Note: Understand the impact before trying.

    # su - iceadm -c "HDBSettings.sh systemReplicationStatus.py"
    # cs_clusterstate -i
    # crm_attribute -n hana_ice_site_srHook_BERG -v SFAIL -t crm_config -s SAPHanaSR
    # SAPHanaSR-showAttr

* Example for removing orphaned global srHook attribute. This might be done after upgrading from old-style srHook, to avoid confusion caused by different HANA HADR provider API versions. See also SAPHanaSR.py(7) and SAPHanaSR-manageAttr(8) from SAPHanaSR-ScaleOut. SID is HA1.

    # SAPHanaSR-showAttr
    # cs_clusterstate -i
    # crm_attribute --delete -t crm_config --name hana_ha1_glob_srHook
    # SAPHanaSR-showAttr

FILES

/usr/share/SAPHanaSR-ScaleOut/SAPHanaSR.py
    the scale-out old-style hook provider, delivered with the RPM

/usr/share/SAPHanaSR-ScaleOut/SAPHanaSrMultiTarget.py
    the scale-out multi-target aware hook provider, delivered with the RPM

/hana/shared/srhook/SAPHanaSR.pyc
    the old-style hook provider, if pre-compiled for the particular HANA (optional)

/hana/shared/$SID/global/hdb/custom/config/global.ini
    the on-disk representation of HANA global system configuration

/hana/shared/$SID/global/hdb/custom/config/nameserver.ini
    the on-disk representation of HANA nameserver configuration

/etc/sudoers , /etc/sudoers.d/
    the sudo permissions configuration

/usr/sap/$SID/HDB$nr/$host/trace/
    the directory with HANA trace files

/usr/sap/$SID/HDB$nr/.crm_attribute.$SITE
    the internal cache for srHook status changes while Linux cluster is down, file is owned by ${SID}adm and must never be touched

REQUIREMENTS
1. SAP HANA starting with version 1.0 SPS11 patch level 112.02. Older versions do not provide the srHook method srConnectionChanged(). With the mentioned HANA versions uni-directional chained system replication is possible. With HANA 2.0 SPS04 and later multi-target system replication is possible as well. See also SAPHanaSR-ScaleOut(7) for supported API versions and scenarios.

2. The user ${sid}adm needs execution permission as user root for the command crm_attribute.

3. The hook provider needs to be added to the HANA global configuration, in memory and on disk (in persistence).

4. If the hook provider should be pre-compiled, the particular Python version that comes with SAP HANA has to be used.

5. The Linux cluster needs to be up and running to allow HA/DR provider events being written into CIB attributes. The current HANA SR status might differ from CIB srHook attribute after Linux cluster maintenance.

6. Running srHook script and RA need to be of same or compatible generation. This is indicated by node attributes.

BUGS
Global and site-specific properties for HANA SR status can not be used at same time.
In case of any problem, please use your favourite SAP support process to open a request for the component BC-OP-LNX-SUSE. Please report any other feedback and suggestions to feedback@suse.com.

SEE ALSO
SAPHanaSR-ScaleOut(7) , SAPHanaSR.py(7) , ocf_suse_SAPHanaTopology(7) , ocf_suse_SAPHanaController(7) , SAPHanaSR-monitor(8) , SAPHanaSR-showAttr(8) , SAPHanaSR-manageAttr(8) , crm_attribute(8) , sudo(8) , sudoers(5) , python(8) ,
https://documentation.suse.com/sbp/all/?context=sles-sap ,
https://documentation.suse.com/sles-sap/ ,
https://www.susecon.com/doc/2015/sessions/TUT19921.pdf ,
https://www.susecon.com/doc/2016/sessions/TUT90846.pdf ,
https://www.susecon.com/archive-2019.html ,
https://www.susecon.com/archive-2020.html ,
http://help.sap.com/saphelp_hanaplatform/helpdata/en/13/67c8fdefaa4808a7485b09815ae0f3/content.htm ,
http://help.sap.com/saphelp_hanaplatform/helpdata/en/5d/f2e766549a405e95de4c5d7f2efc2d/content.htm ,
http://help.sap.com/saphelp_hanaplatform/helpdata/en/12/00ab8ef0c54c54be2d0e7f5327f7ed/content.htm?frameset=/en/13/67c8fdefaa4808a7485b09815ae0f3/frameset.htm&current_toc=/en/00/0ca1e3486640ef8b884cdf1a050fbb/plain.htm&node_id=413 ,
https://help.sap.com/saphelp_hanaplatform/helpdata/en/3f/1a6a7dc31049409e1a9f9108d73d51/content.htm

AUTHORS
A.Briel, F.Herschel, L.Pinne.

COPYRIGHT
(c) 2015-2016 SUSE Linux GmbH, Germany.
(c) 2017-2021 SUSE LLC
SAPHanaSR.py comes with ABSOLUTELY NO WARRANTY.
For details see the GNU General Public License at http://www.gnu.org/licenses/gpl.html