Fronting JBoss with Apache

This document provides the steps to have an Apache front for Jboss or Tomcat. The following topics are included:

Configuring Apache

The following instructions are from the Jboss community docs.

  • Add this line at the very bottom in APACHE_HOME/conf/httpd.conf:

     

    # Include mod_jk configuration file
         Include conf/mod-jk.conf
  • Under APACHE_HOME/conf, create mod-jk.conf and populate it as follows:

     

    # Load mod_jk module
       # Specify the filename of the mod_jk lib
       LoadModule jk_module modules/mod_jk.so
       # Where to find workers.properties
       JkWorkersFile conf/workers.properties
       # Where to put jk logs
       JkLogFile  /var/log/mod_jk.log
       # Set the jk log level [debug-error-info]
       JkLogLevel info
       # Select the log format
       JkLogStampFormat "[%a %b %d %H:%M.%S %Y]"
       # JkOptions indicates to send SSK KEY SIZE
       # Notes:
       # 1) Changed from +ForwardURICompat.
       # 2) For mod_rewrite compatibility, use +ForwardURIProxy (default since 1.2.24)
       JkOptions +ForwardKeySize +ForwardURICompatUnparsed -ForwardDirectories
       # JkRequestLogFormat
       JkRequestLogFormat "%w %V %T"
       # Mount your applications
       JkMount /__application__/* loadbalancer
       # You can use external file for mount points.
       # It will be checked for updates each 60 seconds.
       # The format of the file is: /url=worker
       # /examples/*=loadbalancer
       JkMountFile conf/uriworkermap.properties
       # Add shared memory.
       # This directive is present with 1.2.10 and
       # later versions of mod_jk, and is needed for
       # for load balancing to work properly
       # Note: Replaced JkShmFile logs/jk.shm due to SELinux issues. Refer to
       JkShmFile run/jk.shm
       # Add jkstatus for managing runtime data
       <Location /jkstatus></Location>
       JkMount status
       Order deny,allow
       Deny from all
       Allow from 127.0.0.1
       </Location>
  • If you are going to multiple Jboss applications and will be defining workers other than loadbalancer in workers.properties make sure to JkMount those as well in mod-jk.conf.

 

Note

Everything in this mod-jk.conf is loaded into httpd.conf which defaults to the port 80 settings.

 

  • Under APACHE_HOME/conf, create workers.properties and populate it as follows (customize Nodes as needed):

     

    # Define list of workers that will be used
       # for mapping requests
       # The configuration directives are valid
       # for the mod_jk version 1.2.18 and later
       #
       worker.list=loadbalancer,status
       # Define Node1
       # modify the host as your host IP or DNS name.
       worker.node1.port=8009
       worker.node1.host=node1.mydomain.com
       worker.node1.type=ajp13
       worker.node1.lbfactor=1
       # worker.node1.connection_pool_size=10 (1)
       # Define Node2
       # modify the host as your host IP or DNS name.
       worker.node2.port=8009
       worker.node2.host= node2.mydomain.com
       worker.node2.type=ajp13
       worker.node2.lbfactor=1
       # worker.node1.connection_pool_size=10 (1)
       # Load-balancing behaviour
       worker.loadbalancer.type=lb
       worker.loadbalancer.balance_workers=node1,node2
       # Status worker for managing load balancer
       worker.status.type=status
  • Create a uriworkermap.properties file in the APACHE_HOME/conf directory. This file should contain the URL mappings you want Apache to forward to Tomcat. The format of the file is /url=worker_name. To get things started, paste this example into the file you created. This will configure mod_jk to forward requests to /jmx-console and /web-console to Tomcat.

     

    # Simple worker configuration file
       #
       # Mount the Servlet context to the ajp13 worker
       /jmx-console=loadbalancer
       /jmx-console/*=loadbalancer
       /web-console=loadbalancer
       /web-console/*=loadbalancer
  • Restart Apache

Configuring JBoss/Tomcat

  • Locate the server.xml file in your JBoss instance. If you are using the default JBoss server, use the following command:

     

    cd $JBOSS_HOME/server/default
       find * -name server.xml
  • If you are using a different server, replace "default" with the name of the server you are using.
  • Locate the <Engine/.> element and add a jvmRoute attribute. The jvmRoute attribute value must match the name specified in workers.properties:

     

    <Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">
       .
       </Engine>
  • Make sure that at least one AJP 1.3 connector port is uncommented in the server.xml as follows. Apache talks to Jboss/tomcat using this AJP 1.3 port, not the standard port:

     

    <Connector port="8009" address="$\{jboss.bind.address\}"
          emptySessionPath="true" enableLookups="false" redirectPort="8443"
          protocol="AJP/1.3"></Connector>
  • Start JBoss with the "-b 0.0.0.0" argument so it will listen on all network interfaces, allowing apache to communicate with it.

Adding SSL

On the Apache server:

  • If your CA gave you an intermediate cert edit this line to include it:

     

    SSLCertificateChainFile /etc/pki/tls/certs/DigiCertCA.crt
  • Add to the bottom of ssl.conf but before </VirtualHost>:

     

    JkMount /__application__/* loadbalancer
       JkMountFile conf/uriworkermap.properties
  • If you are pointing to multiple jboss applications, make sure to put those JkMount statements here as well.
  • If the Apache server needs to have port 80 as well as 443 open for secure and nonsecure content, use the following to force secure connections for sites that require it. Add this to httpd.conf replacing SERVERNAMEHERE with your jboss server name:

     

    RewriteEngine On
       RewriteCond  %\{SERVER_PORT\} \!^443$
       RewriteRule ^/SERVERNAMEHERE(.*)$  https://%\{SERVER_NAME\}/SERVERNAMEHERE$1 [L,R]
       RewriteLog      "/var/log/httpd/rewrite.log"
       RewriteLogLevel 2

Notes

Some jboss applications have more than one server inside the jboss instance and these will have to be mapped via uriworkermap.properties as well. To check this:

  • Go to the jboss home directory.
  • Go to defaut/work/jboss.web/localhost •ls -al
  • Anything that isn't invoked, web-console, jbossws, jbossmq-httpil, or jmx-console, is a Jboss server instance.

What Ports

  • To see what ports jboss is configured to listen to, go to jboss home and:

     

    find * -name server.xml -exec grep -H "Connector port" \{\} \;
  • To see what ports Jboss is ACTUALLY listening to:

     

    for myport in $(ps -ef |grep jboss|grep -v grep|awk \{'print $2;'\}|xargs); do netstat -anp |grep $myport|grep LISTEN;done

Deploying OpenSpecimen in Apache Front Ending Environment

For deploying OpenSpecimen in the Apache front end JBOSS environment you need to take care of the following properties in the caTissueInstall.properties file:

  • jboss.server.host = Specify the IP address/host name of the Apache server, with which the end users are going to access the application. Here you need not specify the actual JBOSS host because that information is only required by Apache for communicating with JBOSS.
  • jboss.container.secure = Set it to true if your Apache server is running on secure port.
  • jboss.server.port = Specify the port on which the Apache server is listening (by default it listens on port 80, if you are running it on https then the port should be 443.).

Apache by default listens on both port 80 and 443 (HTTP and HTTPS).  You should properly configure the Apache server to match your deployment environment.  For example, if you are deploying OpenSpecimen with HTTPS then only port 443 should be opened.

You need to specify the JBOSS IP in the worker.properties[-i] file, and to map the application URLs
like /openspecimen you need to modify the uriworker.properties[-i] file in Apache Server.

Please note that for secure OpenSpecimen connections to work properly, SSL termination should not happen before Apache (or JBoss). For example, you should not terminate your SSL connections at the load balancer.