Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
Showing results for 
Search instead for 
Did you mean: 
In a previous blog I explained an example setup of SAP HANA2 XS Advanced (XSA) with host auto-failover: SAP HANA 2.0 XS Advanced: a host auto-failover installation/configuration example. Based on some requests I received recently this blog will discuss a different variant, an example how you can establish SAP HANA2 XSA failover with HANA System Replication (HSR). But first, a special thanks to marcbecker for providing a ton of insights and making this blog possible!

While the HANA System Replication failover configuration with the core HANA Database is well known, the additional steps when XS Advanced (XSA) is installed are less well known. In below steps I give an example how it can be configured. When you read through the notes several decisions must be made for your own implementation, so your configuration may be different.

Pay special attention to the routing mode, the default in the hdblcm installer uses port based routing, but as documented in SAP Note 2245631, for a production system hostname routing is recommended.

For this example, the setup will include:

  • Two HANA instances installed as documented in the General Prerequisites for Configuring SAP HANA System Replication

  • Hostname based routing

  • Standalone SAP Web Dispatcher as the chosen failover router

  • No SSL termination at the failover router

  • XSA default domain is and configured in the DNS

  • To secure the traffic with TLS/SSL, obtain a wildcard certificate for the XSA default domain. Specific options can be found under section “Certificate Steps”

  • IP addresses:

    • Failover Web Dispatcher ends in .198

    • SAP HANA/XSA Primary ends in .199

    • SAP HANA/XSA Secondary ends in .232

Please make sure the above decisions and data points are completed before performing the configuration.

Let’s start with testing the DNS pre-requisite, both and *. must resolve to the failover web dispatcher:

Install the Failover SAP Web Dispatcher guided by SAP Note 908097, my example uses version 7.49 patch 214. Make sure you can login to the SAP Web Dispatcher Administration URL. Depending on your end-users the SAP Web Dispatcher may be located in a separate zone such as the DMZ.

After the installation, update the SAP Web Dispatcher profile to reflect your hostnames and ports, for HANA the XSA port will be 3##33, where ## represents the HANA instance number. In below example the HANA instance number is 19 and the SID is SR1, adjust this if your instance is different. Replace XSA Primary and XSA Secondary to reflect your hostnames (fqdn):

  • wdisp/system_0 = NAME=SR1, SID=SR1, SRCVHOST=*:31933, EXTSRV=https://<PRIMARY>:31933;https://<SECONDARY>:31933

  • icm/server_port_0=PROT=ROUTER, PORT=31933, TIMEOUT=60, PROCTIMEOUT=600

Other settings to consider:

Make sure that the SAP Web Dispatcher is running before installing XSA. In addition, the port (in my example 31933) has to be open between the Failover Web Dispatcher server and the HANA servers in both directions.

Next install HANA Primary and Secondary instances, or if HANA is already installed, ensure the HANA System Replication pre-requisites are met. Do not configure HANA System Replication at this point. Follow the official HANA installation guides on to install the Primary and Secondary. Make sure to adhere to the pre-requisites for HANA System Replication:

From SAP Note 2300936:

In a system replication setup, database content – including XS advanced system and application data – is replicated from a primary system to a secondary system. XS advanced services and applications will run on the currently active system, only. On the secondary system, XS advanced services will be in an idle state until the takeover takes place. Then, all XS advanced services are started which in turn brings up all XS advanced applications on the secondary system. In order to set up System Replication with XS advanced, the same version of XS advanced has to be installed on the primary and the secondary system.


On the Primary install XSA:

If you install from the HANA 2.0 SPS## media DVD (SPS03 used in this example), then all components are on the DVD. If you install from downloaded patch media (individual components), then check SAP notes:


In my example I execute hdblcm, select my instance SR1, and select ‘xs’ from the list of installable components:

during the XS Advanced installation hdblcm prompts for routing mode and XSA Domain Name:

After the installation, let’s perform a quick check. Make sure you are logged in as the <sid>adm user, issue command “xs-admin-login” (or “xs login”) and enter the XSA_ADMIN password:

Next check the URL’s with command “xs service-urls” (or “xs a” for the full list):

Verify that the URL’s work, a quick example is to test the XSA landing page at https://api.<domain>:<port>. In this example the URL is Since we have not configured the SSL certificates yet, you will get a security warning from the browser because a self-signed certificate is used. Depending on the browser you may be able to click through the warnings (twice) and get to the login page, but at this point it is not yet important to login. Just make sure the URL resolves and you see the landing page.

