http://www.unidata.ucar.edu/projects/THREDDS/tech/ tutorial/GettingStarted.

html
providing innovative data services and tools to transform the conduct of geoscience

Data Available Data Types Forecast Model Output Satellite Data Radar Data Lightning Data Wind Profiler Data Aircraft-Borne (ACARS) GPS Meteo. Data (SuomiNet) Textual Weather Bulletins Data Resources Data Usage Guide LDM Feedtypes IDD Operational Status Archived Data Access Software o Display & Analysis o AWIPS II o GEMPAK o IDV o McIDAS o Data Access & Management o LDM o LDM-McIDAS Decoders o LibCF o NetCDF o NetCDF/GRIB Decoders o NetCDF Java o NetCDF Perl o RAMADDA o THREDDS Data Server o UDUNITS Downloads o Download Software o GEMPAK o IDV o McIDAS o LDM o LDM-McIDAS Decoders
o o o o o o o o o o o o o o

NetCDF NetCDF/GRIB Decoders NetCDF Java NetCDF Perl RAMADDA TDS UDUNITS Terms & Conditions Provision of Software Support o Support Resources o Documentation o Training Tutorials o Mailing Lists o Support Archives o Submit a Request o Suggested Support Process o Email-Based o Web-Based o Terms & Conditions o Obtaining Support o Register as a User Community o Outreach & Opportunities o News from Unidata o Unidata Events o News from the Community o Job Opportunities o DeSouza Award o Equipment Awards o We Are Community Driven o Participating Institutions o Collaborations o Education Resources o Software & Data in Use o How to Participate o Governance o Policy Committee o Users Committee o Publications & Resources o Bibliography o Glossary of Terms Projects o Current Projects o CADIS o Case Studies

o o o o o o o o o

o o o o o o o o o o o o o

Common Data Model CONDUIT GALEON GEON IDV Google Africa Initiative GRIDSPEC HYDRO-NEXRAD Internet Data Distribution McIDAS-V Data Intercomparisons Next-Generation LDM OPULS Tropical Cyclone IDV News from Unidata News from Unidata Unidata Events News from the Community News From the Community Community Jobs News Archives Archived CommunitE-letters Archived News Releases

News
o o o o o o o o o

Events 2012 EarthCube Workshop o Unidata Events o Calendar of Events o Seminar Series o Conferences & Meetings o Unidata Workshops o Training Workshops o Triennial Workshops o Regional Workshops o Data Workshops About Us o The Unidata Program o Overview of Unidata o Highlights & Reports o Unidata Leaflet o Unidata Director's Page o Our Organization o Working Groups o Reporting Structure o Staff Listing o Contact Unidata o Contact Information
o

Visit Unidata

site:w w w .unidat

00842466462294

FORID:9

UTF-8

TDS Workshop Home Getting Started with Tomcat, Java and the TDS

Getting Started with Tomcat, Java and the TDS

Installing Java and Tomcat
System requirements
JDK Installation help
Users of GCJ and OS-provided packages (linux) for Java and/or Tomcat may want to reference the THREDDS mailing list for installation help.

Sun Java 7 (latest version) Apache Tomcat 7.x

While there are different distributors of Java and servlet containers, Unidata develops, uses and tests the THREDDS Data Server using Sun Java and the Apache Tomcat servlet container.

Installing Java
1. Download current Java SE Developer Kit (JDK) from Sun. Use the latest 1.7 version of the JDK. At the time of this workshop, that is version Java SE 7u9. We will be using the Linux x64-bit tar.gz file:
jdk-7u9-linux-x64.tar.gz

2. Install the JDK as per the Sun installation instructions. Copy the binary tar.gz file into the installation directory (/home/tds/GettingStarted/ in this example):
$ pwd /home/tds

$ ls -l drwxr-xr-x drwxr-xr-x drwxr-xr-x 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 9 14:02 Desktop 9 12:55 Documents

2 tds ustaff 4096 Oct 19 17:49 Downloads

drwxr-xr-x 14 tds ustaff 4096 Oct 19 16:02 epd drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 2 tds ustaff 4096 Oct 8 15:52 GettingStarted 9 12:55 Music 9 13:48 netcdf-java-4.3 9 12:55 Pictures 9 12:55 Public 9 12:55 Templates 9 12:55 Videos

