"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "libdap-3.8.2/README.dodsrc" of archive libdap-3.8.2.tar.gz:

    1 $Id: README.dodsrc 18646 2008-04-25 19:21:25Z jimg $
    2 
    3 Current for version 3.7.6 (12 March 2007)
    4 
    5 The libdap client-side configuration file (.dodsrc) is used to configure how
    6 clients cache responses and how they interact with proxy servers. By default
    7 the configuration file resides in a users home directory and is called
    8 `.dodsrc'. This can be changed by creating the environment variable
    9 DODS_CONF and setting it to the full pathname of the configuration file.
   10 
   11 About the Win32 builds:
   12 
   13 For Win32 (Windows XP and Vista) a client linked with libdapclient will look
   14 for the .dodsrc file in the following locations: C:\Dods; %APPDATA%; %TEMP%;
   15 and %TMP%. If no .dodsrc file is found, the library will create one in
   16 %APPDATA%. Note that on some Windows XP machines a user's 'Application Data'
   17 directory is hidden. To see and edit the .dodsrc file, open a file browser
   18 window from the Start menu, go to your home directory and then type in 
   19 'Application Data'. The .dodsrc file will be created by the first OPeNDAP
   20 client to run if there's not a copy already there.
   21 
   22 Another note about the Win32 builds and the .dodsrc file: It appears that
   23 client-side caching does not work in recent versions of the library, so until
   24 further notice, leave USE_CACHE set to zero.
   25 
   26 New feature added with libdap version 3.7.3 (7 Nov 2006)
   27 
   28 The configuration file can now be used to control client-side behavior when
   29 accessing servers using SSL. By default, certificates must be signed by a
   30 certificate authority. The libcurl package recognizes a large set of 
   31 CAs; you can sign your own certificates as well (but see the OpenSSL
   32 documentation for more information). In addition, server hosts must identify
   33 themselves using the same name as is used in the certificate.
   34 
   35 To disable these features, set the configuration parameter VALIDATE_SSL to
   36 zero. By default, these features are now enabled following the defaults for
   37 libcurl.
   38 
   39 If a DODS client starts and cannot find the configuration file, then one with
   40 default parameters will be created in the user's home directory. By default
   41 caching will be enabled with a maximum cache size of 20M and a default
   42 expiration time of 24 hours. By default no proxy server is configured and SSL
   43 hosts and certificates are validated. Also by default, compression is not
   44 activated.
   45 
   46 A sample configuration file looks like (the line numbers are not part of the
   47 file; they've been added to make the description clearer):
   48 
   49 0   # Comments start with a `#' in the first column.
   50 1	USE_CACHE=1
   51 2	MAX_CACHE_SIZE=20
   52 3	MAX_CACHED_OBJ=5
   53 4	IGNORE_EXPIRES=0
   54 5	CACHE_ROOT=/home/jimg/.dods_cache/
   55 6	DEFAULT_EXPIRES=86400
   56 7	DEFLATE=0
   57 8	VALIDATE_SSL=1
   58 9	PROXY_SERVER=http,http://jimg:password@dcz.dods.org/
   59 10	NO_PROXY_FOR=http,dcz.dods.org
   60 11	AIS_DATABASE=.ais_sst_database
   61     
   62 COMMENTS 
   63 Starting a line with a `#' makes that line a comment. 
   64 
   65 CACHING 
   66 
   67 The parameters on lines 1 through 6 determine how the DAP++ library will use
   68 its HTTP 1.1 cache. If the value of USE_CACHE is 1, the cache is active. A
   69 value of 0 turns off the cache. Make sure you use zero (0) and not the letter
   70 `O'.
   71 
   72 The value of MAX_CACHE_SIZE sets the maximum size of the cache in megabytes.
   73 Once the cache reaches this size, caching more objects will cause cache
   74 garbage collection. The algorithm used is to first purge the cache of any
   75 stale entries and then remove remaining entries starting with those that have
   76 the lowest hit count. Garbage collection stops when 90% of the cache has been
   77 purged.
   78 
   79 The value of MAX_CACHED_OBJ sets the maximum size of any individual object in
   80 the cache in megabytes. Objects received from a server larger than this value
   81 will not be cached even if there's room for them without purging other
   82 objects.
   83 
   84 The parameter CACHE_ROOT contains the pathname to the cache's top directory.
   85 If two or more users want to share a cache, then they must both have read and
   86 write permissions to the cache root.
   87 
   88 If the value of IGNORE_EXPIRES is 1, then Expires: headers in response
   89 documents will be ignored. The value of DEFAULT_EXPIRES sets the expiration
   90 time for any response that does not include either an Expires or
   91 Last-Modified header. The value is given in seconds; 86,400 is 24 hours. In
   92 general you should *not* ignore the Expires header; the server probably had a
   93 good reason to send it along with the response. This parameter is here for
   94 unusual situations.
   95 
   96 Note: If a Last-Modified header is returned with the response, and there's
   97 *no* Expires header, the expiration time is is 10% of the difference between
   98 the current time and the LM time or 48 hours, whichever is smaller. Note that
   99 libdap ignores the DEFAULT_EXPIRES time in this case. Any request made before
  100 the expiration time will use the cached response without validation. Any
  101 request made after the expiration time will use a conditional GET. Servers
  102 that have been upgraded to 3.2 or greater will return a 304 response if the
  103 cached response is still valid or a new response if it is not valid.
  104 
  105 If the value of ALWAYS_VALIDATE is 1, then all accesses will be validated with
  106 the origin server. A value of 0 causes libwww to use the more complex
  107 expiration and validate algorithm.
  108 
  109 CONTROLLING DATA COMPRESSION
  110 
  111 If the DEFLATE parameter is set to one (DEFLATE=1) then clients will request 
  112 that servers compress data transmissions. Servers may or may not honor this
  113 request depending on their abilities.
  114 
  115 SSL VALIDATION
  116 
  117 Set VALIDATE_SSL to zero to turn off SSL server host and certificate
  118 validation. By default, SSL hosts and certificates are now validated. If
  119 you're using your own certificates and don't want to pay to have them signed
  120 by a CA or to run your own authorization site, use this to defeat SSL
  121 validation. The old libdap default behavior was to _not_ perform validation
  122 (because that was the old libcurl default) and we've included this option so
  123 that you can get that old behavior.
  124 
  125 PROXY SERVERS
  126 
  127 Note that the parameters PROXY_SERVER and NO_PROXY_FOR may be repeated
  128 to add multiple proxy servers, suppress proxy access for several hosts, etc.
  129 
  130 Lines 9 and 10 contain the parameters used to configure a proxy server.
  131 The parameter PROXY_SERVER configures a default proxy server. The format is
  132 
  133     PROXY_SERVER=<protocol>,<proxy host url>
  134 
  135 The only supported protocols are http, https, and ftp.
  136 <proxy host url> must be a full URL to the host running the proxy server. If a
  137 password is used to access the proxy server, include it in the URL using the
  138 <user:password@host> syntax as shown in the example.
  139 
  140 The NO_PROXY parameter provides a simple way to say that access to a certain
  141 host should never go through a proxy. The syntax of NO_PROXY is:
  142 
  143     NO_PROXY=<protocol>,<hostname>
  144 
  145 where <protocol> is as for PROXY_SERVER
  146 <hostname> is the name of the host, not a url.
  147 
  148 The Ancillary Information Service
  149 
  150 See README.AIS for more information about the AIS.