Table of Contents
This chapter describes the basic concepts, rules, and configurations of virtual hosts.
Virtual hosts allow different web applications to be mapped with the same URL based on the Internet domain name. In other words, two or more domain names (for example, “www1.foo.com” and “www2.foo.com”) can exist on a single web engine and use different web contexts.
Note
From the perspective of web engines, web contexts and web applications are the same.
This section describes the purpose and rules of virtual hosts and how ServletContext objects are related to virtual hosts.
Purpose
Virtual hosts allows mapping of different web applications to the same URL based on the domain name mapped to the virtual host. This allows service providers to provide multiple web sites on a single web engine. This is similar to the function that provides a virtual host through the Host header of HTTP 1.1.
A virtual host is a group of web contexts that can be configured on a web engine. Refer to [Figure 1.1] for more information about where the virtual host is positioned as a web engine component.
The following diagram shows how virtual hosts are used depending on their purposes.
In the previous example, it appears that the same context path (/service) is being accessed through two different addresses. There is one server, but from the perspective of the clients, there appear to be two servers, "www.foo.com" and "www.bar.com".
The service provider can provide different services with the same "/service" address pattern. In the previous example, "www.foo.com" provides services in Korean and "www.bar.com" provides services in English.
Rules
The following rules apply when creating virtual hosts.
-
A virtual host must have a virtual host name
The name is used to refer to the virtual host in the configuration file and must be unique within the web engine.
-
One or more domain names and IP addresses can be mapped to a single virtual host
JEUS calls this a host name. Note that the same host name cannot be mapped to different virtual hosts.
-
Web contexts with the same name cannot be deployed to different virtual hosts.
Note
The Servlet standard state that a same web context cannot be shared by different virtual hosts.
-
Different web contexts with the same path can be deployed on different virtual hosts, but those with the same path cannot exist on the same virtual host.
The web context name is the application or module name that is defined in the Java EE standard. The path is the context root or the context path that is defined in the web application. The web context names are managed for the purpose of deployment, and the web engine manages the context paths.
JEUS web engines have a default virtual host. When deploying a web context, if a virtual host is not set, the web context will be deployed to the default virtual host. The name of the default virtual host is 'DEFAULT_HOME'. This is a reserved word that cannot be used as another virtual host name.
In the Servlet API, the javax.servlet.ServletContext.getContext(String contextPath) method returns the ServletContext object that is located in the "contextPath". This method returns the ServletContext that exists on the virtual host to which the ServletContext belongs.
If the object does not exist on the virtual host, the default virtual host will be searched for.
This section describes how to map URLs to web contexts on a virtual host.
The following example shows the relationships between a web engine, virtual hosts, and web contexts.
The following describes the virtual hosts and web contexts that are mapped to URLs based on the previous figure, [Figure 5.2].
-
http://www.foo.com/ctx1/test.jsp
Matching virtual host A Matching web context name ctx1 -
http://www.foo.com/ctx2/test.jsp
Matching virtual host A Matching web context name ctx2 -
http://www.bar.com/ctx1/
Matching virtual host B Matching web context name ctx1-1 -
http://www.bar2.com/ctx1/test.jsp
Matching virtual host C Matching web context name None (404 Not Found) -
http://www.foo2.com/ctx2/
Matching virtual host C Matching web context ctx2-2
Note
Web context name and context path have different concepts. In general, they have the same value, but they are different when the services are distinguished by virtual host as in the previous example.
URLs are matched in the following order.
-
Match the host header domain name and port string with all registered virtual hosts. If there is a matching virtual host, the web context is searched within the virtual host.
Note
Port information in the format of "IP:Port" can be mapped to a host name set in a virtual host. If port information exists, entire host headers (including ports) are matched.
-
If a web context cannot be found, search within the default virtual host.
-
If the web context does not exist in the default virtual host, a 404 Not Found error is thrown.
Virtual hosts can be added, modified, and deleted in WebAdmin or the console tool.
Note
In the configuration examples of this section, "A", "B", and "C" are used as the host names for convenience. Use meaningful names in the production environment.
Virtual hosts can be added in WebAdmin or the console tool.
Using WebAdmin
The following shows how to add virtual hosts in WebAdmin.
-
Click [Servers] from the left menu to go to the list of servers. Click on a server to go to the server configuration page. Go to the [Engine] > [Web Engine] > [Virtual Host] tab on the configuration page.
-
Click [Lock & Edit] to change to configuration mode.
-
Click [Add] to add a virtual host, and click [OK]. The following diagram shows how to configure a virtual host named virtual_host1.
Item Description Virtual Host Name Name that is used internally to refer to the virtual host.
"DEFAULT_HOST" is a reserved word and cannot be used.
Host Name Multiple tags that contain domain names or IP addresses. Properties Properties can be applied by virtual hosts. The properties defined in JEUS can be applied. For more information, refer to JEUS Reference Book. "1.6. Web Engine Properties". Encoding Encoding for each virtual host. For more information, refer to "1.6.5. Encoding". Cookie policy Cookie policy for each virtual host. For more information, refer to "1.6.8. Cookie Policy". -
After completing the configuration, click [Apply Changes] to apply the changes.
-
The following shows the result of adding the three virtual hosts.
Using the Console Tool
To add virtual hosts using the console tool, execute the add-virtual-host command as in the following. Refer toJEUS Reference Book. "4.2.8.7. add-virtual-host" for more information about the command.
add-virtual-host [-cluster <cluster-name> | -server <server-name>] [-f, --forceLock] <virtual-host-name> -list <host-name-list>
Virtual hosts can be modified in WebAdmin or the console tool.
Using WebAdmin
The following shows how to add virtual hosts in WebAdmin.
-
Click [Servers] from the left menu to go to the list of servers. Click on a server to go to the server configuration page. Go to the [Engine] > [Web Engine] > [Virtual Host] tab on the configuration page.
Click on the virtual host name to modify from the list of virtual hosts. (Refer to [Figure 5.5] )
-
Click [Lock & Edit] to change to configuration mode.
-
Configure items on the Virtual Host configuration page.
-
Access logs can be configured for virtual hosts in the Access Log tab. Refer to Section 1.6.10, “Configuring Access Logs by Virtual Host” for more information. After changing the configuration, click [OK].
-
After completing the configurations, click [Apply Changes] to apply the changes.
-
The following result is displayed. The server must be restarted to apply the changes.
Using the Console Tool
To modify virtual hosts using the console tool, execute the modify-virtual-host command. For more information about the command, refer to JEUS Reference Book. "4.2.8.17. modify-virtual-host".
modify-virtual-host [-cluster <cluster-name> | -server <server-name>] [-f, --forceLock] <virtual-host-name> [-aluph <access-log-use-parent-handler (true/false)>| -alf <access-log-format> | -aluse <use-access-log (true/false)> | -alhnl <access-log-enable-host-name-lookup> | -alext <access-log-excluded-extensions>] [-hnrm <host-name> | -hnadd <host-name>] [-ast <attach-stacktrace-on-error>]
WebAdmin or the console tool can be used to delete virtual hosts.
Using WebAdmin
The following shows how to delete a virtual host in WebAdmin.
-
Click [Servers] from the left menu to go to the list of servers. Click on a server to go to the server configuration page. Go to the [Engine] > [Web Engine] > [Virtual Host] tab on the configuration page.
Click [Delete] next to the virtual host from the virtual host list to delete it. (Refer to [Figure 5.5])
-
After the virtual host is deleted successfully, the virtual host will be removed from the list and a the following message will be displayed.
-
After completing the configuration, click [Apply Changes] to apply the changes.
Note
If there are applications that are connected to the virtual host (if there are applications that are deployed using the virtual host as the target), the virtual host will not be deleted. When this happens, the connected target must be deleted from the application to delete the virtual host. Refer to JEUS Applications & Deployment Guide. "4.3.9. Removing a Target Server of Running Applications" for more information about deleting web application targets.
Using the Console Tool
To delete virtual hosts using the console tool, execute the remove-virtual-host command as in the following. For more information about the command, refer to JEUS Reference Book. "4.2.8.28. remove-virtual-host".
remove-virtual-host [-cluster <cluster-name> | -server <server-name>] [-f,--forceLock] <virtual-host-name>