GrADS-DODS Server - Configuration File Reference

Table of Contents

Basic format description

The GDS configuration file is in XML format. This means it must start with the following line:

<?xml version="1.0" encoding="ISO-8859-1"?>

and then contain a set of nested "tags" .Each tag specifies the configuration options for a particular module of the server. In cases where configuration for a module is more complex, the tag for that module may contain further tags. Tags are written in one of two forms. For a tag with no contents, the syntax is:

<tagname attribute="value" ... />

and for a tag with contents, it is:

<tagname attribute="value" ...>
  (other tags)
</tagname>

The GDS configuration file does not currently use plain text or CDATA segments.

back to table of contents

Example of a configuration file

This is what your configuration file might look like:

<?xml version="1.0" encoding="ISO-8859-1"?>
<gds name="my_server home="http://www.some.edu/~jdoe/data_server_info.html">
  <catalog temp_entries="500">
    <data>
       <dataset name="my_data" file="/data/my_data.ctl" format="ctl"/>
       <datadir name="my_model_runs" file="/data/mruns/" suffix=".nc" format="nc"
                doc="http://www.some.edu/my_online_data/mrun_info.html" />
       <mapdir name="private_data">
         <datalist file="secret_datasets.lst"/>
       </mapdir>
    </data>
  </catalog>
  <log mode="rotate">
    <log_override module="tool/invoker" level="verbose"/>
  </log>
  <grads>
    <invoker grads_dir="/home/jdoe/grads/" time="600"/>
    <analyzer storage="250" time="60"/>
    <dods subset_size="2000" />
    <uploader/>
  </grads>
  <mapper>
    <service-admin auth="sDFe294f3nv034u8"/>
  </mapper>
  <privilege_mgr default="public">
    <ip_range mask="127.0.0.1" privilege="full" />
    <ip_range mask="192.168" privilege="full" />
    <privilege name="full" /> <!-- no restrictions -->
    <privilege name="public"
               analyze_allowed="false"
               abuse_hits="1000"
               abuse_timeout="24/>
      <deny path="/private_data">
    </privilege>
  </privilege_mgr>
  <servlet>
    <filter-overload limit="20" />
  </servlet>
</gds>  

back to table of contents

Tag hierarchy

The following table shows the tag structure of the configuration file. This corresponds to the runtime structure of the server. The top level tag must always be <gds>. Each tag must be contained by the tag immediately to its left, and can contain any of the tags to its right. Tags followed by * can appear multiple times.

<gds> <catalog> <data> <dataset>*  
<datadir>*  
<datalist>*  
<mapdir>* <dataset>*
<datadir>*
<datalist>*
<mapdir>*
<log> <log_override>  
<grads> <invoker>
<analyzer>
<uploader>
<dods>
<servlet> <filter-*>
<mapper> <service-*>
<privilege_mgr> <ip_range>*
<privilege>* <allow>*  
<deny>*  

back to table of contents

Tag definitions

An alphabetical list of the tags used in the configuration file, and the attributes that can be set for each tag.

<allow> Contained by <privilege>. Allows access to data objects for this privilege set. Used to partially or completely override a <deny>. Can in turn be partially or completely overriden by another <deny>
path The path for data objects to be affected. Access will be allowed to any data objects whose path matches (starts with) the path given, unless the data object also matches a <deny> tag with a more specific path. Also see inherit in <privilege>.
 
<analyzer> Contained by <grads>. Configuration for performing analysis tasks
storage Maximum size allowed for an analysis result, in kilobytes
time Maximum timean analysis task is allowed to run before it is aborted, in seconds (overrides time setting in <invoker>)
 
<catalog> Contained by <gds>. Configuration information for the server's catalog of data entries
     contains: <data>
temp_entries Maximum number of temporary entries (uploads or analysis results) that the server should store
temp_storage Maximum disk space the server should use for temporary entries, in megabytes.
temp_age Amount of time after which a temporary entry should be deleted, in hours.
 
