Port Configuration

By default, Tomcat comes configured to listen for requests on port 8080. This is actually a very common test port for various web server applications and may conflict with an existing application running in the local environment. To change the port number, execute the following commands to edit the server.xml configuration file (the example uses vi, but any editor will suffice):

% cd /usr/local/tomcat/conf
% vi server.xml
        

A search for 8080 should discover the following block of XML statements:

<Server port="8005" shutdown="SHUTDOWN">
  ...
  <Service name="Catalina">
    ...
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
    ...
  </Service>
</Server>
        

In general, ports 1023 and below are commonly reserved by the system and require root user privileges to access. Ports 1024 through 49151 are sporadically used by applications registered with IANA. If the need is for another available port, than ports in the 9000 range are commonly available without conflict in most environments. The following three scenarios will help guide the port selection:

• To avoid a conflict with another application listening on port 8080, try changing the port to 8090, otherwise 9000 and above are usually unused.
• If running multiple Tomcat servers, than 8090 is still a good alternative but the shutdown and redirect ports also need to be modified so that they do not conflict with the other Tomcat server.
• If this Tomcat server is intended to respond to operational requests, then the port should be changed to 80 along with changing the redirect port to 443. The alternative to having Tomcat listen on port 80 is to have another web server (e.g., Apache HTTP Server, Microsoft IIS, etc.) listen on that port and have it redirect requests to the Tomcat server at port 8080. This type of configuration is covered in the Tomcat documentation and should also be covered in the documentation for the other web server.

Manager Interface Configuration

Another common configuration change involves enabling the Manager interface. The Manager interface is not necessary to run Tomcat but it is nice for viewing status and deploying applications. In order to enable the interface, an account must be specified in the Tomcat users configuration file with the appropriate role. Execute the following commands to edit the tomcat-users.xml configuration file:

% cd /usr/local/tomcat/conf
% vi tomcat-users.xml
        

Add the two XML statements listed below within the <tomcat-users> block.

<tomcat-users>
  ...
  <role rolename="manager-gui"/>
  <user username="<username>" password="<password>" roles="manager-gui"/>
  ...
</tomcat-users>
        

The first statement defines the manager-gui role and the second statement defines a user with that role. Replace the <username> and <password> in the second statement with desired values for the local environment. This document discusses using the Manager interface in the Deploy Application section below.

Environment Configuration

The Tomcat application server allows environment-specific variables to be set and utilized by the server. This is accomplished by creating a file named setenv.sh in the /usr/local/tomcat/bin directory. This file will be sourced by the startup script specified in the Launch Tomcat section below. To adjust the memory settings for Tomcat, the contents of the file should look something like the following:

#!/bin/sh
CATALINA_OPTS="-Xms256m -Xmx2048m -XX:MaxPermSize=256m"
        

Note: For Red Hat RPM installations, the environment variables can be specified in the /etc/tomcatX/tomcatX.conf file where X is the major version of Tomcat. Although the environment configuration is not limited to the following variables, these two are the most common:

• CATALINA_OPTS
  

  This environment variable allows the user to pass in application-specific Java properties to the applications that are deployed on the Tomcat server. In the example above, the initial and maximum memory settings for Tomcat are specified. Although exhaustive testing has not been performed, these settings have worked well in a number of environments. The location of the Derby database for the Registry Service may also be specified in this variable with the derby.system.home property. This property is described in more detail in the Installation document for the Registry Service.

• JAVA_HOME
  

  In most environments there will be one Java installation and this variable should reference the root directory of that installation (i.e., JAVA_HOME=/usr/local/java). Because Tomcat 7 and the PDS software require Java 1.6, it may have been required to install this version of Java while version 1.5 was already installed in the local environment. By referencing the Java 1.6 installation with this variable in the setenv.sh script, it allows the rest of the local environment to utilize the Java 1.5 installation.

Certificate Generation

Although a certificate can be purchased from a well-known Certificate Authority(CA) such as VeriSign or Thawte, this section will detail generating a self-signed certificate. Execute the following command to generate a self-signed certificate for the Tomcat Server:

% $JAVA_HOME/bin/keytool -genkey -alias <virtual-host-name> -keyalg RSA \
-keystore /usr/local/tomcat/.keystore
        

The <virtual-host-name> parameter above should be the name of the machine where the Tomcat Server will be accessed. The password entered in the first password prompt will be the password for the keystore where your server certificate is stored. The keytool command will prompt for additional information. The following is an example of executing the keytool command in the EN environment:

Enter keystore password:  <password>
Re-enter new password: <password>
What is your first and last name?
  [Unknown]:  Sean Hardman
What is the name of your organizational unit?
  [Unknown]:  Engineering Node
What is the name of your organization?
  [Unknown]:  Planetary Data System
What is the name of your City or Locality?
  [Unknown]:  Pasadena
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Sean Hardman, OU=Engineering Node, O=Planetary Data System, \
L=Pasadena, ST=California, C=US correct?
  [no]:  yes

Enter key password for <pdsops.jpl.nasa.gov>
  (RETURN if same as keystore password):  
        

Although the above is informational, it will help browser clients identify the source of the certificate.

SSL Configuration

After generating the server certificate, configure the Tomcat Server to enable Secure Sockets Layer (SSL) access. Execute the following commands to edit the server.xml configuration file (the example uses vi, but any editor will suffice):

% cd /usr/local/tomcat/conf
% vi server.xml
        

Configure the Tomcat Server to listen on the port 8443, with an SSL transport. Make sure the following block is not commented out and add the keystoreFile and keystorePass attributes as follows:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
          maxThreads="150" scheme="https" secure="true"
          clientAuth="false" sslProtocol="TLS" 
          keystoreFile="/usr/local/tomcat/.keystore"
          keystorePass="<password>"/>
        

The <password> value should be the password that was entered above during the certificate generation step. To enable the single sign on feature of the Tomcat server, make sure following element is not commented out:

<Valve class="org.apache.catalina.authenticator.SingleSignOn"/>
        

Additional configuration is required for each deployed application (e.g., Registry Service) to take advantage of secure access via SSL. See the Installation documents for each of those services.

User Configuration

Setup user accounts for accessing the secure Tomcat Server. These accounts must be specified in the Tomcat users configuration file with the appropriate role. Execute the following commands to edit the tomcat-users.xml configuration file:

% cd /usr/local/tomcat/conf
% vi tomcat-users.xml
        

Add the two XML statements listed below within the <tomcat-users> block.

<tomcat-users>
  ...
  <role rolename="{node}-admin"/>
  <user username="<username>" password="<password>" roles="{node}-admin"/>
  ...
</tomcat-users>
        

The first statement defines the {node}-admin role and the second statement defines a user with that role. Replace the {node} portion of the role with your PDS Node abbreviation (e.g., atm, en, geo, img, naif, ppi, rings, rs, sbn). Replace the <username> and <password> in the second statement with the desired account for the local environment.