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