NOAA Operational Model Archive and Distribution System

GrADS Data Server Configuration File Reference

1. 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:

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.

2. 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" /> 
    <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>

3. 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>
		<privilege>	<deny>

4. 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

NCEP NOMADS Version 2.2.9, October 2024