SSL Setup Notes: 3.2.2 via Apache

[Keith Elliott <ke...@nurelm.com>]

Hi folks,
 
I just setup Apache to talk to Tomcat via SSL.  The available docs were
helpful, 
but there were a couple holes (which are probably clarified in the
recent docs, 
but I’m still using 3.2.2).
 
If it helps, here are the notes I took when getting everything rolling:
 
======================================================================
How to Make Apache talk to Tomcat via SSL:
======================================================================
Keith Elliott, NuRelm, Mar. 19, 2002
 
 
Setup httpd.conf/mod_jk to use the AJP13 connection protocol (not AJP12)

to communicate between Apache and Tomcat.
 
Configure Apache:
 
Let's pick apart our Apache config as of 3/13/2002...
 
## Tomcat Integration:
LoadModule jk_module modules/mod_jk.so
<IfModule mod_jk.c>
JkWorkersFile /usr/local/tomcat/conf/workers.properties
JkLogFile  logs/jk.log
JkLogLevel warn
JkMount /*.jsp ajp12
JkMount /servlet/* ajp12
JkMount /examples/* ajp12
JkMount /login ajp12
</IfModule>
 
We LoadModule, but we do not AddModule.  Does this matter?  The Apache 
docs state that LoadModule loads an external module AND adds a module
for 
use.  The AddModule directive enables the use of modules that are
compiled
into Apache, but not turned-on.  So, if you use LoadModule, you don't
need
to use AddModule.  I've seen folks use AddModule anyway, so I guess it
does
not hurt anything.
 
Why do we use IfModule?  What does it do?  The IfModule directive tests
to
see if the listed module is included in Apache -- either compiled in or
dynamically loaded using LoadModule.  If so, then the nested statements
are
processed.  We don't need to use IfModule, because we always load mod_jk
just before we execute its directives.
 
JkWorkersFile is required.  This tells mod_jk where your
workers.properties
file lives.  The workers.properties file is used to describe instances
of
Tomcat that are hanging out, ready to process requests.  We've been
using the
default file that came with 3.2.2 on a production machine for over a
year - so
you probably don't need to mess with it.  I just began looking into
adding SSL
capability, so I checked to make sure that a default setup was included
for
AJP13.  It is, and I didn't mess with it.  One AJP13 property of
interest is
cachesize.  It is commented out in our default workers.properties.  From
Tomcat-Workers-HowTo.html...
 
  "cachesize specifies the number of open socket connections that the
worker
   will keep. By default this value is 1, but multithreaded web servers
such
   as Apach2.xx, IIS and Netscape will benefit the most by setting this
value 
   to a higher level (such as the estimated average concurrent users for
   Tomcat)."
 
Also from Tomcat-Workers-HowTo.html...
 
  "The ajp12, ajp13 and lb worker definitions can work without modifying
the
   default workers.properties file. However to make the jni worker come
into
   life you should set the following properties in the file:
 
   workers.tomcat_home - Have it point to your tomcat_home. E.g. 
                         wrkers.tomcat_home=c:\jakarta-tomcat 
   workers.java_home - Have it point to where you placed your JDK. E.g. 
                       workers.java_home=c:\jdk1.2.2 
   ps - Have it point to the file system separator of your OS. E.g. ps=\
"
 
We don't use JNI, so I didn't mess with the above properties.
 
In summary, you don't need to update workers.properties to make it work
with
SSL & AJP13.
 
JkLogFile & JkLogLevel are self explanatory.  The possible log levels
are
debug, info, error and emerg; info is the default.  I don't know where
we got
"warn".  Our jk.log file was never created after running for a year.  Oh
Well.
 
JkMount assigns URLs to Tomcat, and defines the "Worker" that handles
the
requests.  "Workers" refers to the protocol that handles the
communication.  
We set them all to ajp12, we should simply change it to ajp13 to handle
SSL.  
 
Note our /login setup (shown below).  We allow users to hit 
www.whatever.com/login to view their login page.
Our web.xml files add "/login" as a servlet alias.  If you don't tell
Apache
to let Tomcat handle it via a JKMount directive, then Apache will
attempt to
find the /login directory and present a 404 message.  Our web.xml files 
redirect /login to our LoginController.
 
  <servlet>
    <servlet-name>login</servlet-name>
 
<servlet-class>com.nurelm.client.security.LoginController</servlet-class
>
  </servlet>
  <servlet-mapping>
    <servlet-name>login</servlet-name>
    <url-pattern>/login</url-pattern>
  </servlet-mapping>
 
I'll remove the "JkMount /examples/* ajp12" line.  We don't use it.
 
Next, Configure Tomcat:
 
http://jakarta.apache.org/tomcat/tomcat-3.2-doc/mod_jk-howto.html says
to 
add the following block should be included in server.xml.
 
   <RequestInterceptor
     className="org.apache.tomcat.modules.server.Ajp13Interceptor"
     port="8009"/>
 
I did that and it did not work.  I studied the server.xml file and added
the
following block (copying that AJP12 connector just above it):
 
   <!-- Apache AJP13 support. Added by KTE on March 17, 2002.  
        I'm guessing that 13 is just like 12, but 13 listens on 8009
   -->
   <Connector className="org.apache.tomcat.service.PoolTcpConnector">
     <Parameter name="handler" 
 
value="org.apache.tomcat.service.connector.Ajp13ConnectionHandler"/>
     <Parameter name="port" value="8009"/>
   </Connector>
 
That's it!  Now if you setup SSL and serve up JSPs, it seems to work.  I
have
not tested it thoroughly, but initial tests work fine.
 
I did hit one snag:  I had an old copy of mod_jk.so which required
Apache to
be restarted after each Tomcat restart (it'd give Internal Server Error 
messages.   The mod_jk-howto.html doc states that mod_jk is not
dependent on
the version of Tomcat (you can use the 3.3 distribution under 3.2).  So
I
grabbed
http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3/bin/linux/i
386/mod_jk-3.3-ap13-eapi.so.  
After replacing the old mod_jk.so file, the restart problem is gone.
 
 
Virtual Hosting Notes:
 
The Apache docs state that you need a separate IP for each virtual host
that
uses SSL (b/c of the SSL protocol).  Since I didn't like the sound of
this, 
I researched it a while.
 
Conclusion:  You do need a separate IP for each virtual host.  It's
really 
not that big of a deal.  Just set up the virtual host using the IP-based

scheme instead of the name based scheme.  Rackspace will provide you w/ 
multiple IPs for $2/mo.