Installing SAP HANA, express edition into WSL2 (Windows Subsystem for Linux)
In this blog post I will describe the steps I went through to experimentally install SAP HANA, express edition into WSL2 – Windows Subsystem for Linux Version 2. Before I jump into any content, though, I want to start with a disclaimer.
Although I work for SAP, what I’m describing here is not an official SAP supported approach to install or run our software. This is the result of my personal experimentation and exploration. Use at your own risk.
What is WSL?
What is the Windows Subsystem for Linux? As the name suggests this is a feature for the Microsoft Windows operating system for running Linux within that environment via a lightweight virtualization approach.
The description directly from Microsoft:
The Windows Subsystem for Linux lets developers run a GNU/Linux environment — including most command-line tools, utilities, and applications — directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.
WSL version 2 is major change to the offering by introducing a full Linux Kernel and system call compatibility. Personally I had tried to get HANA running on WSL 1 but failed because of the lack of system calls. But with the recent introduction of WSL2 (and backport to older patch levels of Windows making it available in corporate environments like SAP’s) I was ready to give things another try.
If you want to read more about the features and benefits of WSL2:
There are so many developer subtopics that could be explored here: Docker integration, VSCode Remote Containers support, etc. But for today, let’s focus on the experience for installing and running HANA Express.
One benefit I really like is that access to the file system of the Linux distribution direction from within Windows Explorer. This makes it super easy to move files and content back and forth between the host OS and the various guests. Also notice from the screenshot that I’m running both openSUSE Leap 15.2 and Ubuntu. I’m going to use openSUSE to run HANA Express but Ubuntu to do clean Linux development via VSCode Remote Containers.
One of the great benefits compared to running regular Virtual Machines is that these Linux distributions start up almost instantaneously. They have large scale access to the Host hardware yet only allocate things like Memory upon need using a dynamic allocation mechanism. My openSUSE distribution shows 51Gb memory to it yet only 18Gb is actually allocated at the host OS/hardware level.
As we will see later, there is also a very unified networking experience. Ports are automatically forwarded into the Linux containers. Also the Windows networking configuration is automatically replicated into all the Linux containers. This further simplifies setup and even makes Linux container to container communication super easy.
Now that we see why if you are a Windows user that WSL2 might be interesting – especially for developers. But why not take this to the extreme given the improved performance and kernel/system call support in WSL2 we should now be able to install server software – like SAP HANA. To that end, here are the steps and my experience installing into WSL2. I would advise you to read all the way to the end before trying this yourself. Spoiler Alert: I did hit some problems that I didn’t find until the end that made me backup and repeat some steps. But I’m going to detail this in the order in which I experienced it.
First I’ve installed and updated to WSL2. If you are running Windows 1903 or 1909, there are some additional steps to get the backported version of WSL2: https://devblogs.microsoft.com/commandline/wsl-2-support-is-coming-to-windows-10-versions-1903-and-1909/
I’m not going to repeat all the installation steps or process here as its already detailed well elsewhere and I didn’t really run into any specific issues. I did end up installing two Linux distributions – openSUSE and Ubuntu. Because openSUSE being so close to Enterprise SUSE, I’ll use that as my starting point for installing HANA Express.
I’m a bit of a control freak. Therefore my favorite way to install HANA Express is to use the binary installer and answer most of the questions myself.
I start with the binary installer and can easily copy it to my openSUSE Linux distribution because the Linux file system is available within Windows Explorer.
I kick off the installation using the SAP HANA Lifecycle Management command line tool. Some things you might notice from this screenshot: Yes I’m using the HANA 2.0 SPS 05 version of HANA Express. No this version isn’t available publicly yet. No I don’t know when it will become available. 😉 But as an SAP employee I have access to the release candidates and I’m helping to test the new version before public release. I don’t believe there is any special or specific in the upcoming SPS 05 version for WSL2; it just so happens that since I was doing a clean install I wanted to also use the internal testing version.
The other important item to notice is that I’m using the Local Host Name of localhost. HANA and particularly XSA is very sensitive to the hostname. localhost in this case would be used even from the Host OS to redirect to the UAA. And yes this works because all the ports from the Linux container receive automatic port forwarding from the host OS. But spoiler alert: this will cause me problems later simply because of port conflicts with services already running in the Windows OS.
The installation was off and running on a purely standard copy of openSUSE Leap 15.2 right from the Microsoft Store. https://www.microsoft.com/en-us/p/opensuse-leap-152/9mzd0n9z4m4h
For several minutes the installation progressed without error (and very fast compared to my experience with full VMs).
But I spoke too soon. Near the end of the installation process during the creation of the secure store I received an error that an OS library, libatomic.so.1, was missing. I had anticipated that there might be missing dependencies or prerequisites compared to Enterprise SUSE.
Luckily everything that was missing can easily be added from the standard repositories. In openSUSE you have the tool named YaST2 that can be used to install extra software. I search for libatomic1 and I see that it’s part of gcc.
Therefore rather than hunt down separate dependencies, I decided to search for gcc and install the whole of the gcc8 package. https://gcc.gnu.org/
After installing the gcc and restarting the installation I actually hit one more missing dependency, libnuma. NUMA or Non-Uniform Memory Access is certainly a Linux server feature of the type that HANA would use but might not be present in a standard, end user focused distribution.
Luckily just like the gcc, we can return to YaST2 and install this additional feature from the standard repositories. No special repository setup or SAP specific configuration needed here. And of course if you were starting from scratch doing the installation yourself, you could install both of these dependencies first and never even fail in the HANA installation.
After these two dependencies are in place, I repeat the installation process but this time it goes all the way to completion without any errors. So two OS dependencies that are needed, but otherwise HANA Express basically works out of the box on WSL2 now.
Returning to the Windows Host OS, I can now access HANA using localhost as though it is installed in Windows as a native application. No special networking configuration or setup. It just plain works. And in fact if you are only going to use the HANA database without XSA, I would probably recommend just installing with the hostname localhost and let the automatic port forwarding do its magic.
With that initial success in the win column, I was ready to move on and use the HANA installer to now add XSA to my system as well. My original idea was to only do a lightweight DB only installation. However the performance was so good and the installation process so easy, I figured why not go all in and do a full XSA install as well.
And everything worked just great. Adding XSA went off without a single error. I could launch a web browser in Windows, use localhost and I’m accessing XSA application now as well.
But then I installed some more XSA applications – Cockpit, Web IDE, etc. And I hit my first real serious problem. The ports in the 51XXX range didn’t work. As it turns out it was simply some existing Windows services already running in the host OS using these same ports. Port forwarding only works for any port not already bound at the host OS level.
This actually makes a lot of sense and is necessary to avoid conflicts with the host OS. But as it turns out each Linux Container of course has its own unique IP address assigned. You aren’t required to use the port forwarding via localhost but can directly access the Linux container specifically.
I use this technique and lookup the IP address of the openSUSE container instance. I then configure the hosts file in my Windows host OS version (c:\windows\system32\drivers\etc\hosts). WSL handles this exceptionally well, pushing any of the changes to the Windows networking configuration into all the Linux containers. So no double maintenance is needed. I setup an alias named hxehost (much like when you use HANA Express in a VM) in the Windows hosts file and both of my Linux distributions get this same configuration pushed to them.
The most painful part here is that I uninstalled and then did a complete reinstall specifying that hxehost alias right at the beginning of the process when the installer asked me for Local Host Name. With this one minor change, everything worked so much better. I can now access all the XSA applications in my web browser and I can still access HANA Express from my other, Ubuntu distribution as well.
I’ve been using this new setup for a few days now. I’m super pleased with the performance compared to my previous setup using Hyper-V. The integration with Windows Explorer is particularly nice. But overall the simplification of the setup (especially on the network side even with the little work I had to do with the hxehost alias) is way easier than Hyper-V full VMs. Another major plus is the interaction between multiple containers and the host OS. So if you are on a version of Windows that has access to WSL2, I’d strongly recommend you give it a try. It’s a great, full featured Linux experience.
Great set of instructions, and even though i do not share the enthusiasm for WSL regardless how easy Microsoft would try to make us use their linux, i may have found a mention on when HXE SPS 05 may be released. Nothing official, obviously, but it does sound like a Christmas present to me:
Always appreciating your great support and knowledge sharing with the rest of the SAP community.
First of all, thank you very much for your work and contribution to the community.
I would like to ask you about the experience in the uninstallation of HANA Express and, in general, a Linux subsystem. I like to work with VM for everything due to the simplicity of the approach where my host system is always clean. I understand the improve in the performance and the integration between the subsystem and the main windows system... but I am afraid about the health of my system.
You can still backup and restore individual WSL2 containers. --export and --import command. I also found it clean to just unregister a distribution and then reinstall it from the store. I did that several times in my early experiments. Using the same export/import command you can run multiple instances of the same Distro or create a "base image" that you start new work from. But another thing to consider is Docker Desktop but with WSL 2 as its engine. https://docs.docker.com/docker-for-windows/wsl/
I understand. Now the next step is to hands-on.
Thank you very much.
Thanks! I was planning on using a HyperV VM but with your guide I might try to use WSL instead.
Were you able to get WSL2 containers to work in your local network? I am still using WSL1 mostly because while I can connect to the WSL2 instance from my host PC I cannot connect to any hosts in my local network from inside the instance. For example I mostly use WSL to ssh into other linux hosts in my network which doesn't work anymore on WSL2 without apparently reconfiguring the windows firewall (which requires admin privileges and seems quite dangerous) .
Also when in a home office scenario VPN connections in WSL are a nightmare. On WSL1 I have to execute a script every time I connect the host machine to the VPN or the network interface changes and on WSL2 I haven't even tried after hearing about it leaking the VPN traffic .
I also have WSL2 crash or freeze or consume all available memory on my system quite often especially when trying to use the remote-wsl functionality of VSCode .
I've not experienced what you described. The one issue I did hit was specific to the SAP internal network configuration for McAfee firewall blocking outbound internet connections from within the WSL container. But our IT was already aware of the issue and pushed a configuration change that corrected it.
On the VPN topic I personally only use the VPN very rarely. But I am aware that activating the VPN will cut off network to the WSL. However I've also found that the SAP VPN also disrupted Hyper-V and VMWare as well. Luckily there are very few instances when the VPN is needed these days for us at SAP. So many systems are in the cloud now. I might only use the VPN for a few minutes at most each week.
I've not had any freezes at all (knock on wood). I have noticed that WSL2 doesn't immediately release memory once allocated even if the guest OS relinquishes it. But I also haven't had memory shortfalls. I guess I either have enough memory to spare or when other memory intensive applications start they've been able to reclaim upon need.
Useful post, Thomas. bingo ?
Thomas Jung Thank you very much for your work and for sharing the knowledge. The installation, as you have described indeed runs smoothly. I did it in less than an hour while it always took me several hours and attempts to finally install using the VM method. One thing I noted, even though the installation runs smoothly, the WSL2 hogs both the CPU and RAM. I ran the installation on a PC with 64GB RAM. At one point the Linux instance was using 92% of RAM and 100% of CPU. Nevertheless, the issues seem to be fixed by setting some reasonable resource constraints for WSL2.
Thank you for sharing the knowledge.But we got error message "Unknown user password combination" when the installation fail. Do you have any suggestion for reference?
SAP HANA Lifecycle Management - SAP HANA Express Edition 2.00.045.00.1575639312
Resuming pending install at step 'Configuring Topology'
Start reading from input channel...... Done.
Resume of SAP HANA Express Edition Installation failed
Configuration error (batch mode):
Unknown user password combination
Log file written to '/var/tmp/hdb_HXE_hdblcm_install_2020-10-17_16.10.25/hdblcm.log' on host 'W701126'.
Failed to install HDB server.
I kind of doubt there is anything WLS specific about that error. Seems the most likely cause would be an incorrect password input. Perhaps the hostagent already existed on the system and the password you input doesn't match. I'd suggest trying again doing a clean install or better to ask the question in the HANA Express specific forum to see if anyone else has encountered this error.
Nice and clear blog Thomas Jung. Thanks for putting it together.
Some quick feedback, not sure if others had a similar experience. I was able to do my first time Hana Express install following your blog with a couple of additional changes.
Interesting. Did you have those two extra dependencies on the same distribution and version I used? I did this on OpenSUSE-Leap and version 15.2.
Yes, the same here.
Great post and info Thomas Jung !!! Thanks for make easier the SAP developers life XD An awesome next step would be a Docker Image with Hana Express ready to use, do you see it possible?
SAP does have Docker images for HANA Express https://hub.docker.com/publishers/saplabs
I´ve to correct my suggestion: i meant a Hana Express docker image, for Windows, running on WSL2 instead Hyper-V. I dont even know if this is possible...
Anyway, the improvements the team is working on are awesome!! Thanks for your help!!
This guide really helps, got HANA express running on my Thinkpad. WSL + opensuse15.3 rocks , hxe+xsa all good...
hana express 2.0 WSL2 IBM Thinkpad