docs/administration-guide/src/main/asciidoc/webapps.adoc

type=page
status=published
title=Administering Web Applications
next=logging.html
prev=threadpools.html
~~~~~~

= Administering Web Applications

[[GSADG00009]][[gbbjk]]


[[administering-web-applications]]
== 6 Administering Web Applications

This chapter explains how to administer web applications in the
{productName} 7 environment.

The following topics are addressed here:

* link:#beagk[Invoking a Servlet by Alternate Means]
* link:#gixud[Changing Log Output for a Servlet]
* link:#beagc[Defining Global Features for Web Applications]
* link:#gixrb[Redirecting a URL]
* link:#gfaad[Administering `mod_jk`]
* link:#CIHJDAJD[Administering `mod_proxy_ajp`]

Instructions for accomplishing some of these tasks by using the
Administration Console are contained in the Administration Console
online help.

[[beagk]][[GSADG00548]][[invoking-a-servlet-by-alternate-means]]

=== Invoking a Servlet by Alternate Means

You can call a servlet deployed to {productName} by using a URL in a
browser or embedded as a link in an HTML or JSP file. The format of a
servlet invocation URL is as follows:

[source]
----
http://server:port/context-root/servlet-mapping?name=value
----

The following table describes each URL section.

[[GSADG857]][[sthref20]][[fvyhk]]


Table 6-1 URL Fields for Servlets Within an Application

[width="100%",cols="21%,79%",options="header",]
|===
|URL element |Description
|server`:`port a|
The IP address (or host name) and optional port number.

To access the default web module for a virtual server, specify only this
URL section. You do not need to specify the context-root or servlet-name
unless you also wish to specify name-value parameters.

|context-root a|
For an application, the context root is defined in the `context-root`
element of the `application.xml`, `sun-application.xml`, or
`sun-web.xml` file. For an individually deployed web module, the context
root is specified during deployment.

For both applications and individually deployed web modules, the default
context root is the name of the WAR file minus the `.war` suffix.

|servlet-mapping |The `servlet-mapping` as configured in the `web.xml`
file.

|`?`name`=`value`...` |Optional request parameters.
|===


[[GSADG00166]][[giyhf]]
Example 6-1 Invoking a Servlet With a URL

In this example, `localhost` is the host name, `MortPages` is the
context root, and `calcMortgage` is the servlet mapping.

[source]
----
http://localhost:8080/MortPages/calcMortgage?rate=8.0&per=360&bal=180000
----

[[GSADG00167]][[giyib]]
Example 6-2 Invoking a Servlet From Within a JSP File

To invoke a servlet from within a JSP file, you can use a relative path.
For example:

[source,xml]
----
<jsp:forward page="TestServlet"/><jsp:include page="TestServlet"/>
----

[[gixud]][[GSADG00549]][[changing-log-output-for-a-servlet]]

=== Changing Log Output for a Servlet

`ServletContext.log` messages are sent to the server log. By default,
the `System.out` and `System.err` output of servlets are sent to the
server log. During startup, server log messages are echoed to the
`System.err` output. Also by default, there is no Windows-only console
for the `System.err` output.

You can change these defaults using the Administration Console Write to
System Log box. If this box is checked, `System.out` output is sent to
the server log. If it is unchecked, `System.out` output is sent to the
system default location only.

[[beagc]][[GSADG00550]][[defining-global-features-for-web-applications]]

=== Defining Global Features for Web Applications

You can use the `default-web.xml` file to define features such as
filters and security constraints that apply to all web applications.

For example, directory listings are disabled by default for added
security. To enable directory listings in your domain's
`default-web.xml` file, search for the definition of the servlet whose
`servlet-name` is equal to `default`, and set the value of the
`init-param` named `listings` to `true`. Then restart the server.

[source,xml]
----
<init-param>
   <param-name>listings</param-name>
   <param-value>true</param-value>
</init-param>
----

