Sun logo      Previous      Contents      Next     

Sun Java™ System Application Server Platform Edition 8 Administration Guide

Chapter 11
The HTTP Service

This chapter describes how to configure virtual servers and HTTP listeners for the HTTP service of the Sun Java™ System Application Server Platform Edition 8.

About the HTTP Service

What Is the HTTP Service?

The HTTP service is the component of the Sun Java™ System Application Server Platform Edition 8 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 you to use 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 Sun Java™ System Application Server Platform Edition 8 is running.

Note: Do not confuse an Internet domain with the administrative domain of the Application Server. (See Administrative Domains.)

For instance, assume you want to host these domains on your physical server:

www.aaa.com
www.bbb.com
www.ccc.com

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

This means that all of these URLs will be handled by your physical server:

http://www.aaa.com:8080/web1
http://www.bbb.com:8080/web2
http://www.ccc.com:8080/web3

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

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

http://www.bbb.com:8080/web3

For this mapping to work, you have to 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, you would add these domains to your /etc/hosts file (if the setting for hosts in your /etc/nsswitch.conf file includes files).

When you start the Application Server, it starts two virtual servers automatically:

For development, testing, and deployment of Web services in a non-production environment, server may be the only virtual server you need. You normally use additional virtual servers to 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 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, it 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, or with different IP addresses and the same port number. For example, you could specify 1.1.1.1:8081 and 1.1.1.1:8082. Additionally, you could specify 1.1.1.1:8081 and 1.2.3.4:8081, if your machine was configured to respond to both these addresses.

However, if you use 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 you have an HTTP listener using 0.0.0.0:8080 (all IP addresses on port 8080), you cannot also create an HTTP listener that uses 1.2.3.4:8080.

Since you typically have access to only one IP address for the system running the Application Server, you typically create listeners that use the 0.0.0.0 IP address and different port numbers, with each port number serving a different purpose. If you do have access to more than one IP address, you could instead use each address to serve a different purpose.

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

All these listeners use the IP address 0.0.0.0 and the port numbers you specified as your HTTP server port numbers during installation. If you accepted the default values for the port numbers, http-listener-1 uses port 8080, http-listener-2 uses port 1043, and admin-listener uses port 4848.

Each HTTP listener has a default virtual server, which is the server to which it 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, you 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 where they are then picked up by worker threads. Ideally, you want to have 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. In the Application Server, there is no distinction between acceptor and request processing (worker) threads, i.e., each HTTP listener thread is responsible for accepting and processing requests. For this reason, the HTTP listeners in the Application Server’s default configuration use 100 acceptor threads.

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 should be the alias name if your server uses an alias. If a client sends a Host: header, that host name supersedes the HTTP listener’s server name value in redirects. You can also specify a redirect port if you do not want to use the port number specified in the original request.

A redirect occurs in one of these situations:

You also specify whether security is enabled for an HTTP listener and what kind of security you are using (for example, which SSL protocol and which ciphers).

This means that if you deploy a Web application on the Application Server, you access it with the URL http://localhost:8080/ (or http://localhost:1043/ if it is a secure application), along with the context root you specified for the Web application. You access the Admin Console with the URL http://localhost:4848/ or http://localhost:4848/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, you must create at least one HTTP listener before you create a new virtual server.

Admin Console Tasks for the HTTP Service

Configuring the HTTP Service

  1. In the tree component, select the HTTP Service node.
  2. On the HTTP Service page, you can set properties that apply to all of the service’s HTTP listeners.

    3. Table 11-1 lists these properties.

  3. Click Save.

Table 11-1  HTTP Service Properties 

Property Name

Description

Default Value

bufferSize

The size (in bytes) of the buffer to be provided for input streams created by HTTP listeners.

2048

connectionTimeout

The number of milliseconds HTTP listeners will wait, after accepting a connection, for the request URI line to be presented.

60000
(60 seconds)

maxKeepAliveRequests

The maximum number of HTTP requests that can be pipelined until the connection is closed by the server. Setting this attribute to 1 will disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining.

100

tcpNoDelay

If set to true, the TCP_NO_DELAY option will be set on all HTTP listeners. This option improves performance under most circumstances.

true

Admin Console Tasks for Virtual Servers