2 tds ustaff 4096 Oct 19 17:52 workshop

$ cp Downloads/jdk-7u9-linux-x64.tar.gz GettingStarted/

$ ls -l

GettingStarted/

-rw-r--r-- 1 tds ustaff 96043498 Oct 19 17:56 jdk-7u9-linux-x64.tar.gz

Move into the installation directory and unpack the archive file:
$ cd GettingStarted/ $ pwd /home/tds/GettingStarted

$ ls -l -rw-r--r-- 1 tds ustaff 96043498 Oct 19 17:56 jdk-7u9-linux-x64.tar.gz

$ tar zxvf jdk-7u9-linux-x64.tar.gz

This will extract the JDK in the installation directory:

$ ls -l drwxr-xr-x 8 tds ustaff 4096 Sep 24 21:38 jdk1.7.0_09

-rw-r--r-- 1 tds ustaff 96043498 Oct 19 17:56 jdk-7u9-linux-x64.tar.gz

Troubleshooting
Depending on your OS you may need install either the 32-bit or 64-bit version of the JDK.

Installing Tomcat
Tomcat on Windows
For more information about installing Tomcat on Windows OS, see the Tomcat setup guide for installation on different platforms.

1. Download current version of the Tomcat 7 servlet container. At the time of this workshop, that is version 7.0.32. We will be using the binary tar.gz file:
apache-tomcat-7.0.32.tar.gz

2. Install Tomcat as per the Apache Tomcat installation instructions. Copy the binary tar.gz file into the installation directory (/home/tds/GettingStarted/ in this example):
$ pwd /home/tds/GettingStarted

$ cp ~/Downloads/apache-tomcat-7.0.32.tar.gz .

$ ls -l -rw-r--r-- 1 tds ustaff 7701019 Oct 19 17:59 apache-tomcat-7.0.32.tar.gz

drwxr-xr-x 8 tds ustaff

4096 Sep 24 21:38 jdk1.7.0_09

-rw-r--r-- 1 tds ustaff 96043498 Oct 19 17:56 jdk-7u9-linux-x64.tar.gz

Unpack the archive file:

$ tar xvzf apache-tomcat-7.0.32.tar.gz

This will create a Tomcat directory:

$ ls -l drwxr-xr-x 9 tds ustaff -rw-r--r-- 1 tds ustaff drwxr-xr-x 8 tds ustaff 4096 Oct 19 18:00 apache-tomcat-7.0.32 7701019 Oct 19 17:59 apache-tomcat-7.0.32.tar.gz 4096 Sep 24 21:38 jdk1.7.0_09

-rw-r--r-- 1 tds ustaff 96043498 Oct 19 17:56 jdk-7u9-linux-x64.tar.gz

Exercise One: Install Java and Tomcat

Using the steps outlined in the above sections, install the JDK and Tomcat in /home/tds/GettingStarted

Tomcat Directory Structure: Quick Tour

Exploring the Tomcat directory structure
1. Examine the Tomcat directory structure, aka ${tomcat_home}. Move into ${tomcat_home} and do a long listing:
$ cd apache-tomcat-7.0.32 $ ls -l drwxr-xr-x 2 tds ustaff drwxr-xr-x 2 tds ustaff drwxr-xr-x 2 tds ustaff 4096 Oct 19 18:00 bin 4096 Oct 3 01:52 conf

4096 Oct 19 18:00 lib 3 01:52 LICENSE 3 01:51 logs 3 01:52 NOTICE

-rw-r--r-- 1 tds ustaff 56812 Oct drwxr-xr-x 2 tds ustaff -rw-r--r-- 1 tds ustaff 4096 Oct 1192 Oct

-rw-r--r-- 1 tds ustaff

8826 Oct

3 01:52 RELEASE-NOTES 3 01:52 RUNNING.txt

-rw-r--r-- 1 tds ustaff 15557 Oct drwxr-xr-x 2 tds ustaff drwxr-xr-x 7 tds ustaff drwxr-xr-x 2 tds ustaff

4096 Oct 19 18:00 temp 4096 Oct 4096 Oct 3 01:52 webapps 3 01:51 work

2. Familiarize yourself with the following important directories.

bin/ o o