If `listings` is set to `true`, you can also determine how directory
listings are sorted. Set the value of the `init-param` named `sortedBy`
to `NAME`, `SIZE`, or `LAST_MODIFIED`. Then restart the server.

[source,xml]
----
<init-param>
   <param-name>sortedBy</param-name>
   <param-value>LAST_MODIFIED</param-value>
</init-param>
----

The `mime-mapping` elements in `default-web.xml` are global and
inherited by all web applications. You can override these mappings or
define your own using `mime-mapping` elements in your web application's
`web.xml` file. For more information about `mime-mapping` elements, see
the Servlet specification.

You can use the Administration Console to edit the `default-web.xml`
file, or edit the file directly using the following steps.

[[fvymc]][[GSADG00370]][[to-use-the-default-web.xml-file]]

==== To Use the `default-web.xml` File

1. Place the JAR file for the filter, security constraint, or other
feature in the domain-dir``/lib`` directory.
2. Edit the domain-dir``/config/default-web.xml`` file to refer to the JAR file.
3. To apply your changes, restart {productName}.
+
See link:domains.html#ginqj[To Restart a Domain].

[[gixrb]][[GSADG00551]][[redirecting-a-url]]

=== Redirecting a URL

You can specify that a request for an old URL be treated as a request
for a new URL. This is called redirecting a URL.

To specify a redirected URL for a virtual server, use the `redirect_n`
property, where n is a positive integer that allows specification of
more than one. Each of these `redirect_n` properties is inherited by all
web applications deployed on the virtual server.

The value of each `redirect_n` property has two components which can be
specified in any order:

* The first component, `from`, specifies the prefix of the requested URI
to match.
* The second component, `url-prefix`, specifies the new URL prefix to
return to the client. The from prefix is replaced by this URL prefix.

[[GSADG00168]][[giyis]]
Example 6-3 Redirecting a URL

This example redirects `from` `dummy` to `etude`:

[source,xml]
----
<property name="redirect_1" value="from=/dummy url-prefix=http://etude"/>
----

[[gfaad]][[GSADG00552]][[administering-mod_jk]]

=== Administering `mod_jk`

The Apache Tomcat Connector `mod_jk` can be used to connect the web
container with web servers such as Apache HTTP Server. By using
`mod_jk`, which comes with {productName}, you can front {productName} with Apache HTTP Server.

You can also use `mod_jk` directly at the JSP/servlet engine for load
balancing. For more information about configuring `mod_jk` and Apache
HTTP Server for load balancing with {productName} 7 refer to
"link:ha-administration-guide/http-load-balancing.html#GSHAG00009[Configuring HTTP Load Balancing]" in {productName} High Availability Administration Guide.

The following topics are addressed here:

* link:#gixqw[To Enable `mod_jk`]
* link:#gixpx[To Load Balance Using `mod_jk` and {productName}]
* link:#gjpat[To Enable SSL Between the `mod_jk` Load Balancer and the
Browser]
* link:#gjpan[To Enable SSL Between the `mod_jk` Load Balancer and
{productName}]

[[gixqw]][[GSADG00371]][[to-enable-mod_jk]]

==== To Enable `mod_jk`

You can front {productName} with Apache HTTP Server by enabling the
`mod_jk` protocol for one of {productName}'s network listeners, as
described in this procedure. A typical use for `mod_jk` would be to have
Apache HTTP Server handle requests for static resources, while having
requests for dynamic resources, such as servlets and JavaServer Pages
(JSPs), forwarded to, and handled by the {productName} back-end
instance.

When you use the `jk-enabled` attribute of the network listener, you do
not need to copy any additional JAR files into the ``/lib`` directory. You
can also create JK connectors under different virtual servers by using
the network listener attribute `jk-enabled`.

