TDS Configuration file


The TDS configuration file ${tomcat_home}/content/thredds/threddsConfig.xml allows the TDS administrator to control the behavior of the TDS. This is the complete reference document for TDS version 4.6.

In general, you do not have to change any of these parameters, since the TDS will use default settings. If you do change any of these, you must restart the thredds webapp (e.g., through the tomcat manager application) for them to take effect. The exception is that the catalogRoot elements will be reread by doing a Debug/Reinit, if you have remote management enabled.

Here is an annotated example threddsConfig.xml.


Contents


TDS global configuration options

Server Description

In the serverInformation element, you can provide basic information about your server including contact information, and information about the group that hosts the server.

<serverInformation>
    <name>Initial TDS Installation</name>
    <logoUrl>/thredds/threddsIcon.gif</logoUrl>
    <logoAltText>Initial TDS Installation</logoAltText>

    <abstract>Scientific Data</abstract>
    <keywords>meteorology, atmosphere, climate, ocean, earth science</keywords>

    <contact>
      <name>Support</name>
      <organization>My Group</organization>
      <email>support@my.group</email>
      <phone></phone>
    </contact>
    <hostInstitution>
      <name>My Group</name>
      <webSite>http://www.my.group/</webSite>
      <logoUrl>myGroup.gif</logoUrl>
      <logoAltText>My Group</logoAltText>
    </hostInstitution>
</serverInformation>

The information provided in the serverInformation element is used in:

NOTE: The best way to use your own logo is to put it in the ${tomcat_home}/content/thredds/public/ directory, and specify it in serverInformation as /thredds/<name>, e.g.:

<logoUrl>/thredds/yourIcon.gif</logoUrl>

Server Information Documents

The TDS supports the following requests for server information:

Generated HTML Pages

In the htmlSetup element, you can configure which CSS documents are used in all the HTML pages generated by the TDS. Default CSS files are provided with the thredds.war distribution, and should not be modified. Instead, these can be overridden by placing the appropriate CSS files in the ${tomcat_home}/content/thredds/public/ directory and pointing to them here:

<htmlSetup>
1)  <standardCssUrl>tds.css</standardCssUrl>
2)  <catalogCssUrl>tdsCat.css</catalogCssUrl>    
3)  <openDapCssUrl>tdsDap.css</openDapCssUrl>
4)  <googleTrackingCode>239487348739933</googleTrackingCode>
</htmlSetup>
where:
  1. The CSS used in TDS dataset pages.
  2. The CSS used in TDS catalogs pages
  3. The CSS used in the OPeNDAP form.
  4. Google Analytics Tracking Code (GATC) enables tracking catalog use. Obtain the GATC from Google and enter it here to enable this feature. (since version 4.3.14)

Controlling THREDDS catalog output

since version 4.1

<catalogWriting>
  <useBytesForDataSize>false<useBytesForDataSize/>
</catalogWriting>

Extra Catalog Roots

<catalogRoot>tempCatalog.xml</catalogRoot>
<catalogRoot>idd/catalog.xml</catalogRoot>
<catalogRoot>catgen/subdir/enhancedCatalog-1.0.xml</catalogRoot>

These elements name your root catalogs that are not referenced from your main catalog ( ${tomcat_home}/content/thredds/catalog.xml). On startup, the TDS reads the main catalog and any root catalogs you list here, plus any catalogs that are referenced by them in a catalogRef. Data roots and other needed information are found and cached. All the catalogs found in this way are called static catalogs, and all static catalogs must live under the ${tomcat_home}/content/thredds directory.

Adding Viewers

<Viewer>my.package.MyViewer</Viewer>

You can place a link to your own Viewer on the TDS HTML page, by loading a viewer at runtime. This line is needed in the config file only if you are writing your own Java class.

Adding Dataset Sources

<datasetSource>my.package.DatasetSourceImpl</datasetSource>

You can add a DataSource - essentially an IOSP with access to Servlet request parameters, by loading a dataset source at runtime.


