This chapter explains how to set up and administer virtual servers using your Sun Java System Web Server.
This chapter contains the following sections:
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.
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.
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 SP12 Administrator’s Configuration File Reference.
This section includes the following topics:
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 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:
Programs, see Chapter 16, Extending Your Server With Programs.
Content Management, see Chapter 17, Content Management.
Configuration Styes, see Chapter 18, Applying Configuration Styles.
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 SP12 NSAPI Programmer’s Guide. For more information on using variables in the user interface, see Using Variables.
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.
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.
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 0.0.0.0, 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 0.0.0.0 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 18.104.22.168:81 and 22.214.171.124:82. Additionally, you could have 126.96.36.199:81 and 188.8.131.52:81, 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.
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:
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.
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).
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.
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, www.aaa.com, www.bbb.com, www.ccc.com , 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, www.aaa.com).
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.
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.
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 the listen socket is configured to only a default virtual server, that virtual server is selected.
If the listen socket has more than one virtual server configured to it, the request Host header is matched to the URL host of a virtual server. If no Host header is present or no URL host matches, the default virtual server for the connection group is selected.
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 SP12 NSAPI Programmer’s Guide.
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 http://www.sun.com/products/info.html 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.
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.
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 SP12 Installation and Migration Guide.
Sun Java System Web Server has many features, such as SSL and access control, that you can use with virtual servers. Many of these features involve configuration for all servers, for a server instance, for a class of virtual servers, or an individual virtual server. The following sections describe the features and provide information on where to look for more information.
This section includes the following topics:
If you want to use SSL on a virtual server, you use an IP-address-based virtual server. The customary port is 443. It is difficult to use SSL on a URL-host-based virtual server because Sun Java System Web Server must read the request before determining which URL host to send the request to. Once the server reads the request, the initial handshake, where security information is exchanged, has already happened.
The only exception is when URL-Host-based virtual servers all have the same SSL configuration, including the same server certificate, using “wildcard certificates.” For more information, see Chapter 7, Using Certificates and Keys.
One way to implement SSL with virtual servers is to have two listen sockets, one using SSL and listening to port 443, and one that is not using SSL. A user would typically access the virtual server through the non-SSL listen socket. When the need to have secure transactions arises, users could click a button on the web page to start initiating secure transactions. After that, the requests go through the secure listen socket.
Because SSL transactions are much slower than non-SSL transactions, this design limits the SSL transactions to only the ones that are necessary. Faster, non-SSL connections are used the rest of the time.
For more information on setting up and using security with your Sun Java System Web Server and virtual servers, see Chapter 7, Using Certificates and Keys . For a diagram of a sample SSL configuration with virtual servers, see Example 2: Secure Server.
With virtual servers you have the ability to set up access control on a per virtual server basis. You can even configure it so that each virtual server can have user and group authentication using an LDAP database. For more information, see Controlling Access for Virtual Servers.
For more information on setting up and using CGIs, see Installing CGI Programs.
Configuration styles are an easy way to apply a set of options to specific files or directories that your various virtual servers maintain. For more information on using configuration styles see Chapter 18, Applying Configuration Styles.
The user interface for administering virtual servers has three parts:
The Server Manager contains settings that affect the server as a whole (or all virtual servers).
The Class Manager contains settings that affect a single class and the virtual servers within the class.
The Virtual Server Manager contains settings for an individual virtual server.
In addition, a user interface for end-users who have an individual virtual server is available. For more information, see Allowing Users to Monitor Individual Virtual Servers.
This section includes the following topics:
To access the Class Manager follow these steps
From the Server Manager, click the Virtual Server Class Tab.
Click Manage Classes.
Choose a class and click Manage.
You can also click the class name in the tree view of the server, or click the Class Manager button link in the upper right corner of the Server Manager.
From the Class Manager, click the Virtual Server Tab.
Click Manage Virtual Servers.
Choose a virtual server, and click Manage.
You can also click the virtual server name in the tree view of the server.
You can use a command line utility, HttpServerAdmin, to perform the same virtual server tasks as you can perform using the user interface. For more information on the command line utility HttpServerAdmin, see Appendix A, Command Line Utilities.
You can use variables to give virtual-server specific values for a class without having to define each value individually. A variable is defined in the obj.conf file. You can define your own variables, but the user interface will not recognize them. The variable that is most useful in the user interface is the variable $id, which represents the ID of the virtual server. Whenever you enter this variable, the server substitutes the value for the individual virtual server ID.
There are a few other variables, such as $accesslog (the path to each virtual server’s access log) and $docroot (the path to each virtual server’s document root), that you may occasionally see, but $id is the only one you should need to enter into a field.
For more information on variables, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.
Dynamic reconfiguration allows you to make configuration changes to a live web server without having to stop and restart the web server for the changes to take effect. You can dynamically change all configuration settings and attributes in server.xml and its associated files without restarting the server. So any changes that you make within the virtual server user interface can by applied without restarting the server. You can dynamically reconfigure your server after changes using the reconfiguration script or the user interface.
On UNIX platforms the dynamic reconfiguration script is a shell script named ’reconfig’ located in each instance’s directory. There are no commandline arguments to this script. You can run the reconfiguration script by simply typing ’reconfig’ from the server instance’s directory.
On Windows, the dynamic reconfiguration script is a batch file called ’reconfig.bat located in each instance’s directory. There are no command line arguments. You can run the reconfiguration script by simply typing ’reconfig’ or ’reconfig.bat’ from the server instance’s directory.
When run, this script initiates a dynamic reconfiguration of the server, similar to the user interface, and displays the server messages related to reconfiguration.
To access the dynamic reconfiguration screen, click the Apply link found in the upper right corner of the Server Manager, Class Manager, and Virtual Server Manager pages, then click the Load Configuration Files button on the Apply Changes page. If there are errors in installing the new configuration, the previous configuration is restored.
Create a listen socket
Create a class of virtual servers
Configure the services for the class
Create the virtual servers in a virtual server class
Configure virtual servers
Please note that you must enter an existing virtual server in the default virtual server field when you create a listen socket. You can use the virtual server created when you installed the server, and then go back and change it after you’ve created additional virtual servers.
To create a listen socket, perform the following steps:
From the Server Manager, click the Preferences tab.
Click Add Listen Socket.
Fill in the fields.
Listen sockets must have a unique combination of port number and IP address. You can use either IPV4 or IPV6 addresses. If you want to create a listen socket for IP-address-based virtual servers, the IP address must be 0.0.0.0, ANY, any or INADDR_ANY, meaning it listens on all IP addresses on that port.
You can also enable security (SSL) for this listen socket.
The Server Name field specifies the host name in the URLs the server sends to the client. This field affects URLs the server automatically generates. It does not affect the URLs for directories and files stored in the server. This name should be the alias name if your server uses an alias.
From the Server Manager, click the Virtual Server Class tab.
Click Add Class.
Name the class.
Insert a document root for the class.
The directory must already exist. All virtual servers for this class will have document roots in this absolute path, unless you specify otherwise. If you use /$id as the last part of the path, a document root folder named for the virtual server ID is automatically created within the class’ document root path.
Once you have created a class of virtual servers, choose the services associated with the class. For more information, see Chapter 17, Content Management.
From the Server Manager, click the Virtual Server Class tab.
Click Edit Classes.
From the drop-down list next to the class you want, choose Edit or Delete.
You cannot delete the default class.
Use the Document Root field to change to absolute path to the class’ default document root.
The document roots for virtual servers in this class are created within this directory by default.
Enter On in the Accept Language field if you wish this class of virtual servers to use accept language header parsing.
The default is Off.
If you want to change the CGI defaults associated with a class, click Advanced.
A window with the CGI defaults appears. Edit the fields and click OK to return to the Edit a Class window. The Reset button rolls back your changes.
Click OK. The class is changed or deleted.
Some of the characteristics that differentiate one class of virtual servers from another are the services that are enabled for that class of virtual servers. For example, one class of virtual servers might have CGIs enabled while another doesn’t. For more information on setting up services, see Chapter 17, Content Management.
Once you have set up a virtual server class, you can create a virtual server. Because virtual servers are members of a particular virtual server class, you create virtual servers on the Class Manager.
For more information, see Creating a Virtual Server.
You can override some class settings at the virtual server level and also configure additional settings. You configure these settings in the Class Manager.
For more information, see Creating a Virtual Server.
A special user interface exists for the administrators of individual virtual servers that allows them to view settings for their virtual servers and to view their access and error logs. For example, if you have an intranet with three virtual servers for three different departments, each department can view their settings and log files individually.
For security reasons, this administration user interface is on a separate port from either the administration server port or the web server instance port.
This user interface runs on a virtual server within the administration server. This virtual server is set up by default and is called useradmin. You must set up a listen socket in the administration server that is separate from the listen socket the administration server runs on, so that people can access the virtual server administration user interface without having access to your administration server port.
The following figure, Allowing Users to Monitor Individual Virtual Servers, shows the administrators of individual virtual servers accessing the useradmin virtual server in order to access the information for their virtual servers.
When you turn on a virtual server, if you edit certain settings in the Administration Server’s /config/server.xml file, users can administer it, through the following URL:
The server instance doesn’t include the “https” portion of the server instance name.
To determine the virtual server ID, look up the server.xml file of the server instance.
The following figure shows the user interface that the end users see:
After you install Sun Java System Web Server 6.1, you will find that the server_root/https-admserv/config/server.xml file contains certain commented-out entries that create:
a default listen socket for a virtual server called useradmin.
a virtual server class for the virtual server.
To set up useradmin, all you need to do is to uncomment these entries.
Create a new listen socket that runs a port separate from the port that the administration server uses.
For example, if your administration server runs on port 8888, this new listen socket must have a different port number. Using a different listen socket helps safeguard your administration server.
For security reasons, you cannot add this listen socket through the user interface. Instead, you add it in the administration server’s server.xml file.
Open the administration server’s server.xml file, found at server_root/https-admserv/config/server.xml.
Uncomment the commented lines containing default values for the LS, VSCLASS, and VS elements. Example:
<!-- <LS id="ls2" port="9999" servername="plaza" defaultvs="useradmin"> --> <!-- <VSCLASS id="userclass" objectfile="userclass.obj.conf"> <VS id="useradmin" connections="ls2" mime="mime1" aclids="acl1" urlhosts="plaza"> <PROPERTY name="docroot" value="/export1/wsinst/docs"> <USERDB id="default"> <WEBAPP uri="/user-app" path="/export1/wsinst/bin/https/webapps/user-app"> </VS> </VSCLASS> -->
This action will enable useradmin, created on a separate port for security reasons.
Save your changes to server.xml.
Apply the changes by restarting the Administration Server.
For any virtual server in any server instance, you should now be able to access the administrator UI by using the following URL:
To protect the virtual server administration from unauthorized users, you can set up ACLs. Because the URI for each virtual server is unique, you can set access so that only the correct administrator can access the settings for a virtual server.
For more information, see Chapter 10, Controlling Access to Your Server.”
Each virtual server can have its own log files. By default, all virtual servers share the log file of the server instance. If you allow users to view their log files, in most cases you should change the log file settings so that each virtual server has its own access and error log.
For more information, see Configuring Virtual Server Log Settings.
Sun Java System Web Server’s virtual server architecture is very flexible. A server instance can have any number of secure and non-secure listen socket. You can have both IP-address-based and URL-host-based virtual servers.
In addition, you can group virtual servers with similar settings into any number of virtual server classes. All virtual servers in a virtual server class share the same request processing instructions in obj.conf.
Every virtual server can (but does not have to) have its own list of ACLs, its own mime.types file, and its own set of Java Web Applications.
This design gives you maximum flexibility to configure the server for a variety of applications. The following examples discuss some of the possible configurations available for Sun Java System Web Server.
After a new installation of the Sun Java System Web Server, you have one server instance. This server instance has just one listen socket listening on port 80 (or whatever you selected at installation) of any IP address to which your computer is configured.
Some mechanism in your local network establishes a name-to-address mapping for each of the addresses to which your computer is configured. In the following example, the computer has two network interfaces: the loopback interface (the interface that exists even without a network card) on address 127.0.0.1, and an ethernet interface on address 10.0.0.1.
The name example.com is mapped to 10.0.0.1 via DNS. The listen socket is configured to listen on port 80 on any address to which that machine is configured ("ANY:80" or "0.0.0.0:80").
In this configuration, connections to the following reach the server and are served by virtual server VS1
http://127.0.0.1/ (initiated on example.com)
http://localhost/ (initiated on example.com)
Use this configuration for traditional web server use. You do not need to add additional virtual servers or listen sockets. You configure the settings of the server by changing the settings for defaultclass (VS1 is a member of defaultclass), and the VS1 itself.
If you want to use SSL in the default configuration, you can simply change the listen socket to secure mode. Just as you set security in previous versions of the Sun Java System Web Server.
You can also add a new secure listen socket configured to ANY:443 and associate VS1 to the new listen socket. The virtual server now has listen sockets, one that uses SSL, and one that doesn’t. Now your server will serve the same content both with and without SSL, i.e. http://example.com/ and https://example.com/ deliver the same content.
A more complex configuration of the Sun Java System Web Server is one in which the server hosts a few virtual servers for an intranet deployment. For example, you have three internal sites where employees can look up other users’ phone numbers, look at maps of the campus, and track the status of their requests to the Information Services department. Previously (in this example), these sites were hosted on three different computers that had the names phone.example.com, maps.example.com and is.example.com mapped to them.
To minimize hardware and administrative overhead, you want to consolidate all three sites into one web server living on the machine example.com. You could set this up in two ways: using URL-host-based virtual servers or using separate listen sockets. Both have their distinct advantages and disadvantages.
While URL-host-based virtual servers are easy to set up, they have the following disadvantages:
Supporting SSL in this configuration requires non-standard setup using wildcard certificates. For more information see Chapter 5, J2SE-based Security for Web Container and Web Applications.
URL-host-based virtual servers don’t work with legacy HTTP clients
You could also set up the IP-address-based configuration with one listen socket per address:
The advantages to IP-address-based virtual servers are:
They work with older clients that do not support the HTTP/1.1 Host header.
Providing SSL support is straightforward.
The disadvantages are:
They require configuration changes on the host computer (configuration of real or virtual network interfaces)
They don’t scale to configurations with thousands of virtual servers
Both configurations require setting up name-to-address mappings for the three names. In the IP-address-based configuration, each name maps to a different address. The host machine must be set up to receive connections on all these addresses. In the URL-host-based configuration, all names can map to the same address, the one the machine had originally.
The configuration with multiple listen sockets could give you a minimal performance gain because the server does not have to find out the address the request came in on. However, using multiple listen sockets also results in additional overhead (memory and scheduling) because of the additional acceptor threads.
Mass hosting is a configuration in which you enable several low-traffic virtual servers. For example, an ISP that hosts many low-traffic personal home pages would fall into this category.
The virtual servers are usually URL-host-based and are in one of multiple virtual server classes, depending on the level of service provided. For example, you could have one class that allows only static content, and another one that allows static content plus CGIs.
Notice that the virtual server installed when you installed the server, VS1, still exists in defaultclass.