Using mod_jk 1.2.x with JBoss/Tomcat bundle and Apache2
Quick Overview
- Download Apache2
- Download modjk 1.2.x
- Change the main Apache config to include modjk config
- Create the modjk config
- Configure the modjk workers (which JBoss/Tomcat nodes Apache uses)
- Configure the Apache URIs served by modjk (the applications served by JBoss/Tomcat)
- Restart Apache
- Configure Tomcat (Give each JBoss/Tomcat a jvmRoute for session stickness)
- Restart JBoss
- Test it
More Details
This wiki outlines the various steps required to install a basic load-balancing solution based on JBoss/Tomcat and mod_jk 1.2.
Step #1: Download Apache2 Web Server
Get the latest Apache2 package from Apache.org and install it. We require no special configuration, just use the default settings. In the following steps, APACHE_HOME will represent the Apache install directory.
Step #2: Download mod_jk 1.2.x
Download the latest package available from Tomcats’s ‘Download Tomcat connector section’ page . Always download the latest stable release if possible.
Rename the lib mod_jk.so and drop it in APACHE_HOME/modules directory.
NOTE: Don’t use any release prior to mod_jk 1.2.15. Earlier releases are fairly buggy.
Note: Darwin Ports supports the installation of mod_jk on OS X. See http://darwinports.opendarwin.org/ for more info.
Step #3: Setup Apache to use modjk
Add this line at the very bottom in APACHE_HOME/conf/httpd.conf :
# Include mod_jk configuration file Include conf/mod-jk.conf
Step #4: Create the modjk config
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 logs/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 # Note: Changed from +ForwardURICompat. # See http://tomcat.apache.org/security-jk.html 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 # https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=225452 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>
mod_jk is ready to forward requests to JBoss instances. We need now to setup the workers
Step #5: Configuring workers
Under APACHE_HOME/conf, create workers.properties and populate it as follows:
# 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
Important: Please review http://tomcat.apache.org/connectors-doc/reference/workers.html for the directive descriptions. Especially lookout for the comments on cachsize for Apache 1.3.x.
(1) You should only set the connection_pool_size if the number of allowed connection to the Httpd is higher than maxThreads in server.xml
If you specify worker.loadbalancer.sticky_session=Off, each request will be load balanced between node1 and node2. But when a user opens a Session on one server, it is a good idea to always forward this user’s requests to the same server. Otherwise the user’s session data would need to be synchronized between both servers. This is called a “sticky session”, as the client is always using the same server he reached on his first request. Session stickiness is enabled by default.
Side Note: a non-loadbalanced setup with a single node required the “worker.list=node1” entry before mod_jk would function correctly. Without this setting I would only get a 500 error and no other useful messages in log or otherwise. -Harlequin516
Side Note: I tried both loadbalanced and single node methods on Fedora 4. Both setups causing jk.shm errno=13 and jk-runtime-status errno=13 in the mod_jk.log. Could only get 500 errors. As a last resort disabled selinux on apache server. Restarted service and connection was made first try. -paulbrown
Step #6: Create the URI to worker map file
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:
# Simple worker configuration file # # Mount the Servlet context to the ajp13 worker /jmx-console=loadbalancer /jmx-console/*=loadbalancer /web-console=loadbalancer /web-console/*=loadbalancer
This will configure mod_jk to forward requests to /jmx-console and /web-console to Tomcat. Step #7: Restart Apache
Step #8: Configure Tomcat
To complete the configuration, we also need to name each node accordingly to the names specified in workers.properties.
Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/server.xml (replace /all with your own server name)
Locate the <Engineā¦.> element and add an attribute jvmRoute:
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1"> . </Engine>
The jvmRoute attribute must match the name specified in workers.properties. In the server.xml file, make sure that the AJP 1.3 Connector is uncommented, e.g.:
<!-- A AJP 1.3 Connector on port 8009 --> <Connector port="8009" address="${jboss.bind.address}" emptySessionPath="true" enableLookups="false" redirectPort="8443" protocol="AJP/1.3"/>
If you are only accepting requests via mod_jk, you can comment out the regular HTTP Connector; Tomcat then won’t listen on port 8080.
Step #9: Activate the UseJK Valve in JBoss (not needed with Tomcat Standalone)
Finally, we need to tell Tomcat to add the jvmRoute value to its session cookies so that mod_jk can route incoming requests.
Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml (replace /all with your own server name)
Locate the <attribute> element with a name of UseJK, and set its value to “true”:
<attribute name="UseJK">true</attribute>
Note that tomcat version can be 50 or 55 depending on the AS that you use. Step #10: Restart JBoss AS.
Step #11: Access the JBoss AS web-console through Apache by browsing to http://localhost/web-console and you should see the JBoss web console page.
Note: to use mod_jk with Jboss 2 (e.g. jboss 2.4.6), you must edit jboss.jcml. Add the ‘jvmRoute=<<myWorker>>’ to the Engine element under the EmbeddedCatalinaSX? mbean.