Checking for Updates

<TdsUpdateConfig>
  <logVersionInfo>true</logVersionInfo>
</TdsUpdateConfig>

The TdsUpdateConfig element controls if the TDS checks with Unidata regarding possible updates. The default (true) is for the TDS to check for the current stable and development release versions, and to log that information in the TDS serverStartup.log file as INFO entries. If you do not want the TDS to check for this on startup, set this to false.


Controlling Data Services

Remote Catalog Service for Catalogs

Catalog services are available by default for catalogs served by the local TDS. But for remote catalogs these services must be explicitly enabled in threddsConfig.xml:

<CatalogServices>
  <allowRemote>true</allowRemote>
</CatalogServices>

OPeNDAP Service

<Opendap>
  <ascLimit>50</ascLimit>
  <binLimit>500</binLimit>
  <serverVersion>opendap/3.7</serverVersion>
</Opendap>

This controls the OPeNDAP data service. Because its easy for a user to inadvertantly request very large amounts of data, the TDS limits the size of the data response. In our experience legitimate requests ask for subset sizes that are well below the defaults.

  1. ascLimit: maximum size of an ascii data request , in Megabytes. Default 50 Mbytes.
  2. binLimit: maximum size of a binary data request , in Megabytes. Default is 500 Mbytes.
  3. serverVersion: this is the String thats returned by the OPeNDAP getVersion request, and also placed into the XDOS-Server HTTP Header on all OPeNDAP responses.

WCS Service

The OGC WCS service provided as part of the TDS is described in more detail here. By default this service is disabled. It can be enabled by including the following in the threddsConfig.xml file:

<WCS>
  <allow>true</allow>
</WCS>

The following shows all the configuration options available in the WCS section of the threddsConfig.xml file with the default values shown:

<WCS>
  <allow>false</allow>
  <dir>(see the note below)</dir>
  <scour>15 min</scour>
  <maxAge>30 min</maxAge>
</WCS>

We recommend that you include in the threddsConfig.xml file only the options you want to change. Here is the description of the various options:

  1. allow: a value of "true" enables the WCS service.
  2. dir: the working directory where generated files are cached before being sent to the client (see choosing a cache directory). If not otherwise set, the TDS will use the ${tomcat_home}/content/thredds/cache/wcs/ directory. We recommend that you do not specify a WCS.dir element, and use the default.
  3. scour: how often to scour the working directory, to delete files that were not successfully downloaded.
  4. maxAge: how long to leave the files in the working directory while the download is occurring. The files are deleted after a successful download. Do not set to <= 0.

WMS Service

The OGC WMS service provided as part of the TDS is described in more detail here. By default this service is disabled. It can be enabled by including the following in the threddsConfig.xml file:

<WMS>
  <allow>true</allow>
</WMS>

The following shows all the configuration options available in the WMS section of the threddsConfig.xml file with the default values shown:

<WMS>
  <allow>false</allow>
  <allowRemote>false</allowRemote>
  <paletteLocationDir>/WEB-INF/palettes</paletteLocationDir>
  <maxImageWidth>2048</maxImageWidth>
  <maxImageHeight>2048</maxImageHeight>
</WMS>

We recommend that you include in the threddsConfig.xml file only the options you want to change. Here is the description of the various options:

  1. allow: a value of "true" enables the WMS service.
  2. allowRemote: a value of "true" enables the WMS service for datasets available from a remote server.
  3. paletteLocationDir: optionally specify the location of the directory containing your own palette files, by specifying the directory where they are contained. If the directory location starts with a "/", the path is absolute, otherwise it is relative to ${tomcat_home}/content/thredds/. If you don't specify it, or specify it incorrectly, the default palettes will be used, which are in the war file under WEB-INF/palettes.
  4. maxImageWidth: the maximum image width in pixels that this WMS service will return.
  5. maxImageHeight: the maximum image height in pixels that this WMS service will return.

NetCDF Subset Service (NCSS)

