Let’s start with testing the DNS pre-requisite, both serge.xs2tests-wdf.sap.corp and *. serge.xs2tests-wdf.sap.corp 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.
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:
- https://launchpad.support.sap.com/#/notes/2347931 for XSA versioning
- https://launchpad.support.sap.com/#/notes/2510063 for SAP HANA 2.0 SPS03 Web IDE
- https://launchpad.support.sap.com/#/notes/2507070 if installing multiple XSA on the same host
- https://launchpad.support.sap.com/#/notes/2596466 for the XSA FAQ
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 https://api.serge.xs2tests-wdf.sap.corp:31933/. 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.
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. 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.
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.
High level steps in this example:
- in the SAP Web Dispatcher generate a wildcard certificate request, get it signed by your Certificate Authority of choice, import the certificate chain
- from the command line export the certificate in p12 format, convert it to pem format and prepare the certificate files for XSA import
- in the XSA environment, import the certificate files and restart XSA
- 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. 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 serge.xs2tests-wdf.sap.corp, so I set the CN to CN=*. serge.xs2tests-wdf.sap.corp. By using the wildcard CN the certificate will apply for webide.serge.xs2tests-wdf.sap.corp, xsa-admin.serge.xs2tests-wdf.sap.corp, 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.
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/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 star.serge.xs2tests-wdf.sap.corp.p12
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 star.serge.xs2tests-wdf.sap.corp.p12 -out star.serge.xs2tests-wdf.sap.corp.pem -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.
—–BEGIN PRIVATE KEY—–
Exported Private Key
—–END PRIVATE KEY—–
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).
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 serge.xs2tests-wdf.sap.corp -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
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:
- 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).
- 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):
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:
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: