Skip to Content
Author's profile photo Tobias Winterhalter

Name-based virtual hosts and one SAP Web Dispatcher to access multiple SAP systems

September 9, 2014

SAP Note 2010948 obsoletes the scenario described in this article. Web Dispatcher 7.4 and higher has now built-in capabilities to serve multiple systems based on virtual host names. I recommend to use Web Dispatcher 7.41.

SAP Web Dispatcher 7.20 introduced the long awaited functionality of serving multiple SAP systems. In principle, this means that any SAP landscape – however complex – can be served by one single Web Dispatcher. In this article I want to show how this feature can be combined with name-based virtual hosts to access multiple SAP systems behind one Web Dispatcher in an elegant and fairly low maintenance fashion.

This is the example landscape I will use for the purpose of this article:

When running in front of multiple systems, Web Dispatcher has to apply a multi-stage routing decision for each request. For each request, it has to determine the target system first, and then dispatch the request to the appropriate application server in the selected target system. There are several methods to identify the target system:

  • by access point (IP address and/or port)
  • by URL prefix
  • by a SAP specific HTTP header field called x-sap-webdisp-target-sid

IP-based virtual hosts

The first method can be used to identify the target system based on virtual hostnames, but it requires a physical access point for Web Dispatcher to listen on.

For our example landscape we would require:

  • the Web Dispatcher host to have at least three network interfaces
  • Web Dispatcher to listen on at least three different network interfaces (in this case, each time on port 80)
  • the DNS to resolve each,, and to the IP address of one of the network interfaces

The following picture shows this setup in more detail:


This is certainly a valid approach, but as the landscape gets more and more complex and as even more systems are to be served, the requirement to have a separate network interface for each system is becoming an increasing cost factor. This method of virtual host separation is IP-based since every virtual host requires a network interface, which in turn requires at least one IP address.

Name-based virtual hosts

Name-based virtual hosts offer a different approach. In this case, the DNS will resolve all virtual hostnames to one IP address, and Web Dispatcher only listens on the network interface that has this IP address (of course, having multiple interfaces and IP addresses is still an option, e.g. for high availability purposes).

Web Dispatcher then has to look at the hostname of the request to identify the target system. This can be achieved by using Web Dispatcher’s modification handler to insert the special header field x-sap-webdisp-target-sid into the request. The value of this header field has to be set to the system ID of the desired target system, based on some information in the request, such as the Host header field. Thanks to the order in which the request goes through the handlers (… > modification handler > … > routing handler), the routing handler will find the special header field previously inserted by the modification handler and use its value to identify the target system for the request.

The necessary configuration for our example landscape would look like this:

  1. DNS must resolve all three hostnames to the IP address of the Web Dispatcher host.
  2. All systems must be defined in the Web Dispatcher profile:
       wdisp/system_0 = SID=ECC, MSHOST=sapecc1, MSPORT=8100
       wdisp/system_1 = SID=CRM, MSHOST=sapcrm1, MSPORT=8100
       wdisp/system_2 = SID=EP1, MSHOST=sapepcs, MSPORT=8101
  3. Modification handler must be added to the Web Dispatcher profile:
       icm/HTTP/mod_0 = PREFIX=/, FILE=mod_rules.txt
  4. One rule must be added to the rule file (in this case, mod_rules.txt) for each virtual host (i.e., system):
       if %{HTTP_HOST} regimatch “”
         SetHeader x-sap-webdisp-target-sid ECC [break]
       if %{HTTP_HOST} regimatch “”
         SetHeader x-sap-webdisp-target-sid CRM [break]
       if %{HTTP_HOST} regimatch “”
         SetHeader x-sap-webdisp-target-sid EP1 [break]

The following picture shows the name-based setup in more detail:


Requirements and possible issues

Web Dispatcher can identify the target system only if it knows the hostname. This information is available in HTTP/1.1 with the mandatory Host header field. Consequently, HTTP/1.1 is a requirement for the name-based virtual hosts solution described in this article. HTTP/1.1 is the standard for all common Web browsers supported by SAP, so this requirement should not be of much concern.

When using HTTPS, Web Dispatcher needs to see the decrypted request in order to evaluate the Host header. This is no problem when Web Dispatcher terminates or re-encrypts SSL. But the special ROUTER protocol (End-to-End SSL) cannot be used.

In case of DNS issues, users sometimes try to use IP addresses in the URL instead of the hostname, e.g. This causes a problem because the IP address does not uniquely identify the target system, so Web Dispatcher cannot decide where to dispatch such a request.

