This section of the SECURe documentation collects together descriptions of how to carry out Tomcat administration tasks required for the installation and running of the Web servlet based software (the CAS and Shibboleth Origin). More details can be found on the Tomcat web site. Throughout this page, it is assumed that the TOMCAT_HOME environment variable has been set to refer to the directory in which your Tomcat installation has been installed, e.g.:
# export TOMCAT_HOME=/usr/local/tomcat
You will need to be the root user to carry out many of the actions described on this page.
To use the administration interface securely, you will need to have set up a Tomcat administrative user who has the privileges needed to run the manager. (The interface will ask for a user name and password when you try to access the management section.) To do this, you need to edit the Tomcat user file, which is located at $TOMCAT_HOME/conf/users/tomcat-users.xml if Tomcat is installed from a RedHat RPM, and $TOMCAT_HOME/conf/tomcat-users.xml if it was installed from source. The file should be edited to look something like:
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="tomcat"/> <role rolename="manager"/> <role rolename="admin"/> <user username="admin" password="adminpwd" roles="tomcat,admin,manager"/> </tomcat-users>
You may already have done this. Nevertheless, you need to ensure that your administrator has "manager" as one of its roles. To reload this file after making changes, you will need to restart Tomcat. (From this point onwards, you should not need to do so again.)
To restart Tomcat, there are two possible methods. If Tomcat was installed with a RedHat RPM type:
# /sbin/service tomcat4 restart
(Replace tomcat4 with the equivalent if you are running a Tomcat version other than 4.) If Tomcat has been installed from source, you need to:
# $TOMCAT_HOME/bin/shutdown.sh
and then check whether tomcat actually has shut down (it does not do so immediately, which can be confusing):
# ps -Af |grep tomcat root 14346 1 0 2003 ? 00:01:38 /usr/local/j2sdk1.4.2//bin/java -Djava.endorsed.dirs=/usr/local/tomcat/common/endorsed -classpath /usr/local/j2sdk1.4.2//lib/tools.jar:/usr/local/tomcat/bin/bootstrap.jar -Dcatalina.base=/usr/local/tomcat -Dcatalina.home=/usr/local/tomcat -Djava.io.tmpdir=/usr/local/tomca root 24136 23382 0 12:18 pts/1 00:00:00 grep tomcat
(while there is a process like the first above listed, tomcat is running). Then start again with:
# $TOMCAT_HOME/bin/startup.sh
First, copy the software .war file into the web applications directory:
# cp application.war $TOMCAT_HOME/webapps
Then, you can either restart Tomcat, or use the management interface to deploy the new software.
To access the Tomcat Management interface, go to the home page of your Tomcat installation (by default http://secure.institution.ac.uk:8080/). If your Tomcat installation has been successful, this should have an administration menu down the left hand side; the top two entries, labelled "Tomcat Administration" and "Tomcat Manager" are what concern us here. We found that the administration routines were rendered inoperable by the changes made to the Tomcat server configuration (changing the Listener in the server.xml file) to support the Shibboleth Origin. If working, however, this application can be used to manage Tomcat users and roles - usernames and passwords required to access particular applications. (Authentication as a user permitted to take on the "admin" role is required to access this application.) If the service is inoperative, it will be necessary to manage users by editing the tomcat-users.xml file as described above and restarting the Tomcat server after each change.
The Manager application permits an administrator to manage the services mounted on the Tomcat server. (To use the application, authentication as a user entitled to take on the "manager" role is required.) There are two ways to deploy a new service using this application. First, if the ".war" file containing the application is placed in the Tomcat webapps directory as described above, then simply reloading the application list will deploy it. It is also possible to load files which are stored elsewhere using the "Upload a WAR file to install" input box. (You can also load an application which is not archived as a WAR file using the section of the form above this box.) Loaded applications should appear in the application list.
When changes are made to the configuration of an application, it is necessary to reload it into the Tomcat server for the changes to take effect. This can be done by restarting the server, but this is potentially disruptive especially if errors in the configuration file prevent Tomcat from starting up correctly. It is also possible to do this using the Manager interface. Here, each service available is listed, toghether with links to perform the actions "Start", "Stop", "Reload", and "Remove" (links only operational as appropriate - you cannot stop an already stopped service). The names of the actions describe precisely what they do.
Copyright © SECURe Project Team, 2004
Document last updated: 13/03/04