"Fossies" - the Fresh Open Source Software Archive

Member "libspf2-1.2.10/src/include/spf_dns_cache.h" (28 Jan 2012, 4450 Bytes) of package /linux/privat/libspf2-1.2.10.tar.gz:

    1 /* 
    2  * This program is free software; you can redistribute it and/or modify
    3  * it under the terms of either:
    4  * 
    5  *   a) The GNU Lesser General Public License as published by the Free
    6  *      Software Foundation; either version 2.1, or (at your option) any
    7  *      later version,
    8  * 
    9  *   OR
   10  * 
   11  *   b) The two-clause BSD license.
   12  *
   13  * These licenses can be found with the distribution in the file LICENSES
   14  */
   15 
   16 
   17 
   18 
   19 #ifndef INC_SPF_DNS_CACHE
   20 #define INC_SPF_DNS_CACHE
   21 
   22 
   23 /**
   24  * @file
   25  *
   26  * The caching DNS layer provides a quick, in-process cache of DNS
   27  * information.  It is not designed to be a general DNS cache, it is
   28  * tailored to the needs of the SPF system.  In particular, you can
   29  * cache compiled SPF records, thus reducing the need to constantly
   30  * recompile commonly used ones.
   31  *
   32  * In most cases, it is best to have at least a small DNS caching
   33  * layer as the top layer.
   34  *
   35  * Multiple caching DNS layers can be created, which could sometimes
   36  * be useful.  For example, caches of different sizes will have
   37  * different hash collisions, thus reducing the number of redundant
   38  * queries sent to lower DNS layers.
   39  *
   40  *
   41  * For an overview of the DNS layer system, see spf_dns.h
   42  */
   43 
   44 
   45 /**
   46  * These routines take care of creating/destroying/etc. the objects
   47  * that hold the DNS layer configuration. SPF_dns_server_t objects contain
   48  * malloc'ed data, so they must be destroyed when you are finished
   49  * with them, or you will leak memory. 
   50  *
   51  * cache_bits determines the size of the DNS cache.  The cache will be
   52  * 2^cache_bits entries large.
   53  *
   54  * If debugging is turned on, information about cache hits and misses
   55  * will be generated.
   56  */
   57 SPF_dns_server_t    *SPF_dns_cache_new(SPF_dns_server_t *layer_below,
   58                 const char *name, int debug, int cache_bits);
   59 
   60 
   61 /**
   62  * By default, the caching DNS layer uses the Time To Live (TTL)
   63  * values that are obtained from the actual DNS Resource Records (RR).
   64  * However, because we know more about the situation than general
   65  * caching DNS resolvers, we can adjusted the TTLs to be more
   66  * appropriate for the email system.  For example, since DNS errors
   67  * will cause a 4xx temporary failure to be returned by the MTA, and
   68  * the RFCs require the sending MTA to wait a while before it tries to
   69  * resend the message, we can cache DNS errors for a while.  General
   70  * caching resolvers can't know if the next request needs the latest
   71  * information about a name server being down, so it doesn't cache
   72  * this information.
   73  *
   74  * The caching DNS layer allows the following minimal TTL values:
   75  *
   76  * min_ttl  The absolute minimum TTL value in all cases.
   77  *
   78  * err_ttl  The minimum TTL value to use when there is a DNS error.
   79  *
   80  * txt_ttl  The minimum TTL value to use when a TXT query is done.
   81  *              In the case of SPF, these are the SPF records and the
   82  *      explanation records.  This TTL value is used even when
   83  *      no record is found, so domains that haven't set up SPF
   84  *      records won't be constantly queried.  Since SPF
   85  *      records are intended to not be changed often, this
   86  *      value can be fairly large.
   87  *
   88  * rdns_ttl The minimum TTL value to use when looking up information
   89  *      in the reverse DNS tree.  This applies to both valid
   90  *      results, and when an error is detected.
   91  *
   92  * Note that more than one of these TTL values may apply.  A TXT RR
   93  * lookup that fails will have a TTL that is the largest of the
   94  * min_ttl, the err_ttl and the txt_ttl values.
   95  * 
   96  */
   97 
   98 void     SPF_dns_cache_set_ttl( SPF_dns_server_t *spf_dns_server,
   99                 time_t min_ttl, time_t err_ttl,
  100                 time_t txt_ttl, time_t rdns_ttl );
  101 
  102 /**
  103  * The caching DNS layer can try to conserve it's cache to only those
  104  * queries that will likely to be used often.  If told to conserve the
  105  * cache entries, it will not cache queries that were constructed from
  106  * things like the client IP address or the local part of the
  107  * envelope-from email address.  Such information may well be cached
  108  * by the general DNS resolver, so the answers may be quickly obtained
  109  * anyway.
  110  *
  111  * By default, caches with fewer than 4k entries (12 bits) will try to
  112  * conserve the cache entries, but larger caches will not.  This is
  113  * just a guess though.  In reality, it will depend a great deal on
  114  * how active your mail server is and what the typical TTL values that
  115  * you get from the particular DNS records you query are.
  116  */
  117 
  118 void     SPF_dns_set_conserve_cache( SPF_dns_server_t *spf_dns_server,
  119                 int conserve_cache );
  120 
  121 #endif