There are several possible solutions for this issue:

  1. Web Dispatcher rejects requests that were called with an IP address:
    With the rules in the above example, this would be the default behaviour. Since none of these rules match a hostname pattern, Web Dispatcher would respond to the request with a 500 Internal Server Error and the error detail No target SAP system for request.
    Different behaviours such as a custom error page, a redirect, or a Forbidden response can be achieved with additional rules, e.g.:
       if %{HTTP_HOST} regimatch “[0-9]*[.][0-9]*[.][0-9]*[.][0-9]*”
         RegIForbiddenUrl ^/.* –
  2. Web Dispatcher forwards requests that were called with an IP address to a specific target system:
       if %{HTTP_HOST} regimatch “” [or]
       if %{HTTP_HOST} regimatch “”
         SetHeader x-sap-webdisp-target-sid EP1 [break]
  3. If possible, Web Dispatcher uses additional information to determine the correct target system:
    The most obvious source of information is the URL path. However, anything that can be evaluated by the modification handler, such as header fields or query parameters, is a possible criterion to determine the correct target system. Criteria can also be grouped together.
    Here is a very simple example which makes use of the URL path:
       if %{HTTP_HOST} regimatch “” [or]
       if %{PATH} regimatch “^/irj”
         SetHeader x-sap-webdisp-target-sid EP1 [break]

    This last option is only available if there is sufficient information that can uniquely identify the target system. For example, as soon as two systems serve a resource with the exact same name, it is no longer possible to use the URL path alone, e.g. http://host1/sap/public/logo.gif and http://host2/sap/public/logo.gif.

A completely missing hostname causes similar issues as the use of the IP address. This could happen if a browser uses HTTP/1.0 and does not send the Host header field. The same three solutions as above are also valid in this case, and a rule to reject such requests would look like this:

   if %{HTTP_HOST} regimatch “”
     RegIForbiddenUrl ^/.* –

Finally, one last issue should be mentioned. Even the official Web Dispatcher documentation currently contains the following erroneous example:

   if %{HTTP_HOST} regimatch wd_erp*
     SetHeader x-sap-webdisp-target-sid ERP [break]
   if %{HTTP_HOST} regimatch wd_ce1*
     SetHeader x-sap-webdisp-target-sid CE1 [break]
   RegForbiddenUrl ^/(.*) –

These rules do not work because of the way Web Dispatcher separates header rules from other rules. All header rules are executed first, followed by all other rules. The [break] statement in a header rule will only terminate the execution of the header rules, but the other rules will still be executed. In the example above, this will lead to a Forbidden response for all requests (that match the RegForbiddenUrl rule).

The correct solution to achieve the behaviour intended in the example looks a bit awkward and requires double maintenance of all known hostnames since Web Dispatcher does not support else clauses for its if conditions:

   if %{HTTP_HOST} !regimatch “” [and]
   if %{HTTP_HOST} !regimatch “” [and]
   if %{HTTP_HOST} !regimatch “”
     RegForbiddenUrl ^/.* –


Name-based virtual hosts require fewer resources (e.g., IP addresses) when used as identification criteria in a Web Dispatcher for a Multiple Systems scenario and should, therefore, be preferred over IP-based virtual hosts. The modification handler offers sufficient flexibility and functionality to define rules that can identify the correct target system, even if users type in the IP address instead of the hostname, or if the hostname is missing entirely (e.g., browser uses HTTP/1.0).

Further reading

