Virtual Host in WebSphere and Configuration Guide – Explained

What is Virtual Host and How to Configure in WebSphere Application Server (WAS)?

One of the very first terminologies you will hear in WAS Deployment is a virtual host. Many of you asked me about the virtual host and configuration guide so here I have explained following.

  • What is a virtual host?
  • How to create/configure?
  • How to change virtual host in existing deployed application?
  • Virtual host related errors
  • Best Practices

So, what is a Virtual host?

Virtual host means allowing multiple URL’s (ex –,,, washost:9443, on a single application through associated virtual host. This can be either IP-based or name-based. Virtual host configuration is done through WAS administrative console.

Using virtual host, you can also define the MIME types. In default WAS installation, you will have two virtual host admin_host & default_host, which you may use or can create the new one for your application. Let’s take a look at below illustration of a virtual host.


So now you know about the virtual host and next is to create & configure it.

Virtual host creation is done through WAS administrative console, located under Environment >> Virtual hosts. Let’s create one and name it – sample_hosts

  • Login into WAS Administrative Console
  • Go to Environment >> Virtual hosts
  • Click on New

You can see two inbuilt virtual hosts in above list which I mentioned above.


  • Enter the name – sample_hosts


  • Click on OK

So now you have a new virtual host and it’s time to configure it.

There are two types of configuration you can do and both configurations are located inside virtual host under “Additional Properties”.

Host Aliases: here you can enter DNS/Host/IP Name and Port, which will be allowed, to access the application using this virtual host.

  • Go to Environment >> Virtual hosts
  • Select the virtual host from the list
  • Click on Host Aliases
  • Click on New
  • Enter Host Name & Port
  • Click OK and save/review the configuration and here is what I created


MIME Types: here you can add/create/modify MIME types for your application. However, by default WAS would have more than 640+ MIME types created which will cover almost any type of application. This default list is created when you create any virtual host.

  • Go to Environment >> Virtual hosts
  • Select the virtual host from the list
  • Click on MIME Types
  • Click on New to create one. However, as I mentioned above most likely you don’t need to create, as almost all type of application will be covered with default lists.

So next is to change virtual host in deployed application

There might be a scenario where you got to segregate virtual host based on application. Here is how you can change the virtual host for any application.

  • Login into WAS administrative console
  • Go to applications>> Websphere enterprise applications
  • Select your application and click on Virtual hosts located under Web Module Properties
  • Select the desired virtual host and click on OK


  • Click on Review/Save the configuration. You must restart the JVM in order to get the virtual host reflected.

You might be interested to know virtual host configuration is stored in virtualhosts.xml. Location may differ from environment to environment so best way to find the exact location of virtualhosts.xml is: –

On UNIX environment

find / -name virtualhosts.xml

Through WAS Console

When you make any changes in the virtual host it will ask you to review/save. Click on Review and it will show you the path of virtualhosts where it will save the configuration.

Now the time to go through world famous WebSphere error related to the virtual host, which is most likely due to either not configured, or misconfiguration.

Error related to Virtual host

A WebGroup/Virtual Host to handle /test has not been defined SRVE0255E: A WebGroup/Virtual Host to handle localhost:8080 has not been defined.

If you are getting above error when you access application then you will learn in just a few minutes how to fix it.

Let’s take a look at error carefully. There are two things you got to look which I highlighted in red color.

Firstlocalhost has not been defined

The application is throwing an error because localhost doesn’t exist in Host Aliases of a respective virtual host. So quick fix is to add localhost in your virtual host.

This could be also when you have multiple virtual host and application is mapped to incorrect virtual host. So you got to review the configuration and ensure localhost exist in requested virtual host.

Second8080 port number

Most of the time you will configure the virtual host with URL and default Http/https port, which is 80 or 443. However, if you want to access the application directly (bypassing web server) by using JVM and port you need to enter IP/Host and Port details in Host Aliases.

So to fix this – you got to ensure localhost:8080 is added to a virtual host, which is mapped to respective application.

Last section of this article – Best practices of using Virtual Host in WAS environment.

Every application is unique and one configuration may not work well in other. However, there are some rules you may follow which has helped me and hope you too.

  • If you are having multiple applications in single cell, you may consider using a separate virtual host for each or at least for a group of applications.
  • Take a backup of WebSphere configuration before you make any changes so if something goes wrong you may recover to original state without damage.
  • Restart mapped JVM after making changes to virtual host so configuration is reflected.
  • Propagate (if managed web server) & Generate Web Server plugin and restart Web Server to get the configuration reflected.
  • Don’t put * in Host Aliases as this means any URL is allowed which may lead to a security loophole.

I hope you have the better understanding about Virtual Host in IBM WebSphere Application Server now. that’s all for today and I hope you like it.

11 thoughts on “Virtual Host in WebSphere and Configuration Guide – Explained”

  1. Hi Chandan,

    After configuring the virtual host and activating the ssl, if it try to access the URL https://hostname/maximo I am getting internal server error for the primary url and /maximo not found on this server for the child server url’s. Could you please guide me on this.

  2. Hi Chandan,

    Is it possible to create a new virtualhost for a portal site hosted in a cluster in order to hit a specific node directly without relying on changing the cookie to access that node for troubleshoot needs?

    Thank you


    I am new to WAS, your post helps me a lot in understanding WAS, please post more errors and the respective troubleshooting steps, keep up the good work.

Leave a Comment

Your email address will not be published. Required fields are marked *