tomcat setup

INSTALLATION GUIDE

Prerequisites:
- Tomcat 5.5 or above
- Ant 1.6 or above
- Java 1.5 or above

Directory structure
===================

- Authentication_Public
  - readme.txt                  (This readme file)
  - doc: documentation directory
    - readme.tx                 (This readme file)
    - User_Auth_Gateway_Specification_3.0.doc (Ken's requirement specs)
    - User_Auth_Gateway_Specification_3.0.html (Ken's requirement specs)
    - api_index.html            (Ken's API document)
    - html                      (Ken's API document)
  - c                           (Source directory for C code)
    - makefile                  (makefile containing targets for building C code)
    - net_sf_jpam_Pam.h         (JNI header file generated from src/Pam.java)
    - Pam.c                     (C code for libjpam.so)
    - pam_test.c                (Basic PAM test without JNI)
    - pam_thread_safety_test.c  (Test thread safety of PAM module)
      - net-sf-jpam             (PAM service configuration file to be copied to /etc/pam.d dir)
  - src                         (Source directory for java code)
    - setup_ant.csh             (Script for setting up java and ant environment)
    - build.xml                 (Ant build file, like makefile for gmake)
    - authUtility               (Source code for authUtility.jar used by both auth server and clients)
    - gatewayTest               (Source code for testing auth server)
    - net                       (Source code for JPam.jar)
    - servlets                  (Source codoe for servlets for auth server)
    - smbAuthentication         (Source code for authentication methods: 
  - build                       (Directory created by ant build to store class and jar files. Deleted by ant clean.)
  - WebRoot                     (Web deployment directory to be copied to tomcat)
    - smb_body2.html            (Port of login page used by WEBLOGIN servlet)
    - smb_login_header.html     (Port of login page used by WEBLOGIN servlet)
    - smb_menu.html             (Port of login page used by WEBLOGIN servlet)
    - WEB-INF                   (Containing config files for this webapp)
      - AuthGatewayApps.xml     (Config file to specify which applications can send requests to auth server)
      - AuthGatewayMethods.xml  (Config file to specify which auth methods are available)
      - AuthGatewaySystems.xml  (Config file to specify which hosts can send requests to auth server)
      - pam.prop                (Configuration file for PamAuthMethod)
      - SimpleUserDB.xml        (Configuration file for SMBAuth_SimpleUserDB auth method)
      - web.xml                 (Web app definition file mapping servlet classes and URL paths)
      - classes                 (Containing servlet classes and log4j property file)
        - log4j.properties      (Log4j config file specifying log level and output filename)
      - lib                     (Containing jar and shared library files)
        - commons-logging.jar   (Apache logging API)
        - log4j-1.2.13.jar      (Log4j)
        - authUtility.jar       (Classes used by auth server and clients)
        - gatewayTest.jar       (Tests)
        - JPam.jar              (Java interface for PAM authentication)
        - libjpam.so            (Implementation of native methods in JPam.jar for calling PAM authentication API in C)
        - smbAuthentication.jar (Authentication method classes)


Building libjpam.so
===================

1. Check out Authentication_Public from cvs.

 > cd $SRC_DIR
 > cvs co Authentication_Public

2. Build libjpam.so. For Linux x86, use make target 'libjpam.x86' and use 'libjpam.x86' for Linux x86 64-bit architecture. 
   See more target options in the Authentication_Public/c/makefile.

 > cd Authentication_Public/c
 > gmake libjpam.x86
 
   You should see libjpam.so in Authentication_Public/c directory. This shared library will be copied to WebRoot/WEB-INF/lib
   when you run ant in src directory later.
   
3. Note that net_sf_jpam_Pam.h is generated from the src/Pam.java class which defines native mathods implemented in c/Pam.c.

 > cd Authentication_Public/src
 > javac -d . -cp ${SRC_DIR}/WebRoot/WEB-INF/lib/commons-logging.jar net/sf/jpam/*.java
 > javah -jni net.sf.jpam.Pam
 > cp net_sf_jpam_Pam.h ../c
 
4. Setup PAM service configuration file by editing c/net-sf-jpam file and copy it to /etc/pam.d directory. Learn how 
   to configure this file by reading the comments in net-sf-jpam file. This file tells PAM API which authentication
   will be used to authenticate the user. Pam.c (in libjpam.so) calls pam_start with the name of the service configuration 
   file, which is net-sf-jpam in this case.
   
5. Test that PAM authentication is working by running the pam_test. Login with username and credential (i.e. password) 
   expected by the authentication modules you have setup in net-sf-jpam configuration file. If the login is successful, 
   the program will print out "...User XXX is permitted access."

 > cd Authentication_Public/c
 > gmake test
 > ./pam_test.csh
 Username: penjitk
 Password:
  
 ...Service handle was created.
 Trying to see if the user is a valid system user...
 ***Message from PAM is: Password: 
 ***Msg_style to PAM is: 1
 ***Msg_style to PAM is: PAM_PROMPT_ECHO_OFF
 ***Sending password
 ...User penjitk is permitted access.
 

Building servlets and jar files
===============================

1. Configure Java and Ant environment by editing setup_ant.csh script. You may not need to source this file if JAVA_HOME env 
   is already setup ant is already in the executable path.

 > cd Authentication_Public/src
 > vi setup_ant.csh 
 
2. Source setup_ant.csh and build the java code with build.xml
 
 > source setup_ant.csh
 > ant

All class and jar files are generated in Authentication_Public/build directory. If the build is successful, the files to be deployed
in tomcat will be copied to WebRoot/WEB-INF/classes and WebRoot/WEB-INF/lib directories as shown below. Note that libjpam.so is copied
from c directory.
 
 - WebRoot
   - WEB-INF
     - classes
       - APPFORWARD.class
       - APPLOGIN.class
       - EndSession.class
       - FRAMELOGIN.class
       - SessionStatus.class
       - EBLOGIN.class
     - lib
       - authUtility.jar
       - gatewayTest.jar
       - JPam.jar
       - smbAuthentication.jar
       - libjpam.so
       
To remove these files, use ant clean.
  
  > ant clean
  

Deploying auth server in tomcat
===============================

1. Install tomcat 5.5 or above. Follow instruction as described in http://tomcat.apache.org/tomcat-5.5-doc/setup.html. 

2. Enable SSL. Choose between using native SSL implementation (apache apr library, which, in turn, use the openssl library) 
   or the java implementation (JSSE). 
   The apr library provides a more efficient SSL implementation. If you decide to use apr, follow step 4 and skip step 5. 
   For JSSE, skip step 4 and go to step 5. 
   
3. Build and config apr library.

4. Enable SSL port by following instruction in http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html, as summarized below:

 > cd $CATALINA_HOME/conf
 > vi server.xml
 

Uncomment the "SSL HTTP/1.1 Connector" entry.
    
 

4.1. Generate private and public key, and add it to the default keystore ($HOME/.keystore file) by using keytool. 
   See http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html for more information about keytool.
   Note that the entry in the keystore, in this case, is called 'tomcat'.
   
 > keytool -genkey -alias tomcat -keyalg RSA
 
4.2 Generate a public-key certificate from the 'tomcat' entry in the above keystore. server.crt file will be created
   in the current directory. This file can be imported into its trusted certificate keystore used by a java application that wishes
   to communicate with auth server (or this tomcat) via the secure port.

 > keytool -export -alias tomcat -file server.crt
 

4.3 Generate a new keystore file and add server.crt.

 > 
 
5. 
 
6. Copy WebRoot to $CATALINA_HOME/webapps directory.

 > cd $CATALINA_HONE/webapps
 > cp -r $SRC_DIR/Authentication_Public/WebRoot gateway
 
Remove CVS directories under gateway directory.

 > cd $CATALINA_HOME/webapps/gateway
 > find . -name CVS
 
 ./CVS
 ./WEB-INF/CVS
 ./WEB-INF/classes/CVS
 ./WEB-INF/lib/CVS
 
 > rm -rf ./CVS ./WEB-INF/CVS ./WEB-INF/classes/CVS ./WEB-INF/lib/CVS
 
 6. Configure auth server by following instructions in the section below.
 
 7. Restart tomcat.
 
 > cd $CATALINA_HOME/bin
 > ./shutdown.sh
 > ./startup.sh
  
For smbws1:

 > ssh blctl@smbws1
 > sudo /etc/init.d/tomcat-auth stop
 > sudo /etc/init.d/tomcat-auth start
 
 
Configuring auth server
=======================

Configuration files are in gateway/WEB-INF directory, except for log4j.properties which is in gateway/WEB-INF/classes directory.

1. AuthGatewayApps.xml

This file contains a list of application names accepted by the authentication server. Each request contains a parameter 
called AppName, for example,

 https://smbws1.slac.stanford.edu:8447/gateway/servlet/WEBLOGIN?AppName=SMBTest&....
 
SMBTest is the application name for this request. AppName parameter must match one of the names in listed in AuthGatewayApps.xml. 
An example of the application listed in the file:

 
    SMBTest
 

2. AuthGatewayMethods.xml

This file contains definitions of authentication methods which can be performed by this authentication server. 
An example of an authentication method definition:

 
     smb_config_database
     edu.stanford.slac.ssrl.smb.authentication.SMBAuth_ConfigDB
     .slac.stanford.edu
     SMBSessionID
     /usr/local/tomcat-auth/conf/smb_login_header.html
     /usr/local/tomcat-auth/conf/smb_menu.html
     /usr/local/tomcat-auth/conf/smb_body2.html
     
        UserType
        UserPriv
        UserName
        OfficePhone
        JobTitle
        Beamlines
        UserStaff
        RemoteAccess
        Enabled
        AllBeamlines
     
 

The method name is smb_config_database, which is mapped to SMBAuth_ConfigDB class in WEB-INF/lib/smbAuthentication.jar.
If the authentication method name is specified in the request, the server will authenticated the user by using the requested 
method. Otherwise, the first method found on the list in this file will be used as a default.

 https://smbws1.slac.stanford.edu:8447/gateway/servlet/WEBLOGIN?AuthMethod=smb_config_database&....
 
Below are descriptions of auth method parameters:

name: Authentication method name
classes: Java class name, must be installed as a jar in /usr/local/tomcat-auth/webapps/gateway/WEB-INF/lib
domain: Cookie domain name.
keyname: Name of the cookie in which the session id will be stored
login_header_include: Top portion of the login page. Specify only the name, no file path. The file is expected to be in the gateway top directory.
login_body_top_include: Menu of the login page. Specify only the name, no file path. The file is expected to be in the gateway top directory.
login_body_bottom_include: Footer of the login page. Specify only the name, no file path. The file is expected to be in the gateway top directory.
auth_properties: Contaisn a list of specific properties returned (in the HTTP response header and body) by this authentication method.


3. AuthGatewaySystems.xml

This contains a list of accepted hosts from which the connection is originated. For example:

 
     134.79.28.111
     biotest.slac.stanford.edu
 
 
If the connection comes from a host not listed in this file, the server will return an HTTP error "403 forbidden".


Configuring simple_user_database authentication method
======================================================

Firstly, please note that simple_user_database should only be used for testing only.

simple_user_database authentication method will be used to authentication the user if simple_user_database
config is placed as the first method in AuthGatewayMethods.xml file or if the request URL contains parameter 
AuthMethod=simple_user_database. The method is implemented by src/smbAuthentication/SMBAuth_SimpleUserDB.java
(class file in gateway/WEB-INF/lib/smbAuthentication.jar).

This authentication method requires a config file called SimpleUserDB.xml. The file is read everytime when the 
username and password are sent to the server to be authenticated or when a session id is sent to be validated.
You can modify this file any time and new data will be realized the nex the server processes a request. 

This is a file that represents a simple user's database containing username, password and other information including
beamline access permissions. It also contains a definition of AllBeamlines, which is a list of available beamlines; and 
a list of user information. Below is an example of the file:

 
 
   
   
   
      abc
      4
      Test User 1
      1-650-555-1212
      Beamline Scientist
      ALL
      Y
      Y
      Y
   
 
 
In the above example, there is only one user in this file, JohnDoh. The password 'abc' does not have to be the real
unix password. It is used only when the user logs in on the auth server login page. The rest of the parameters are 
user's information which are returned in the HTTP response header if the login is successful or if the session 
id is successfully validated. In this example, JohnDoh has permissions to access all of the beamlines, defined 
by the 'AllBeamlines' parameter.


Configuring smb_pam method
==========================

The config of smb_pam authentication method must be placed as the first method in AuthGatewayMethods.xml or the
request URL must contain parameter AuthMethod=smb_pam for this method to be used. This method is implemented 
by src/smbAuthentication/PamAuthMethod.java (class file in gateway/WEB-INF/lib/smbAuthentication.jar).

This authentication method uses PAM API to authenticate username and password. User information including
beamline access permissions returned in the HTTP response, if the authentication is successful, is read 
from SimpleUserDB.xml file like in the case of simple_user_database method described above.

This method requires two config files: pam.prop and SimpleUserDB.xml. It authenticates the user by passing 
the username and password to PAM authentication API to be authenticated by the designated authentication modules.
The authentication modules is specified in PAM service configuration file in /etc/pam.d directory. By default,
this smb_pam authentication method uses net-sf-jpam service, which corresponds to /etc/pam.d/net-sf-jpam file.

If you want to use a different PAM service, you will need to modify pam.prop and set pamModule config accordingly.

- pam.prop is read once at when the server starts up. It specifies PAM service name, for example, net-sf-jpam. See the above 
section 'Building libjpam.so' for more detail about this file. The service name specified by pamModule config in 
pam.prop must correspond to a file name in /etc/pam.d directory. This file specifies which authentication modules 
to be used to authenticate the user.

The other config you can set in this file is pamLibPath which is a path to libjpam.so. By default this config is 
set to libjpam.so without a directory path. The default directory path is gateway/WEB-INF/lib. If this config is
not set, the library is assumed to be gateway/WEB-INF/lib/libjpam.so.

- SimpleUserDB.xml is the same as the one used by simple_user_database authentication method except that the password
parameter is not used (because PAM authentication is used instead to authenticate the username and password).


Testing auth server
===================

1. Test if tomcat is running and accepting requests on non-secure and secure port by entering the following URLs in
   a browser. For example, if the non-secure port is 8080 and secure port is 8443:
   
 http://:8080
 https://:8443
   
For smbws1:

 http://smbws1.slac.stanford.edu:8084
 https://smbws1.slac.stanford.edu:8447

   
2. Test if the auth server working by entering the following URL in a browser:

 https://:8443/gateway/servlet/WEBLOGIN?AppName=SMBTest&URL=https://:8443/gateway/servlet/SessionStatus?AppName=SMBTest
 
You should see a login page that asks you to enter a username and password. In this case the default authentication 
method will be used. Enter a valid username and password according to this authentication method. If the login is successful, 
the server will return user's information in the HTTP response, for example:

 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=612E206DA247303C9F3EE4CE746682CF
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1189813780411
 Auth.SessionAccessed=1189813798942
 Auth.UserID=penjitk
 Auth.Method=smb_config_database
 Auth.AllBeamlines=BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 Auth.UserType=UNIX
 Auth.RemoteAccess=Y
 Auth.Enabled=Y
 Auth.UserPriv=4
 Auth.UserName=Beam Line Control
 Auth.JobTitle=
 Auth.Beamlines=ALL
 Auth.OfficePhone=
 Auth.UserStaff=Y 


For smbws1, enter the following URL.

 https://smbws1.slac.stanford.edu:8447/gateway/servlet/WEBLOGIN?AppName=SMBTest&URL=https://smbws1.slac.stanford.edu:8447/gateway/servlet/SessionStatus?AppName=SMBTest


3. Test login and session id validation by using a test classes in WebRoot/WEB-INF/lib/gatewayTest.jar 
and scripts in src/gatewayTest directory. Enter a valid username and password according you authentication method,
and enter a valid servlet host and port for your auth server.
   
 > cd Authentication_Public/src/gatewayTest
 > ./authgatewaybeantest.csh
 Username: penjitk
 Password:
 servletHost [https://smbws1.slac.stanford.edu:8447]:
 
The test sends a request to auth server to authenticate the username and password. If the login is successful, it will 
go into an infinite loop to validate the session id returned from the login. 


If you specify https in servletHost, first, you will have to import the server certificate as its trusted certificate in a keystore.
The generation of the server certificate is described in the secion 'Deploying auth server in tomcat' above. Use keytool 
to import the certificate:

 > cd Authentication_Public/src/gatewayTest
 > cp $CATALINA_HOME/conf/server.crt .
 > keytool -import -keystore authcerts -alias auth -file server.crt

The command will create a keystore called 'authcerts' and an entry for this certificate called 'auth'. The keystore is saved
as a file called 'authcerts' in the current directory. authgatewaybeantest.csh starts the JVM with '-Djavax.net.ssl.trustStore=authcerts',
which specifies that it will accept an certificates stored in authcerts keystore.

To print out the certificate in a readable format:

 > keytool -printcert -file server.crt
 
To list all certificates in the keystore:

 > keytool -list -keystore authcerts

If the certificate is not imported correctly into the keystore and if the javax.net.ssl.trustStore option is not set to the
keystore that contains this certificate, the test program will produce the following error:

 Exception in thread "main" javax.net.ssl.SSLHandshakeException: java.security.ce
 rt.CertificateException: Couldn't find trusted certificate
       at com.sun.net.ssl.internal.ssl.BaseSSLSocketImpl.a(DashoA6275) 
 

4. How to test GetOneTimeSession
- Check that the one-time session can only be validated once.
- Check that the one-time session can not be used to generate another one-time session.

4.1 Create a session if by sending a username and password to the authentication server. Open the following URL in a browser and enter username and password:

 https://smbws1.slac.stanford.edu:8447/gateway/servlet/WEBLOGIN?AppName=SMBTest&URL=https://smbws1.slac.stanford.edu:8447/gateway/servlet/SessionStatus?AppName=SMBTest
 
You should see something like the following as a returned page:

 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=EA3DAAA1656F4B61E4F439294A3A8CC1
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1190321742648
 Auth.SessionAccessed=1190321748617
 Auth.UserID=blctl
 Auth.Method=smb_config_database
 Auth.AllBeamlines=BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 Auth.UserType=UNIX
 Auth.RemoteAccess=Y
 Auth.Enabled=Y
 Auth.UserPriv=4
 Auth.UserName=Beam Line Control
 Auth.JobTitle=
 Auth.Beamlines=ALL
 Auth.OfficePhone=
 Auth.UserStaff=Y

The session id is EA3DAAA1656F4B61E4F439294A3A8CC1 which can be reused until the session expires.

4.2 Create a one-time session from the session id from step 4.1. Open a new terminal and run telnet:

 > ssh smbdev1
 > telnet smbws1.slac.stanford.edu 8084
 Trying 134.79.31.29...
 Connected to smbws1.slac.stanford.edu (134.79.31.29).
 Escape character is '^]'.
 GET /gateway/servlet/GetOneTimeSession?SMBSessionID=DA3ED6C97247E3E9401FDE1F5CDC7649&AppName=SMBTest&RecheckDatabase=True HTTP/1.1
 Host: smbws1.slac.stanford.edu:8084
 Connection: close
 
The response is like the following: 

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=596BA9A052D487737B41A384E47F4807; Path=/gateway
 Auth.SessionKey: SMBSessionID
 Auth.SMBSessionID: 596BA9A052D487737B41A384E47F4807
 Auth.SessionValid: TRUE
 Auth.SessionCreation: 1190321863276
 Auth.SessionAccessed: 1190321863276
 Auth.UserID: blctl
 Auth.Method: smb_config_database
 Auth.OneTimeSession: TRUE
 AllBeamlines: BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 UserType: UNIX
 RemoteAccess: Y
 Enabled: Y
 UserPriv: 4
 UserName: Beam Line Control
 Beamlines: ALL
 JobTitle: 
 OfficePhone: 
 UserStaff: Y
 Content-Type: text/plain;charset=ISO-8859-1
 Content-Length: 443
 Date: Thu, 20 Sep 2007 20:57:43 GMT
 Connection: close
 
 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=596BA9A052D487737B41A384E47F4807
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1190321863276
 Auth.SessionAccessed=1190321863276
 Auth.UserID=blctl
 Auth.Method=smb_config_database
 Auth.OneTimeSession=TRUE
 AllBeamlines=BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 UserType=UNIX
 RemoteAccess=Y
 Enabled=Y
 UserPriv=4
 UserName=Beam Line Control
 Beamlines=ALL
 JobTitle=
 OfficePhone=
 UserStaff=Y
 Connection closed by foreign host.
 
The one-time session id we have just generated is 596BA9A052D487737B41A384E47F4807.

4.3 Check that one-time session id from step 4.2 is valid. Run telnet again.

 > telnet smbws1.slac.stanford.edu 8084
 Trying 134.79.31.29...
 Connected to smbws1.slac.stanford.edu (134.79.31.29).
 Escape character is '^]'.
 GET /gateway/servlet/SessionStatus;jsessionid=B26432A85C97E6154022E7B40F71AF23?AppName=SMBTest&RecheckDatabase=True HTTP/1.1
 Host: smbws1.slac.stanford.edu:8084
 Connection: close

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Auth.SessionKey: SMBSessionID
 Auth.SMBSessionID: B26432A85C97E6154022E7B40F71AF23
 Auth.SessionValid: TRUE
 Auth.SessionCreation: 1190321770968
 Auth.SessionAccessed: 1190321770968
 Auth.UserID: blctl
 Auth.Method: smb_config_database
 Auth.OneTimeSession: TRUE
 Auth.AllBeamlines: BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 Auth.UserType: UNIX
 Auth.RemoteAccess: Y
 Auth.Enabled: Y
 Auth.UserPriv: 4
 Auth.UserName: Beam Line Control
 Auth.Beamlines: ALL
 Auth.JobTitle: 
 Auth.OfficePhone: 
 Auth.UserStaff: Y
 Content-Type: text/plain;charset=ISO-8859-1
 Content-Length: 493
 Date: Thu, 20 Sep 2007 20:57:15 GMT
 Connection: close

 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=B26432A85C97E6154022E7B40F71AF23
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1190321770968
 Auth.SessionAccessed=1190321770968
 Auth.UserID=blctl
 Auth.Method=smb_config_database
 Auth.OneTimeSession=TRUE
 Auth.AllBeamlines=BL1-5;BL7-1;BL9-1;BL9-2;BL11-1;BL11-3
 Auth.UserType=UNIX
 Auth.RemoteAccess=Y
 Auth.Enabled=Y
 Auth.UserPriv=4
 Auth.UserName=Beam Line Control
 Auth.Beamlines=ALL
 Auth.JobTitle=
 Auth.OfficePhone=
 Auth.UserStaff=Y
 Connection closed by foreign host.
 
4.4 Repeat step 4.3 to prove that it can not be validated twice. This time you should get the following response:

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Auth.SessionKey: NA
 Auth.NA: NA
 Auth.SessionValid: FALSE
 Auth.SessionCreation: NA
 Auth.SessionAccessed: NA
 Auth.UserID: NA
 Auth.Method: NA
 Content-Type: text/plain;charset=ISO-8859-1
 Content-Length: 139
 Date: Thu, 20 Sep 2007 20:57:22 GMT
 Connection: close

 Auth.SessionKey=NA
 Auth.NA=NA
 Auth.SessionValid=FALSE
 Auth.SessionCreation=NA
 Auth.SessionAccessed=NA
 Auth.Method=NA
 Connection closed by foreign host.
 
 
Test auth server with telnet and openssl
========================================

1. Test HTTP  with telnet.

 > telnet smbws1.slac.stanford.edu 8084
 Trying 134.79.31.29...
 Connected to smbws1.slac.stanford.edu (134.79.31.29).
 Escape character is '^]'.
 GET http://smbws1.slac.stanford.edu:8084/gateway/servlet/SessionStatus;jsessionid=67E5B496AD10785154DA3C3BE58AD392?AppName=SMBTest HTTP/1.1
 Host: smbws1.slac.stanford.edu:8084
 Connection: close
 
The response is as follows:

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=67E5B496AD10785154DA3C3BE58AD392; Path=/gateway
 Auth.SessionKey: SMBSessionID
 Auth.SMBSessionID: 67E5B496AD10785154DA3C3BE58AD392
 Auth.SessionValid: TRUE
 Auth.SessionCreation: 1192124956079
 Auth.SessionAccessed: 1192124956079
 Auth.UserID: bluser
 Auth.Method: smb_config_database
 Auth.OneTimeSession: TRUE
 Content-Type: text/plain;charset=ISO-8859-1
 Content-Length: 257
 Date: Thu, 11 Oct 2007 17:49:15 GMT
 Connection: close
 
 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=67E5B496AD10785154DA3C3BE58AD392
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1192124956079
 Auth.SessionAccessed=1192124956079
 Auth.UserID=bluser
 Auth.Method=smb_config_database
 Auth.OneTimeSession=TRUE
 
 Connection closed by foreign host.
 
 2. Test HTTPS with openssl.
 
 > openssl s_client -quiet -connect smbws1.slac.stanford.edu:8447
 depth=0 /C=US/ST=California/L=Menlo Park/O=Stanford Linear Accelerator Center/OU=SSRL Macromolecular Crystallography/CN=smbws1.slac.stanford.edu/emailAddress=thomas.eriksson@slac.stanford.edu
 verify error:num=18:self signed certificate
 verify return:1
 depth=0 /C=US/ST=California/L=Menlo Park/O=Stanford Linear Accelerator Center/OU=SSRL Macromolecular Crystallography/CN=smbws1.slac.stanford.edu/emailAddress=thomas.eriksson@slac.stanford.edu
 verify return:1 
 GET /gateway/servlet/SessionStatus;jsessionid=67E5B496AD10785154DA3C3BE58AD392?AppName=SMBTest HTTP/1.1
 Host: smbws1.slac.stanford.edu:8447
 Connection: close
 
The response is as follows:

 HTTP/1.1 200 OK
 Server: Apache-Coyote/1.1
 Set-Cookie: JSESSIONID=67E5B496AD10785154DA3C3BE58AD392; Path=/gateway
 Auth.SessionKey: SMBSessionID
 Auth.SMBSessionID: 67E5B496AD10785154DA3C3BE58AD392
 Auth.SessionValid: TRUE
 Auth.SessionCreation: 1192124956079
 Auth.SessionAccessed: 1192124956079
 Auth.UserID: bluser
 Auth.Method: smb_config_database
 Auth.OneTimeSession: TRUE
 Content-Type: text/plain;charset=ISO-8859-1
 Content-Length: 257
 Date: Thu, 11 Oct 2007 17:49:15 GMT
 Connection: close
 
 Auth.SessionKey=SMBSessionID
 Auth.SMBSessionID=67E5B496AD10785154DA3C3BE58AD392
 Auth.SessionValid=TRUE
 Auth.SessionCreation=1192124956079
 Auth.SessionAccessed=1192124956079
 Auth.UserID=bluser
 Auth.Method=smb_config_database
 Auth.OneTimeSession=TRUE


Troubleshooting
===============

- Tomcat crashing with the following output in catalina.out. See http://issues.apache.org/bugzilla/show_bug.cgi?id=40925 for an 
existing bug report on tomcat website. Seems like the apr (Apache Portable Runtime) could be the culprit.

Info about apr: http://tomcat.apache.org/tomcat-5.5-doc/apr.html. This document suggests versions libraries:

*APR 1.2+ development headers (libapr1-dev package)
*OpenSSL 0.9.7+ development headers (libssl-dev package)
*JNI headers from Java compatible JDK 1.4+
*GNU development environment (gcc, make)

Use the following command to find out the version number of the shared library on your machine:

*rpm -qi apr
*rpm -qi openssl

The shared libraries used by tomcat is speicied in $CATALINA_HOME/bin/setenv.sh, as -Djava.library.path=/usr/local/apr/lib. 
The apr library is build in /usr/local/tomcat/src/apr/



Excerpt of the error messages from catalina.out:

 #
 # An unexpected error has been detected by HotSpot Virtual Machine:
 #
 #  SIGSEGV (0xb) at pc=0x6ca297e0, pid=14532, tid=1758460832
 #
 # Java VM: Java HotSpot(TM) Server VM (1.5.0_12-b04 mixed mode)
 # Problematic frame:
 # C  [libapr-1.so.0+0x187e0]  apr_pollset_remove+0x18
 #
 # Can not save log file, dump to screen..
 #
 # An unexpected error has been detected by HotSpot Virtual Machine:
 #
 #  SIGSEGV (0xb) at pc=0x6ca297e0, pid=14532, tid=1758460832
 #
 # Java VM: Java HotSpot(TM) Server VM (1.5.0_12-b04 mixed mode)
 # Problematic frame:
 # C  [libapr-1.so.0+0x187e0]  apr_pollset_remove+0x18
 #
 
 ---------------  T H R E A D  ---------------
 
 Current thread (0x6bd545c0):  JavaThread "http-8447-45" daemon [_thread_in_native, id=19889]
 
 siginfo:si_signo=11, si_errno=0, si_code=1, si_addr=0x00000018
 .
 .
 .
 Stack: [0x68c7f000,0x68d00000),  sp=0x68cfec10,  free space=511k
 Native frames: (J=compiled Java code, j=interpreted, Vv=VM code, C=native code)
 C  [libapr-1.so.0+0x187e0]  apr_pollset_remove+0x18
 C  [libtcnative-1.so.0.1.6+0x110b0]
 C  [libtcnative-1.so.0.1.6+0x113af]  Java_org_apache_tomcat_jni_SSLSocket_handshake+0x117
 
 Java frames: (J=compiled Java code, j=interpreted, Vv=VM code)
 J  org.apache.tomcat.jni.SSLSocket.handshake(J)I
 J  org.apache.tomcat.util.net.AprEndpoint.setSocketOptions(J)Z
 J  org.apache.tomcat.util.net.AprEndpoint$Worker.run()V
 v  ~I2CAdapter
 j  java.lang.Thread.run()V+11
 v  ~StubRoutines::call_stub

 ---------------  P R O C E S S  ---------------
 .
 .
 . 


Symtoms
=======
- Tomcat JVM crashs after 1 day of multi-client test: 15 client processes, each sending 1 request between 0 - 200 msec interval (around 10 requests/second). All processes combined
will make average about 150 requests/second. apr version 0.9.4. 
- If the requests are sent via HTTPS, the tomcat will crash after about 1 day.
- Does it have anything to do with using HTTPS? Requests sent via HTTP instead of HTTPS.
- Does it have anything to do with DB connection (which is HTTPS or HTTP?)? Use simple user db method instead of MySQL method.
- Can we printout debug message from 


Related links
=============

*A more complete installation guide in /home/webserverroot/servlets/tomcat-smbws1/Authentication_Public/doc/readme.txt and /home/webserverroot/servlets/tomcat-smbws1/MySQLAuthMethod/doc/readme.txt. Or check out Authentication_Public and MySQLAuthMethod
and see the readme.txt file in doc directory.

JNI:
*http://java.sun.com/docs/books/jni/download/jni.pdf

Log4j:
*http://logging.apache.org/log4j/1.2/manual.html

Enabling SSL for tomcat:
*http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html
*http://mircwiki.rsna.org/index.php?title=Configuring_Tomcat_to_Support_SSL
*http://tomcat.apache.org/tomcat-5.5-doc/apr.html

Java security:
*http://java.sun.com/developer/technicalArticles/Security/secureinternet2/
*http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html
*http://java.sun.com/docs/books/tutorial/security/sigcert/index.html
*http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html

Openssl:
*http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html
*http://www.openssl.org/docs
*http://mark.foster.cc/wiki/index.php/OpenSSL_to_Keytool_Conversion_tips
*http://mark.foster.cc/wiki/index.php/Keytool_to_OpenSSL_Conversion_tips