1. Install Apache HTTP Server and `mod_jk`.
* For information on installing Apache HTTP Server, see
`http://httpd.apache.org/docs/2.2/install.html`.
* For information on installing `mod_jk`, see
`http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html`.
2. Configure the following files:
* `apache2/conf/httpd.conf`, the main Apache configuration file
* `apache2/conf/workers.properties`
+
link:#gixrq[Example 6-4] and link:#gixqt[Example 6-5] provide examples
of configuring these two files.
3. Start Apache HTTP Server (`httpd`).
4. Start {productName} with at least one web application deployed.
+
In order for the `mod_jk`-enabled network listener to start listening
for requests, the web container must be started. Normally, this is
achieved by deploying a web application.
5. Create a jk-enabled network listener by using the
link:reference-manual/create-network-listener.html#GSRFM00046[`create-network-listener`] subcommand.
+
[source]
----
asadmin> create-network-listener --protocol http-listener-1 \
--listenerport 8009 --jkenabled true jk-connector
----
6. If you are using the `glassfish-jk.properties` file to use
non-default values of attributes described at
`http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html`), set the
`jk-configuration-file` property of the network listener to the
fully-qualified file name of the `glassfish-jk.properties` file.
+
[source]
----
asadmin> set server-config.network-config.network-listeners.network-listener.\
jk-connector.jk-configuration-file=domain-dir/config/glassfish-jk.properties
----
7. If you expect to need more than five threads for the listener,
increase the maximum threads in the `http-thread-pool` pool:
+
[source]
----
asadmin> set configs.config.server-config.thread-pools.thread-pool.\
http-thread-pool.max-thread-pool-size=value
----
8. To apply your changes, restart {productName}.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00169]][[gixrq]]
Example 6-4 `httpd.conf` File for `mod_jk`

This example shows an `httpd.conf` file that is set for `mod_jk`. In
this example, `mod_jk` used as a simple pass-through.

