GrADS-DODS Server - Administrator's Guide
Table of Contents
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 1.3 or
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. GDS version 2.0 requires GrADS 2.0.a3 or higher. The latest version of GrADS is available at the GrADS home page.
The latest version of the GDS is available at the GDS home page as a compressed tar archive.
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 (see Tomcat settings).
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
Next, double check with other users and/or your system administrator, to make sure that port settings for the GDS do not conflict with ports that are already in use. By default the GDS uses ports 9090 and 9095. See Tomcat settings for instructions on how to change these.
At this point, you should be able to start the server and view the example dataset.
If you plan to serve netCDF, HDF, or OPeNDAP data sets, also make sure that the
when the GDS tries to access any netCDF, HDF or DODS data.
Next you will want to put your data online.
First, make sure that all of your datasets are ready to be opened by GrADS. If you have COARDS-compliant NetCDF data, they are ready to go as is. Otherwise, you may need to generate some CTL and/or map files. See the GrADS documentation for more information on how GrADS works with various data formats.
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
Note that the GDS 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 OPeNDAP-enabled client.
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.
An important warning for serving changing collections of data, such as real-time observations:
Always post new or modified data under new handles. Never modify the contents of an existing dataset.
Many OPeNDAP clients work on the assumption that the dataset they are making requests from will not change. If it does, they may behave erratically, or worse, return the wrong data values to the user. The user may not even realize this has happened.
For example, if you add new model run data daily, use an absolute date,
By contrast, if you were to use relative times - e.g., post March 1 data
The one exception is that it is safe to simply extend the time dimension of a dataset, as long as you keep the origin (t=0) time of the dataset the same. This will not cause any problems for clients unaware of the change, as all data requests in the older time ranges will still return the same data as before the change.
There are four scripts in the server home directory that are used to
control the GDS, which send brief messages to the terminal, and record
their actions in more detail in the file
These now invoke the corresponding scripts in the bin directory, which have been completely rewritten:
The behavior of these scripts is similar to the old startup scripts, but there are some major improvements.
Firstly, they can now be run from any directory; it is not necessary
Second, to reduce the chance of downtime,
Third, gds-start.sh now waits until the GDS is ready to handle requests
before exiting, and exits with a non-zero return code if the server fails
to start. This allows reliable scripting of follow-on commands which require
the GDS to be running, without the need for kludges such as
The GDS has a web-based administration interface which is accessed by URLs of the form:
The authorization string can be kept from appearing in the log files by using POST rather than GET requests to perform administration tasks. There is a form which can be used to do this, at :
Alternately, a utility such as
For convenience, there is a script called
By default, the administration utility can only be invoked through the local network interface; that is, it will only accept requests originating from IP address 127.0.0.1. Additional IP addresses can be allowed to make administration requests by using the admin_enabled attribute of the <privilege> tag.
Because they alter the state of internal structures, administration commands can only run while the server is idle. The administration service has a timeout attribute which controls the length of time it will wait for the server to become idle. If this time expires, it will return with an error message, and the command will not be performed.
Except under very heavy loads, this should not be an issue, as even a momentary idle is sufficient. However, on certain systems, it appears that normal data requests can occasionally get "hung" in the middle of transmission, and never finish. This will prevent administrative commands from running, because the server can't consider itself to be idle until all outstanding requests are complete. The cause for this problem is under investigation and it will hopefully be resolved soon; however, in the meantime, it is advisable when scripting the administrative command, to include a fallback to a restart of the server, should the administrative command time out more than once.
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
You can also use the
The GDS startup shell uses the values of several environment variables if present. These are:
The GDS derives settings for all of its modules from an
XML configuration file. The name of this file is specified at startup;
the default is
The configuration file reference describes the XML tags that can be used in this file.
Note that the pre-configured Tomcat
bundled with the GDS is now version 4.1, and is located in the directory
file for Tomcat is
Warning: if two or more Tomcat servers on the same machine are trying to use the same port settings, the startup and shutdown commands will affect both servers unpredictably, and only one of them will actually be able to handle requests.
If your server is shutting down unexpectedly, not starting up, or not
responding to the "
An explanation of Tomcat and the settings in its configuration file can be found at the Tomcat home page
Both Tomcat and the GrADS-DODS 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
The GDS comes with some static web pages which can be accessed using
Tomcat (including this manual). These pages are located in the subdirectory
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.
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
Once you have added it, you will need to set the property
Source code is included with the GDS, under the path