A.3 The OPeNDAP Client Initialization File (.dodsrc)

The following section refers only to OPeNDAP clients from release 3.2 and after.

When an OPeNDAP client starts up, it checks to see whether the user has an initialization file available to control the setting of a number of parameters having to do with caching, proxy servers, and other http issues. If this file is not found, one is created in the user's home directory, using default values.²⁴

The client initialization file is usually called .dodsrc, and is usually located in the user's home directory. You can change this by creating an environment variable called DODS_CACHE_INIT and setting it to the full pathname of the configuration file. As of OPeNDAP version 3.4, you should use DODS_CONF instead. DODS_CACHE_INIT is deprecated, and will disappear in future releases.

Here is a sample configuration file:

# Sample configuration file
USE_CACHE=1
MAX_CACHE_SIZE=20
MAX_CACHED_OBJ=5
IGNORE_EXPIRES=0
CACHE_ROOT=/home/user/.dods_cache/
DEFAULT_EXPIRES=86400
PROXY_SERVER=http,http://dcz.dods.org/
PROXY_FOR=http://dax.dods.org/.*,http://dods.org/
NO_PROXY_FOR=http://dcz.dods.org
DEFLATE=1
ALWAYS_VALIDATE=0

Comments

Starting a line with a # makes that line a comment.

Caching

The parameters on lines 2 through 7 control caching. The OPeNDAP client can store data you've requested on your local computer. If you repeat a request, the data can be retrieved from this local cache, saving the expense of a network connection. Most web browsers operate the same way. You can control the caching behavior with the following configuration file parameters.

CACHE_ROOT

This parameter contains the pathname to the cache's top directory. If two or more users want to share a cache, then they must both have read and write permissions to the cache root.

MAX_CACHE_SIZE

The value of MAX_CACHE_SIZE sets the maximum size of the cache in megabytes. Once the cache reaches this size, caching more objects will cause cache garbage collection. OPeNDAP will first purge the cache of any stale entries and then remove remaining entries starting with those that have the lowest hit count. Garbage collection stops when 90% of the cache has been purged.

MAX_CACHED_OBJ

This parameter sets the maximum size of any individual object in the cache in megabytes. Objects received from a server larger than this value will not be cached even if there's room for them without purging other objects.

Many web documents, and OPeNDAP data, are delivered with an expiration date in their header information. Generally, this is done for time-sensitive information that may not be valid after the expiration date. You can control the behavior of the OPeNDAP client with respect to expiration dates with two configuration file parameters.

IGNORE_EXPIRES

If the value of this parameter is 1 (one), then expiration dates will be ignored, and the caching behavior will be ruled by the DEFAULT_EXPIRES parameter.

DEFAULT_EXPIRES

Any data received without an expiration time will expire in the number of seconds given by this parameter. If IGNORE_EXPIRES is zero, this will apply to all data, whether or not it comes with an expiration date. The value is given in seconds. The configuration in the example is set for 24 hours.

Proxy Servers

An OPeNDAP client can negotiate proxy servers, with help from directions derived from its configuration file. There are three parameters that control proxy behavior. There can be more than one of each of these declarations.

PROXY_SERVER

This identifies a proxy server to use for all OPeNDAP requests, except for requests specifically modified by the other two proxy behavior directives. The format is:

PROXY_SERVER=protocol,proxy_URL
  

Where protocol is the name of an internet protocol, and proxy_URL must be a full URL to the host running the proxy server. HTTP is the only internet protocol supported by DODS, so protocol will always read http. There can be more than one proxy declaration, in which case, the OPeNDAP client will use the first proxy server on the list that responds.

PROXY_FOR

The PROXY_FOR parameter provides a way to specify that URLs which match a regular expression should be accessed using a particular proxy server. The syntax for PROXY_FOR is:

PROXY_FOR=regular expression,proxy_URL[,flags]
  

Where regular expression is an expression which matches the URL or group of URLs. For example `http://dax.dods.org/.*hdf' would match a URL ending in `.hdf' at dax.dods.org. The regular expression uses the POSIX basic syntax.proxy_URL is the same as above.

The flags parameter is an optional integer that configures the regular expression matcher. A value of zero sets the default. The four flag values and their meanings are:

REG_EXTENDED

If set, use the POSIX extended syntax regular expressions. To set this, add 1 to the value of flags.

REG_NEWLINE

If set, then . and [ ...] don't match newline. Also, the regular expression matcher will try a match beginning after every newline. Set this by adding 2 to flags.

REG_ICASE

If set, then we consider upper- and lowercase versions of letters to be equivalent when matching. Set by adding 4 to flags.

REG_NOSUB

If set, then when PREG is passed to regexec, that routine will report only success or failure, and nothing about the registers. Add 8 to flags to set this.

You can find a brief tutorial to regular expressions in the OPeNDAP bookshelfat Introduction to Regular Expressions.

NO_PROXY

Use this parameter to say that access to a certain host should never go through a proxy without using the more complicated regular expression syntax. The syntax of NO_PROXY is:

NO_PROXY=protocol,hostname
  

Where protocol is as for PROXY_SERVER, hostname is the name of the host, not a url.

Compression

Many OPeNDAP servers support compression of the returned data. This can save network bandwidth, and transmission time. You can tell your client to ask the server for compressed data by including a line in your .dodsrc file like this:

DEFLATE=1

Using a value of zero will make the client request only uncompressed data. If the directive is omitted, the default value is zero.

Validation

Caching data locally can be risky if the data in question change often. The ALWAYS_VALIDATE option controls whether the OPeNDAP client checks the validity of the cached data. The validity check in this case is simply a comparison of the date the data was cached with the "Last-modified" date of the remote data. If the configuration value is set to 1, the client will always validate the cached data. If set to 0, the data will not be validated (but may expire, according to the cache policy set by the DEFAULT_EXPIRES configuration directive).

If the directive is omitted, the default value is zero. That is, the default behavior is not to validate the data.