Skip to Content

SAP HANA 2.0 XS Advanced: a host auto-failover installation/configuration example


While the host-auto 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 ports routing, but as documented in SAP Note 2245631 for a production system hostname routing is recommended.

For this example, the setup will include:

  • HANA Installed with two nodes in host auto-failover configuration
  • Hostname 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
  • IP addresses:
    • Failover Web Dispatcher ends in .198
    • XSA Master ends in .199
    • XSA Stand-by ends in .200

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:

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 01 and the SID is PR1, adjust this your instance is different. Replace XSA Master and XSA Standby to reflect your hostnames (fqdn):

  • icm/server_port_0=PROT=ROUTER, PORT=30133, TIMEOUT=60, PROCTIMEOUT=600
  • wdisp/system_0 = NAME=PR1, SID=PR1, SRCVHOST=*:30133, EXTSRV=https://<XSA Master>:30133#MAIN_INSTANCE;https://<XSA Standby>:30133#FAILOVER_INSTANCE
  • wdisp/server_0=NAME=MAIN_INSTANCE, LBJ=1, ACTIVE=1
  • wdisp/server_1=NAME=FAILOVER_INSTANCE,LBJ=2147483647, ACTIVE=1

Other settings to consider:

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



Next install HANA and XSA, or if HANA is already installed, add XSA. Follow the official HANA installation guides on to install the multi-node cluster for host-auto failover. The HANA 2.0 revision has to be at least revision 21.

In my example during the XS Advanced installation prompts for routing mode and XSA Domain Name:

After the installation, let’s 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”):

Verify that the URL’s work, a quick example is to test the xsa-admin URL since the XSA_ADMIN user already has the required authorizations whereas it does not for the webide (see webide post-installation link for additional steps). 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.

The expected xsa-admin url response:

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

Depending on the browser you may be able to click through the warnings and get to the login page, but at this point it is not yet important to login. Just make sure the URL resolves and gets a response. If you get an error response, such as 503, check the output of “xs a” and make sure xsa-admin 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

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:

  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 HANA

Step 1

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

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

Recreate the PSE where the CN is set with a wildcard. In my example, my XSA domain name was set to, so I set the CN to CN=*. By using the wildcard CN my certificate will apply for,, 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:

Step 2

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/W01/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/W01/sapgenpse export_p12 -p /hana/shared/WD5/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. Make sure the lines for “bad attributes”, “subject”, and “issuer” are not part of the new files.

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 Master XSA host as the <sid>adm user of the XSA Master HANA instance. As the target directory, you can select $SECUDIR, which defaults to /usr/sap/<SID>/HDB<##>/<hostname>/sec (example /usr/sap/PR1/HDB01/XSA-Master/sec).



Step 3

Next, we can import the certificates, note that a restart of the xscontroller 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>

In my example:

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

As shown in the screenprint next we need to restart the xscontroller.  There are several ways in this example we show it from the HANA Studio (be aware that another option is to restart the entire XSA using command “XSA restart”). Open the administrator perspective connected to the SYSTEMDB, go to the Landscape tab, right click on xscontroller and choose stop. You will get a pop up message that the xscontroller might restart, since it is the default setting and a newly installed instance the xscontroller will start automatically.

And confirm:

You can monitor the xscontroller restart from the landscape tab in the HANA studio, or check the xscontroller_0.log file in the Diagnosis Files tab or at the OS level in the SAP HANA trace directory.

Once the xscontroller restarted, open a new browser and retest the xsa-admin url. Now the browser security status should show green after logging in:

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

Now you are ready to test the failover. Make sure that the HANA 2.0 revision is at least revision 21.

Be the first to leave a comment
You must be Logged on to comment or reply to a post.