Important Tomcat Directories

The webapps Directory

The webapps directory is where web applications are placed to be run by Tomcat. Tomcat automatically monitors this directory and when it finds a new .war file it will attempt to install it as an application. If there is an error in the deployment, such as a problem with the file, it will report that in the the log file catalina.out.

Exercise: Do this:

ls $TOMCAT_HOME/webapps

Among other things, you should see the thredds.war file that was previously installed, and a directory called thredds. This is the TDS code. Tomcat installed the TDS automatically in a directory named threddswhen the thredds.war file was placed there.

The logs Directory

Once Tomcat has been started it will generate some log files and put them in the logs directory. The files that are generated depends on how the server is configured. Here is an example from one recent Tomcat installation using the default configuration:

[tomcat@lead3 ~/logs]$ ls -lt
total 12
-rw-r--r-- 1 tomcat leadstaff  234 Jul 26 11:49 localhost.2007-07-26.log
-rw-r--r-- 1 tomcat leadstaff 1597 Jul 26 11:49 catalina.2007-07-26.log
-rw-r--r-- 1 tomcat leadstaff 1710 Jul 26 11:49 catalina.out
-rw-r--r-- 1 tomcat leadstaff    0 Jul 26 11:49 localhost_access_log.2007-07-26.txt
-rw-r--r-- 1 tomcat leadstaff    0 Jul 26 11:49 admin.2007-07-26.log
-rw-r--r-- 1 tomcat leadstaff    0 Jul 26 11:49 host-manager.2007-07-26.log
-rw-r--r-- 1 tomcat leadstaff    0 Jul 26 11:49 manager.2007-07-26.log

ls $TOMCAT_HOME/logs

The log file catalina.out is Tomcat's main log file and can be worth watching when Tomcat is started or when an web application is placed in the webabbs directory to ensure that no errors occurred. A successful launch of Tomcat generates lots of entries in catalina.out, but that stream of entries generally ends with a line like this, which indicates a successful start up:

Jul 26, 2007 11:49:09 AM org.apache.catalina.startup.Catalina start
INFO: Server startup in 5080 ms

Similarly, if there seems to a problem in the execution of Tomcat or a web application, catalina.out is good place to look for an error. Or, just check the logs directory for the file most recently written and see if any errors are reported there.

The localhost_access_log file (such as localhost_access_log.2007-07-26.txt in the example above) is useful in both Tomcat and TDS administration because it tracks all requests made to the Tomcat server and the response given by the server. For example, this line:

128.117.156.28 - - [26/Jul/2007:11:59:54 -0700] "GET /thredds/tdr/storm/catalog.html HTTP/1.1" 200 2139

The content Directory

Exercise: Do this:

ls $TOMCAT_HOME/content

You should see the thredds directory. Now do:

ls $TOMCAT_HOME/thredds

Exercise: Do this:

        ls $TOMCAT_HOME/conf
    

The outermost element of server.xml is a Server element, which represents the entire Tomcat servlet container and defines its characteristics as a whole.

Access Logging Configuration: Valve Elements

Attributes to this valve are used to configure the information reported in the log file. Here is an example of a simple Access Log Valve that came with a recent Tomcat distribution:

<Valve className="org.apache.catalina.valves.AccessLogValve"
                 directory="logs"  prefix="localhost_access_log." suffix=".txt"
                 pattern="common" resolveHosts="false"/>

<Valve className="org.apache.catalina.valves.AccessLogValve"
                 directory="logs"  prefix="access." suffix=".log"
                 pattern="%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i" %D"
                 resolveHosts="false"/>

 128.117.126.9 - - [23/Jun/2007:23:52:42 -0600] "GET /thredds/catalog/fmrc/NCEP/GFS/Global_2p5deg/catalog.html HTTP/1.0" 200 4014 "null" "www.dlese.org,support@dlese.org" 30463

This section introduces the Tomcat authentication mechanism by describing how to enable authentication in order to use the Tomcat manager. (Enabling remote TDS management is described under Tools for Managing TDS, Using Remote Management.)

We'll start this section with background material about the Manager and the file tomcat-users.xml, then provide detailed information about the steps required to enable authentication. In a nutshell, there are two steps required to enable authentication for the Tomcat Manager:

• Configure tomcat-users.xmlwith the required role and user information
• Restart Tomcat to pick up the changes

The Tomcat Manager

Here is an example of a very simple tomcat-users.xml file:

<tomcat-users>
    <role rolename="tdrAdmin />
    <user name="Anne" password="secret" roles="tdrAdmin" />
</tomcat-users>

You can think of roles as similar to groups in Unix-like operating systems, because access to specific web application resources is granted to all users possessing a particular role (rather than enumerating the list of associated usernames). A particular user can have any number of roles associated with their username.