Assigned Tags

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

      Hi Tobias

      Hello again, glad to find you here.

      one simple question from my side, how can I tell if icm/HTTP/mod_0 = PREFIX=/,FILE=action-rules.txt take effect or not´╝č

      I follow up your instructions but it seems no effect at all, and I couldn't find keyword IcrFindTargetSystem in the dev_webdisp file.

      please lighten me.



      Author's profile photo Tobias Winterhalter
      Tobias Winterhalter
      Blog Post Author

      Hi Ethan,

      In the Web Admin UI, click on Modification Handler in the menu on the left side. This will show you the currently active rules. If the list of rules is empty although you specified some rules in your text file, there was most likely a syntax error while parsing the file during Web Dispatcher startup. You should find ERROR lines in dev_webdisp showing more info about what happened.

      Best regards,


      Author's profile photo Raoul Shiro
      Raoul Shiro

      Hello Tobias,

      Thank you for the very informative post ; I was about to ask our Windows Administrator to create several IP based virtual hosts , when I discovered your blog and the alternative solution ; name based virtual hosts and usage of modification handlers.

      In our case though, we are using HTTPS  , more precisely SSL Termination  :

      Client ---> HTTPS ---> Webdipatcher ---->HTTP---> SAP Backends

      So according to your blog, it should be supported

      So imagine that the three SAP systems should be accessed as follow :




      I would need to ask for the creation of those three virtual hostnames, which must resolve by the DNS to the IP address of the Web Dispatcher host.

      In our case the sapwebdispather profile parameter is  as follows :

      icm/server_port_1 = PROT=HTTPS,PORT=443,TIMEOUT=30,PROCTIMEOUT=1800

      I am a bit confused by the rule file configuration, even if we use the HTTPS protocol do we still add the same filtering rules based on HTTP_HOST ? Or is there any additional configuration step for HTTPS ?

         if %{HTTP_HOST} regimatch ""

           SetHeader x-sap-webdisp-target-sid ECC [break]

         if %{HTTP_HOST} regimatch ""

           SetHeader x-sap-webdisp-target-sid CRM [break]

         if %{HTTP_HOST} regimatch ""

           SetHeader x-sap-webdisp-target-sid EP1 [break]

      Thank you very much for your attention

      Author's profile photo Tobias Winterhalter
      Tobias Winterhalter
      Blog Post Author

      Hello Raoul,

      The filtering rules remain the same, regardless of the protocol HTTP or HTTPS.

      HTTP_HOST is the name of the variable that contains the hostname of the request. You can find all variables in the "Using Variables" section of the documentation I quoted in the article (

      Best regards,


      Author's profile photo Mike Spry
      Mike Spry

      Hello Tobias,

      We want to use IP based virtual host definition with one web dispatcher in a SSL re-encryption scenario. How do you configure the web dispatcher to use different SSL certificates for their associated unique hostnames?

      For example, we currently have one web dispatcher and one hostname defined in the web dispatcher configuration using the following parameters.

      wdisp/ssl_certhost =


      If we add two additional virtual (IP) hostnames to web dispatcher configuration then how do we account for the new hostname SSL certificates?

      Additional hosts added are:



      Each of these new hostnames has a SSL certificate, how would one web dispatcher configuration account for this?

      Thank you for your help.

      -Mike Spry

      Author's profile photo Tobias Winterhalter
      Tobias Winterhalter
      Blog Post Author

      Hello Mike,

      With Web Dispatcher 7.2, you can use only one server certificate. You can either issue the certififcate to a wildcard host (*, or add additional hostnames as "Subject Alternative Names" (aka SAN certificate, google it). The latter is more secure.

      Now the good news: Web Dispatcher 7.4 added the feature of system specific SSL configurations. See SAP Note 1937653.

      In any case, it might be a good idea to update to Web Dispatcher 7.4 because in the very near future, it will offer a much easier built-in support for virtual hosts which will render my article entirely obsolete. I will update the article once the feature is available.



      Author's profile photo Former Member
      Former Member

      Correct me if I'm wrong but even having the latest patch level doesn't allow you to have per server port SSL server certificates. Configuration yes which is a great thing, but there is still the limitation of one SSL server certificate per Web Dispatcher.

      Author's profile photo Tobias Winterhalter
      Tobias Winterhalter
      Blog Post Author

      Oops, that is correct. The system specific SSL parameters are only relevant for the back-end connection, not for the front-end connection.

      So for the server certificate, the two options I described above remain the only ones.

      Sorry for the confusion, and thank you for pointing this out.

      Author's profile photo Former Member
      Former Member

      Hi Tobias,

      I am also interested in this name-based virtual hosts option.  My backend systems already exist and I am  not sure if I can use this as an option.

      I want to hit my Web Dispatcher using webdisp1, webdisp2, webdisp3 and then redirect those to multiple ABAP back-end systems and eventually a some JAVA systems.  I also have a selection of IP addresses I can use.

      I have done this on older versions of the SAP Web Dispatcher but it requires a separate installation for each backend and unique IP addresses.

      I couldn't understand how the Web Dispatcher routing would work in my scenario with existing back-end systems. I may need to add another URL to SSL Server Standard folder.  I would need to hide the URL string information in Internet Explorer.  Just thinking out loud here....

      really good information.


      Dan Mead

      Author's profile photo Former Member
      Former Member

      Hi Tobias,

      This configuration for Name based Virtual hosts is great and works like a charm.

      But is there any possibility of not showing the host name/port of the backend systems the web dispatcher is forwarding the requests to...

      The issue is that it simply forwards the request with the backend hostname/port shown on the browser after the redirect.

      Am i missing something? what else can I do in the mod rules without using some other reverse proxy/product?

      Thank you


      Author's profile photo Mauricio Zeledon
      Mauricio Zeledon

      Hello all,

      I have the following scenario:

      ASCS on one server, ERS on another server (HA configured for both). One primary app server and one additional app server (not HA for these).

      I need to allow users to access Fiori apps using one single URL. What would be the proper config for this? Every app server uses its own hostname. Also, I am configuring SSO using SAML20.

      Any ideas?