Sun Java System Web Server 6.1 SP9 Administrator's Guide

Virtual Servers Overview

When you use virtual servers you can offer to companies or individuals domain names, IP addresses, and some server monitoring capabilities with a single installed server. For the users, it is almost as if they have their own web servers, though you provide the hardware and basic web server maintenance.

Note –

If you are not using virtual servers, you still use the items in the Class Manager to configure content, programs, and other features for your web server instance. When you install the web server, a default virtual server for the instance is created. You manage the content and services for this default virtual server using the virtual server user interface.

To set up virtual servers, you need to set up the following:

The settings for virtual servers are stored in the server.xml file, found in the server_root/server_ID/config directory. You do not need to edit this file to use virtual servers, but you can. If you would like to learn more about this file and how to edit it, see the Sun Java System Web Server 6.1 SP9 Administrator’s Configuration File Reference.

This section includes the following topics:

Multiple Server Instances

In past releases of the Sun Java System Web Server, unique configuration information for virtual servers was not very flexible. Quite often users created separate server instances in order to have a straightforward way to have servers with separate configuration information. The 6.0 version release of Sun Java System Web Server introduced separate configuration information for each virtual server class. Multiple server instances are still supported, but if your goal is to have many servers with separate configuration information, virtual servers are a better choice.

Virtual Server Classes

Virtual servers are grouped into classes. Using classes you can configure similar virtual servers at the same time, so you don’t have to configure each one separately. Though all virtual servers in a class share the same basic configuration information, you can also set variables and change configuration per virtual server. If you do not want virtual servers to share configuration information, you can create a single virtual server for every virtual server class. However, if your virtual servers share similar properties, you can group them in a class and configure them together.

For example, if you work for an Internet Service Provider (ISP) and want to provide different levels of hosting for different customers at different prices, you can set up several classes of virtual servers for your customers. You might enable Java servlets and JSPs for one class of virtual servers, and disable Java servlets and JSPs for a less expensive class of virtual servers.

You create a class of virtual servers by naming it and setting up a document root, where all virtual servers belonging to the class will have their document roots by default. You can use the $id variable so that each virtual server within the class will have a separate document root within the class’ document root. For more information, see Document Root.

After creating the class of virtual servers, you associate services with it. You can turn on or configure the following types of services for a class of virtual servers:

The obj.conf File

All virtual servers in a class share an obj.conf file, which stores information about the virtual server class. Some of that information is stored in variables, so that individual virtual servers can have specific variable values substituted on the fly.

For more information about obj.conf and variables, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide. For more information on using variables in the user interface, see Using Variables.

Virtual Servers in a Class

A virtual server that belongs to a class is called a member of that class. Some virtual server settings are configured for all virtual servers in a class, and some are configured individually. These settings are configured on the Class Manager’s Virtual Servers tab. For more information, see Chapter 15, Creating and Configuring Virtual Servers.

The Default Class

When you install Sun Java System Web Server, the installer automatically creates a single class, called defaultclass. It contains one virtual server member, by default, for your server instance. You can add additional virtual servers to the default class, but you cannot delete your default virtual server from the class. You also cannot delete the default class.

Listen Sockets

Connections between the server and clients happen on a listen socket. Each listen socket you create has an IP address, a port number, a server name, and a default virtual server. If you want a listen socket to listen on all configured IP addresses on a given port for a machine, use, any, ANY, or INADDR_ANY for the IP address.

When you install Sun Java System Web Server, one listen socket, ls1, is created automatically. This listen socket uses the IP address and the port number you specified as your HTTP server port number during installation (the default is 80). You cannot delete the default listen socket. If you are not using virtual servers, this one listen socket is sufficient. However, if you are using virtual servers, you may want to create multiple listen sockets for your virtual servers.

Since a listen socket is a combination of IP address and port number, you can have multiple listen sockets with the same IP address and different port numbers, or with different IP addresses and the same port number. For example, you could have and Additionally, you could have and, as long as your machine is configured to respond to both these addresses.

In addition, you specify the number of acceptor threads (sometimes called accept threads) in the listen socket. Acceptor threads are threads that wait for connections. The threads accept connections and put them in a queue where they are then picked up by worker threads. Ideally, you want to have enough accept threads so that there is always one available when a new request comes in, but few enough so that they do not provide too much of a burden on the system. The default value is 1. A good rule is to have one accept thread per CPU on your system. You can adjust this value if you find performance suffering.

Virtual Servers

To create a virtual server you must first decide which class you want it to belong to. Next you need to decide what kind of virtual server you want. To create a virtual server, all you need to specify is a virtual server ID and one or more URL hosts.