When a user attempts to access a protected resource for the first time, Tomcat will challenge the user for a user name and password. Once the user has been authenticated, the relevant information, including the roles to which the user was assigned, is cached for the duration of the user’s login.

tomcat-users.xml is read once when Tomcat is started. For this reason, changes to tomcat-users.xml will not be recognized until Tomcat is restarted.

Configure tomcat-users.xml with User Info and Roles

Role names such as manager should be added to the role attribute of a <user> element. The value of the role attribute can be a single value or a comma separated list of values. For example, to add the manager role to the user Anne in the above example, the result would look like this:

    <tomcat-users>
        <role rolename="tdrAdmin />
        <role rolename="manager" />
        <user name="Anne" password="secret" roles="tdrAdmin,manager" />
    </tomcat-users>

Restart Tomcat

Exercise: Modify the default tomcat-users.xml to add yourself as a user and give yourself the role of manager. Start (or restart) Tomcat, and ensure that you can access the manager application.

There are several digest algorithms. Here we will use the SHA (Secure Hash Algorithm) algorithm.

Configuring Tomcat to Use Digested Passwords

• Configure server.xml to use digested passwords
• Create the digested passwords and put them in tomcat-users.xml
• Restart Tomcat

Configure server.xml to Use Digested Passwords

      <!-- This Realm uses the UserDatabase configured in the global JNDI
      resources under the key "UserDatabase".  Any edits
      that are performed against this UserDatabase are immediately
      available for use by the Realm.  -->
      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase">

      <Realm className="org.apache.catalina.realm.MemoryRealm" digest="SHA" />

The result should look something like this:

      <!--Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase"/-->

      <!--  Added by Anne -->
      <Realm className="org.apache.catalina.realm.MemoryRealm" digest="SHA"/>

Create and Store the Digested Passwords

    $TOMCAT_HOME/bin/digest.sh -a SHA secret

    secret:e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4

If you get output like this:

    (anne) lead3: /opt/tomcat 6 % bin/digest.sh -a SHA secret
    /opt/tomcat/bin/setclasspath.sh: line 58: [: =: unary operator expected
    secret:e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4

You must the copy the digested password, the part to the right of the colon character, into tomcat-users.xml in place of the clear text password.

Restart Tomcat

    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>

We will put this same XML snippet in the web.xml file belonging to the Manager application.

In the file server/webapps/manager/WEB-INF/web.xml, find this

     <!-- Define a Security Constraint on this Application -->
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>HTMLManger and Manager command</web-resource-name>
      <url-pattern>/jmxproxy/*</url-pattern>
      <url-pattern>/html/*</url-pattern>
      <url-pattern>/list</url-pattern>
      <url-pattern>/sessions</url-pattern>
      <url-pattern>/start</url-pattern>
      <url-pattern>/stop</url-pattern>
      <url-pattern>/install</url-pattern>
      <url-pattern>/remove</url-pattern>
      <url-pattern>/deploy</url-pattern>
      <url-pattern>/undeploy</url-pattern>
      <url-pattern>/reload</url-pattern>
      <url-pattern>/save</url-pattern>
      <url-pattern>/serverinfo</url-pattern>
      <url-pattern>/status/*</url-pattern>
      <url-pattern>/roles</url-pattern>
      <url-pattern>/resources</url-pattern>
    </web-resource-collection>
    <auth-constraint>
       <!-- NOTE:  This role is not present in the default users file -->
       <role-name>manager</role-name>
    </auth-constraint>
  </security-constraint>

Now add the user-data-constraint element, like this:

     <!-- Define a Security Constraint on this Application -->
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>HTMLManger and Manager command</web-resource-name>
      <url-pattern>/jmxproxy/*</url-pattern>
      <url-pattern>/html/*</url-pattern>
      <url-pattern>/list</url-pattern>
      <url-pattern>/sessions</url-pattern>
      <url-pattern>/start</url-pattern>
      <url-pattern>/stop</url-pattern>
      <url-pattern>/install</url-pattern>
      <url-pattern>/remove</url-pattern>
      <url-pattern>/deploy</url-pattern>
      <url-pattern>/undeploy</url-pattern>
      <url-pattern>/reload</url-pattern>
      <url-pattern>/save</url-pattern>
      <url-pattern>/serverinfo</url-pattern>
      <url-pattern>/status/*</url-pattern>
      <url-pattern>/roles</url-pattern>
      <url-pattern>/resources</url-pattern>
    </web-resource-collection>
    <!-- Require use of port 8443 -->
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
    <auth-constraint>
      <role-name>manager</role-name>
    </auth-constraint>
  </security-constraint>