GrADS Data Server - Administrator's Guide

1. Installation

Requirements

The GDS can run on any UNIX platform for which both Java and GrADS are available.

You will need a Java Virtual Machine (JVM) that supports Java v1.2 or higher. Enter java -version at the Unix command prompt to find out what JVM you have currently installed on your system. The Java Virtual Machine is a free download either from Sun Microsystems, or your operating system manufacturer's website.

You will also need GrADS. Because the server uses some new features in GrADS, you will need version 1.8 or higher. Handling station data and client uploads requires version 1.9 or higher. The latest version of GrADS is available at the GrADS home page.

Download and setup

GrADS Data Server downloads were available at www.iges.org, but can now be found at http://cola.gmu.edu/grads/gds.php.

You do not need root user access to run the GDS. There is no build or system install process, because it is a cross-platform Java application. And any number of GDSes can be run on the same system, as long as they are configured to use different ports.

After unpacking the archive, all you need to do is edit the configuration file, and tell the GDS where to find GrADS, by editing the invoker tag. If you are not using a full GrADS distribution, make sure the GrADS executable you specify is capable of opening the types of dataset you wish to use.

At ths point you should be able to start the server and view the example dataset.

Putting your datasets online

Next you will want to put your data online.

First, make sure that all of your datasets are ready to be opened by GrADS. (for instance, if you have GRIB data, you will need to generate CTL and map files).

Once this is done, all you need to do to put your datasets online is tell the GDS where they are, using the configuration file. This is done by adding <dataset>, <datadir>, and <datalist> tags inside the <data> tag. If you want, you can organize the way the data appear online using <mapdir> tags.

Note that the GrADS Data Server does not attempt to access datasets until the first time they are requested by a client, so it may not immediately complain about unusable datasets. Before you invite others to use your server, therefore, it is a good idea to make sure that all of the datasets you are serving work properly, by opening them in your own DODS-enabled client.

Also note that DODS does not provide a way to notify clients that a given dataset has changed. Thus, if you are planning to serve a changing collection of data, such as real-time observations, plan to always post new data under new handles, rather than overwriting the contents of existing datasets. Otherwise, a user making the wrong assumption could unknowingly generate incorrect results, or become very confused.

Once you have your data loaded and working, it is highly recommended that you familiarize yourself with the configuration options and administrative tools available by reading the remainder of this documentation.

2. Controlling the server

Starting and stopping

There are four scripts in the server home directory that are used to control the GrADS Data Server:

1. startserver - Starts the GDS as a background task.
2. stopserver - Shuts down the GDS.
3. rebootserver - Restarts the GDS.
4. cleanup - Restarts the GDS, deleting all temporary files.

Notes:

• In general, the stopserver script should be preferred to killing the server process, as it allows the GraDS Data Server to shut down gracefully.
• Once the GDS is running, it must be stopped before it can be started again. Otherwise, startserver will print a Java "ConnectException" message and fail.
• If the GraDS Data Server fails because of an invalid configuration, Tomcat will start anyway. Thus, when the GrADS Data Server prints an invalid configuration message, the stopserver script must be run before starting it again.

Web-based administration

The GDS has a web-based administration interface which is accessed by URLs of the form:

/admin?auth=authorization_string&cmd=command_string

The authorization_string given must match the auth setting given in the <service-admin> configuration tag. The command_string can be one of the following:

• reload: Checks for changes to the server configuration. This updates the data catalog, privilege sets, and all other settings contained in the GDS configuration file, without the need to take the server offline.
• clear: Removes all temporary entries from the catalog.

Checking the server status

The script check_gds, found in the servers' home directory, can be used to notify the administrator by email and automatically restart a GrADS Data Server if it goes offline. This script requires the lynx web browser, or some other command-line utility that can download documents via HTTP.

To use the script, edit it to use the base URL and home directory of the server it is to check, and add it as a cron job with the desired frequency. Once in the crontab, the script can be temporarily disabled by placing a file called block_check_gds in the home directory of the GrADS Data Server being checked.

3. Configuration

Startup parameters

The startup script, startserver, contains the following settings:

• HEAP_SIZE: the amount of memory that the Java Virtual Machine will reserve for Tomcat and the GDS.

  By default, the GDS is set to use 150MB. However, under heavy usage, with large numbers of datasets, it may need more than this. Conversely, with only a few datasets online and occasional use, it will need far less. It is worth experimenting with different heap sizes if you want to reduce the GDS footprint, or if the GDS is reporting out of memory errors.

• CONFIG_FILE: the name of the configuration file to use. By default this is set to gds.xml. If the pathname is relative, it is resolved with respect to the home directory of the server.

Configuration file settings

The GDS derives settings for all of its modules from an XML configuration file. The name of this file is specified in the startup script; the default is gds.xml. This file is read every time the server starts, and every time a reload command is given using the administrative web interface

The configuration file reference describes the XML tags that can be used in this file.

Tomcat settings

The configuration file for Tomcat is tomcat/conf/server.xml. This file can be edited to change the network port that the GDS runs on, and to increase the size of the connection pool, among other things.

An explanation of Tomcat and the settings in its configuration file can be found at the Tomcat home page

Security

Both Tomcat and the GrADS Data Server support IP-address-based security. Each can be given its own security settings. Tomcat will allow or deny access to the server based on the settings in its configuration files. For finer grained control, use the <ip_range> and <privilege> tags in the GDS configuration file. These settings allow or deny access to specific datasets and server features.

4. Advanced Topics

Static web pages

The GDS comes with some static web pages which can be accessed using Tomcat. These pages are located in the subdirectory tomcat/webapps/ROOT. In general, putting your static content on a separate web server is recommended, since will usually be more efficient than using Tomcat for this. However, Tomcat's static content directory provides an easy way to put up some information about the datasets you are serving, without setting up a separate web server.

Integrating with Apache

The GDS can fairly easily be integrated into an existing Apache web site. All that is required is to set up the link between Tomcat and Apache. Consult the Tomcat home page for more on this process.

Deploying to a different servlet container

It is not necessary to use the copy of Tomcat that is distributed with the GDS, to run the GDS. Any servlet container that supports the Java Servlet API 2.2 or higher can be used.

The GDS web application is in the directory tomcat/webapps/dods. You can generate a Web Application archive (WAR) file by running the makewar script under the path src/. This will generate an archive called dods.war. To add the WAR to your servlet container, follow the servlet container's instructions.

Once you have added it, you will need to set the property anagram.home to the directory containing the rest of the GDS distribution. This can be set either as a Java system property (using the -d switch when invoking Java) or as a servlet context property (follow the servlet container's instructions).

Building from source

Source code is included with the GDS, under the path src/.

• To generate Java documentation from the source code, change to src/ and run the makedoc script.The documentation will be placed in src/doc/.
• To recompile the source code, change to src/ and run the makejar script.

Please note that, while you are welcome to browse and modify the source for your own purposes, and submit patches and/or new features to COLA, you are not granted permission to distribute modified versions of this software.