Chapter 17 Configuring the HTTP Service

This chapter describes how to configure virtual servers and HTTP listeners for the HTTP service component of the Application Server.

About the HTTP Service

What Is the HTTP Service?

Virtual Servers

HTTP Listeners

What Is the HTTP Service?

The HTTP service is the component of the Application Server that provides facilities for deploying web applications and for making deployed web applications accessible by HTTP clients. (See "Deploying a Web Application".) These facilities are provided by means of two kinds of related objects, virtual servers and HTTP listeners.

Virtual Servers

A virtual server, sometimes called a virtual host, is an object that allows the same physical server to host multiple Internet domain names. All virtual servers hosted on the same physical server share the Internet Protocol (IP) address of that physical server. A virtual server associates a domain name for a server (such as www.aaa.com) with the particular server on which the Application Server is running.

Note: Do not confuse an Internet domain with the administrative domain of the Application Server.

Assume also that www.aaa.com, www.bbb.com, and www.ccc.com have web modules web1, web2, and web3, respectively, associated with them.

The first URL is mapped to virtual host www.aaa.com, the second URL is mapped to virtual host www.bbb.com, and the third is mapped to virtual host www.ccc.com.

On the other hand, the following URL results in a 404 return code, because web3 isn’t registered with www.bbb.com:

For this mapping to work, make sure that www.aaa.com, www.bbb.com, and www.ccc.com all resolve to your physical server’s IP address. They need to be registered with the DNS server for your network. In addition, on a UNIX system, add these domains to your /etc/hosts file (if the setting for hosts in your /etc/nsswitch.conf file includes files).

When the Application Server is started, it starts the following virtual servers automatically:

A virtual server named server, which hosts all user-defined web modules

A virtual server named __asadmin, which hosts all administration-related web modules (specifically, the Admin Console). This server is restricted; you cannot deploy web modules to this virtual server.

For development, testing, and deployment of web services in a non-production environment, server is often the only virtual server required. In a production environment, additional virtual servers provide hosting facilities for users and customers so that each appears to have its own web server, even though there is only one physical server.

HTTP Listeners

Each virtual server provides connections between the server and clients through one or more HTTP listeners. Each HTTP listener is a listen socket that has an IP address, a port number, a server name, and a default virtual server.

HTTP listeners must have a unique combination of port number and IP address. For example, an HTTP listener can listen on all configured IP addresses on a given port for a machine by specifying the IP address 0.0.0.0. Alternatively, the HTTP listener can specify a unique IP address for each listener, but use the same port.

Since an HTTP listener is a combination of IP address and port number, you can have multiple HTTP listeners with the same IP address and different port numbers (for example, 1.1.1.1:8081 and 1.1.1.1:8082), or with different IP addresses and the same port number (for example, 1.1.1.1:8081 and 1.2.3.4:8081, if your machine was configured to respond to both these addresses).

However, if an HTTP listener uses the 0.0.0.0 IP address, which listens on all IP addresses on a port, you cannot create HTTP listeners for additional IP addresses that listen on the same port for a specific IP address. For example, if an HTTP listener uses 0.0.0.0:8080 (all IP addresses on port 8080), another HTTP listener cannot use 1.2.3.4:8080.

Because the system running the Application Server typically has access to only one IP address, HTTP listeners typically use the 0.0.0.0 IP address and different port numbers, with each port number serving a different purpose. If the system does have access to more than one IP address, each address can serve a different purpose.

By default, when the Application Server starts, it has the following HTTP listeners:

Two HTTP listeners named http-listener-1 and http-listener-2, associated with the virtual server named server. The listener named http-listener-1 does not have security enabled; http-listener-2 has security enabled.

An HTTP listener named admin-listener, associated with the virtual server named __asadmin. This listener has security enabled.

All these listeners use the IP address 0.0.0.0 and the port numbers specified as the HTTP server port numbers during installation of the Application Server. If the Application Server uses the default port number values, http-listener-1 uses port 8080, http-listener-2 uses port 8181, and admin-listener uses port 4849.

Each HTTP listener has a default virtual server. The default virtual server is the server to which the HTTP listener routes all request URLs whose host component does not match any of the virtual servers that are associated with the HTTP listener (a virtual server is associated with an HTTP listener by listing the HTTP listener in its http-listeners attribute).

In addition, specify the number of acceptor threads in the HTTP listener. Acceptor threads are threads that wait for connections. The threads accept connections and put them in a queue, called the connection queue, where they are then picked up by worker threads. Configure enough acceptor 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 connection queue includes both the new connections just accepted by acceptor threads and persistent connections managed by the Keep-Alive connection management subsystem.