The NetCDF Subset Service provided as part of the TDS is described in more detail here. By default this service is disabled. It can be enabled by including the following in the threddsConfig.xml file:

<NetcdfSubsetService>
  <allow>true</allow>
</NetcdfSubsetService>

The following shows all the configuration options available in the NetcdfSubsetService section of the threddsConfig.xml file with the default values shown:

<NetcdfSubsetService>
  <allow>false</allow>
  <dir>(see the note below)</dir>
  <scour>15 min</scour>
  <maxAge>30 min</maxAge>
  <maxFileDownloadSize>300 MB</maxFileDownloadSize>
</NetcdfSubsetService>

We recommend that you include in the threddsConfig.xml file only the options you want to change. Here is the description of the various options:

  1. allow: a value of "true" enables the NetCDF Subset Service.
  2. dir: the working directory for creating files for download (see choosing a cache directory). If not otherwise set, the TDS will use the ${tomcat_home}/content/thredds/cache/ncss/ directory. We recommend that you do not specify a NetcdfSubsetService.dir element, and use the default.
  3. scour: how often to scour the working directory, to delete files that were not successfully downloaded.
  4. maxAge: how long to leave the files in the working directory while the download is occurring. The files are deleted after a successful download. Do not set to <= 0.
  5. maxFileDownloadSize: maximum size of file that can be requested. Optional; default is that there is no size limitation. If the file is > 2 GB, large format netCDF will be written.

ncISO Service

By default the ncISO services are disabled in the TDS. They can be enabled by including the following in the threddsConfig.xml file:

<NCISO>
  <ncmlAllow>true</ncmlAllow>
  <uddcAllow>true</uddcAllow>
  <isoAllow>true</isoAllow>
</NCISO>

Each of the allow elements above enables the corresponding ncISO service (NCML, UDDC, and ISO). The ncISO services are described in more detail on the ncISO page.


CDM configuration

Feature Collections

<FeatureCollection>
  <RollingFileAppender>
    <MaxFileSize>1 MB</MaxFileSize>
    <MaxBackups>10</MaxBackups>
    <Level>INFO</Level>
  </RollingFileAppender>
</FeatureCollection>

Feature Collection logs are placed in ${tomcat_home}/content/thredds/logs/fc.<collectionName>.log. These are programatically added and therefore cannot be configured in log4j2.xml. By default, each Feature Collection will rollover at 1 MB, and 5 files will be kept. Messages at the level of INFO and above will be enabled. You can change those settings here (note that your changes will apply to all Feature Collections).

NetCDF-4 C library loading

<Netcdf4Clibrary>
  <libraryPath>/usr/local/lib</libraryPath>
  <libraryName>netcdf</libraryName>
  <useForReading>false</useForReading>
</Netcdf4Clibrary>

In order to write netCDF-4 files, you must have the netCDF-4 C library—version 4.3.1 or above—compiled and available on your system, along with all supporting libraries (HDF5, zlib, and curl). The details of this differ for each operating system. The elements above allow you to configure how the library is discovered and used.

For TDS users, we recommend setting the library path and name in threddsConfig.xml as in the above example.

NetCDF-Java runtime Loading

<nj22Config>
  <ioServiceProvider class="edu.univ.ny.stuff.FooFiles"/>
  <coordSysBuilder convention="foo" class="test.Foo"/>
  <coordTransBuilder name="atmos_ln_sigma_coordinates" type="vertical" class="my.stuff.atmosSigmaLog"/>
  <typedDatasetFactory datatype="Point" class="gov.noaa.obscure.file.Flabulate"/>
  <table type="GRIB1" filename="/home/rkambic/grib/tables/userlookup.lst"/>
  <table type="GRIB2" filename="/home/rkambic/grib/tables/grib2userparameters"/>
</nj22Config>

These elements allow you to specify runtime parameters for the Netcdf-Java library from the threddsConfig file. See the Netcdf-Java tutorial for an overview.

Aggregation

