There are essentially two ways to install a standalone SAP Web Dispatcher instance for the Windows Operating System. The standard way uses the SAPinst tool from SAP's Software Provisioning Manager. This method will create an instance with the typical directory structure (/usr/sap/<SID>/SYS, /usr/sap/<SID>/<instance>, etc.), create the usual SAP administrative users on OS level (sapadm, <SID>adm, etc.), register the instance as a Windows service, etc. All this makes the Web Dispatcher installation rather 'heavy', and requires Administrator privileges in order to complete successfully.
The second method consists basically of extracting the Web Dispatcher archive sapwebdisp_nnn.sar into one single directory. This is why I call it a 'flat' installation. It is not necessary to register a service or create extra users. This is a great way to quickly create a Web Dispatcher instance for test purposes as it can be done in just a few minutes. With a bit of manual tweaking, it is still possible to register such a Web Dispatcher instance as a service or integrate it into a bigger SAP system landscape (e.g. sapmmc).
Pain point - Administrator privileges
Unfortunately, both methods require Administrator privileges on most modern Windows OS, at least during installation. The SAPinst method obviously requires Administrator privileges in order to create the new user accounts and register the SAP Start Service. For the flat method, unpacking the archive does not yet require any special privileges, but once you try to run Web Dispatcher, the process will immediately terminate and you will find errors like this one in the dev_webdisp trace file:
*** ERROR => [CreateOsShm] CreateFileMapping(37,65 KB) failed with Err=5
EIO*: Input/output error OR: Access is denied.
The reason for this is that Web Dispatcher is using Named Shared Memory within the Global namespace. In order to do this, the user who is running Web Dispatcher needs the SeCreateGlobalPrivilege privilege. For normal users, this is usually not the case. On the other hand, Services and Network Services have this privilege by default. This is why Web Dispatcher can be started through the SAP Start Service without problems.
For our flat installation method, we have two options:
- Ask an administrator to grant our user the SeCreateGlobalPrivilege privilege. This is done with the help of the Local Security Policy editor:Security Settings > Local Policies > User Rights Management > Create Global Objects > Add User or Group
Once this is done, we can run Web Dispatcher under our normal user account.
- Ask an administrator to register the SAP Start Service for our Web Dispatcher instance. Once the service is registered in our user's name, we can start and stop it at will without requiring Administrator privileges any longer. I will describe this in more detail in section SAP Start Service integration.
Step 0 - Downloading the required files
SAP Note
908097 describes where to find the latest SAP Web Dispatcher archive. Additionally, we need a
SAPCAR.EXE to be able to extract the archive. It can be found under the category
SAP Technology Components on the same path as the Web Dispatcher. At the time of this writing, it is recommended to use
Web Dispatcher release 7.41. This is the most advanced release and adds SSL capabilities right out of the box.
Step 1 - Extracting the archive
Create a target directory, e.g. c:\usr\sap\WDP. In order to prevent difficulties in one of the further steps, it is recommended to keep the entire path free of spaces. This directory will become our DIR_INSTANCE, as well as DIR_EXECUTABLE, DIR_HOME, etc
Change into this directory and execute the following command:
<path to sapcar>\SAPCAR.EXE -xvf <path to sapwebdisp sar>\<name of sapwebdisp sar>
Note that SAPCAR.EXE should not be started from within the target directory. Since the archive also contains this file, extraction will fail because the running SAPCAR.EXE cannot be overwritten with the one from the archive.
Step 2 - Strapping on the boots
Once the archive is unpacked, we can now create a simple profile to get started with our new Web Dispatcher. Luckily, Web Dispatcher comes with a built-in process to quickly create such a profile for us:
sapwebdisp.exe -bootstrap
The bootstrapping process will ask for a few parameters that are required for any meaningful profile:
hostname and port of the Message Server of the SAP system we want to serve
system name and unique system number for our Web Dispatcher instance
HTTP port we want to listen on
- whether we want to prepare for a small, medium or large installation
- admin user and password for the Web Administration Interface
Except for the Message Server connection data, it should be okay to just confirm the defaults. The profile will be created in the same folder where we started sapwebdisp.exe and it will be called sapwebdisp.pfl.
Additionally, the process will create a default authentication file icmauth.txt for the Web Administration Interface with the provided user and password. Both user and password can be changed, or new users can be created at a later point with the help of the wdispmon tool.
At the end of the bootstrapping process, Web Dispatcher will automatically attempt to startup, using the newly created profile.
Step 3 - Manually starting and stopping Web Dispatcher
Now that we have a profile, we can start Web Dispatcher on the command line:
sapwebdisp.exe pf=sapwebdisp.pfl
And stop it by terminating the sapwebdisp process with the Windows Task Manager.
As previously mentioned, starting Web Dispatcher this way will require the SeCreateGlobalPrivilege privilege, or Administrator privileges.
Web Administration Interface
Upon the first startup, Web Dispatcher will automatically extract the Web Admin Interface pages from the wdispadmin.sar archive to a new admin folder in the DIR_INSTANCE directory, and the admin handler will be configured like this:
icm/HTTP/admin_0 = PREFIX=/sap/wdisp/admin,PORT=4300,DOCROOT=./admin,AUTHFILE=icmauth.txt
The Web Administration Interface is opened in the browser with the following URL:
https://<Web Dispatcher host>:4300/sap/wdisp/admin and logon is performed with the admin user and password specified during bootstrap.
SAP Start Service integration
The flat installation includes all files that are required to register Web Dispatcher as a service. This is one way which allows us to use Web Dispatcher without Administrator privileges (once the service is registered, see section Pain point - Administrator privileges)
To register SAP Start Service for our Web Dispatcher instance, we need to perform two steps:
- Prepare the instance profile that was created in section Step 2 - Strapping on our boots :The bootstrapped profile is called sapwebdisp.pfl, but we want to comply now to the usual SAP naming convention and rename it accordingly:
move sapwebdisp.pfl <SID>_W<instance #>_<hostname>
We will reuse the same profile for both the SAP Start Service and Web Dispatcher, but we need to add or modify some parameters:
DIR_INSTANCE = <absolute path to flat folder>
DIR_EXECUTABLE = $(DIR_INSTANCE)
DIR_PROFILE = $(DIR_INSTANCE)
DIR_GLOBAL = $(DIR_INSTANCE)
DIR_HOME = $(DIR_INSTANCE)
SAPGLOBALHOST = <hostname>
INSTANCE_NAME = W<instance #>
Autostart = 1
Restart_Program_00 = local $(DIR_EXECUTABLE)\sapwebdisp.exe pf=$(DIR_PROFILE)\<profile name>
It is important to modify DIR_INSTANCE to an absolute path, otherwise it does not make sense to the SAP Start Service.
The Autostart parameter is optional and will have the effect that Web Dispatcher is automatically started when the SAP Start Service itself is started (e.g. at boot time.) Start_Program_00 could be used instead of Restart_Program_00, but the latter will make sure that the Web Dispatcher process is automatically restarted in case it crashed.
- Ask an administrator to execute the following command: sapstartsrv.exe -r -soap -p <absolute path to profile>\<profile name> -s <SID> -n <instance #> -U <your user> -P <your user's password> -q
You can check in the Services console whether the service was successfully created under the name SAP<SID>_<instance #>.
In case something does not work as expected during service registration or startup, it is always a good idea to check the
Application section of the
Event Viewer. If the service starts up but fails to start the Web Dispatcher process, the file
stderr0in our Web Dispatcher directory should give some hints about what went wrong.
We can now manually control our Web Dispatcher through the running SAP Start Service with the help of sapcontrol:
sapcontrol.exe -user <your user> <your user's password> [-trace sapcontrol.log] -nr <instance #> -function StartSystem
sapcontrol.exe -user <your user> <your user's password> [-trace sapcontrol.log] -nr <instance #> -function StopSystem
sapcontrol.exe -[-trace sapcontrol.log] -nr <instance #> -function GetProcessList
SAP Management Console (sapmmc) integration
After a successful SAP Start Service integration, adding our Web Dispatcher instance to the sapmmc is as simple as that:
SAP Systems > Properties > General (tab) > Options > Used fixed SAP instance list
> Fixed (tab) > Add system/instance
In order to enable the
Syslog view for our instance in sapmmc, create a new subdirectory named
login the Web Dispatcher directory.
Updating the flat installation
After downloading the new archive, terminate the sapwebdisp process in the Task Manager or stop the service via the Services console, extract the new archive as described in Step 1, and restart the service/Web Dispatcher again.
Conclusion
Unfortunately, even the simplified installation method described in this article still requires Administrator privileges on the Windows operating system. Nevertheless, I believe the 'flat' installation method offers a few advantages over the full-blown installation using the Software Provisioning Manager, in particular the possibility to keep everything within your own user account.
Further reading
SAP Web Dispatcher
SAP Start Service