Contains startup.sh, shutdown.sh and other scripts/programs. The *.sh files (for Unix systems) are functional duplicates of the *.bat files (for Windows systems).

conf/ o o o

Server-wide Tomcat configuration. You will modify server.xml and tomcat-users.xml to adjust logging, authentication and access control, enable SSL, etc. Web applications can override some server-wide settings in their own configuration files (more about that later).

webapps/ o o o

Contains web applications directories and WAR files. This is where we will be putting the TDS web application. You will also be using the manager application that comes with Tomcat during this workshop.

logs/ o o o o o

Tomcat log files are here by default. This is one of the directories you will be looking for log files (the TDS logs elsewhere by default). The log files should be your first stop for troubleshooting Tomcat and TDS issues. (Hint, hint.) Logs files may contain useful information for assessing the security of your system. You will become very familiar with the Tomcat-generated catalina.out, catalina.yyyy-mm-dd.log and localhost_access_log.yyyy-mm-dd.log files by the end of this workshop.

Running Tomcat
Starting & stopping Tomcat
1. Tomcat isn't currently running so we need to start it up. Run the startup.sh script in the Tomcat bin/ directory:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32

$ bin/startup.sh

2. Verify Tomcat is running. Look and see if you have a Tomcat process running:
$ ps -ef | grep tomcat tds 2688 1 5 11:01 pts/1 00:00:02 /usr/bin/java Djava.util.logging.config.file=/home/tds/GettingStarted/apache-tomcat7.0.32/conf/logging.properties Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager Djava.endorsed.dirs=/home/tds/GettingStarted/apache-tomcat-7.0.32/endorsed classpath /home/tds/GettingStarted/apache-tomcat7.0.32/bin/bootstrap.jar:/home/tds/GettingStarted/apache-tomcat7.0.32/bin/tomcat-juli.jar -Dcatalina.base=/home/tds/GettingStarted/apachetomcat-7.0.32 -Dcatalina.home=/home/tds/GettingStarted/apache-tomcat-7.0.32 Djava.io.tmpdir=/home/tds/GettingStarted/apache-tomcat-7.0.32/temp org.apache.catalina.startup.Bootstrap start tds 2711 2197 0 11:02 pts/1 00:00:00 grep tomcat

Open a new browser window/tab and go to http://localhost:8080/ to verify Tomcat is running:

3. See if you can shutdown Tomcat. Run the shutdown.sh script in the Tomcat bin/ directory:
$ bin/shutdown.sh

Which Java is Tomcat currently using? (Hint: what was sent to STDOUT when running the startup.sh and shutdown.sh?)

Troubleshooting
Check the logs mostly recently generated in the Tomcat logs for clues about why Tomcat failed to start or stop. Pay particular attention to what is being reported in Tomcat's main log file: catalina.out.

Setting $JAVA_HOME, $JAVA_OPTS and $CATALINA_BASE

Tomcat on Windows
If you're running Tomcat on an instance of Windows OS, you will want to create a setenv.bat file.

We are going to create a file called setenv.sh in the Tomcat bin/ directory to:

allow Tomcat to reference/find the location of $JAVA_HOME and $CATALINA_BASE) during startup and shutdown; increase the amount of memory allocated to the JVM to enhance performance by setting $JAVA_OPTS; and add additional settings to the JVM via $JAVA_OPTS to enable more advanced services we will be learning about later on in this workshop.

1. Create the setenv.sh file. Using your favorite text editor (gedit, vi, emacs, etc.), create a new file called setenv.sh in the Tomcat bin/ directory:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32

$ cd bin $ vi setenv.sh

Add the following information and save your setenv.sh file:

#!/bin/sh # # ENVARS for Tomcat and TDS environment # JAVA_HOME="/home/tds/GettingStarted/jdk1.7.0_09" export JAVA_HOME

CATALINA_BASE="/home/tds/GettingStarted/apache-tomcat-7.0.32" export CATALINA_BASE

JAVA_OPTS="-Xmx4096m -Xms512m -server -Djava.awt.headless=true Djava.util.prefs.systemRoot=$CATALINA_BASE/content/thredds/javaUtilPrefs" export JAVA_OPTS

Settings
Whenever possible, Unidata recommends -Xmx1500m for 32-bit systems, and-Xmx4096m (or more) for 64-bit systems.