<Aggregation>
  <typicalDataset>penultimate</typicalDataset>
</Aggregation>

You can control how NcML Aggregation chooses its typical/template dataset — the one it uses to populate the metadata for the resulting aggregated dataset. Valid values are first, random, latest, and penultimate (latest but one). The default is penultimate.


Disk Caching and temporary files

The various cache directory locations are all under {tomcat_home}/content/thredds/ by default:

cache location description
AggregationCache.dir cache/agg/ for joinExisting aggregations only: write XML files here.
CdmRemote.dir cache/cdmr/ temporary files for cdmremote and cdmrFeature
CdmValidatorService.dir cache/cdmValidate/ temporary files for cdmvalidator (seperate war)
DiskCache.dir cache/cdm/

only used when non-writeable data directory or alwaysUse = true; puts CDM indexes, decompressed files, etc. into this directory

ehcache.dir cache/ehcache/ object cache, put ehcache backup file in this directory
FeatureCollectionCache.dir cache/collection/ when we read GridDataset for FMRC, write an XML summary, store in BDB in this directory
NetcdfSubsetService.dir cache/ncss/ temporary files for NCSS
WCS.dir cache/wcs/ temporary files for WCS

We recommend that you use these defaults, by not specifying them in the threddsConfig.xml file. If you need to move the cache location, move all of them by using a symbolic file link in {tomcat_home}/content/thredds/. At Unidata, we move the entire content directory by creating a symbolic link:

cd {tomcat_home}
ln -s /data/thredds/content content

These various caches at times may contain large amounts of data. You should choose a location that will not fill up (especially if that location affects other important locations like /opt, /home, etc). If you have a large disk for your data, that may be a good location for the cache directories. On unix-like machines, you can run 'df' to get a listing of disks on your machine. The listing includes size and mount location.

The following elements allow fine grain control over the location and scouring of each of these.

CDM library Disk cache

<DiskCache>
  <alwaysUse>false</alwaysUse>
  <dir>/temp/cache/</dir>
  <scour>1 hour</scour>
  <maxSize>10 Gb</maxSize>
</DiskCache>

These elements control where the CDM/NetCDF-Java library writes temporary files, for example when it needs to unzip files, or write GRIB index files, etc. If alwaysUse is true, these temporary files will always be written to the cache directory specified by dir (choosing a cache directory). If alwaysUse is false, TDS will try to write them to the same directory as the original file, and if the TDS doesnt have write permission it will then write the files to the cache directory. Write permission will be determined by what rights the Tomcat user has (the user that starts up Tomcat). For security reasons, you want to carefully limit the file permissions of the Tomcat user.

When opening a file, if alwaysUse is true, TDS looks only in the cache directory for the temporary file. If alwaysUse is false, TDS will first look for the temporary file in the same directory as the original file, and if not found, then will look in the cache.

Every scour amount of time, the largest items in the cache will be deleted, until the directory has less than maxSize bytes. Note that the directory will sometimes exceed maxSize, and will only be knocked back to maxSize when the scour thread runs. To turn off scouring, set the scour time to 0 (eg "0 secs").

If not otherwise set, the TDS will use the ${tomcat_home}/content/thredds/cache/cdm directory. We recommend that you use this default, by not specifying the DiskCache.dir element.

Aggregation Cache

since version 4.1

<AggregationCache>
  <dir>/tomcat_home/content/thredds/cache/agg/</dir>
  <scour>24 hours</scour>
  <maxAge>90 days</maxAge>
  <cachePathPolicy>nestedDirectory</cachePathPolicy>
</AggregationCache>

If you have joinExisting Aggregations, coordinate information will be written to a cache directory specified by dir (choosing a cache directory). If not otherwise set, the TDS will use the ${tomcat_home}/content/thredds/cache/agg/ directory. We recommend that you use this default, by not specifying a AggregationCache.dir element.

Every scour amount of time, any item that hasnt been changed since maxAge time will be deleted. If you have aggregations that never change, set scour to "-1" to disable the operation. Otherwise, make maxAge longer than the longest time between changes. Basically, you don't want to remove active aggregations.