A set of request processing threads retrieves incoming HTTP requests from the connection queue and processes the requests. These threads parse the HTTP headers, select the appropriate virtual server, and run through the request processing engine to service the request. When there are no more requests to process, but the connection can be kept persistent (either by using HTTP/1.1 or sending a Connection: keep-alive header), the request processing thread assumes the connection to be idle and passes the connection to the Keep-Alive connection management subsystem.

The Keep-Alive subsystem periodically polls such idle connections and queues those connections with activity into the connection queue for future processing. From there, a request processing thread again retrieves the connection and processes its request. The Keep-Alive subsystem is multi-threaded, as it manages potentially tens of thousands of connections. Efficient polling techniques are used, by dividing the number of connections into smaller subsets, to determine which connections are ready with requests and which of those connections have idled for sufficient time to deem them closed (beyond a maximum permissible Keep-Alive timeout).

The HTTP listener’s server name is the host name that appears in the URLs the server sends to the client as part of a redirect. This attribute affects URLs the server automatically generates; it does not affect the URLs for directories and files stored in the server. This name is normally the alias name if the server uses an alias. If a client sends a Host: header, that host name supersedes the HTTP listener’s server name value in redirects.

Specify a redirect port to use a different port number from that specified in the original request. A redirect occurs in one of these situations:

If a client tries to access a resource that no longer exists at the specified URL (that is, the resource has moved to another location), the server redirects the client to the new location (instead of returning a 404), by returning a designated response code and including the new location in the response’s Location header.

If a client tries to access a resource that is protected (for example, SSL) on the regular HTTP port, the server redirects the request to the SSL-enabled port. In this case, the server returns a new URL in the Location response header, in which the original nonsecure port has been replaced with the SSL-enabled port. The client then connects to this new URL.

Specify also whether security is enabled for an HTTP listener and what kind of security is used (for example, which SSL protocol and which ciphers).

To access a web application deployed on the Application Server, use the URL http://localhost:8080/ (or https://localhost:8181/ if it is a secure application), along with the context root specified for the web application. To access the Admin Console, use the URL https://localhost:4849/ or https://localhost:4849/asadmin/ (its default context root).

Because a virtual server must specify an existing HTTP listener, and because it cannot specify an HTTP listener that is already being used by another virtual server, create at least one HTTP listener before creating a new virtual server.

Admin Console Tasks for the HTTP Service

Configuring the HTTP Service

Configuring the HTTP Service Access Log

Configuring the HTTP Service

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Select the HTTP Service node.

On the HTTP Service page, you can set properties that apply to all of the service’s HTTP listeners.

The following table lists these properties.

Table 17-1 HTTP Service Properties
Property Name	Description	Default Value
`traceEnabled`	If set to true, enables the TRACE operation. Set this property to false to make the Application Server less susceptible to cross-site scripting attacks.	false
`monitoringCacheEnabled`	If set to true, the Application Server caches local values of the statistics of the HTTP Service to answer statistics queries. This value improves performance. If set to false, the Application Server queries the HTTP Service for each statistics value.	true
`monitoringCacheRefreshInMillis`	Specifies the time interval, in milliseconds, after which the monitoring cache is refreshed.	5000
`sslCacheEntries`	Specifies the number of SSL sessions that can be cached. There is no upper limit.	10000
`sslSessionTimeout`	Specifies the number of seconds before an SSL2 session times out.	100
`ssl3SessionTimeout`	Specifies the number of seconds before an SSL3 session times out.	86400
`sslClientAuthDataLimit`	Specifies the maximum amount of application data, in bytes, that is buffered during the client certificate handshake phase.	1048576
`sslClientAuthTimeout`	Specifies the number of seconds before the client certificate handshake phase times out.	60
`keepAliveQueryMeanTime`	Specifies the desired keep-alive latency (in milliseconds).	100
`keepAliveQueryMaxSleepTime`	Specifies the upper limit to the time slept (in milliseconds) after polling keep-alive connections for further requests.	100
`stackSize`	Specifies the maximum stack size of the native thread.	OS/ Machine dependent
`statsProfilingEnabled`	If set to false, disables the recording of monitoring statistics by the HTTP Service, which improves performance. If t this property is set to false, enabling monitoring for the HTTP service has no effect.	true
`chunkedRequestBufferSize`	Specifies the default buffer size, in bytes, for un-chunking request data.	8192
`chunkedRequestTimeoutSeconds`	Specifies the default timeout (in seconds) for un-chunking request data.	60
`dnsCacheEnabled`	If set to true, allows the user to monitor statistics related to DNS caching. This property takes effect only if the DNS Lookup box on the HTTP Protocol tab is selected. Otherwise, the property setting is ignored.	false

