Skip to Content
Author's profile photo Lucia Subatin

HANA Express and XS Advanced: When you cannot modify the hosts file…

Use the IP address to access the applications

Nothing like having administration rights over your computers and servers, especially when you are using HANA Express with XS Advanced (the “server + applications” image) and need to change the hosts file to map the IP with the default name of the host, hxehost to connect.

The instructions tell you that you need to either edit the file in C:\Windows\System32\drivers\etc or in /etc/ for Mac… some people, try this and find that they have:

No administration rights to edit the hosts file

So what happens when you have a powerful virtual machine on a cloud environment but you do not have permissions or the possibility to edit the hosts file? You stay out of XS Advanced apps in your HXE Virtual Machine? Do you miss all the fun and tooling? No, you have the option to rename the system to the DNS or, better yet, the external IP address.

So this makes sense/applies to:

This works in other pre-configured flavors of HXE installations, like the downloadable HXE VM. However, most of the other methods will not throw exceptions when performing a full rename of the system as documented in the administration guide. I’ll spare you those gory details and continue to the quickest solution I have found (so far).

Renaming the XSA domain name only

I will be using the IP address as the XSA domain name, but you can replace it with a proper, working DNS name.

Get a static IP address

Whatever platform you are using, make sure the IP address that was assigned to your machine will stay there. By default, the virtual machines in cloud providers are configured with an ephemeral IP address. Make sure you switch it to static so that you do not get a new one when the machine is rebooted.

Modify the xscontroller.ini file

I am using vi for this.

It’s OK if you haven’t used it before, I won’t tell anyone. Here are the very basics: the arrows will move you around, when you are ready to modify a line press “i”, when you are done editing press Esc + “:” + “wq”. If you panic, need to exit and not save, press Esc + “:” + “q!”.
sudo vi /hana/shared/HXE/global/hdb/custom/config/xscontroller.ini

In the file, replace `hxehost`  with your external IP address or domain name:

Create a file with passwords

This is to avoid the renaming program to ask you for passwords. Again, “vi pwd.xml” will open an editor.

Don’t feel offended by the following note, but the devil is in the details: make sure you replace Password123 and HXHana4 with your own passwords if you are copying the file.
<?xml version="1.0" encoding="UTF-8"?>

For more details on this file, you can check this piece of the help.

Renaming time!

Switch to hxeadm and stop the database (the exit piece is not necessary in the downloadable VM, in case you are doing that there):

sudo su – hxeadm
HDB stop

Now replace the IP_ADDRESS with your own external IP address (or domain name, HANA likes it if you call her smart, for example)  and cast this spell in your console:

cat ./pwd.xml | sudo /hana/shared/HXE/hdblcm/hdblcm --action=rename_system --nostart --skip_hostagent_calls --certificates_hostmap=hxehost=IP_ADDRESS --xs_domain_name=IP_ADDRESS --read_password_from_stdin=xml -b

Let the magic happen and wait for the success message:

Turn the database on, give it like… 5 minutes, log in to the the XS CLI and voilá!

HDB start
xs a

Are you getting an error?

If you are getting something like the following:

Could not connect to authorization endpoint https://hxehost:39032/uaa-security: Error executing request GET https://hxehost:39032/uaa-security/login: No name matching hxehost found

Don’t panic and be patient. The renaming needs the database to be up and running before it can finish the process. Go, get some coffee or beverage of your choice and try the xs-admin-login piece again in a couple of minutes.

If you need to see some progress while you are waiting, tail this file: /usr/sap/HXE/HDB90/hxehost/trace/xscontroller_0.log

And enjoy all the hard work the platform is doing for you.

As usual, see you around on Twitter or LinkedIn!

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Ebu Sho
      Ebu Sho

      Hi Lucia,

      Do you know why the "Host ID" in XSA Cockpit Host management didn't change after SAP HANA Express host rename (the whole question here: ) ?


      Author's profile photo Uwe Fetzer
      Uwe Fetzer

      Thank you Lucia, you saved my (Sun-)day 🙂

      Author's profile photo Lucia Subatin
      Lucia Subatin
      Blog Post Author

      Really glad to know it helped 🙂

      Author's profile photo Steven De Saeger
      Steven De Saeger

      Thanks Lucia ... works perfectly !

      Author's profile photo Octav Onu
      Octav Onu

      Lucia, you're simply the best.


      1000 x Kudos and are not enough.


      I am on docker and after I have done all steps described above, I have encounter this:

      xs a

      FAILED: SSL connection error (supposedly untrusted connection, check the certificates)


      After xs login --skip-ssl-validation all apps started on the new IP.


      Do you have any advice against skip-ssl-validation?


      Thank you,


      Author's profile photo Lucia Subatin
      Lucia Subatin
      Blog Post Author

      Hi Octav,


      Thanks for the kudos, you made my day 🙂

      Don't worry about the --skip-ssl-validation. We need it because the certificate in HXE is self signed, but that flag is the the way to work around it (that, or installing a proper certificate).

      Glad it helped,


      Author's profile photo Octav Onu
      Octav Onu

      HI Lucia,

      Can you please advise me. After changing the domain name and api_url i cannot build against the development space. Seems that di-builder is trying to access the old host(hxehost).

      Thank you,




      (Project Space Builder) Starting the builder deployment in space development...
      Checking the builder status in the required space...
      Starting the builder MTA deployment...

      Uploading 1 files:
      Failed to upload files
      Failed to upload files
      Error occured during communication with HTTP server
      Error occured during communication with HTTP server
      Broken pipe (Write failed) (local port 62694 to address (hxehost), remote host unknown)
      Broken pipe (Write failed) (local port 62698 to address (hxehost), remote host unknown)
      File upload finished
      Uploading 1 files:
      Failed to upload files

      File upload finished

      Starting process xs2-deploy...
      Failed to start process

      Could not deploy the builder. Cause: Could not deploy the builder MTA..
      Could not deploy the builder MTA.
      The builder deployment has finished with status: FAILED in space development.


      Author's profile photo Lucia Subatin
      Lucia Subatin
      Blog Post Author

      Hi Octav,

      Can you redeploy the builder manually with the di-space-enablement app?

      Unfortunately, I haven't tested this specific scenario with the Docker full image but remember that error was solved by a manual redeploy of the builder in previous releases.

      Fingers crossed,


      Author's profile photo Gerald Iakobinyi-Pich
      Gerald Iakobinyi-Pich

      Hello Lucia,


      I have tried the steps you described here, and it worked when replacing the XSA domain name with an IP Address.

      It failed however when trying to replace it with a DNS.

      The error I get is the following:

      Renaming of SAP HANA Express Edition System failed.
      Rename System failed
      Error occurred while executing SAP HANA Express Edition System rename (hdbrename)
      Renaming SAP HANA instance failed!
      Renaming master failed!
      Cannot start instance HXE (HDB90) on host ‘hxehost’
      Start instance 90 on host ‘hxehost’ (worker, xs_worker) failed.
      FAIL: The following processes are not running:
      hdbxscontroller HDB XS Controller
      Check the log file for SAP HANA Database error messages


      Did I miss something?

      Is there some additional configuration required for having this working with a DNS.




      Author's profile photo Lucia Subatin
      Lucia Subatin

      Hi Gerald,

      Sorry for the delay, I'm not getting notifications out of that account anymore.

      I'm assuming you setup the DNS for HANA before attempting the rename? If you did and it is resolvable from within the OS in the VM, I would check at the controller logs to see what the actual error is.