|
Packit |
a4aae4 |
$Id$
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Current for version 3.7.6 (12 March 2007)
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The libdap client-side configuration file (.dodsrc) is used to configure how
|
|
Packit |
a4aae4 |
clients cache responses and how they interact with proxy servers. By default
|
|
Packit |
a4aae4 |
the configuration file resides in a users home directory and is called
|
|
Packit |
a4aae4 |
`.dodsrc'. This can be changed by creating the environment variable
|
|
Packit |
a4aae4 |
DODS_CONF and setting it to the full pathname of the configuration file.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
About the Win32 builds:
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
For Win32 (Windows XP and Vista) a client linked with libdapclient will look
|
|
Packit |
a4aae4 |
for the .dodsrc file in the following locations: C:\Dods; %APPDATA%; %TEMP%;
|
|
Packit |
a4aae4 |
and %TMP%. If no .dodsrc file is found, the library will create one in
|
|
Packit |
a4aae4 |
%APPDATA%. Note that on some Windows XP machines a user's 'Application Data'
|
|
Packit |
a4aae4 |
directory is hidden. To see and edit the .dodsrc file, open a file browser
|
|
Packit |
a4aae4 |
window from the Start menu, go to your home directory and then type in
|
|
Packit |
a4aae4 |
'Application Data'. The .dodsrc file will be created by the first OPeNDAP
|
|
Packit |
a4aae4 |
client to run if there's not a copy already there.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Another note about the Win32 builds and the .dodsrc file: It appears that
|
|
Packit |
a4aae4 |
client-side caching does not work in recent versions of the library, so until
|
|
Packit |
a4aae4 |
further notice, leave USE_CACHE set to zero.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
New feature added with libdap version 3.7.3 (7 Nov 2006)
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The configuration file can now be used to control client-side behavior when
|
|
Packit |
a4aae4 |
accessing servers using SSL. By default, certificates must be signed by a
|
|
Packit |
a4aae4 |
certificate authority. The libcurl package recognizes a large set of
|
|
Packit |
a4aae4 |
CAs; you can sign your own certificates as well (but see the OpenSSL
|
|
Packit |
a4aae4 |
documentation for more information). In addition, server hosts must identify
|
|
Packit |
a4aae4 |
themselves using the same name as is used in the certificate.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
To disable these features, set the configuration parameter VALIDATE_SSL to
|
|
Packit |
a4aae4 |
zero. By default, these features are now enabled following the defaults for
|
|
Packit |
a4aae4 |
libcurl.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
If a DODS client starts and cannot find the configuration file, then one with
|
|
Packit |
a4aae4 |
default parameters will be created in the user's home directory. By default
|
|
Packit |
a4aae4 |
caching will be enabled with a maximum cache size of 20M and a default
|
|
Packit |
a4aae4 |
expiration time of 24 hours. By default no proxy server is configured and SSL
|
|
Packit |
a4aae4 |
hosts and certificates are validated. Also by default, compression is not
|
|
Packit |
a4aae4 |
activated.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
A sample configuration file looks like (the line numbers are not part of the
|
|
Packit |
a4aae4 |
file; they've been added to make the description clearer):
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
0 # Comments start with a `#' in the first column.
|
|
Packit |
a4aae4 |
1 USE_CACHE=1
|
|
Packit |
a4aae4 |
2 MAX_CACHE_SIZE=20
|
|
Packit |
a4aae4 |
3 MAX_CACHED_OBJ=5
|
|
Packit |
a4aae4 |
4 IGNORE_EXPIRES=0
|
|
Packit |
a4aae4 |
5 CACHE_ROOT=/home/jimg/.dods_cache/
|
|
Packit |
a4aae4 |
6 DEFAULT_EXPIRES=86400
|
|
Packit |
a4aae4 |
7 DEFLATE=0
|
|
Packit |
a4aae4 |
8 VALIDATE_SSL=1
|
|
Packit |
a4aae4 |
9 PROXY_SERVER=http,http://jimg:password@dcz.dods.org/
|
|
Packit |
a4aae4 |
10 NO_PROXY_FOR=http,dcz.dods.org
|
|
Packit |
a4aae4 |
11 AIS_DATABASE=.ais_sst_database
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
COMMENTS
|
|
Packit |
a4aae4 |
Starting a line with a `#' makes that line a comment.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
CACHING
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The parameters on lines 1 through 6 determine how the DAP++ library will use
|
|
Packit |
a4aae4 |
its HTTP 1.1 cache. If the value of USE_CACHE is 1, the cache is active. A
|
|
Packit |
a4aae4 |
value of 0 turns off the cache. Make sure you use zero (0) and not the letter
|
|
Packit |
a4aae4 |
`O'.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The value of MAX_CACHE_SIZE sets the maximum size of the cache in megabytes.
|
|
Packit |
a4aae4 |
Once the cache reaches this size, caching more objects will cause cache
|
|
Packit |
a4aae4 |
garbage collection. The algorithm used is to first purge the cache of any
|
|
Packit |
a4aae4 |
stale entries and then remove remaining entries starting with those that have
|
|
Packit |
a4aae4 |
the lowest hit count. Garbage collection stops when 90% of the cache has been
|
|
Packit |
a4aae4 |
purged.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The value of MAX_CACHED_OBJ sets the maximum size of any individual object in
|
|
Packit |
a4aae4 |
the cache in megabytes. Objects received from a server larger than this value
|
|
Packit |
a4aae4 |
will not be cached even if there's room for them without purging other
|
|
Packit |
a4aae4 |
objects.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The parameter CACHE_ROOT contains the pathname to the cache's top directory.
|
|
Packit |
a4aae4 |
If two or more users want to share a cache, then they must both have read and
|
|
Packit |
a4aae4 |
write permissions to the cache root.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
If the value of IGNORE_EXPIRES is 1, then Expires: headers in response
|
|
Packit |
a4aae4 |
documents will be ignored. The value of DEFAULT_EXPIRES sets the expiration
|
|
Packit |
a4aae4 |
time for any response that does not include either an Expires or
|
|
Packit |
a4aae4 |
Last-Modified header. The value is given in seconds; 86,400 is 24 hours. In
|
|
Packit |
a4aae4 |
general you should *not* ignore the Expires header; the server probably had a
|
|
Packit |
a4aae4 |
good reason to send it along with the response. This parameter is here for
|
|
Packit |
a4aae4 |
unusual situations.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Note: If a Last-Modified header is returned with the response, and there's
|
|
Packit |
a4aae4 |
*no* Expires header, the expiration time is is 10% of the difference between
|
|
Packit |
a4aae4 |
the current time and the LM time or 48 hours, whichever is smaller. Note that
|
|
Packit |
a4aae4 |
libdap ignores the DEFAULT_EXPIRES time in this case. Any request made before
|
|
Packit |
a4aae4 |
the expiration time will use the cached response without validation. Any
|
|
Packit |
a4aae4 |
request made after the expiration time will use a conditional GET. Servers
|
|
Packit |
a4aae4 |
that have been upgraded to 3.2 or greater will return a 304 response if the
|
|
Packit |
a4aae4 |
cached response is still valid or a new response if it is not valid.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
If the value of ALWAYS_VALIDATE is 1, then all accesses will be validated with
|
|
Packit |
a4aae4 |
the origin server. A value of 0 causes libwww to use the more complex
|
|
Packit |
a4aae4 |
expiration and validate algorithm.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
CONTROLLING DATA COMPRESSION
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
If the DEFLATE parameter is set to one (DEFLATE=1) then clients will request
|
|
Packit |
a4aae4 |
that servers compress data transmissions. Servers may or may not honor this
|
|
Packit |
a4aae4 |
request depending on their abilities.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
SSL VALIDATION
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Set VALIDATE_SSL to zero to turn off SSL server host and certificate
|
|
Packit |
a4aae4 |
validation. By default, SSL hosts and certificates are now validated. If
|
|
Packit |
a4aae4 |
you're using your own certificates and don't want to pay to have them signed
|
|
Packit |
a4aae4 |
by a CA or to run your own authorization site, use this to defeat SSL
|
|
Packit |
a4aae4 |
validation. The old libdap default behavior was to _not_ perform validation
|
|
Packit |
a4aae4 |
(because that was the old libcurl default) and we've included this option so
|
|
Packit |
a4aae4 |
that you can get that old behavior.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
PROXY SERVERS
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Note that the parameters PROXY_SERVER and NO_PROXY_FOR may be repeated
|
|
Packit |
a4aae4 |
to add multiple proxy servers, suppress proxy access for several hosts, etc.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
Lines 9 and 10 contain the parameters used to configure a proxy server.
|
|
Packit |
a4aae4 |
The parameter PROXY_SERVER configures a default proxy server. The format is
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
PROXY_SERVER=<protocol>,<proxy host url>
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The only supported protocols are http, https, and ftp.
|
|
Packit |
a4aae4 |
<proxy host url> must be a full URL to the host running the proxy server. If a
|
|
Packit |
a4aae4 |
password is used to access the proxy server, include it in the URL using the
|
|
Packit |
a4aae4 |
<user:password@host> syntax as shown in the example.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The NO_PROXY parameter provides a simple way to say that access to a certain
|
|
Packit |
a4aae4 |
host should never go through a proxy. The syntax of NO_PROXY is:
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
NO_PROXY=<protocol>,<hostname>
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
where <protocol> is as for PROXY_SERVER
|
|
Packit |
a4aae4 |
<hostname> is the name of the host, not a url.
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
The Ancillary Information Service
|
|
Packit |
a4aae4 |
|
|
Packit |
a4aae4 |
See README.AIS for more information about the AIS.
|