Click the Access Log tab to configure access log rotation. Click the other tabs to configure request processing, the Keep-Alive subsystem, the connection pool, the HTTP protocol, and the HTTP file cache.

Click Save.

Configuring the HTTP Service Access Log

Use this page to enable and configure rotation for the access logs for the virtual servers. These logs are in the domain_root_dir/domain_dir/logs/access directory and are named as follows:

Click Load Defaults to load the default values. To change the rotation properties for these logs, do the following:

Check the File Rotation box to turn on file rotation. By default, file rotation is enabled.

From the Rotation Policy drop-down list, choose a policy. (The only policy available is time.)

In the Rotation Interval field, type a numeric value to specify the number of minutes between rotations of the access log. This field is valid only if the Rotation Policy is time. The default is 1440 minutes.

In the Rotation Suffix field, type a string value to specify the suffix to be added to the log file name after rotation. The default is %YYYY;%MM;%DD;-%hh;h%mm;m%ss;s.

In the Format field, enter a string value to specify the format of the access log. Use the formats shown in the following table. The default format is %client.name% %auth-user-name% %datetime% %request% %status% %response.length%.

Table 17-2 Token Values for Access Log Format
Data	Token
Client Host Name	`%client.name%`
Client DNS	`%client.dns%`
System Date	`%datetime%`
Full HTTP Request line	`%request%`
Status	`%status%`
Response Content Length	`%response.length%`
Referer Header	`%header.referer%`
User-agent	`%header.user-agent%`
HTTP Method	`%http-method%`
HTTP URI	`%http-uri%`
HTTP Query String	`%query-str%`
HTTP Protocol Version	`%http-version%`
Accept Header	`%header.accept%`
Date Header	`%header.date%`
If-Modified-Since Header	`%header.if-mod-since%`
Authorization Header	`%header.auth%`
Any valid HTTP header value defined in RFC 2616 (`any` is also a valid header value; it is specified as a variable here)	`%header.`any%
Name of Authorized User	`%auth-user-name%`
Value of a Cookie	`%cookie.value%`
Virtual Server ID	`%vs.id%`

Click Save to save the changes, or Load Defaults to return to the default settings.

Configuring HTTP Service Request Processing Threads

Click Load Defaults to load the default values.

In the Thread Count field, type a numeric value to specify the maximum number of request processing threads. The default is 128.

In the Initial Thread Count field, type the number of request processing threads that will be available when the server starts. The default is 48.

In the Thread Increment field, type the number of request processing threads to be added when the number of requests exceeds the initial thread count. The default is 10.

In the Request Timeout field, type the number of seconds after which requests will time out. The default is 30 seconds.

In the Buffer Length field, type the size (in bytes) of the buffer used by the request processing threads to read the request data. The default is 4096 bytes.

Click Save to save the changes, or Load Defaults to return to the default settings.

Configuring the HTTP Service Keep-Alive Subsystem

Click Load Defaults to load the default values.

In the Thread Count field, type the number of keep-alive threads to be used. The default is 1.

In the Max Connections field, type the maximum number of persistent connections to be maintained. The default is 256.

In the Time Out field, type the maximum number of seconds for which a keep-alive connection should be kept open. The default is 30 seconds.

Click Save to save the changes, or Load Defaults to return to the default settings.

Configuring the HTTP Service Connection Pool

Use this page to configure the connection pool for the HTTP service connection queue:

Click Load Defaults to load the default values.

In the Max Pending Count field, type the maximum number of pending connections to be allowed for an HTTP listener. The default is 4096.

In the Queue Size field, type the maximum size of the connection queue, in bytes. This value also specifies the maximum number of outstanding connections the server can have. The default is 4096.

In the Receive Buffer Size field, type the size of the receive buffer for an HTTP listener. The default is 4096.

In the Send Buffer Size field, type the size of the send buffer for an HTTP listener. The default is 8192.

Click Save to save the changes, or Load Defaults to return to the default settings.

Configuring the HTTP Protocol for the HTTP Service

Click Load Defaults to load the default values.

In the Version field, type the version of the HTTP protocol to be used (HTTP/1.0 or HTTP/1.1). The default is HTTP/1.1.

Select the DNS Lookup box to enable lookup of the DNS entry for the client. The default is false.

Remove the check from the SSL box to disable security in the server globally. Leave this value set to true to be able to use SSL for any listener that has security enabled. The default is true.