<data> Contained by <catalog>. List of data objects to be served.
  contains: <dataset> <datadir> <datalist> <mapdir>
 
<datadir> Contained by <data>, <mapdir>. Specifies a directory in which to search for data objects
name This will be prefixed to the online name of all data objects in this directory. (optional - default is the filename of the directory)
file The local filename for this directory
recurse If set to "true", all subdirectories will also be searched. (optional - default is true)
prefix Only files whose names begin with the prefix will be loaded (optional)
suffix Only files whose names end with the suffix will be loaded (optional)
doc see <dataset>
das see <dataset>
format see <dataset>
 
<datalist> Contained by <data>, <mapdir>. Specifies a file containing a list of data objects
  name This will be prefixed to the online name of all data objects in the list. (optional)
list_format

The format of the list. Available options are:
"file": each line contains only a filename (default)
"name": each line contains an online name, followed by a filename (separated by whitespace)

doc see <dataset>
das see <dataset>
format see <dataset>
 
<dataset> Contained by <data>, <mapdir>. Specifies a single data object to be served.
name The online name for the data object. (optional - default is the portion of the file or URL after the last "/")
file A filename, if the data object is locally stored
url A DODS URL if the data object is remotely stored
doc A URL pointing to documentation for this dataset (optional)
das Location of a supplemental DAS, which will be merged with the auto-extracted attributes for this data object. (optional)
format

The storage format of the data object
"ctl" : GrADS described data (includes sequential, GRIB, BUFR and station data) (default)
"nc": netCDF
"hdf": HDF-SDS
"dods": DODS URL

 
<deny> Contained by <privilege>. Denies access to data objects for this privilege set
path

The path for data objects to be affected. Access will be denied to any data objects whose path matches (starts with) the path given, unless the data object also matches an <allow> tag with a more specific path. Also see inherit in <privilege>.
<dods> Contained by <grads>. Configuration for fulfilling DODS requests
subset_size Maximum allowed size allowed for a subset operation, in kilobytes
buffer_size Size of buffer used to stream subset data to the network, in kilobytes
 
<filter-*> Contained by <servlet>. Tags of this type contain configuration information for the request filters. To configure a filter named X, create a tag of the form <filter-X> with the attributes you wish to set.
  filters that can be configured
abuse blocks excessive hits from a specific IP address
analysis performs analysis tasks for requests that include them
overload rejects requests when the server is under heavy load
generic attributes:
enabled If set to "false", the filter will simply pass all requests through, taking no action (default is "true")
filter-specific attributes:
hits for "abuse" filter, specifies the number of hits to allow per hour from the same IP
timeout for "abuse" filter, specifies how long to deny access after an IP exceeds the hit limit, in hours
limit for "overload" filter, specifies the maximum number of simultaneous requests to allow
 
<gds> Top-level tag. Contains all configuration information for the server
  contains: <catalog> <log> <tool> <servlet> <mapper> <privilege_mgr>
  name A descriptive name for this server installation, which will be used in dynamically generated web pages.
  home The URL for this server's home page. This home page can be located on a different server. However, in order to avoid confusing users, it should always link back to the GDS directory listings. If possible it should also provide a way to contact the server administrator.
 
<grads> Contained by <gds>. Configuration for the tool used to access, analyze, and store data
  contains: <invoker> <uploader> <analyzer> <dods>
 
<invoker> Contained by <grads>. Configuration for invoking GrADS as an external process
grads_dir The path of a full GrADS distribution
grads_bin The path to a single GrADS executable. Use this if a full distribution is not available.
time Maximum time a GrADS process is allowed to run before it is aborted, in seconds. This is solely intended as a safeguard against GrADS unexpectedly hanging, and should be set to several minutes or more.
 
<ip_range> Contained by <privilege_mgr>. Assigns privileges according to the IP address of the request
mask A partial IP address. Requests will be given privileges according to the ip_range with the most specific mask that matches. Setting mask to "" sets the global privilege level, which will be given to any request that does not match another ip_range.
privilege name of the set of privileges to grant to this IP range
 