cachePathPolicy controls how cache files are stored in dir. It must be set to one of oneDirectory or nestedDirectory (the default). oneDirectory will put all cache files into the same directory, while nestedDirectory will preserve their directory structure. Use nestedDirectory for large aggregations, as some file systems struggle when a directory contains thousands of files.

This cache information is intended to be permanent; it stores coordinate information from each file in the aggregation, so that the file does not have to be opened each time the dataset is opened. If you have large joinExisting aggregations, there will be a very pronounced difference with and without this cache.

The cache information is updated based on the recheckEvery field in the joinExisting aggregation element.

FeatureCollection cache

since version 4.2

This is where persistent information is kept about FMRCs, in order to speed them up. We recommend that you use the default settings, by not specifying this option.

 <FeatureCollection>
<dir>/tomcat_home/content/thredds/cache/collection/</dir> <maxSize>20 Mb</maxSize> <jvmPercent>2</jvmPercent>
</FeatureCollection>
  1. dir: location of Feature Collection cache, currently implemented with Berkeley DB. If not otherwise set, the TDS will use the${tomcat_home}/content/thredds/cache/collection/ directory We recommend that you use this default, by not specifying a FeatureCollection.dir element.
  2. maxSize: maximum amount of memory to be used for this cache.
  3. jvmPercent: alternately, set the memory use as a percent of JVM memory, ie -Xmx value. maxSize will override if present. Default is 2 %.

GRIB Index redirection

since version 4.3.15

<GribIndex>
  <alwaysUse>false</alwaysUse>
  <neverUse>false</neverUse>
  <dir>/tomcat_home/content/thredds/cache/grib/</dir>
  <policy>nestedDirectory</policy>
  <scour>0 hours</scour>
  <maxAge>90 days</maxAge>
</GribIndex>

These elements control where Grib index files are written.

  1. If alwaysUse is true, grib index files will always be written to the index directory specified by dir (choosing a cache directory). If neverUse is true, the index directory will never be used. If neither is set, the TDS will try to write grib indexes to the same directory as the original file, and if the TDS doesnt have write permission it will then write the files to the index directory. Write permission will be determined by what rights the Tomcat user has (the user that starts up Tomcat). For security reasons, you want to carefully limit the file permissions of the Tomcat user.

  2. The policy must be set to one of oneDirectory or nestedDirectory (the default). oneDirectory will put all index files into the same directory, while nestedDirectory will preserve the directory structure of the index files. Use nestedDirectory for large collections of files, as some file systems struggle when a directory contains thousands of files.

  3. Every scour amount of time, any files in the cache that are older than maxAge will be removed. To turn off scouring, set the scour time to 0 (eg "0 hours"), or leave out the <scour> element. Typically you do not want to scour the indices.

Managing the GRIB indices is an important task, and can be difficult if the files are changing, as in a rolling archive, or for very large collections. There are two typical ways to do this:

  1. For rolling archives, allow the indices to be written in the same directory as the data files by specifying <neverUse>true</neverUse> or by not using a <neverUse> or <alwaysUse> element (which uses the default behavior). When you delete the data files, delete the corresponding indices. (The TDM will eventually handle the task of mainintaining a rolling archive by deleting files).
  2. If you need to keep the index files separate from your data files, set <alwaysUse>true</alwaysUse>, and use <policy>nestedDirectory</policy>. There is currently no way to specify different cache directories for different datasets. All GRIB indices, both gbx9 and ncx2, are kept in the same cache.

A good rule of thumb is that the index files will need disk space between 500 and 1000 times smaller than the size of the grib data files. So a 1 Terabyte collection of GRIB data will need up to 2 GB of indices.


Object Caching

The default settings will work well enough, and you should only tune them if you have performance problems, and are able to monitor their effect.

File Handle Caching

