Sun Java™ System Application Server Platform Edition 8 Administration Guide |
Chapter 11
The HTTP ServiceThis 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 ServiceWhat 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.comAssume also that www.aaa.com,
www.bbb.com
, andwww.ccc.com
have web modulesweb1
,web2
, andweb3
, 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/web3The first URL will be mapped to virtual host
www.aaa.com
, the second URL will be mapped to virtual hostwww.bbb.com
, and the third will be mapped to virtual hostwww.ccc.com
.On the other hand, the following URL will result in a 404 return code, because
web3
wasn’t registered withwww.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
, andwww.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 forhosts
in your/etc/nsswitch.conf
file includesfiles
).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:
- Two HTTP listeners named
http-listener-1
andhttp-listener-2
, associated with the virtual server namedserver
. The listener namedhttp-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
.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, andadmin-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:
- When the resource you are trying to access no longer exists at the specified URL (that is, the resource has moved to another location), the server may redirect 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 may redirect the request to the SSL-enabled port. In this case, the server will return a new URL in the Location response header, in which the original nonsecure port has been replaced with the SSL-enabled port. The client will then connect to this new URL.
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/
(orhttp://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 URLhttp://localhost:4848/
orhttp://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 ServiceConfiguring the HTTP Service
- In the tree component, select the HTTP Service node.
- On the HTTP Service page, you can set properties that apply to all of the service’s HTTP listeners.
Table 11-1 lists these properties.
- Click Save.
Admin Console Tasks for Virtual ServersCreating a Virtual Server
- In the tree component, 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 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.
- 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).- In the area opposite State, select either On, Off, or Disabled. The default is On.
- Leave the HTTP Listeners field empty. It will be filled in automatically when you create an HTTP listener and associate it with this server.
(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.)- 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.
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.
- 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
).- 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
andaccesslog
, set to default values.- 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.
Equivalent
asadmin
command:create-virtual-server
Editing a Virtual Server
Deleting a Virtual 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 thevirtual-server
elements of the Application Server’sdomain.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 ListenersCreating an HTTP Listener
- In the tree component, 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, deselect the Enabled checkbox if you do not want to enable the listener when you restart the server.
- 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.
Note: The values any, ANY, and INADDR_ANY are also valid values for this field, but are currently unsupported (bug #5004719).
- 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 combo box.
- 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.
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.
- 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 theX-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.- 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:
- Check the Enabled box in the Security field.
- If you want 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:
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
Deleting an HTTP Listener
It is possible to delete the
http-listener-1
,http-listener-2
, andadmin-listener
HTTP listeners, but this is not recommended. If you plan to do so, you should first copy thehttp-listener
elements of the Application Server’sdomain.xml
file to a safe place so that you can restore the settings if needed.Equivalent
asadmin
command:delete-http-listener