In the Forced Response Type field, type the response type to be used if there is no MIME mapping available matching the extension. The default value is text/html; charset=iso-8859-1.

In the Default Response Type field, type the default response type. The default value is text/html; charset=iso-8859-1. The value is a semicolon-delimited string consisting of content-type, encoding, language, and charset.

Click Save to save the changes, or Load Defaults to return to the default settings.

Configuring the HTTP File Cache for the HTTP Service

The file cache stores static content so that the server handles requests for such content quickly.

Click Load Defaults to load the default values.

Check the Globally box to enable file caching. The default is true.

Check the File Transmission box to enable the use of the TransmitFileSystem method on Windows. The default is false.

In the Max Age field, type the maximum age, in seconds, of a valid cache entry. The default is 30 seconds.

In the Max Files Count field, type the maximum number of files in the file cache. The default is 1024.

In the Hash Init Size field, type the initial number of hash buckets. The default is zero.

In the Medium File Size Limit field, type the maximum size, in bytes, of a file that can be cached as a memory mapped file. The default is 537,600 bytes.

In the Medium File Size field, type the total size, in bytes, of all files that are cached as memory mapped files. The default is 10,485,760 bytes.

In the Small File Size Limit field, type the maximum size, in bytes, of a file that can be read into memory. The default is 2048 bytes.

In the Small File Size field, type the total size, in bytes, of all files that are read into memory. The default is 1,048,576 bytes.

Choose ON or OFF from the File Caching Enabled drop-down list to enable or disable caching of file content if the size of the file is less than the medium file size limit. The default is ON.

Click Save to save the changes, or Load Defaults to return to the default settings.

Admin Console Tasks for Virtual Servers

Creating a Virtual Server

Editing a Virtual Server

Deleting a Virtual Server

Creating a Virtual Server

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the Virtual Servers node.

On the Virtual Servers page, click New. The Create Virtual Server page appears.

In the ID field, type a unique name for the virtual server. This value is used to identify the virtual server internally. It is not exposed to HTTP clients. The host names that are exposed to HTTP clients must be specified in the Hosts field.

In the Hosts field, type the host name or names for the machine on which the server is running. Use either actual or virtual host names that are registered with the DNS server for your network (and, on a UNIX system, in your /etc/hosts file).

In the area opposite State, select either On, Off, or Disabled. The default is On.

Leave the HTTP Listeners field empty. It is filled in automatically when you create an HTTP listener and associate it with this server.

(Use of this field requires that you specify an existing HTTP listener. You must not, however, specify a listener that is used by another virtual server; if you do, an error appears in the server log. Since a listener must be associated with an existing virtual server when it is created, all existing listeners are used by another virtual server.)

From the Default Web Module drop-down list, choose the deployed web module (if any) that is to respond to all requests that cannot be mapped to other web modules deployed to the virtual server.

If a Default Web Module is not specified, the web module that has an empty context root is used. If there is no web module with an empty context root, a system default web module is created and used.

In the Log File field, type the path name of the file where logging messages from this virtual server will appear. Leave this field empty to send logging messages to the default server log, domain_root_dir/domain_dir/logs/server.log.

In the Additional Properties area, click Add Property to add a property for the virtual server. Whether you specify properties or not, the new server has the default properties docroot and accesslog, set to default values.

Click OK to save the virtual server.

Table 17-3 Virtual Server Properties
Property Name	Description
`docroot`	Absolute path to root document directory for server. Default is domain_root_dir`/`domain_dir`/docroot.`
`accesslog`	Absolute path to server access logs. Default is domain_root_dir`/`domain_dir`/logs/access`.
`sso-enabled`	If false, single sign-on is disabled for this virtual server, and users must authenticate separately to every application on the virtual server. Single sign-on across applications on the Application Server is supported by servlets and JSP pages. This feature allows multiple applications that require the same user sign-on information to share this information, rather than have the user sign on separately for each application. Default is true.
`sso-max-inactive-seconds`	Specifies the number of seconds after which a user’s single sign-on record becomes eligible for purging if no client activity is received. Since single sign-on applies across several applications on the same virtual server, access to any of the applications keeps the single sign-on record active. Default is 300 seconds (5 minutes). Higher values provide longer single sign-on persistence for users at the expense of more memory use on the server.
`sso-reap-interval-seconds`	Specifies the number of seconds between purges of expired single sign-on records. Default is 60.
allowLinking	If true, resources that are symbolic links will be served for all web applications deployed on this virtual server. Individual web applications may override this setting by using the `sun-web-app` property `allowLinking` in the `sun-web.xml` file: `<sun-web-app> <property name="allowLinking" value="{true\|false}"/> </sun-web-app>` Default is true.

