$Id$

Current for version 3.7.6 (12 March 2007)

The libdap client-side configuration file (.dodsrc) is used to configure how

clients cache responses and how they interact with proxy servers. By default

the configuration file resides in a users home directory and is called

`.dodsrc'. This can be changed by creating the environment variable

DODS_CONF and setting it to the full pathname of the configuration file.

About the Win32 builds:

For Win32 (Windows XP and Vista) a client linked with libdapclient will look

for the .dodsrc file in the following locations: C:\Dods; %APPDATA%; %TEMP%;

and %TMP%. If no .dodsrc file is found, the library will create one in

%APPDATA%. Note that on some Windows XP machines a user's 'Application Data'

directory is hidden. To see and edit the .dodsrc file, open a file browser

window from the Start menu, go to your home directory and then type in 

'Application Data'. The .dodsrc file will be created by the first OPeNDAP

client to run if there's not a copy already there.

Another note about the Win32 builds and the .dodsrc file: It appears that

client-side caching does not work in recent versions of the library, so until

further notice, leave USE_CACHE set to zero.

New feature added with libdap version 3.7.3 (7 Nov 2006)

The configuration file can now be used to control client-side behavior when

accessing servers using SSL. By default, certificates must be signed by a

certificate authority. The libcurl package recognizes a large set of 

CAs; you can sign your own certificates as well (but see the OpenSSL

documentation for more information). In addition, server hosts must identify

themselves using the same name as is used in the certificate.

To disable these features, set the configuration parameter VALIDATE_SSL to

zero. By default, these features are now enabled following the defaults for

libcurl.

If a DODS client starts and cannot find the configuration file, then one with

default parameters will be created in the user's home directory. By default

caching will be enabled with a maximum cache size of 20M and a default

expiration time of 24 hours. By default no proxy server is configured and SSL

hosts and certificates are validated. Also by default, compression is not

activated.

A sample configuration file looks like (the line numbers are not part of the

file; they've been added to make the description clearer):

0   # Comments start with a `#' in the first column.

1	USE_CACHE=1

2	MAX_CACHE_SIZE=20

3	MAX_CACHED_OBJ=5

4	IGNORE_EXPIRES=0

5	CACHE_ROOT=/home/jimg/.dods_cache/

6	DEFAULT_EXPIRES=86400

7	DEFLATE=0

8	VALIDATE_SSL=1

9	PROXY_SERVER=http,http://jimg:password@dcz.dods.org/

10	NO_PROXY_FOR=http,dcz.dods.org

11	AIS_DATABASE=.ais_sst_database

COMMENTS 

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

CACHING 

The parameters on lines 1 through 6 determine how the DAP++ library will use

its HTTP 1.1 cache. If the value of USE_CACHE is 1, the cache is active. A

value of 0 turns off the cache. Make sure you use zero (0) and not the letter

`O'.

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. The algorithm used is to 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.

The value of MAX_CACHED_OBJ 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.

The parameter CACHE_ROOT 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.

If the value of IGNORE_EXPIRES is 1, then Expires: headers in response

documents will be ignored. The value of DEFAULT_EXPIRES sets the expiration

time for any response that does not include either an Expires or

Last-Modified header. The value is given in seconds; 86,400 is 24 hours. In

general you should *not* ignore the Expires header; the server probably had a

good reason to send it along with the response. This parameter is here for

unusual situations.

Note: If a Last-Modified header is returned with the response, and there's

*no* Expires header, the expiration time is is 10% of the difference between

the current time and the LM time or 48 hours, whichever is smaller. Note that

libdap ignores the DEFAULT_EXPIRES time in this case. Any request made before

the expiration time will use the cached response without validation. Any

request made after the expiration time will use a conditional GET. Servers

that have been upgraded to 3.2 or greater will return a 304 response if the

cached response is still valid or a new response if it is not valid.

If the value of ALWAYS_VALIDATE is 1, then all accesses will be validated with

the origin server. A value of 0 causes libwww to use the more complex

expiration and validate algorithm.

CONTROLLING DATA COMPRESSION

If the DEFLATE parameter is set to one (DEFLATE=1) then clients will request 

that servers compress data transmissions. Servers may or may not honor this

request depending on their abilities.

SSL VALIDATION

Set VALIDATE_SSL to zero to turn off SSL server host and certificate

validation. By default, SSL hosts and certificates are now validated. If

you're using your own certificates and don't want to pay to have them signed

by a CA or to run your own authorization site, use this to defeat SSL

validation. The old libdap default behavior was to _not_ perform validation

(because that was the old libcurl default) and we've included this option so

that you can get that old behavior.

PROXY SERVERS

Note that the parameters PROXY_SERVER and NO_PROXY_FOR may be repeated

to add multiple proxy servers, suppress proxy access for several hosts, etc.

Lines 9 and 10 contain the parameters used to configure a proxy server.

The parameter PROXY_SERVER configures a default proxy server. The format is

    PROXY_SERVER=<protocol>,<proxy host url>

The only supported protocols are http, https, and ftp.

<proxy host url> must be a full URL to the host running the proxy server. If a

password is used to access the proxy server, include it in the URL using the

<user:password@host> syntax as shown in the example.

The NO_PROXY parameter provides a simple way to say that access to a certain

host should never go through a proxy. 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.

The Ancillary Information Service

See README.AIS for more information about the AIS.