Version 29

    Using mod_jk 1.2.x with JBoss/Tomcat bundle and IIS 4.x or 5.x

     

    Overview

     

    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: Install IIS Web Server

     

    For Windows XP/2000 Users

    1. Control Panel

    2. Add or Remove Programs

    3. Add/Remove Windows Components

    4. Check Internet Information Services (IIS) box

     

    Step 2: Download/Install mod_jk 1.2.x

     

    Download and run the latest "isapi_redirect-1.2.x.exe" available from Jakarta's 'binary downloads' pageAgain, make sure you download mod_jk1.2 (JK 1.2 Binary Releases).

     

     

    • Note:* Some of the jk distributions do not include a msi or exe file.  In those cases, just download the isapi.dll, and then create a directory for isapi, such as C:\isapi_redirect-1.2.x\, and add the following subtree to this directory:

    • Note:* It is highly discouraged to run any mod_jk version pre 1.2.27 as there are a few security flaws along with one bug that breaks sticky sessions.

     

    conf\uriworkermap.properties

     

    conf\workers.properties.minimal

     

    bin\isapi_redirect.dll

     

    log\

     

     

     

    ISAPI_REDIRECT_HOME will represent the mod_jk install directory.

     

    • Note: ensure that isapi_redirect.dll has the appropriate read & execute permissions in the OS. e.g., if the website is going to access the isapi filter using anonymous user access, then the IIS internal user, typically IUSR_[MACHINENAME], must have read & execute permissions on isapi_redirect.dll. If this is not done, you may get 401.3 errors.

     

     

    +

    • Note:* the below conf files only work with mod-jk 1.2.10 (or higher), 1.2.6 does not support several of the directives given

     

    Note: if there is no executable available at the download site, use the following instructions on how to configure mod_jk for IIS (involves manual registry and IIS configuration): http://tomcat.apache.org/connectors-doc/webserver_howto/iis.html

     

    +

     

    mod_jk is ready to forward requests to JBoss instances. We need now to setup the workers.

     

     

     

    Step 3: Configuring Workers

    Under ISAPI_REDIRECT_HOME/conf/, modify the workers.properties.minimal to be:

     

    For Load Balanced (Multiple Node Configs)

                  # Define list of workers that will be used
                  # for mapping requests
                  
                  # Define Node1
                  worker.node1.port=8009
                  worker.node1.host=node1.mydomain.com
                  worker.node1.type=ajp13
                  worker.node1.lbfactor=1 
                  #ping_mode as of mod_jk 1.2.26
                  worker.node1.ping_mode=A
                  worker.node1.socket_timeout=10
    
                  # Define Node2
                  worker.node2.port=8009
                  worker.node2.host=node2.mydomain.com
                  worker.node2.type=ajp13
                  worker.node2.lbfactor=1 
                  #ping_mode as of mod_jk 1.2.26
                  worker.node2.ping_mode=A
                  worker.node2.socket_timeout=10
    
                  # Load-balancing behaviour
                  worker.loadbalancer.type=lb
                  worker.loadbalancer.balance_workers=node1, node2
                  worker.loadbalancer.sticky_session=0
                  worker.list=loadbalancer
    
                  # Status worker for managing load balancer
                  worker.status.type=status
    
    

     

    For Non-Load Balanced (Single Node Configs)

                # Define list of workers that will be used
                # for mapping requests            
                worker.list=node1
                  
                # Define Node1
                worker.node1.port=8009
                worker.node1.host=node1.mydomain.com
                worker.node1.type=ajp13
                #ping_mode as of mod_jk 1.2.26
                worker.node1.ping_mode=A
                worker.node1.socket_timeout=10
                
    
                # Status worker for managing load balancer
                worker.status.type=status
    
    

    (1) local_worker should be commented out to enable load-balancing. Otherwise, only fail-over is available.

     

    Basically, this configures mod_jk to perform weighted round-robin load balancing with sticky sessions between two servlet containers node1 and node2(aka: Tomcat) listening on port 8009.

     

    If you specify worker.loadbalancer.sticky_session=0, 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.

    To enable session stickiness, you need to set worker.loadbalancer.sticky_session to 1.

     

    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

     

    Step 4: Create the URI to worker map file

     

    Edit uriworkermap.properties file in the ISAPI_REDIRECT_HOME/conf directory.  This file should contain the URL mappings you want IIS 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
    

    This will configure mod_jk to forward requests to /jmx-console to Tomcat.

     

    Step 5: Re-start IIS

     

    1. Control Panel

    2. Administrative Tools

    3. Services

    4. World Wide Web Publishing

    5. Restart

     

    ISAPI_REDIRECT_HOME/log/isapi_redirect.txt - will log errors if you've mis-configured mod_jk

     

    note: If you change the your workers.properties.minimal or uriworkermap.properties file at any time, you must restart the actual SERVICE "World Wide Web Publishing", not just restart the website from within the IIS console.  Otherwise, your changes will NOT be picked up!  Thanks Bill!

     

    +

    • Note:* Go to the Default Web Site in your Web Sites Directory in IIS and view Properties, go to the tab ISAPI Filters, in you haven't got the Jakarta Filter you installed, add the filter (the executable file is "isapi_redirect.dll" in ISAPI_REDIRECT_HOME/bin )and restart IIS.

    +

     

    Step 6: Configure Tomcat

     

    To complete the configuration, we also need to name each node accordingly to the names specified in workers.properties.   Also don't forget to set connectionTimeout="600000" on the AJP connector.

     

    Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/server.xml (replace /all with your own server name)

     

    Locate the <Engine&133;.> 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.

     

    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

    element with a name of UseJK, and set its value to "true":

                   <attribute name="UseJK">true</attribute>
    

     

    Step 7: Restart JBoss AS.

     

    Step 8: Access the JBoss AS jmx-console through Apache by browsing to http://localhost/jmx-console and you should see the JBoss JMX console page.

     

    Troubleshooting

     

    HTTP 500 Internal Server Error with Windows XP Professional and IIS 5.1 if you keep getting HTTP 500 errors with the Tomcat Connector IIS ISAPI redirector then check your Windows Event Viewer log.  If you see the error 'Class not registered' then your IIS install is broken.  You need to reinstall COM+ and then possibly correct the security settings of the Microsoft Distributed Transaction Coordinator.

     

    The famous Class not registered

     

    COM+ Errors and Component Services Problems

     

    Resources

     

    JBoss Clustering Guide: Additional details about HTTP Session replication, workers.properties and other goodies.

     

    Using mod_jk 1.2.x with JBoss/Tomcat bundle and Apache2

     

    Configuring Tomcat and Apache With JK 1.2

     

    Tomcat - Workers HowTo

     

    Tomcat user-mail archive

     

    mod_jk FAQ