Looking Ahead
You will learn more about the TDS Web Map Service (WMS) later on in this workshop.

The parameters we pass to $JAVA_OPTS:

o o o o -Xms

is the initial allocated memory of the JVM (for performance). -Xmx the maximum allocated memory of the JVM (for performance). -server tells the Hostspot compiler to run the JVM in "server" mode. -Djava.awt.headless=true is needed to prevent graphics rendering code from assuming a graphics console exists. Without this, WMS code will crash the server in some circumstances.
Djava.util.prefs.systemRoot=$CATALINA_BASE/content/thredds/javaUt ilPrefs allows the java.util.prefs of the TDS WMS to write system preferences

to a location that is writable by the Tomcat user. 2. Implement your changes by restarting Tomcat. Restart Tomcat and examine the output generated to the terminal window by the startup script:
$ ./startup.sh Using CATALINA_BASE: Using CATALINA_HOME: /home/tds/GettingStarted/apache-tomcat-7.0.32 /home/tds/GettingStarted/apache-tomcat-7.0.32

Using CATALINA_TMPDIR: /home/tds/GettingStarted/apache-tomcat-7.0.32/temp Using JRE_HOME: /home/tds/GettingStarted/jdk1.7.0_09

Using CLASSPATH: /home/tds/GettingStarted/apache-tomcat7.0.32/bin/bootstrap.jar:/home/tds/GettingStarted/apache-tomcat7.0.32/bin/tomcat-juli.jar

Did you notice any difference in the what is being reported to STDOUT during startup?

Take a look at the running Tomcat process to see the new $JAVA_OPTS settings:
$ ps -ef | grep tomcat tds 2819 1 28 11:17 pts/1 00:00:02 /home/tds/GettingStarted/jdk1.7.0_09/bin/java Djava.util.logging.config.file=/home/tds/GettingStarted/apache-tomcat7.0.32/conf/logging.properties -Xmx4096m -Xms512m -server Djava.awt.headless=true Djava.util.prefs.systemRoot=/home/tds/GettingStarted/apache-tomcat7.0.32/content/thredds/javaUtilPrefs Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager Djava.endorsed.dirs=/home/tds/GettingStarted/apache-tomcat-7.0.32/endorsed classpath /home/tds/GettingStarted/apache-tomcat7.0.32/bin/bootstrap.jar:/home/tds/GettingStarted/apache-tomcat7.0.32/bin/tomcat-juli.jar -Dcatalina.base=/home/tds/GettingStarted/apachetomcat-7.0.32 -Dcatalina.home=/home/tds/GettingStarted/apache-tomcat-7.0.32 Djava.io.tmpdir=/home/tds/GettingStarted/apache-tomcat-7.0.32/temp org.apache.catalina.startup.Bootstrap start

Environment Variables
For more information on the environment variable prerequisites used by Tomcat, consult ${tomcat_home}/bin/catalina.sh (or catalina.bat) file. What allows us to create the setenv.sh file and have its contents read? (Hint: have a look at the catalina.sh file in the Tomcat bin/ directory at lines 24 and 133).

Troubleshooting
o o Do not forget include the 'm' in your -Xms and -Xmx settings. You may have allocated too much memory for the JVM settings if Tomcat fails to start and you get the following error reported in the Tomcat log catalina.out:
Error occurred during initialization of VM Could not reserve enough space for object heap

Likewise, if there is an error with your JVM memory allocation syntax in the setenv.sh file, it will be reported to catalina.out:
Error occurred during initialization of VM Incompatible minimum and maximum heap sizes specified

If you intend to use WMS and see something like the following in reported in catalina.out:
May 25, 2010 6:28:22 PM java.util.prefs.FileSystemPreferences syncWorld WARNING: Couldn't flush system prefs: java.util.prefs.BackingStoreException: /etc/.java/.systemPrefs/org create failed.

You will need to set the java.util.prefs.systemRoot system property in $JAVA_OPTS to a location that is writable by the user that Tomcat, e.g.:
#!/bin/sh # # ENVARS for Tomcat and TDS environment # JAVA_HOME="/home/tds/GettingStarted/jdk1.7.0_09" export JAVA_HOME

CATALINA_BASE="/home/tds/GettingStarted/apache-tomcat-7.0.32" export CATALINA_BASE

