spf_dns_cache.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
SPF_dns_server_t *	SPF_dns_cache_new (SPF_dns_server_t *layer_below, const char *name, int debug, int cache_bits)
void	SPF_dns_cache_set_ttl (SPF_dns_server_t *spf_dns_server, time_t min_ttl, time_t err_ttl, time_t txt_ttl, time_t rdns_ttl)
void	SPF_dns_set_conserve_cache (SPF_dns_server_t *spf_dns_server, int conserve_cache)

---

Detailed Description

The caching DNS layer provides a quick, in-process cache of DNS information. It is not designed to be a general DNS cache, it is tailored to the needs of the SPF system. In particular, you can cache compiled SPF records, thus reducing the need to constantly recompile commonly used ones.

In most cases, it is best to have at least a small DNS caching layer as the top layer.

Multiple caching DNS layers can be created, which could sometimes be useful. For example, caches of different sizes will have different hash collisions, thus reducing the number of redundant queries sent to lower DNS layers.

For an overview of the DNS layer system, see spf_dns.h

Definition in file spf_dns_cache.h.

---

Function Documentation

SPF_dns_server_t* SPF_dns_cache_new	(	SPF_dns_server_t *	layer_below,
		const char *	name,
		int	debug,
		int	cache_bits
	)

These routines take care of creating/destroying/etc. the objects that hold the DNS layer configuration. SPF_dns_server_t objects contain malloc'ed data, so they must be destroyed when you are finished with them, or you will leak memory.

cache_bits determines the size of the DNS cache. The cache will be 2^cache_bits entries large.

If debugging is turned on, information about cache hits and misses will be generated.

Definition at line 487 of file spf_dns_cache.c.

References SPF_dns_server_struct::add_cache, SPF_dns_cache_config_t::cache, SPF_dns_cache_config_t::cache_lock, SPF_dns_cache_config_t::cache_size, SPF_dns_cache_config_t::conserve_cache, SPF_dns_server_struct::debug, SPF_dns_server_struct::destroy, SPF_dns_cache_config_t::err_ttl, SPF_dns_server_struct::get_exp, SPF_dns_server_struct::get_spf, SPF_dns_cache_config_t::hash_mask, SPF_dns_server_struct::hook, SPF_dns_server_struct::layer_below, SPF_dns_server_struct::lookup, SPF_dns_cache_config_t::max_hash_len, SPF_dns_cache_config_t::min_ttl, SPF_dns_server_struct::name, NULL, SPF_dns_cache_config_t::rdns_ttl, SPF_ASSERT_NOTNULL, SPF_error, and SPF_dns_cache_config_t::txt_ttl.

Referenced by SPF_server_new().

void SPF_dns_cache_set_ttl	(	SPF_dns_server_t *	spf_dns_server,
		time_t	min_ttl,
		time_t	err_ttl,
		time_t	txt_ttl,
		time_t	rdns_ttl
	)

By default, the caching DNS layer uses the Time To Live (TTL) values that are obtained from the actual DNS Resource Records (RR). However, because we know more about the situation than general caching DNS resolvers, we can adjusted the TTLs to be more appropriate for the email system. For example, since DNS errors will cause a 4xx temporary failure to be returned by the MTA, and the RFCs require the sending MTA to wait a while before it tries to resend the message, we can cache DNS errors for a while. General caching resolvers can't know if the next request needs the latest information about a name server being down, so it doesn't cache this information.

The caching DNS layer allows the following minimal TTL values:

min_ttl The absolute minimum TTL value in all cases.

err_ttl The minimum TTL value to use when there is a DNS error.

txt_ttl The minimum TTL value to use when a TXT query is done. In the case of SPF, these are the SPF records and the explanation records. This TTL value is used even when no record is found, so domains that haven't set up SPF records won't be constantly queried. Since SPF records are intended to not be changed often, this value can be fairly large.

rdns_ttl The minimum TTL value to use when looking up information in the reverse DNS tree. This applies to both valid results, and when an error is detected.

Note that more than one of these TTL values may apply. A TXT RR lookup that fails will have a TTL that is the largest of the min_ttl, the err_ttl and the txt_ttl values.

Definition at line 555 of file spf_dns_cache.c.

References SPF_dns_cache_config_t::cache_lock, SPF_dns_cache_config_t::err_ttl, SPF_dns_server_struct::hook, SPF_dns_cache_config_t::min_ttl, NULL, SPF_dns_cache_config_t::rdns_ttl, SPF_ASSERT_NOTNULL, and SPF_dns_cache_config_t::txt_ttl.

void SPF_dns_set_conserve_cache	(	SPF_dns_server_t *	spf_dns_server,
		int	conserve_cache
	)

The caching DNS layer can try to conserve it's cache to only those queries that will likely to be used often. If told to conserve the cache entries, it will not cache queries that were constructed from things like the client IP address or the local part of the envelope-from email address. Such information may well be cached by the general DNS resolver, so the answers may be quickly obtained anyway.

By default, caches with fewer than 4k entries (12 bits) will try to conserve the cache entries, but larger caches will not. This is just a guess though. In reality, it will depend a great deal on how active your mail server is and what the typical TTL values that you get from the particular DNS records you query are.

Definition at line 577 of file spf_dns_cache.c.

References SPF_dns_cache_config_t::conserve_cache, SPF_dns_server_struct::hook, NULL, and SPF_ASSERT_NOTNULL.

---