SAPHanaSR-ScaleOut-XSA(7)

📦 version 1.3.4, in opensuse-leap 16.0

💅 NAME 💅

SAPHanaSR-ScaleOut-XSA — no cap, this is the page about automating SAP HANA system replication for standalone XSA setups. Like, the whole vibe. 🦋

✨ DESCRIPTION ✨

Okay bestie, gather round, because this manual page is your whole guide to setting up and managing the automation of SAP HANA system replication (SR) in scale-out setups that have a standalone eXtended application Services Advanced (XSA) server in the mix. 🎀

Heads up though: this page is specifically the standalone-XSA flavour. If you're running some other scale-out scenario, go read SAPHanaSR-ScaleOut(7) instead — that's your girl for the general case. 💖

So what even is SAP HANA XSA? It's a platform for developing and executing micro-service oriented applications. That's the whole thing. Iconic, honestly. ✨

🌸 the actual setup, iykyk 🌸

The scale-out standalone XSA scenario is two nodes per site. Two. Per site. Let that sink in. 🫶

  • One node runs the HANA master namesever and an indexserver.
  • The other node runs an HANA nameserver slave and the standalone XSA server — but no indexserver. Not a single one. 💀

HANA system replication is set up between the two sites, and on top of that, the XSA Filesystem Storage (fss) is shared across the sites. Yes, across. Both of them. 🔥

👑 and the cluster resource config? 👑