Editing a Virtual Server

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the Virtual Servers node.

Select the virtual server to be edited.

On the Edit Virtual Server page, you can perform these tasks:

Change the host name in the Hosts field.

Change the value of the State setting.

Add or remove an HTTP listener.

Change the Default Web Module selection.

Change the Log File value.

Add, remove, or modify properties.

Click Save to save the changes.

Deleting a Virtual Server

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the Virtual Servers node.

On the Virtual Servers page, check the box next to the name of the virtual server to be deleted.

Click Delete.

It is possible to delete the __asadmin virtual server, but this is not recommended. If you plan to do so, first copy the virtual-server elements of the Application Server’s domain.xml file to a safe place so that the settings can be restored if needed.

Admin Console Tasks for HTTP Listeners

Creating an HTTP Listener

Editing an HTTP Listener

Deleting an HTTP Listener

Creating an HTTP Listener

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the HTTP Listeners node.

On the HTTP Listeners page, click New. The Create HTTP Listener page appears.

In the Name field, type a name for the listener.

In the Listener field, remove the check from the Enabled box if you do not want to enable the listener when the server restarts.

In the Network Address field, type 0.0.0.0 if you want the listener to listen on all IP addresses for the server, using a unique port value. Otherwise, type a valid IP address for the server.

In the Listener Port field, type a unique port value if the Network Address field is 0.0.0.0, or the desired port value if you are using another IP address.

Choose a virtual server from the Default Virtual Server drop-down list.

In the Server Name field, type the host name to be used in the URLs the server sends to the client. This name is the alias name if your server uses an alias. If your server does not use an alias, leave this field empty.

In the Advanced area, perform any of the following tasks:

To redirect requests to another port, type a value in the Redirect Port field. The Application Server automatically redirects the request if these two conditions exist:

This listener is supporting non-SSL requests.

A request is received for which a matching security constraint requires SSL transport.

By default, the Application Server uses the port number specified in the original request.

Change the number of Acceptor Threads.

Remove the check from the Powered By box to disable the inclusion of the X-Powered-By: Servlet/2.4 header in servlet-generated HTTP response headers.

The Java Servlet 2.4 Specification defines this header, which containers may add to servlet-generated responses. Similarly, the JavaServer Pages™ (JSP™) 2.0 Specification defines an X-Powered-By: JSP/2.0 header to be added (on an optional basis) to responses that use JSP technology. The inclusion of the X-Powered-By: JSP/2.0 header is enabled by default for web applications. The goal of these headers is to aid web site administrators in gathering statistical data about the use of Servlet and JSP technology.

For information on enabling and disabling the X-Powered-By header for JSP pages, see the chapter entitled “Deployment Descriptor Files” in the Application Server Developer’s Guide. See "Further Information" for a link to this document.

Production environments might decide to omit the generation of X-Powered-By headers to hide their underlying technology.

To create a listener that is not secure, click OK.

In the SSL section of this page, you can configure the listener to use SSL, TLS, or both SSL and TLS security.

Check the Enabled box in the Security field.

To force clients to authenticate themselves to the server when using this listener, check the Enabled box in the Client Authentication field.

Enter the name of an existing server keypair and certificate in the Certificate NickName field. See the Security chapter for more information.

In the SSL3/TLS section:

Check the security protocol(s) to be enabled on the listener. Check either SSL3 or TLS, or both.

Check the cipher suite used by the protocol(s). To enable all cipher suites, check All Supported Cipher Suites. You can also enable individual cipher suites.

The listener is now listed in the HTTP Listeners field for the virtual server that is specified as the Default Virtual Server.

Editing an HTTP Listener

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the HTTP Listeners node.

Select the HTTP listener to be edited.

On the Edit HTTP Listener page, modify any of the settings.

Click Save to save the changes.

Deleting an HTTP Listener

In the tree component, expand the Configurations node.

Select the instance to configure:

To configure a particular instance, select the instance’s config node. For example, for the default instance, server, select the server-config node.

To configure the default settings for future instances that use a copy of default-config, select the default-config node.

Expand the HTTP Service node.

Select the HTTP Listeners node.

On the HTTP Listeners page, check the box next to the name of the HTTP listener to be deleted.

Click Delete.

It is possible to delete the http-listener-1, http-listener-2, and admin-listener HTTP listeners, but this is not recommended. If you plan to do so, first copy the http-listener elements of the Application Server’s domain.xml file to a safe place so that the settings can be restored if needed.