This section includes the following topics:

Types of Virtual Servers

Prior to the version 6.0 release of Sun Java System Web Server, there were two kinds of virtual servers: hardware and software. Hardware virtual servers had unique IP addresses associated with them. Software virtual servers did not have unique IP addresses, but instead had unique URL hosts.

In Sun Java System Web Server 6.0 and Sun Java System Web Server 6.1, these concepts are no longer quite accurate. All virtual servers have a URL host specified. However, the virtual server may also be associated with an IP address based on its listen socket.

When a new request comes in, the server determines which virtual server to send it to based on the IP address or the value in the Host header. It evaluates the IP address first. For more information, see Virtual Server Selection for Request Processing.

IP-Address-Based Virtual Servers

To have multiple IP addresses on a single computer, you must map them through the operating system or provide additional cards. To set up multiple IP addresses through the operating system, use the Network Control Panel (Windows) or the ifconfig utility (UNIX/Linux).

Note –

Directions for using ifconfig vary from platform to platform. Consult your operating system documentation for more information.

Typically you create an IP-address-based virtual server by creating a listen socket that listens on a specific IP address. The listen socket’s default virtual server is an IP-address-based virtual server. For more information on ways to deploy virtual servers, see Deploying Virtual Servers.

URL-Host-Based Virtual Servers

You can set up URL-host-based virtual servers by giving them unique URL hosts. The contents of the Host request header directs the server to the correct virtual server.

For example, if you want to set up virtual servers for customers aaa, bbb, and ccc) so that each customer can have an individual domain name, you first configure DNS to recognize that each customer’s URL,,, , resolves to the IP address of the listen socket you are using. You then set the URL hosts for each virtual server to the correct setting (for example,

Because URL-Host-based virtual servers use the Host request header to direct the user to the correct page, not all client software works with them. Older client software that does not support the HTTP Host header does not work. These clients will receive the default virtual server for the listen socket.

Default Virtual Server

URL-Host-based virtual servers are selected using the Host request header. If the end user’s browser does not send the Host header, or if the server cannot find the specified Host header, the default virtual server services the request.

The default virtual server is set by listen socket. You specify a default virtual server when you create a listen socket. You can always change the default virtual server.

Virtual Server Selection for Request Processing

Before the server can process a request, it must accept the request via a listen socket, then direct the request to the correct virtual server.

A virtual server is then selected as follows:

If a virtual server is configured to an SSL listen socket, its URL host is checked against the subject pattern of the certificate at server startup, and a warning is generated and written to the error log if they don’t match.

After the virtual server is determined, the server executes the obj.conf file for the virtual server class to which the virtual server belongs. For details about how the server decides which directives to execute in obj.conf, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.

Document Root

The primary document directory or document root is the central directory that contains all the virtual server’s files to make available to remote clients.

The document root directory provides an easy way to restrict access to the files on a virtual server. It also makes it easy to move documents to a new directory (perhaps on a different disk) without changing any of the URLs because the paths specified in the URLs are relative to the primary document directory.

For example, if your document directory is C:\sun\servers\docs, a request such as tells the server to look for the file in C:\sun\servers\docs\products\info.html. If you change the document root (that is, you move all the files and subdirectories), you only have to change the document root that the virtual server uses, instead of mapping all URLs to the new directory or somehow telling clients to look in the new directory.

When you install the Sun Java System Web Server, you designate a document root for your web server instance. That becomes the document root for the default class. You can change that directory at the class level or override it at the individual virtual server level.

When you add a class, you also need to specify a document directory. That directory is an absolute path. However, if you simply enter an absolute path, the document roots for all virtual servers belonging to the class default to the same directory. If you include the variable $id at the end of your document root absolute path, every virtual server has a default document root of class_doc_root/virtual_server_ID. For example, if your class’ document directory is /sun/servers/docs/$id, the default document directory for a virtual server vs1 that belongs to the class is /sun/servers/docs/vs1.

For more information on variables, see Using Variables.

You can also override the class’ default document directory at the individual virtual server level.

Log Files

When you create a new virtual server, by default the log file is the same log file as the server instance. In most cases you will want each individual virtual server to have its own log file. To set this up, you can change the log path for each virtual server.

For more information, see Configuring Virtual Server Log Settings.

Migrating Virtual Servers from a Previous Release

If you used virtual servers in the 4.1 version of iPlanet Web Server, you can migrate them to the current release using the migration tool. For more information, see the Sun Java System Web Server 6.1 SP9 Installation and Migration Guide.