<RandomAccessFile>
  <minFiles>400</minFiles>
  <maxFiles>500</maxFiles>
  <scour>11 min</scour>
</RandomAccessFile>

There is a pool of shared RandomAccessFile objects, each of which stores an open OS file handle. Since each OS has a maximum on the number of open file handles per process, you must make sure that the sum of the maxFiles does not exceed your OS maximum. For better performance, make these numbers as high as possible.

NetcdfFile Objects

<NetcdfFileCache>
  <minFiles>100</minFiles>
  <maxFiles>150</maxFiles>
  <scour>12 min</scour>
</NetcdfFileCache>
<TimePartition>
  <minFiles>100</minFiles>
  <maxFiles>150</maxFiles>
  <scour>13 min</scour>
</TimePartition>

These elements control the size of the TDS cache for objects for 1) NetcdfFile objects, and 2) Grib Partition files, respectively. Up to maxFiles objects will be cached, and every scour amount of time, older items in the cache will be released, until only minFiles objects are left. The scour element uses any valid udunits time string, such as sec, min, hour, day. To disable the cache, set maxFiles to 0.

Static Catalog Caching

since version 4.2.8

Static catalogs are cached for performance, under the assumption there are a small number of them. If you have a large number of static catalogs, you may turn caching off to save memory, at the cost of some performace slowdown. Root catalogs are always cached, as are catalogs with datasetFmrc and featureCollections in them.

<Catalog>
  <cache>false</cache>
</Catalog>

IGNORE BELOW THIS

LOOK the following may not be working

You may also set cache=false on a datasetRoot element. This controls whether a file is put in the NetcdfFile object cache. All files that are found through that datasetRoot are affected. Example:

 <catalog xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0"
  xmlns:xlink="http://www.w3.org/1999/xlink" name="THREDDS Catalog for  NetCDF Files" version="1.0.3">      
     
  <service name="ncdods" serviceType="OpenDAP" base="/thredds/dodsC/"/>      

  <datasetRoot path="FVCOM" location="/http/www/CODFISH/Data/COM/" cache="false"/>
  <datasetRoot path="ZZTOP" location="/http/www/CODFISH/Data/ZCOM/" />
      
  <dataset name="GOM2 Forecast" ID="gom2_nocache" serviceName="ncdods" urlPath="FVCOM/NECOFS/Forecasts/NECOFS_GOM2_FORECAST.nc" dataType="Grid"/>     
  <dataset name="GOM3 Forecast" ID="gom3_nocache" serviceName="ncdods" urlPath="FVCOM/NECOFS/Forecasts/NECOFS_GOM3_FORECAST.nc" dataType="Grid"/>     
  <dataset name="MASSBAY Forecast" ID="massbay_nocache"  serviceName="ncdods" urlPath="ZZTOP/NECOFS/Forecasts/NECOFS_FVCOM_OCEAN_MASSBAY_FORECAST.nc"  dataType="Grid"/> 
</catalog>    
 

In the above example, the files

will not be cached, but this one will be cached:

Ehcache Object Cache

NOT CURRENTLY USED

The ehcache object cache is backed up in this directory. Currently, only OS directory scans are cached here.

<ehcache>
  <configFile>/tomcat_home/webapp/WEB-INF/ehcache.xml</configFile>
  <dir>/tomcat_home/content/thredds/ehcache/</dir>
</ehcache>

The contentRoot Element

DO NOT USE

Intended to chain together multiple "content" directories. For instance, the following:

<contentRoots>
  <contentRoot>motherlode</contentRoot>
  <contentRoot>idd</contentRoot>
</contentRoots>

chains together:

The dataRoot Element

NOT YET IMPLEMENTED

Eventually will provide macro-replacment in datasetScan location attributes. For instance:

<DataRoots>
  <idd>/data/ldm/pub</idd>
</DataRoots>

Could be used with:

<datasetScan ... location="${iddDataRoot}/fsl">...</datasetScan>

THREDDS This document is maintained by elves and was last updated June 2016. Send comments to THREDDS support.