[source]
----
LoadModule jk_module /usr/lib/httpd/modules/mod_jk.so
JkWorkersFile /etc/httpd/conf/worker.properties
# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel debug
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send all jsp requests to GlassFish
JkMount /*.jsp worker1
# Send all glassfish-test requests to GlassFish
JkMount /glassfish-test/* worker1
----

[[GSADG00170]][[gixqt]]
Example 6-5 `workers.properties` File for `mod_jk`

This example shows a `workers.properties` that is set for `mod_jk`. This
`workers.properties` file is referenced in the second line of
link:#gixrq[Example 6-4].

[source]
----
# Define 1 real worker using ajp13
worker.list=worker1
# Set properties for worker1 (ajp13)
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
----

[[GSADG858]]

See Also

For more information on Apache, see `http://httpd.apache.org/`.

For more information on Apache Tomcat Connector, see
`http://tomcat.apache.org/connectors-doc/index.html`.

[[gixpx]][[GSADG00372]][[to-load-balance-using-mod_jk-and-glassfish-server]]

==== To Load Balance Using `mod_jk` and {productName}

Load balancing is the process of dividing the amount of work that a
computer has to do between two or more computers so that more work gets
done in the same amount of time. Load balancing can be configured with
or without security.

In order to support stickiness, the Apache `mod_jk` load balancer relies
on a `jvmRoute` system property that is included in any `JSESSIONID`
received by the load balancer. This means that every {productName}
instance that is front-ended by the Apache load balancer must be
configured with a unique `jvmRoute` system property.

1. On each of the instances, perform the steps in link:#gixqw[To Enable
`mod_jk`].
+
If your instances run on the same machine, you must choose different JK
ports. The ports must match `worker.worker*.port` in your
`workers.properties` file. See the properties file in
link:#gixqt[Example 6-5].
2. On each of the instances, create the `jvmRoute` system property of
{productName} by using the link:reference-manual/create-jvm-options.html#GSRFM00042[`create-jvm-options`]
subcommand.
+
Use the following format:
+
[source]
----
asadmin> create-jvm-options "-DjvmRoute=/instance-worker-name"/
----
where instance-worker-name is the name of the worker that you defined to
represent the instance in the `workers.properties` file.
3. To apply your changes, restart Apache HTTP Server and {productName}.

[[GSADG00171]][[gjjzu]]
Example 6-6 `httpd.conf` File for Load Balancing

This example shows an `httpd.conf` file that is set for load balancing.

[source]
----
LoadModule jk_module /usr/lib/httpd/modules/mod_jk.so
JkWorkersFile /etc/httpd/conf/worker.properties
# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel debug
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send all jsp requests to GlassFish
JkMount /*.jsp worker1
# Send all glassfish-test requests to GlassFish
JkMount /glassfish-test/* loadbalancer
----

[[GSADG00172]][[gjjzf]]
Example 6-7 `workers.properties` File for Load Balancing

This example shows a `workers.properties` or `glassfish-jk.properties`
file that is set for load balancing. The `worker.worker*.port` should
match with JK ports you created.

[source]
----
worker.list=worker1,worker2,loadbalancer
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
worker.worker1.lbfactor=1
worker.worker1.socket_keepalive=1
worker.worker1.socket_timeout=300
worker.worker2.type=ajp13
worker.worker2.host=localhost
worker.worker2.port=8010
worker.worker2.lbfactor=1
worker.worker2.socket_keepalive=1
worker.worker2.socket_timeout=300
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=worker1,worker2
----

[[gjpat]][[GSADG00373]][[to-enable-ssl-between-the-mod_jk-load-balancer-and-the-browser]]

==== To Enable SSL Between the `mod_jk` Load Balancer and the Browser

To activate security for `mod_jk` on {productName}, you must first
generate a Secure Socket Layer (SSL) self-signed certificate on the
Apache HTTP Server with the `mod_ssl` module. The tasks include
generating a private key, a Certificate Signing Request (CSR), a
self-signed certificate, and configuring SSL-enabled virtual hosts.

[[GSADG859]]

Before You Begin

The `mod_jk` connector must be enabled.

1. Generate the private key as follows:
+
[source]
----
openssl genrsa -des3 -rand file1:file2:file3:file4:file5 -out server.key 1024
----
where `file1:file2:` and so on represents the random compressed files.
2. Remove the pass-phrase from the key as follows:
+
[source]
----
openssl rsa -in server.key -out server.pem
----
3. Generate the CSR is as follows:
+
[source]
----
openssl req -new -key server.pem -out server.csr
----
Enter the information you are prompted for.
4. Generate a temporary certificate as follows:
+
[source]
----
openssl x509 -req -days 60 -in server.csr -signkey server.pem -out server.crt
----
This temporary certificate is good for 60 days.
5. Create the `http-ssl.conf` file under the `/etc/apache2/conf.d`
directory.
6. In the `http-ssl.conf` file, add one of the following redirects:
* Redirect a web application, for example, `JkMount /hello/* worker1`.
* Redirect all requests, for example, `JkMount /* worker1`.
+
[source]
----
# Send all jsp requests to GlassFish
JkMount /*.jsp worker1
# Send all glassfish-test requests to GlassFish
JkMount /glassfish-test/* loadbalancer
----

[[GSADG00173]][[gjpnc]]
Example 6-8 `http-ssl.conf` File for `mod_jk` Security

A basic SSL-enabled virtual host will appear in the `http-ssl.conf`
file. In this example, all requests are redirected.

[source]
----
Listen 443
<VirtualHost _default_:443>
SSLEngine on
SSLCipherSuite ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile "/etc/apache2/2.2/server.crt"
SSLCertificateKeyFile "/etc/apache2/2.2/server.pem"
JkMount /* worker1
</VirtualHost>
----

[[gjpan]][[GSADG00374]][[to-enable-ssl-between-the-mod_jk-load-balancer-and-glassfish-server]]

==== To Enable SSL Between the `mod_jk` Load Balancer and {productName}

This procedure does not enable SSL transfer between `mod_jk` and
{productName}. It enables `mod_jk` to forward SSL-encrypted
information from the browser to {productName}.

[[GSADG860]]

Before You Begin

The self-signed certificate must be configured.

1. Perform the steps in link:#gixqw[To Enable `mod_jk`].
2. Start another {productName} with at least one web application
deployed.
+
In order for the `mod_jk`-enabled network listener to start listening
for requests, the web container must be started. Normally, this is
achieved by deploying a web application.
3. Follow instructions from link:http_https.html#ggnbj[To Configure an
HTTP Listener for SSL] on the `mod_jk` connector.
+
Use the following format:
+
[source]
----
asadmin> create-ssl --type http-listener --certname sampleCert new-listener
----
4. Add the following directives in the `httpd.conf` file under the
`/etc/apache2/conf.d` directory:
+
[source]
----
# Should mod_jk send SSL information (default is On)
JkExtractSSL On
# What is the indicator for SSL (default is HTTPS)
JkHTTPSIndicator HTTPS
# What is the indicator for SSL session (default is SSL_SESSION_ID)
JkSESSIONIndicator SSL_SESSION_ID
# What is the indicator for client SSL cipher suit (default is SSL_CIPHER )
JkCIPHERIndicator SSL_CIPHER
# What is the indicator for the client SSL certificated? (default is SSL_CLIENT_CERT )
JkCERTSIndicator SSL_CLIENT_CERT
----
5. To apply your changes, restart Apache HTTP Server and {productName}.

[[CIHJDAJD]][[GSADG861]][[administering-mod_proxy_ajp]]

=== Administering `mod_proxy_ajp`

The Apache Connector `mod_proxy_ajp` can be used to connect the web
container with Apache HTTP Server. By using `mod_proxy_ajp`, you can
front {productName} with Apache HTTP Server.

[[GSADG862]][[sthref21]]


[[to-enable-mod_proxy_ajp]]
==== To Enable `mod_proxy_ajp`

You can front {productName} with Apache HTTP Server and its
`mod_proxy_ajp` connector by enabling the AJP protocol for one of
{productName}'s network listeners, as described in this procedure. A
typical use for `mod_proxy_ajp` would be to have Apache HTTP Server
handle requests for static resources, while having requests for dynamic
resources, such as servlets and JavaServer Pages (JSPs), forwarded to,
and handled by the {productName} back-end instance.

1. Install Apache HTTP Server.
+
For information on installing Apache HTTP Server, see
`http://httpd.apache.org/docs/2.2/install.html`.
2. Configure `apache2/conf/httpd.conf`, the main Apache configuration
file.
+
For example:
+
[source]
----
LoadModule proxy_module /usr/lib/httpd/modules/mod_proxy.so
LoadModule proxy_ajp_module /usr/lib/httpd/modules/mod_proxy_ajp.so

Listen 1979
NameVirtualHost *:1979
<VirtualHost *:1979>
   ServerName localhost
   ErrorLog /var/log/apache2/ajp.error.log
   CustomLog /var/log/apache2/ajp.log combined

   <Proxy *>
     AddDefaultCharset Off
     Order deny,allow
     Allow from all
   </Proxy>

   ProxyPass / ajp://localhost:8009/
   ProxyPassReverse / ajp://localhost:8009/
</VirtualHost>
----
3. Start Apache HTTP Server (`httpd`).
4. Create a jk-enabled network listener by using the
`create-network-listener` subcommand.
+
[source]
----
asadmin> create-network-listener --protocol http-listener-1 \
--listenerport 8009 --jkenabled true jk-connector
----
5. If you expect to need more than five threads for the listener,
increase the maximum threads in the `http-thread-pool` pool:
+
[source]
----
asadmin> set configs.config.server-config.thread-pools.thread-pool.\
http-thread-pool.max-thread-pool-size=value
----
6. To apply your changes, restart {productName}.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG863]]

See Also

For more information on Apache, see `http://httpd.apache.org/`.

For more information on the Apache `mod_proxy_ajp` Connector, see
`http://httpd.apache.org/docs/2.1/mod/mod_proxy.html` and
`http://httpd.apache.org/docs/2.1/mod/mod_proxy_ajp.html`.

For more information on the AJP protocol, see
`http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html`.

[[GSADG1049]][[sthref22]]


[[to-load-balance-using-mod_proxy_ajp-and-glassfish-server]]
==== To Load Balance Using `mod_proxy_ajp` and {productName}

Load balancing is the process of dividing the amount of work that a
computer has to do between two or more computers so that more work gets
done in the same amount of time. In the {productName} context, load
balancing is most frequently used to distribute work among the instances
in a {productName} cluster.

To configure load balancing using `mod_proxy_ajp`, you must use the
`mod_proxy_balancer` Apache module in addition to `mod_proxy_ajp`.

In order to support stickiness, the `mod_proxy_balancer` load balancer
relies on a `jvmRoute` system property that is included in any
`JSESSIONID` received by the load balancer. Consequently, every
{productName} instance that is front-ended by the Apache load
balancer must be configured with a unique `jvmRoute` system property.

1. Install Apache HTTP Server.
+
For information on installing Apache HTTP Server, see
`http://httpd.apache.org/docs/2.2/install.html`.
2. [[BABIFEEC]]
+
Configure `apache2/conf/httpd.conf`, the main Apache configuration file.
+
For example:
+
[source]
----
LoadModule proxy_module /usr/lib/httpd/modules/mod_proxy.so
LoadModule proxy_ajp_module /usr/lib/httpd/modules/mod_proxy_ajp.so
LoadModule proxy_balancer_module /usr/lib/httpd/modules/mod_proxy_balancer.so

# Forward proxy needs to be turned off
ProxyRequests Off
# Keep the original Host Header
ProxyPreserveHost On

   <Proxy *>
      Order deny,allow
      Deny from all
      Allow from localhost
   </Proxy>

# Each BalancerMember corresponds to an instance in the Eclipse GlassFish
# cluster. The port specified for each instance must match the ajp port
# specified for that instance.
<Proxy balancer://localhost>
    BalancerMember ajp://localhost:8009
    BalancerMember ajp://localhost:8010
    BalancerMember ajp://localhost:8011
</Proxy>
----
3. Start Apache HTTP Server (`httpd`).
4. In {productName}, use the `create-network-listener` subcommand to
create a jk-enabled network listener targeted to the cluster.
+
For example:
+
[source]
----
asadmin> create-network-listener --jkenabled true --target cluster1 \
--protocol http-listener-1 --listenerport ${AJP_PORT} jk-listener
----
In this example, `cluster1` is the name of the cluster and `jk-listener`
is the name of the new listener.
5. If you expect to need more than five threads for the listener,
increase the maximum threads in the `http-thread-pool` pool:
+
[source]
----
asadmin> set configs.config.cluster1-config.thread-pools.thread-pool.\
http-thread-pool.max-thread-pool-size=value
----
6. Use the `create-jvm-options` subcommand to create the `jvmRoute`
property targeted to the cluster.
+
For example:
+
[source]
----
asadmin> create-jvm-options --target cluster1 \
"-DjvmRoute=\${AJP_INSTANCE_NAME}"
----
7. Use the `create-system-properties` subcommand to define the
`AJP_PORT` and `AJP_INSTANCE_NAME` properties for each of the instances
in the cluster, making sure to match the port values you used in
Step link:#BABIFEEC[2] when specifying the load balancer members.
+
For example:
+
[source]
----
asadmin> create-system-properties --target instance1 AJP_PORT=8009
asadmin> create-system-properties --target instance1 \
AJP_INSTANCE_NAME=instance1
asadmin> create-system-properties --target instance2 AJP_PORT=8010
asadmin> create-system-properties --target instance2 \
AJP_INSTANCE_NAME=instance2
asadmin> create-system-properties --target instance3 AJP_PORT=8011
asadmin> create-system-properties --target instance3 \
AJP_INSTANCE_NAME=instance3
----
In this example, `instance1`, `instance2` and `instance3` are the names
of the {productName} instances in the cluster.
8. To apply your changes, restart {productName}.
+
See link:domains.html#ginqj[To Restart a Domain].