Use Apache as a secure (reverse) proxy for JBoss 5 AS/EAP

This task can be divided into two independent components (configure Apache to use SSL, set up Apache as a reverse proxy for JBoss) and a single step to make those two work together. The guidelines below have been successfully tested on an Apache 2.2.17/JBoss EAP 5.1.0.GA combination, the latter using Tomcat native libs, on a single server.


Part 1: Use SSL for access to Apache

1) Download and install the Apache Httpd server (version 2.2.6 or higher, 2.2.17 is the current). The folder in which the server is installed is referred to as APACHE_HOME further on.

2) In APACHE_HOME/conf/httpd.conf, un-comment the following lines:

    LoadModule ssl_module modules/mod_ssl.so

    Include conf/extra/httpd-ssl.conf

Then comment the following one (to restrict access without SSL):

    #Listen 80

3) Put your certificate and key in the APACHE_HOME/conf folder, and (if necessary) change the names in APACHE_HOME/conf/extra/httpd-ssl.conf entries to match:

    SSLCertificateFile "[APACHE_HOME]/conf/server.crt"
    SSLCertificateKeyFile "[APACHE_HOME]/conf/server.key"

If you don’t have a CA certificate, you can create a self-signed certificate for testing purposes, see e.g. the OpenSSL FAQ how to do so. An OpenSSL executable is provided in the APACHE_HOME/bin folder.

Remark: On Windows platforms it is not possible to use the SSLPassPhraseDialog-parameter (in httpd-ssl.conf) with the default value ‘builtin’. The simplest (albeit not the safest) solution is to remove the passphrase from the key, removing the need for Apache to ask for it at startup.

4) (Re-)start the Apache server and test whether it works as expected… and don’t forget the ‘https://’!

For an extensive explanation of the SSL configuration possibilities see Apache Module ssl_mod.


Part 2: Set Apache up as a reverse proxy for JBoss

1) Download the mod_jk connector (version 1.2.15 or higher, 1.2.31 is the current), rename the ‘mod_jk-1.2.[*]-httpd-2.2.x.so’ file to ‘mod_jk.so’ and move it to the APACHE_HOME/modules folder.

2) Add the following line to APACHE_HOME/conf/httpd.conf:

    Include conf/mod-jk.conf

3) Create a new file in APACHE_HOME/conf with the name ‘mod-jk.conf’, and fill it with:

    LoadModule jk_module modules/mod_jk.so

    JkWorkersFile conf/workers.properties

    JkLogFile logs/mod_jk.log
    JkLogLevel info
    JkLogStampFormat "[%a %b %d %H:%M:%S %Y]"
    JkRequestLogFormat "%w %V %T"

    JkOptions +ForwardKeySize +ForwardURICompatUnparsed -ForwardDirectories

    # Mount your applications
    ###JkMount /application/* loadbalancer
    # Mount all URLs:
    JkMount /* node1

    # You can addionally use external file for mount points.
    ###JkMountFile conf/uriworkermap.properties
    # Mount file reload check interval in secs (0 = turned off).
    ###JkMountFileReload 60

    # Add shared memory. Used only on unix platforms. The shm file is used by balancer and status workers.
    ###JkShmFile run/jk.shm

    # Add jkstatus for managing runtime data:
    <Location /jkstatus/>
        JkMount status
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1
    </Location>

When not all requests are to be redirected to node1 the line starting with ‘JkMount’ must be adjusted. Furthermore it is possible to use a separate properties file (using ‘JkMountFile’, with entries following the pattern ‘URL=worker’, e.g. ‘/jmx-console=node1’) if you need a more extensive redirection scheme.

In the configuration above the access to the status manager (worker with ID ‘status’) is restricted to clients running on the same host, just for illustrative purposes.

See the Tomcat connector reference for further details and possibilities.

4) Create a new file in APACHE_HOME/conf named  ‘workers.properties’,  and put the following in it:

    # Define list of workers that will be used for mapping requests

    # Define Node1
    # modify the host as your host IP or DNS name.
    worker.node1.type=ajp13
    worker.node1.host=localhost
    worker.node1.port=8009
    worker.node1.ping_mode=A
    #worker.node1.connection_pool_size=10 # Only if the number of allowed connections to the Httpd is higher than maxThreads in JBoss server.xml.
    #worker.node1.lbfactor=1 # Only used for a member worker of a load balancer.
    # For non-loadbalanced setup with a single node:
    worker.list=node1

    # Define Node2
    # modify the host as your host IP or DNS name.
    #worker.node2.type=ajp13
    #worker.node2.host= node2.mydomain.com
    #worker.node2.port=8009
    #worker.node2.ping_mode=A
    #worker.node2.connection_pool_size=10
    #worker.node2.lbfactor=1

    # Load-balancing behaviour
    #worker.loadbalancer.type=lb
    #worker.loadbalancer.balance_workers=node1,node2
    #worker.loadbalancer.sticky_session=Off # Enabled by default.
    #worker.list=loadbalancer

    # Status worker for managing load balancer
    worker.status.type=status
    worker.list=status

Most lines above are commented out, since we’re aiming for a configuration for a single node without loadbalancing. It is straightforward to add more nodes, with or without loadbalancing; just pay attention to the fact that with loadbalancing the worker.list should not refer to the separate nodes but only to the loadbalancer worker.

5) For each (JBoss-)node a ‘jvmRoute’ attribute  must be added to the <Engine>-element in JBOSS_HOME/server/[configuration]/deploy/jbossweb.sar/server.xml, using the corresponding name from the mod_jk-configuration as a parameter:

    <Engine name="jboss.web" defaulthost="localhost" jvmroute="node1">

And for JBoss AS/EAP version 5 and above that is all that is required!

6) If you didn't configure Apache to use SSL, you can now (re-)start the JBoss en Apache servers and test whether the redirecting functions as expected…
If you did configure SSL for Apache, hang on just a bit more...


Part 3: Combining the twee solutions above

To be able to access Apache using SSL after which the request is passed to the JBoss instance over AJP, one last adjustment is required:

1) Move the JkMount directives from the APACHE_HOME/conf/mod-jk.conf file to the APACHE_HOME/conf/extra/httpd-ssl.conf file, and make sure they’re within the <VirtualHost> tags:

    <VirtualHost _default_:443>

    […]

    JkMount /* node1
    <Location /jkstatus/>
        JkMount status
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1
    </Location>

    </VirtualHost>

After a restart of the Apache server the pages served by JBoss will be available over HTTPS from Apache (port 443).

Be aware that they are also still available over HTTP from JBoss directly (on port 8080), since the configuration above didn’t remove that (default) situation. To accomplish that, you should comment the HTTP connector entry in the server.xml file of jbossweb.sar.