<log> Contained by <gds>. Configuration information for the server logger (which functions independently of any logging in Tomcat or the JVM)
  contains: <log_override>
mode

Values are:
"console": all messages will be written to standard output
"file": all log messages will go to a single file
"rotate": log messages will be written to a rotating collection of files

file In file mode, the name of the log file. In rotate mode, the rotating log file names will be this file name plus a date identifier. Default is "log/gds.log".
level

Values are:
"debug": extremely detailed output
"verbose": detailed output
"info": major events and errors (default)
"error": error messages only
"critical": server-critical errors only
print_mem If equal to "true", the available heap space for the JVM will be printed with each log entry
print_module If equal to "true", the name of the module generating the message will be printed.
date_format A template for the date portion of log entries. The template should use the format supported by the java.text.SimpleDateFormat class (see Java 2 API Documentation). If omitted, the logger will use its default format.
 
<log_override> Contained by <log>. Used to set a different level of logging for a specific module
module The name of the module, omitting the initial "gds/"
level see <log>
 
<mapdir> Contained by <data>, <mapdir>. Use to put various data objects under a single online path. Any number of <dataset>, <datadir>, <datalist> and <mapdir> tags may be nested inside this tag.
  contains: <dataset> <datadir> <datalist> <mapdir>
name This will be prefixed to the online name of all data objects inside this tag.
 
<mapper> Contained by <gds>. Configuration for the mapper that assigns each request to a particular service
  contains: <service>
 
<privilege> Contained by <privilege_mgr>. A set of privileges that can be associated with an IP, or used as a baseline for defining more specific sets of privileges. All attributes except "name" are optional.
contains: <allow> <deny>
name Name of this privilege set
inherit

The name of another <privilege> to inherit settings from.
Settings of the the "parent" <privilege> are inherited by this one, unless specifically overridden. Any <allow> and <deny> tags in this privilege set are merged with those of the parent, with precedence going to the "child" in cases where both an <allow> and a <deny> are found for same path.

dods_subset_size Overrides subset_size in <dods>
analyze_allowed If other than "true", turns off analysis capability for this privilege set. Default is true.
analyze_time Overrides time in <analyzer>
analyze_storage Overrides storage in <analyzer>
upload_allowed If other than "true", turns off upload capability for this privilege set. Default is true.
upload_storage Overrides storage in <upload>
abuse_hits Overrides hits in <filter-abuse>
abuse_timeout Overrides timeout in <filter-abuse>
 
<privilege_mgr> Contained by <gds>. Configuration for the privilege manager, which assigns a set of privileges to each request
  contains: <ip_range> <privilege>
  default The name of the default <privilege>, to be assigned to requests that do not match any specified <ip_range>. If this attribute is omitted, a blank privilege set will be created and used as the default.
 
<service-*> Contained by <mapper>. Tags of this type contain configuration information for the network services that the server provides to clients. To configure a service named X, create a tag of the form <service-X> with the attributes you wish to set.
services that can be configured
admin performs adminstrative functions
ascii sends ASCII-format subsets
das sends DODS Data Attribute Structures
dds sends DODS Data Descriptor Structures
dir sends a directory of data objects in HTML
dods sends DODS binary format subsets
help sends a message providing links to user help
info sends a data object summary in HTML
upload receives uploaded data
xml sends complete data object catalog in XML
generic attributes
enabled If set to "false", the service will not be made available (default is "true")
service-specific attributes
auth for "admin" service, specifies the authorization code that must be provided to access the service
 
<servlet> Contained by <gds>. Configuration for the servlet interface
  contains: <filter>
 
<uploader> Contained by <grads>. Configuration for handling uploaded data
   udfread Location of the GrADS udfread utility, used to unpack uploaded data
  storage Maximum size allowed for an upload, in kilobytes
 
 
back to table of contents