The links on the lower right require authentication. If you want to test the authentication, test xsa-cockpit and login as the XSA_ADMIN user. XSA_ADMIN already has the required authorizations for xsa-cockpit whereas it does not for the webide (see webide post-installation link for additional steps).

If you get an error response, such as 503, check the output of “xs a” and make sure xsa-cockpit is in a running state:

For example, if it shows 0/1 then check why the instance was not started (check xs logs command in the admin guide). Note that it is normal for the apps ending in -db to be stopped, these will be started when needed and no user intervention is required.


Certificate Steps

When you inspect the certificate path you will see the self-signed certificate:

To provide secure communication the next section will show the steps to install a signed certificate chain. There are multiple ways to do this, the steps below use the Common Name (CN) with a wildcard. For more information review the help documentation and SAP Note

Note: As of SAP HANA2 SPS03 the help documentation provides an alternate option, namely it suggests to use SubjectAltNames. An example to use SubjectAltNames and its benefits is explained in this blog. The steps from the blog using SubjectAltNames can be used to replace the certificate steps below.

High level steps in this example:

  1. in the SAP Web Dispatcher generate a wildcard certificate request, get it signed by your Certificate Authority of choice, import the certificate chain

  2. from the command line export the certificate in p12 format, convert it to pem format and prepare the certificate files for XSA import

  3. in the XSA environment, import the certificate files and restart XSA


  1. Login to the SAP Web Dispatcher Administration URL and go to PSE Management. Next select SAPSSLS.pse and “Recreate PSE”

Recreate the PSE where the CN is set with a wildcard. Please note that in the help documentation an alternate option is suggested, namely to use SubjectAltNames. An example to use SubjectAltNames and its benefits is explained in this blog. The steps from the blog using SubjectAltNames can be used to replace the certificate steps below.

In my example, my XSA domain name was set to, so I set the CN to CN=*. By using the wildcard CN the certificate will apply for,, etc. Wild-card etc

The next step is to create the CA request and have it signed by your CA. Make sure to have the full chain available for import including the root CA and intermediate signing certificates.

The result:


  1. from the command line export the certificate in p12 format, convert it to pem format and prepare the certificate files for XSA import

Login to the Failover Web Dispatcher server as the <sid>adm user (or whichever user is the Linux owner of the Web Dispatcher directories/files). Change to the $SECUDIR directory, in my instance /hana/shared/W95/sec.

Export the certificate chain we just imported in .p12 format. Make sure to set a compliant password and have it available for the import step we’ll execute later. Command:

/hana/shared/W95/sapgenpse export_p12 -p /hana/shared/W95/sec/SAPSSLS.pse

The next step is to convert the exported .p12 file to .pem format. There are several websites that can do this for you, however using openssl installed locally is a more secure option.


openssl pkcs12 -in -out -nodes

Please be aware that using the -nodes option exports the private key unencrypted. Hence cleanup of any files containing the unencrypted private key should be performed after completing the setup.

The next step is to take parts of the .pem file and create certificate files importable by XSA.

Use your favorite editor to create 2 new files, one will contain the private key and the other the certificate chain. In earlier version of XSA you had to make sure the lines for “bad attributes”, “subject”, and “issuer” are not part of the new files. As of XSA version 1.0.82 this is not necessary any longer.

In the private key file copy the “PRIVATE KEY” section, including begin and end line from the .pem file.

In the chain file copy the certificates, including begin and end line from the .pem file.

Example pkey.pem:


Exported Private Key


Example chain.pem:


Server certificate



Intermediate/Signing certificate



Root certificate


Once the files are created, copy both files to the Primary XSA host as the <sid>adm user of the XSA Primary HANA instance. As the target directory, you can select $SECUDIR, which defaults to /usr/sap/<SID>/HDB<##>/<hostname>/sec (example /usr/sap/SR1/HDB19/PRIMARY/sec).



Step 3:

Next, we can import the certificates, note that a restart of XSA will be required. Make sure you are logged in as the <sid>adm user, issue command “xs-admin-login” (or “xs login”) and enter the XSA_ADMIN password:

The command is:

xs set-certificate <XSA domain> -k <private keyfile> -c <chain file>