Here's the tea: the cluster resource configuration for HANA scale-out with standalone XSA is almost the same as the scale-out ERP scenario, progressive variant. Almost. The differences are, currently:

  • ➕ an additional IPaddr2 resource for the primary XSA worker
  • ➕ an additional SAPHanaFilesystem resource for the XSA fss directory (this one's optional)
  • ➖ no 3rd replication site connected. At all. Not invited. 🙈

🧚 where to get the real details 🧚

For the full picture, go read up on all of these — they're literally right there waiting for you:

…and also peep the IPaddr2 example further down this page. 👀

✨ EXAMPLES ✨

🎀 Example one: the whole setup, big picture

So like, this is the overview for setting up SAP HANA with standalone XSA and system replication. Read it like a vibe check before you commit, bestie.

On all cluster nodes the OS, filesystem, etc. is already installed and configured appropriately for an HANA scale-out scenario. Installation sources for SAP HANA and XSA are prepared. HANA at both sites will be installed using the same wildcard IP address for XSA, so they must not run as primary in parallel. site1 will become primary, site2 will become secondary — and that happens after the final test (step 5.9).

The installation procedure looks like this, and yes, I'm giving you the full list because you deserve the full list:

  • 1.1 collect information and prepare parameter sheet
  • 1.2 provide wildcard DNS entry for the XSA IP address
  • 1.3 export share with XSA fss directory on NFS server
  • 1.4 prepare /etc/fstab on node12 and node22
  • 2.1 set XSA IP address on node12
  • 2.2 install HANA with XSA on site1 with node11 (master/worker) and node12 (xs_worker)
  • 2.3 disable XSA and back-up XSA fss on node12
  • 2.4 change fss to NFS in xscontroller.ini on site1
  • 2.5 create mountpoint for fss share and mount fss from NFS on node12
  • 2.6 restore XSA fss and enable XSA on node12
  • 2.7 stop HANA on site1
  • 2.8 remove XSA IP address from node12
  • 3.1 set XSA IP address on node22
  • 3.2 install HANA with XSA on site2 with node21 (master/worker) and node22 (xs_worker)
  • 3.3 disable XSA and back-up XSA fss on node22
  • 3.4 change fss to NFS in xscontroller.ini on site2
  • 3.5 create mountpoint for fss share and mount fss from NFS on node22
  • 3.6 restore XSA fss and enable XSA on node22
  • 3.7 copy XSA ssfs keystore from site2 to site1
  • 3.8 copy HANA ssfs keystore from site2 to site1
  • 3.9 back-up HANA on node21
  • 3.10 enable HANA system replication on node21
  • 4.1 register HANA site1 as secondary to node21
  • 4.2 start HANA on site1
  • 5.1 check everything is fine at site1 and site2
  • 5.2 stop HANA at site2
  • 5.3 remove XSA IP address from node22
  • 5.4 do manual takeover at site1
  • 5.6 set XSA IP address on node12
  • 5.7 register HANA site2 as secondary to node11
  • 5.8 start HANA on site2
  • 5.9 check everything is fine at site1 and site2

Detailed examples for most of the steps are given below. 💅

🦋 XSA fss entry in /etc/fstab

Needs to be done before the NFS share with XSA fss is mounted locally. This filesystem is needed on both XSA standalone nodes — not on the HANA master nodes.

The correct mount options are depending on the NFS server. However, client-side write caching has to be disabled. The path has to match fss_storage_path in xscontroller.ini. Since the fss directory is mounted below /hana/shared, which also comes from outside, the fss entry should follow later.

nfs1:/s/ha1/xsfss /hana/shared/HA1/xs/controller_data/xsfss nfs4
rw,noac,sync,default 0 0
Note: The NFS share might be monitored, but not mounted/umounted by the HA cluster. See ocf_suse_SAPHanaFilesystem(7) for details.

🧚 Adapting the XSA fss entry in xscontroller.ini

Needs to be adapted after XSA fss has been backed-up and before fss will be restored. Example SID is HA1, directory is xsfss.

# cat /hana/shared/HA1/global/hdb/custom/config/xscontroller.ini
 ...
[fss]
fss_storage_path = /hana/shared/HA1/xs/controller_data/xsfss

🌸 Creating the local mountpoint for XSA fss and mounting it from remote NFS

Needs to be done at both sites before restoring the fss. As above, SID is HA1 and directory is xsfss.

# mkdir /hana/shared/HA1/xs/controller_data/xsfss
# mount /hana/shared/HA1/xs/controller_data/xsfss
# chown ha1adm:sapsys /hana/shared/HA1/xs/controller_data/xsfss

💖 Copying the XSA secure keystore from primary site to secondary

Needs to be done before registering the secondary site. Primary site is site2, secondary site is site1, SID is HA1.

# cd /hana/shared/HA1/global/xsa/security/
# md5sum ssfs/*/*
# rsync -va ssfs node11:$PWD/
# ssh node11 "md5sum $PWD/ssfs/*/*"

⭐ Copying the HANA secure keystore from primary site to secondary

Needs to be done before registering the secondary site. Secondary site node is node11, SID is HA1.

# cd /usr/sap/HA1/SYS/global/security/rsecssfs
# md5sum */*
# rsync -va * node11:$PWD/
# ssh node11 "md5sum $PWD/*/*"

💅 Disabling XSA and backing up the fss

Needs to be done at both sites before changing the fss from local to NFS. SID is HA1.

# su - ha1adm -c "XSA disable; XSA backup-fss"

🎀 Restoring the fss and enabling XSA

Needs to be done at both sites after the fss has been changed from local to NFS. SID is HA1.

Make sure not both active XSA sites will access the shared fss directory at the same time. 😭 Like, genuinely, do not do that.
# su - ha1adm -c "XSA restore-fss; XSA enable"

👑 Stopping HANA, including XSA

Needs to be done at the site that should become secondary, before the fss at the other site is changed from local to NFS. SID is HA1, instance number is 00.

# su - ha1adm
~> sapcontrol -nr 00 -function StopSystem
~> sapcontrol -nr 00 -function WaitforStopped 30 60
~> sapcontrol -nr 00 -function GetSystemInstanceList

🌈 Backing up HANA and enabling system replication as primary site

Needs to be done at the future primary site, before registering the other site as secondary. SID is HA1, primary site is site2, instance number is 00.

# su - ha1adm
~> hdbsql -i 00 -u SYSTEM -d SYSTEMDB \
 "BACKUP DATA FOR FULL SYSTEM USING FILE ('backup')"
~> hdbnsutil -sr_enable --name=site2

🔥 Registering and starting HANA as secondary site

SID is HA1, secondary site is site1, primary master is node21, instance number is 00. Needs primary site up and running — no shortcuts, bestie.

# su - ha1adm
~> hdbnsutil -sr_register --name=site1 \
 --remoteHost=node21 --remoteInstance=00 \
 --replicationMode=sync --operationMode=logreplay
~> sapcontrol -nr 00 -function StartSystem
~> sapcontrol -nr 00 -function WaitforStarted 30 60
~> sapcontrol -nr 00 -function GetSystemInstanceList

🍓 Checking that HANA database and XSA are fine

Should be done at both sites — before anything will be done, and after having done anything on HANA database and XSA. SID is HA1, instance number is 00.

# su - ha1adm
~> hdbnsutil -sr_state
~> sapcontrol -nr 00 -function GetSystemInstanceList
~> cdpy; python landscapeHostConfiguration.py
~> cdpy; python systemReplicationStatus.py
~> XSA info
Note: Older HANA versions do not support systemReplicationStatus.py at secondary site. 💀

🫶 Manual takeover for HANA database and XSA, without the Linux cluster

A manual takeover should be done for testing the HANA database and XSA setup, before integrating with the Linux cluster.

Once HANA database and XSA are controlled by the Linux cluster, the cluster resource has to be set into maintenance before doing a manual takeover. See SAPHanaSR_maintenance_examples(7).

If there is no Linux cluster, a manual takeover can be done by following this procedure:

  1. On both sites: Check everything is fine.
  2. On primary site: Stop HANA database and XSA (sapcontrol ... StopSystem).
  3. On primary site: Remove XSA IP address from XSA node and remove HANA IP address from HANA master node.
  4. On secondary site: Set XSA IP address on XSA node and set HANA IP address on HANA master node.
  5. On secondary site: Do takeover (hdbnsutil -sr_takeover).
  6. On new primary site: Check everything is fine.
  7. On former primary site: Register as new secondary and start (hdbnsutil -sr_register ... ; sapcontrol ... StartSystem).
  8. On both sites: Check everything is fine.

🦋 IPaddr2 resource for primary XSA

Needs to run together with the primary XSA services. Is used by xscontroller for connecting internally, and is used by external clients. Thus this IP address needs to be resolved as wildcard DNS entry.

The shown location constraint works for setups with two nodes per site. Example SID is HA1, instance number is 00, IP address is 192.168.178.188.

primitive rsc_ip_HA1_XSA00 IPaddr2 \
 op monitor interval=20s timeout=20s \
 params ip=192.168.178.188

location loc_ip_HA1_XSA00 \
 rsc_ip_HA1_XSA00 \
 rule 2000: master-rsc_SAPHanaCon_HA1_HDB00 eq 101

See also ocf_hearbeat_IPAddr(2) and SAPHanaSR-ScaleOut_basic_cluster(7).

💜 Alternative IPaddr2 resource for HANA primary master

Alternative resource configuration for the HANA primary master virtual IP address. Instead of following the SAPHanaController resource PROMOTED role by colocation rule, the IPaddr2 resource follows the node score by location rule directly. Example SID is HA1, instance number is 00, IP address is 192.168.178.1.

Note: Understand the impact before trying. For real, for real. 🙈
primitive rsc_ip_HA1_HDB00 IPaddr2 \
 op monitor interval=10s timeout=20s \
 params ip=192.168.178.1

location loc_ip_HA1_HDB00 \
 rsc_ip_HA1_HDB00 \
 rule 2000: master-rsc_SAPHanaCon_HA1_HDB00 eq 150

See also ocf_hearbeat_IPAddr(2) and SAPHanaSR-ScaleOut_basic_cluster(7).

🌟 SAPHanaFilesystem resource for the shared XSA fss

Optional resource to check the NFS sharing XSA fss across sites. The HANA consists of two sites with two nodes each. An additional cluster node is used as majority maker for split brain situations. One filesystem holds the XSA fss, provided by an NFS server and shared across sites. On both XSA worker nodes the NFS share is mounted statically. The SAPHanaFilesystem RA is used for monitoring that filesystem, but not for mounting/umounting. SID is HA1, instance number is 00, shared directory is /hana/shared/HA1/xs/controller_data/xsfss as defined in /etc/fstab, cluster nodes without fss are nodeMM, node11 and node21.

primitive rsc_SAPHanaFil_HA1_XSA00 ocf:suse:SAPHanaFilesystem \
  op start interval="0" timeout="10" \
  op stop interval="0" timeout="20" on-fail="fence" \
  op monitor interval="120" timeout="180" \
  params SID="HA1" InstanceNumber="00"\
  DIRECTORY="/hana/shared/HA1/xs/controller_data/xsfss"

clone cln_SAPHanaFil_HA1_XSA00 rsc_SAPHanaFil_HA1_XSA00 \
  meta clone-node-max="1" interleave="true"

location SAPHanaFil_XSA_not_nodeMM cln_SAPHanaFil_HA1_XSA00 -inf:
nodeMM
location SAPHanaFil_XSA_not_node11 cln_SAPHanaFil_HA1_XSA00 -inf:
node11
location SAPHanaFil_XSA_not_node21 cln_SAPHanaFil_HA1_XSA00 -inf:
node21

See also ocf_suse_SAPHanaFilesystem(7).

📁 FILES 💖

  • /hana/shared/$SID/global/hdb/custom/config/xscontroller.ini — the XSA controller config file. that's literally where the controller reads its settings from, bestie.
  • /hana/shared/$SID/xs/controller_data/fss/ — the default Filesystem Storage directory (yes, fss, we been knew 💅).
  • /hana/shared/$SID/global/xsa/security/ssfs/ — the XSA secure keystore directory. keep it safe, keep it secret 🫶
  • /usr/sap/$SID/SYS/global/security/rsecssfs/ — the HANA database secure keystore directory (different keystore, different directory, don't mix them up, i beg of you).
  • /etc/passwd , /etc/groups — the local users and groups definition files.
  • /etc/fstab — static information about the filesystems.

✨ REQUIREMENTS ✨ (read these, fr fr)

  • SAPHanaSR-angi version 1.3 or later 🎀
  • SAP HANA 2.0 SPS07 rev.79.
  • Currently two nodes per site are supported. One HANA master/worker and one standalone XSA worker. that's the whole squad, no plus-ones 😭
  • The SAP HANA XSA service is installed for hostname based routing. This needs DNS wildcard support at the DNS server side — so go make friends with your DNS admin 🦋
  • Both sites use the same XSA default domain and API URL.
  • The XSA service IP address is configured as a cluster resource and is moved together with the primary XSA. it travels with its girl, periodt.
  • A highly available NFS service provides the shared XSA Filesystem Storage (fss) directory across sites. The fss is configured identically on both sites — mirror, not matching-ish 🌸
  • Linux user <sid>adm has the same UID and GIDs on all cluster nodes. consistency is the vibe check 🔥
  • Linux user <sid>adm has sudo permission ALL for Linux users <sid>xsa and sap<sid>xsa.
  • The XSA secure keystore (ssfs) is copied from primary to secondary site.
  • SAP HANA host auto-failover is not supported. nope. not a thing here. 🚫
  • Multi-target or multi-tier system replication is not supported for continous operation. However, it might be enabled temporarily for a specific purpose — in that case, the XSA Filesystem Storage has to be transfered as well. don't forget the fss, please, i'm begging 🙈
  • SAPHanaController relies on HANA landscape status. Takeover will not be initiated for landscape status 2, 3 and 4. See SAPHanaController-scale-out(7).
  • When recovering the srHook attribute from the cache file at cluster start, SAPHanaController relies on HANA landscape status at both sites going to okay before system replication status. This is not guaranteed for the standalone XSA. So, any maintrenance procedure needs to take care for that. lowkey a trap, so read it twice 💀
  • The sapcontrol function WaitforStopped might return befor the XSA is stopped completely. Thus the landscape status needs to be checked explicitely. like, actually check it. don't trust the return.
  • The XSA scenario should be configured as progressive variant. See SAPHanaSR-angi-scenarios(7).
  • For requirements of the overall scale-out setup, see also the REQUIREMENTS section in SAPHanaSR-ScaleOut(7).
  • For requirements of SAP HANA XSA, please refer to the SAP product documentation. go straight to the source, bestie 📚

💀 BUGS 💀

In case of any problem, please use your favourite SAP support process to open a request for the component BC-OP-LNX-SUSE. that's the magic component name — screenshot it, tattoo it, whatever works 🫶

👀 SEE ALSO 👀

the whole friend group:

SAPHanaSR-angi(7) , SAPHanaSR-ScaleOut(7) , SAPHanaSR-angi-scenarios(7) , SAPHanaController-scale-out(7) , ocf_suse_SAPHanaFilesystem(7) , susChkSrv.py(7) , SAPHanaSR-alert-fencing(7) , SAPHanaSR_maintenance_examples(7) , fstab(5) , nfs(5) ,

https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/5bc11f2ca7744bfd9d23d09e5b616433.html?version=2.0.07 ,

https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/99306be18a1f493b990cf9d8d90cd922.html?version=2.0.07 ,

and the SAP Notes hall of fame 🏆:

  • 1999880 - FAQ: SAP HANA System Replication
  • 1999997 - FAQ: SAP HANA Memory
  • 2183363 - Configuration of SAP HANA internal network
  • 2243019 - Providing SSL certificates for domains defined in SAP HANA extended application services, advanced model
  • 2243156 - Secure user setup for SAP HANA extended application services, advanced model
  • 2245631 - Domains and routing configuration for SAP HANA extended application services, advanced model
  • 2303772 - SAP HANA XS Advanced Model SPS12 Release Note
  • 2300936 - Failover & High Availability with SAP HANA extended application services, advanced model
  • 2300937 - Backup and restore for SAP HANA extended application services, advanced model then notice XSA can't start up with error:
  • 2300943 - Enabling JDBC SSL encryption for SAP HANA extended application services, advanced model
  • 2507070 - Multiple XSA Systems on the same host
  • 2509043 - Standard Sizing Profiles for SAP HANA extended application services, advanced model
  • 2511224 - How to activate a XSA technical user
  • 2564474 - Installation of SAP HANA XS Advanced Runtime fails with error "Assigning Additional Roles to the Local Host failed".
  • 2596466 - FAQ: SAP HANA XS Advanced Information published on SAP
  • 2741459 - VA32 dump: DBSQL_DUPLICATE_KEY_ERROR
  • 2749450 - XSA technical user is frequently locked - authentication failed
  • 2752384 - HANA XS Advanced does not start - Unable to read the SID from the SL config store - authentication failed
  • 2866031 - Web IDE fails to start with "Request to UAA failed: certificate has expired"
  • 2949526 - XS controller is crashing with OutOfMemory Error
  • 3014176 - Applying System Size Dependent Resource Limits During Installation or Upgrade
  • 3083089 - Java heap space: failed to allocate. XSA execution agent error
  • 3110553 - XSA Installation failed due to diserver can't start up
  • 3114270 - How to change the port used by existing application on XSA(XS advanced)
  • 3224631 - Hana is unavailable with message: "process is terminating, because lockfile '/usr/sap/.../../../lock/hdbindexserver@....pid' is missing/wrong."
  • 3234663 - XSA can't start up after system refresh due to error "Unable to locate XSA persistence within tenant db '<DB name>'"
  • 3335637 - Installation of SAP HANA XS Advanced Runtime stucks in adding the role xs_worker
  • 3380973 - Resolving Port Conflicts with SAP HANA XS Advanced
  • 3433435 - How to check XSA memory settings
  • 3449644 - Not able to change the XSA default_domain with xscontroller.ini
  • 3601962 - xscontroller crashes with an out-of-memory error when restaging many applications in parallel

🌈 AUTHORS 🌈

A.Briel, F.Herschel, L.Pinne. legends, honestly 👑

(c) 2025-2026 SUSE LLC

The package SAPHanaSR-angi comes with ABSOLUTELY NO WARRANTY. For details see the GNU General Public License at http://www.gnu.org/licenses/gpl.html

okay so that "ABSOLUTELY NO WARRANTY" is in all caps for a reason — it means what it says, no cap 💅

and that's the whole page, bestie, you made it to the end 🦋✨ this was the SAPHanaSR-ScaleOut-XSA(7) manual, dated 10 Jun 2026 — go forth and keep those XSA keystores copied 💖🌸🫶 👑

📦 where this page comes from