JAVA_OPTS="-Xmx4096m -Xms512m -server -Djava.awt.headless=true Djava.util.prefs.systemRoot=$CATALINA_BASE/content/thredds/javaUtilPrefs" export JAVA_OPTS

Exercise Two: Set $JAVA_HOME, $JAVA_OPTS and $CATALINA_BASE

1. Create a setenv.sh file in the Tomcat bin/ and set $JAVA_HOME, $JAVA_OPTS and $CATALINA_BASE.

Deploying the TDS

About WAR files

WAR is short for Web ARchive. By default, Tomcat will automatically unpack the WAR distribution into directory of the same name upon deployment. Note: the unpacked directory is overwritten each time a new WAR file is deployed.

Downloading & deploying thredds.war

Upgrading the TDS
A maintenance checklist and contains helpful information about upgrading the TDS. New features and configuration changes made between TDS versions are listed for each release.

1. Download the TDS WAR file from Unidata's web site. We will be using the current TDS 4.3 (release candidate) version for this workshop:
thredds.war

2. Deploy the TDS in Tomcat. Put thredds.war in the Tomcat webapps/ directory:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32/bin $ cd ../webapps

$ cp ~/Downloads/thredds.war . $ ls -l

drwxr-xr-x 13 tds ustaff drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x -rw-r--r-6 tds ustaff 5 tds ustaff 5 tds ustaff 3 tds ustaff

4096 Oct 19 18:00 docs 4096 Oct 19 18:00 examples 4096 Oct 19 18:00 host-manager 4096 Oct 19 18:00 manager 4096 Oct 19 18:00 ROOT

1 tds ustaff 40444990 Oct 19 18:10 thredds.war

3. Confirm the TDS has been deployed. If Tomcat is already running, wait a couple of seconds after placing the WAR file in the Tomcat webapps/ and then verify the thredds.war file was unpacked:
$ ls -l drwxr-xr-x 13 tds ustaff drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x -rw-r--r-6 tds ustaff 5 tds ustaff 5 tds ustaff 3 tds ustaff 8 tds ustaff 4096 Oct 19 18:00 docs 4096 Oct 19 18:00 examples 4096 Oct 19 18:00 host-manager 4096 Oct 19 18:00 manager 4096 Oct 19 18:00 ROOT 4096 Oct 19 18:10 thredds

1 tds ustaff 40444990 Oct 19 18:10 thredds.war

Go to http://localhost:8080/thredds/ in your browser to verify the TDS has been deployed:

Troubleshooting
o o Any error in the TDS deployment will be reported in the catalina.out file of the Tomcat logs/ directory. Be sure you have downloaded and deployed the TDS 4.3 (release candidate) version for this workshop (the version number will appear in the blue bar at the bottom of TDS catalog pages).

Exercise Three: Deploy your own instance of the THREDDS Data Server
1. 2. 3. Deploy the TDS in your newly-installed Tomcat. Once deployed, browse the test catalogs & datasets that come with the distribution. Look at the directory contents of the main Tomcat directory ~/GettingStarted/apache-tomcat7.0.32. Do you notice anything new?

Tomcat Log Files

Tomcat logs/
1. Look at the different types of log files being generated in the Tomcat logs/ directory. Move into the logs/ directory to see the type of information being logged:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32/webapps $ cd ../logs

$ ls -l -rw-r--r-- 1 tds ustaff 10635 Oct 19 18:10 catalina.2012-10-19.log -rw-r--r-- 1 tds ustaff 10748 Oct 19 18:10 catalina.out -rw-r--r-- 1 tds ustaff -rw-r--r-- 1 tds ustaff -rw-r--r-- 1 tds ustaff -rw-r--r-- 1 tds ustaff 0 Oct 19 18:02 host-manager.2012-10-19.log 2820 Oct 19 18:10 localhost.2012-10-19.log 0 Oct 19 18:02 localhost_access_log.2012-10-19.txt 0 Oct 19 18:02 manager.2012-10-19.log

Do you see a correspondence between some of the web applications in the Tomcat webapps/ directory and the naming of certain log files? Is there a difference in the information being logged to catalina.out versus catalina.yyyy-mmdd.log? Are some log files more verbose than others?