The command to set the certificate in XSA is:

xs set-certificate -k /usr/sap/PR1/HDB01/PRIMARY/sec/pkey -c /usr/sap/PR1/HDB01/PRIMARY/sec/chain

As mentioned before, next XSA needs to be restarted. A quick way to do this is to reuse the existing putty session since we are already logged into XSA. Simply type “XSA restart”:

Once XSA has restarted, open a new browser and retest the api url. Now the browser security status should show the lock to signal that the connection is secure:

When you inspect the certificate path you will see the full chain:


Enable HANA System Replication on Primary

The next step is to enable the system replication on the primary as documented in the help link: HANA Administration Guide

Make sure the log_mode is set as explained in the help link and that the backups are taken.

Now enable HANA System Replication on the primary:

Next, install XSA on the Secondary. Make sure that the SAP HANA instance on the secondary meets the general prerequisites in the SAP HANA Administration Guide.

In my example I execute hdblcm, select my instance SR1, and select ‘xs’ from the list of installable components:

Make your choices based on your scenario (add hosts, passwords, etc). When you get to the Routing Mode select ports (I will explain). Simply confirm the hostname as the domain name.

Note: the choice for routing mode ports will be fixed later. For now, we just need to get XSA installed, later we will copy the relevant XSA config from the primary to the secondary to bring both in line. The alternative to select routing mode hostnames is an option, but the installer will then need yet another DNS wildcard domain. To avoid this extra work, select ports routing mode and we’ll fix it later.

After successful installation, shut down the SAP HANA instance on the secondary.

Next, copy the SSFS files from the primary to the secondary. From SAP Note 2300936:

  1. Make sure you have considered the necessary steps to prepare the secondary system as described by the section general prerequisites in the HANA Administration Guide. Don't miss to copy the HANA SSFS, as described there (see also SAP Note 2369981).

  2. Perform the following additional steps specific to XS advanced. For XS Advanced > 1.0.34: If present, copy the XSA SSFS files from the primary system to the same location on the secondary system (overwrite the files if already existing in the target location):

  • /usr/sap/<SID>/SYS/global/xsa/security/ssfs/data/SSFS_<SID>.DAT

  • /usr/sap/<SID>/SYS/global/xsa/security/ssfs/key/SSFS_<SID>.KEY

Let’s check the version to see which location we need to copy from/to. Since we shut down the SAP HANA instance on the secondary and both primary and secondary have the same version, the quickest check is on the primary using “xs system-info”:

If the command fails, make sure to login using xs-admin-login as before and rerun the “xs system-info” command.

My version is > 1.0.34. For XSA, in below example I use scp to securely copy the files from /usr/sap/<SID>/SYS/global/xsa/security/ssfs/data/ and /usr/sap/<SID>/SYS/global/xsa/security/ssfs/key:

As mentioned in the general pre-requisites link and SAP Note 2369981, for SAP HANA 2 you also have to copy /usr/sap/<SID>/SYS/global/security/rsecssfs/data and /usr/sap/<SID>/SYS/global/security/rsecssfs/key:

Next, copy the xscontroller.ini file from the primary to the secondary:

After performing these steps, do not start up the secondary system, yet.

Instead, proceed with step 2) of the System Replication setup procedure as described in the SAP HANA Administration Guide (that is register it as secondary at the primary and start it up afterwards).

In this example operationMode async is used, but please choose the appropriate setting for your scenario.

Perform this step on the secondary. Syntax: hdbnsutil -sr_register --name=<name> --remoteHost=<primary> --remoteInstance=19 --replicationMode=async --operationMode=logreplay

Check with hdbnsutil -sr_state:

Some errors are shown since the secondary HANA instance is in a stopped state. But mode and site id look correct. Next, start the HANA instance on the secondary.

After SAP HANA is running, re-execute hdbnsutil -sr_state:

(partial screenprint)

To test, perform a takeover and verify you can access XSA. Below steps are just a quick verification, a more thorough verification is recommended. After verification perform a Failback to restore the initial situation.

After takeover, if SAP HANA is running on the primary, use sapcontrol to stop the SAP HANA instance on the primary. Then on the secondary, check XSA and the certificate:

Open the landing page, and open xsa-cockpit in a new tab:

Log in:

Now you can perform a Failback to restore the initial situation.