Moab Access Portal Administrator's Guide - 1.6 Tomcat-Apache HTTP Integration

Moab Access Portal_®

1.6 Tomcat-Apache HTTP Integration

The Apache Jakarta Tomcat servlet container is one of the most popular and best supported open-source engines that Moab Access Portal_® can be run in, and when combined with the powerful open-source Apache HTTP web server, provide greater efficiency, security, and stability. Other propreitary offerings such as IBM WebSphere, BEA Weblogic, etc. provide even higher levels of support and equal performance gains. Although we recommend none of these solutions above another, this section was written to help those who wish to integrate Tomcat and HTTP in order to host the Access Portal.

1) First ensure that a recent JVM (Java Virtual Machine) is present on your system. Tomcat requires that a JVM be present in order to properly run. It is important that the Java version installed also includes tools to compile Java code, as this is used by Tomcat to compile JSP pages on the fly. The Java 2 SDK 1.4.x available from Sun Microsystems meets all of these requirements.

2) Next download both Tomcat (Apache Jakarta Project) and Apache HTTP (Apache HTTP) in preparation for installation. At time of writing we recommend Tomcat 5.0.x and Apache HTTP 2.0.x. Newer iterations are available, but at this time they are still in development and have not been extensively tested with Access Portal. Binary installation for Tomcat is almost always best, and the same goes with HTTP.

2) Next install the Tomcat binary files. Simply decompress the downloaded file to the location where you wish Tomcat to reside. (Will be referred to as $TOMCAT_HOME for the duration of this document.) The default file permissions should suffice for this stage in installation. (A comprehensive installation guide of Tomcat is beyond this document's scope. Please refer to Tomcat's own documentation for additional help and instruction.)

3) Prepare to start Tomcat by ensuring the environment variable JAVA_HOME is set and points to the location of the installed JVM. (Running which javac may reveal the root directory of the JVM.) Now execute the $TOMCAT_HOME/bin/startup.sh file to start the Tomcat service. Open a browser and abempt to access Tomcat's built-in stand-alone web server at http://hostname:8080/. If you are welcomed by Tomcat's start web page your installation has been thus far successful.

4) Proceed by installing Access Portal. Detailed instructions are given in Installing Access Portal.

5) Test Access Portal's installation by visiting, in a browser, http://hostname:8080/map/. A login screen for the Access Portal should now be visible. If not, check to ensure firewall settings are not restricting packet flow on port 8080.

6) Next install Apache HTTP web server. (A comprehensive installation guide of Apache HTTP is beyond this document's scope. Please refer to Apache HTTP's own documentation for additional help and instruction.)

7) Test the Apache installation by browsing to http://hostname/ (defaults to port 80). You should see a page confirming you successfully installed Apache. If not, check firewall settings and ensure Apache was correctly installed. A vast community of support exists for the Apache HTTP server and may be able to further assist in exceptional installation issues.

8) Prepare Apache to communicate with Tomcat via the Tomcat Connector. The recommended connector version is JK-1.2.x, as it is the most stable and best supported. Use an already compiled binary that matches your OS and version of Apache HTTP most closely. Simply copy the mod_js.so file found in the compressed installation file into the $HTTP_CONF/modules/ directory, where $HTTP_CONF is usually /etc/httpd/. Ensure it has file permissions matching those of other module files in the same directory.

9) Next copy files found in the Access Portal tools directory to the $HTTP_CONF/conf/ directory. The required files include tomcat.conf and workers.properties.

10) Next edit tomcat.conf in its new location and update each line following a CUSTOMIZE comment to reflect the configuration on your system. Save the changes and exit the file.

11) Make a backup of $HTTP_CONF/conf/httpd.conf and then open it for editing. Append the line Include $HTTP_CONF/conf/tomcat.conf to the end of the file (where $HTTP_CONF is the actual directory location.)

12) Restart Apache HTTP. (On most systems, as root, run /etc/init.d/httpd restart.)

13) Verify that Apache is now communicating with Tomcat to service JSP/Servlets and Access Portal by visiting the URL http://hostname/map/ (note that this is on port 80!) You should be directed to MAP's login screen as you were earlier when testing Tomcat's installation. Be aware it may take several seconds for Apache to create an initial connection with Tomcat.

14) Secure Tomcat by restricting access to port 8080 either with firewall settings, or by disabling the stand-alone web server built into Tomcat. You do this by commenting out the XML tag '<Connector port="8080" ...' in $TOMCAT_HOME/conf/server.xml

15) Restart Tomcat to load in configuration changes.

At this point Apache HTTP will serve all static content to users of Access Portal (html, graphics, etc.) while Tomcat will only service dynamic pages created by JSP/Servlet technologies.

1.6.2 Enabling a SSL Connection

It is often desirable to also add an additional layer of security between the end-user's browser and Access Portal by encrypting all data in a SSL connection. By default, Apache 2.x comes built with SSL support, and may already have an available secure connection. Check this by running 'netstat -tpan | grep 443'. If no output is given, you will need to perform additional configuration. (A comprehensive installation guide of SSL is beyond this document's scope. Please refer to OpenSSL and mod_ssl documentation for more complete instruction.) The next few steps give an overview of this process:

1) Ensure OpenSSL is installed on the web server machine. (Running which openssl as superuser should return a path.)

2) Ensure the Apache module mod_ssl is installed on the web server machine. (Look in $HTTP_CONF/modules.)

3) If there is already a ssl.conf file in the $HTTP_CONF/conf directory, simply include this into the httpd.conf file by appending the line Include $HTTP_CONF/conf/ssl.conf to the end of the file. If there is no ssl.conf file available, add the following to your httpd.conf file:

  LoadModule ssl_module modules/mod_ssl.so
  Listen 443
  <VirtualHost _default_:443>
    ErrorLog logs/ssl_error_log
    TransferLog logs/ssl_access_log
    LogLevel warn
    SSLEngine on
    SSLCertificateFile /etc/httpd/conf/ssl.crt/server.crt
    SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.keyA
  </VirtualHost>

4) Verify that the files $HTTP_CONF/ssl.crt/server.crt and $HTTP_CONF/ssl.key/server.key exist. If they do not exist, then a SSL key needs to be created and signed by a CA authority and copied into these locations. If you wish to create a self-signed certificate then you then execute the following commands:

  openssl genrsa -out hostname.domain.key 1024
  openssl req -new -key hostname.domain.key -out hostname.domain.csr
  openssl x509 -days 730 -req -in hostname.domain.csr -signkey hostname.domain.key -out hostname.domain.cert
  cp hostname.domain.key $HTTP_CONF/ssl.key/server.key
  cp hostname.domain.cert $HTTP_CONF/ssl.crt/server.crt
  rm hostname.domain.*

5) Restart Apache HTTP server and verify that a SSL connection is now open on the server machine. (Be wary of firewall settingsettings that may prohibit the binding of port 443!) You can use the 'netstat -tpan | grep 443' to check if HTTP has activated a secure SSL connection.

6) Finally test the SSL connection in a browser by visiting https://hostname/map/.