2. Examining catalina.out. Open another terminal window (hereafter referred to as terminal #2) and run the following command in the new terminal:
$ tail -f /home/tds/GettingStarted/apache-tomcat-7.0.32/logs/catalina.out

In your original terminal window, start/stop and start Tomcat and watch what is being logged to catalina.out in the terminal #2 window.
Is it only errors messages being reported to catalina.out? What messages in catalina.out are from the TDS?

Things to know about catalina.out

catalina.out The Tomcat Users mailing list has seen a lot of traffic dedicated to catalina.out logging and rotation.

Tomcat System.out and System.err gets appended to catalina.out. catalina.out can quickly grow large if the hosted web applications are not specifically catching and logging System.out and System.err to designated files. catalina.out is not automatically rotated in Tomcat. You should employ an outside log rotation program (e.g., logadm or logrotate) to rotate catalina.out.

It is good practice to archive and remove old catalina.out files and other log files out of the Tomcat logs/ on a regular basis. On Windows, the catalina.out file is not automatically created. Instead only the catalina.yyyy-mm-dd.log files are used. These have equivalent content.

Tomcat (Server-Level) Configuration Files

About server.xml
Keep in mind
Tomcat's configuration files, including server.xml can be found in in the Tomcat conf/ directory.

XML file (well-formed syntax is important). Tomcat's main configuration file. Changes to server.xml do not take effect until Tomcat is restarted. Where we make changes to enhance TDS security.

Important elements in server.xml

1. Examine the Elements in server.xml. Move into the Tomcat conf/ directory and examine the server.xml file:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32/logs $ cd ../conf

$ less server.xml

Reference the table below to see how the server.xml elements relate to configuring TDS (mouse-over the element for a description):
Tag Name <Server> Instances 1...1 How it relates to the TDS Not modified unless you want to change the port number Tomcat listens for a SHUTDOWN command. (Enabled by default.) Needed to contain the UserDatabase that corresponds to the UserDatabaseRealm used to authenticate users. (Enabled by default.) Editable user database (tomcat-users.xml)

<GlobalNamingResources>

0...*

<Resource>

0...*

used by UserDatabaseRealm to authenticate users. (UserDatabaseRealm Resource enabled by default.) <Service> 1...* Not modified unless you wish to establish more than one service. (Catalina Service enabled by default.) Used to establish HTTP and SSL connections. Also will communicate with an web server for proxying requests. (HTTP connector enabled by default on port 8080.) Not modified unless you specify a Host other than localhost. (Enabled by default.) The UserDatabaseRealm uses the UserDatabase configured in the global JNDI Resource. (UserDatabaseRealm enabled by default.) The RemoteAddrValve is used to filter access to the TDS based on IP address. (NOT enabled by default. You will need to add this if you want to use IP Filtering.) Not modified unless you specify a Host other than localhost. (localhost enabled by default.) We use the MemoryRealm to configuring Tomcat to use digested passwords. (NOT enabled by default. You will need to add this if you want to use digested passwords.) We modify the AccessLogValve to customize the access logs generated by Tomcat. (NOT enabled by default. You will need to add this if you want to enable access logging.)

<Connector>

1...*

<Engine> <Realm>

1...1 0...*

<Valve>

0...*

<Host>

1...*

<Realm>

0...*

<Valve>

0...*

About tomcat-users.xml

XML file (well-formed syntax is important). Stores user names, passwords and roles. Changes to tomcat-users.xml do not take effect until Tomcat is restarted. What the TDS uses for user authentication and access control.

Important elements in tomcat-users.xml

1. Examine the Elements in tomcat-users.xml. Open the tomcat-users.xml file:

$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32/conf

$ less tomcat-users.xml

Reference the table below to see how the tomcat-users.xml elements relate to configuring TDS (mouse-over the element for a description):
Tag Name <tomcatusers> <role> Instances 1...1 1...* How it relates to the TDS Not modified. (The only tag you get by default.) You will have at least two of these: one for the Tomcat manager application and one for the TDS. (You will need to add if you want to enable role-based authentication.) You will need to create an entry for each user who needs access to the Tomcat manager application and/or the restricted areas of the TDS. (You will need to add if you want to enable user authentication.)

<user>

1...*

Tomcat manager Application

About the manager application
More about manager
For more information about the Tomcat manager application, see the Tomcat Manager App HOW-TO documentation.

"Free" web application that comes with Tomcat distribution. Lives in the manager directory in the Tomcat webapps/ directory. Allows Tomcat administrators to deploy, undeploy, or reload web applications such as the TDS without having to shut down and restart Tomcat. Provides server status statistics for the JVM and each connector you have configured in server.xml.

Accessing the Tomcat manager application

Changes to the manager application
The manager application URLs and roles has been re-structured. See the Tomcat Migration guide for more information.

Attempt to access the Tomcat manager application in your browser: http://localhost:8080/manager/html/. You will be prompted to login via BASIC authentication, which will end in failure since we do not yet have permission to access the manager application:

Based on what we know about Tomcat configuration, which file in the Tomcat conf/ directory should we edit to grant ourselves access to the manager application?

Keep in mind
Changes to tomcat-users.xml do not take effect until Tomcat is restarted.

Granting access to the manager application

1. Modify tomcat-users.xml to add role and user elements. Using your favorite editor, open ${tomcat_home}/conf/tomcat-users.xml:
$ vi tomcat-users.xml

Between the <tomcat-users> tags, add a role element and specify the rolename attribute as manager:
<tomcat-users> <role rolename="manager-gui"/> </tomcat-users>

Now add a new user by adding a user element. Create a username and password for the new user and specify manager-gui as one of the roles (in this example we are creating a user called 'admin' with a corresponding password of 'secret'):
<tomcat-users> <role rolename="manager-gui"/> <user username="admin" password="secret" roles="manager-gui"/> </tomcat-users>

2. Restart Tomcat and log into the manager application. Thinking ahead
To gain access to restricted parts of the TDS, you will perform the same steps you used to grant yourself access to the manager application.

Attempt to access the manager application again (http://localhost:8080/manager/html/), this time logging in using the name and password specified in tomcat-users.xml:

Voil! You should have access to the manager application. Troubleshooting

o o o Check the XML syntax in tomcat-users.xml to make sure it is well-formed and without error. Did you restart Tomcat after you made your changes to tomcat-users.xml? Any errors will be reported in the Tomcat logs/catalina.out file.

Exercise Four: Grant yourself access to the Tomcat manager application

1. Using the steps outlined above, modify tomcat-users.xml to grant yourself access to the Tomcat manager application.

Deploying the TDS using the manager application

1. Use the manager application to undeploy the TDS. Find the TDS in the list of web application on the Applications page. Stop and then Undeploy the TDS:

List the contents of the Tomcat webapps/ directory to verify that both thredds.war and the unpacked thredds/ directory have been removed:
$ pwd /home/tds/GettingStarted/apache-tomcat-7.0.32/conf $ cd ../webapps

$ ls -l drwxr-xr-x 13 tds ustaff 4096 Oct 19 18:00 docs drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x 6 tds ustaff 4096 Oct 19 18:00 examples 5 tds ustaff 4096 Oct 19 18:00 host-manager 5 tds ustaff 4096 Oct 19 18:00 manager 3 tds ustaff 4096 Oct 19 18:00 ROOT

2. Deploy the TDS using the manager application. Upload the TDS WAR file using the Deploy section of the manager application:

Confirm the deployment went as planned by accessing the TDS using your browser: http://localhost:8080/thredds/

Exercise Five: Deploy the THREDDS Data Server using the manager application
1. Using the steps outlined above, deploy the TDS using the manager application.

Next Steps: Where To Go From Here

You're not finished yet
TDS remote management tool
You will need to enable Enable SSL encryption to access TDS remote management tool.

We highly recommend you follow the best practices outlined in the Tomcat and TDS Security Considerations section of the tutorial to finish hardening your server environment. The Basic TDS Configuration and TDS Configuration Catalogs sections of this tutorial covers the TDS configuration files, configuration options and TDS catalog structure. Additional sections of the tutorial cover how to enable OGC/ISO Services, and Using NcML in TDS.

This document is maintained by Unidata. Send comments to THREDDS support. Last updated: November 2, 2012
TDS Workshop Home Getting Started with Tomcat, Java and the TDS

Contact Us Terms of Use Privacy Policy Participation Policy

The Unidata Program Center is a member of the UCAR Community Programs, is managed by the University Corporation for Atmospheric Research, and is funded by the National Science Foundation.