13/29

# 6 Administering Web Applications

This chapter explains how to administer web applications in the Oracle GlassFish Server 3.1.2 environment.

The following topics are addressed here:

- Invoking a Servlet by Alternate Means

- Changing Log Output for a Servlet

- Defining Global Features for Web Applications

- Redirecting a URL

- Administering `mod_jk`

- Administering `mod_proxy_ajp`

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

## Invoking a Servlet by Alternate Means

You can call a servlet deployed to GlassFish Server 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:

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

The following table describes each URL section.

Table 6-1 URL Fields for Servlets Within an Application

URL element | Description
--- | ---
server`:`port | 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 | 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.

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.

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

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:

    <jsp:forward page="TestServlet"/><jsp:include page="TestServlet"/>

## 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.

## 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.

    <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.

    <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.

### 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 GlassFish Server.

   See To Restart a Domain.

## 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.

Example 6-3 Redirecting a URL

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

    <property name="redirect_1" value="from=/dummy url-prefix=http://etude"/>

## 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 GlassFish Server, you can front GlassFish Server with Apache HTTP Server.

The following topics are addressed here:

- To Enable `mod_jk`

- To Load Balance Using `mod_jk` and GlassFish Server

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

- To Enable SSL Between the `mod_jk` Load Balancer and GlassFish Server

### To Enable `mod_jk`

You can front GlassFish Server with Apache HTTP Server by enabling the `mod_jk` protocol for one of GlassFish Server'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 GlassFish Server 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`

   Example 6-4 and Example 6-5 provide examples of configuring these two files.

3. Start Apache HTTP Server (`httpd`).

4. Start GlassFish Server 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 `create-network-listener` subcommand.

       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.

       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:

       asadmin> set configs.config.server-config.thread-pools.thread-pool.\
       http-thread-pool.max-thread-pool-size=value

8. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

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.

    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

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 Example 6-4.

    # 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

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`.

### To Load Balance Using `mod_jk` and GlassFish Server

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 GlassFish Server 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 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 Example 6-5.

2. On each of the instances, create the `jvmRoute` system property of GlassFish Server by using the `create-jvm-options` subcommand.

   Use the following format:

       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 GlassFish Server.

Example 6-6 `httpd.conf` File for Load Balancing

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

    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

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.

    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

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

To activate security for `mod_jk` on GlassFish Server, 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.

Before You Begin

The `mod_jk` connector must be enabled.

1. Generate the private key as follows:

       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:

       openssl rsa -in server.key -out server.pem

3. Generate the CSR is as follows:

       openssl req -new -key server.pem -out server.csr

   Enter the information you are prompted for.

4. Generate a temporary certificate as follows:

       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`.

       # Send all jsp requests to GlassFish
       JkMount /*.jsp worker1
       # Send all glassfish-test requests to GlassFish
       JkMount /glassfish-test/* loadbalancer

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.

    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>

### To Enable SSL Between the `mod_jk` Load Balancer and GlassFish Server

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

Before You Begin

The self-signed certificate must be configured.

1. Perform the steps in To Enable `mod_jk`.

2. Start another GlassFish Server 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 To Configure an HTTP Listener for SSL on the `mod_jk` connector.

   Use the following format:

       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:

       # 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 GlassFish Server.

## 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 GlassFish Server with Apache HTTP Server.

### To Enable `mod_proxy_ajp`

You can front GlassFish Server with Apache HTTP Server and its `mod_proxy_ajp` connector by enabling the AJP protocol for one of GlassFish Server'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 GlassFish Server 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:

       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.

       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:

       asadmin> set configs.config.server-config.thread-pools.thread-pool.\
       http-thread-pool.max-thread-pool-size=value

6. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.

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`.

### To Load Balance Using `mod_proxy_ajp` and GlassFish Server

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 GlassFish Server context, load balancing is most frequently used to distribute work among the instances in a GlassFish Server 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 GlassFish Server 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. Configure `apache2/conf/httpd.conf`, the main Apache configuration file.

   For example:

       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 GlassFish Server
       # 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 GlassFish Server, use the `create-network-listener` subcommand to create a jk-enabled network listener targeted to the cluster.

   For example:

       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:

       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:

       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 2 when specifying the load balancer members.

   For example:

       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 GlassFish Server instances in the cluster.

8. To apply your changes, restart GlassFish Server.

   See To Restart a Domain.