Creating a Virtual Server

  1. In the tree component, expand the HTTP Service node.
  2. Select the Virtual Servers node.
  3. On the Virtual Servers page, click New. The Create Virtual Server page appears.
  4. In the ID field, type the name of the domain. 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.
  5. In the Hosts field, type the host name or names for the machine on which the server is running. You may 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).
  6. In the area opposite State, select either On, Off, or Disabled. The default is On.
  7. Leave the HTTP Listeners field empty. It will be filled in automatically when you create an HTTP listener and associate it with this server.

    8. (If you use this field, you must specify an existing HTTP listener. You may not, however, specify a listener that is used by another virtual server; if you do, the Application Server will not restart and you will have to delete the new virtual server manually from the domain.xml file. Since a listener must be associated with an existing virtual server when it is created, all existing listeners are used by another virtual server.)

  8. In the Default Web Module combo box, choose the deployed Web module (if any) that will respond to all requests that cannot be mapped to other web modules deployed to the virtual server.

    9. If you do not specify a default web module, 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.

  9. 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 if you want logging messages to go to the default server log (install_dir/domains/domain1/config/server.log).
  10. 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 will have the default properties docroot and accesslog, set to default values.
  11. Click OK to save the virtual server.

You must stop and restart the Application Server in order to use the new virtual server.

You can set the properties listed in the following table.

Table 11-2  Virtual Server Properties 

Property Name

Description

docroot

Absolute path to root document directory for server.

Default is install_dir/domains/domain1/docroot

accesslog

Absolute path to server access logs.

Default is install_dir/domains/domain1/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.

Equivalent asadmin command: create-virtual-server

Editing a Virtual Server

  1. In the tree component, expand the HTTP Service node.
  2. Select the Virtual Servers node.
  3. Select the virtual server to be edited.
  4. 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.
  5. Click Save to save your changes.
  6. Stop and restart the Application Server.

Deleting a Virtual Server

  1. In the tree component, expand the HTTP Service node.
  2. Select the Virtual Servers node.
  3. On the Virtual Servers page, select the checkbox next to the name of the virtual server to be deleted.
  4. Click Delete.
  5. Stop and restart the Application Server.

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

Equivalent asadmin command: delete-virtual-server

Admin Console Tasks for HTTP Listeners

Creating an HTTP Listener

  1. In the tree component, expand the HTTP Service node.
  2. Select the HTTP Listeners node.
  3. On the HTTP Listeners page, click New. The Create HTTP Listener page appears.
  4. In the Name field, type a name for the listener.
  5. In the Listener field, deselect the Enabled checkbox if you do not want to enable the listener when you restart the server.
  6. 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.

    7. Note: The values any, ANY, and INADDR_ANY are also valid values for this field, but are currently unsupported (bug #5004719).

  7. 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.
  8. Choose a virtual server from the Default Virtual Server combo box.
  9. In the Server Name field, type the host name to be used in the URLs the server sends to the client. This name should be the alias name if your server uses an alias. If your server does not use an alias, leave this field empty.

    10. Note: The empty string is a valid value for this field, but the Admin Console does not allow you to leave the field empty (bug #5007292). Workaround: After you save the listener, edit the field and remove the string you entered.

  10. In the Advanced area, you may perform the following tasks:
    • To redirect requests to another port, type a value in the Redirect Port field. The Application Server will automatically redirect the request if these two conditions exist: First, this listener is supporting non-SSL requests; and second, 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 (the default is 1, but 100 is a better value).
    • Deselect the Powered By checkbox 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 Sun Java™ System Application Server Platform Edition 8 Developer’s Guide. See Further Information for a link to this document.

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

  11. If you don’t want to make the listener secure, click OK.

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

To set up a secure listener, do the following:

  1. Check the Enabled box in the Security field.
  2. If you want clients to authenticate themselves to the server when using this listener, check the Enabled box in the Client Authentication field.
  3. Enter the name of an existing server keypair and certificate in the Certificate NickName field. See the Security chapter for more information.
  4. In the SSL3/TLS section:
    1. Check the security protocol(s) you want to enable on the listener. You must check either SSL3 or TLS, and can enable both protocols.
    2. Check the cipher suite used by the protocol(s). To enable all cipher suites, check All Supported Cipher Suites. You may also enable individual cipher suites.

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

You must stop and restart the Application Server in order to use the new HTTP listener.

Equivalent asadmin command: create-http-listener

Editing an HTTP Listener

  1. In the tree component, expand the HTTP Service node.
  2. Select the HTTP Listeners node.
  3. Select the HTTP listener to be edited.
  4. On the Edit HTTP Listener page, modify any of the properties you set when you created the listener.
  5. Click Save to save your changes.
  6. Stop and restart the Application Server.

Deleting an HTTP Listener

  1. In the tree component, expand the HTTP Service node.
  2. Select the HTTP Listeners node.
  3. On the HTTP Listeners page, select the checkbox next to the name of the HTTP listener to be deleted.
  4. Click Delete.
  5. Stop and restart the Application Server.

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, you should first copy the http-listener elements of the Application Server’s domain.xml file to a safe place so that you can restore the settings if needed.

Equivalent asadmin command: delete-http-listener



Previous      Contents      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.