DNS Cache

Table of Contents
Level 1 Cache
Level 2 Cache

GreenArrow Engine comes with two DNS caching systems.

Level 1 Cache

This is GreenArrow’s primary cache used for message delivery. This cache is always on and is only accessible by GreenArrow.

Level 2 Cache

This cache can be queried by both GreenArrow and non-GreenArrow components. It is now deprecated and off by default. As the level 1 cache offers greater performance for message delivery, most of the benefits the level 2 cache previously offered no longer exist.

We no longer officially support the level 2 cache unless either:

You’re running a version of GreenArrow which predates the level 1 cache. It was introduced in GreenArrow Engine 4.1.199, which was released in December 2017.
We indicated that the level 2 cache should be used for some reason, such as needing to bypass a slow upstream DNS resolver.

If the level 2 cache is turned on, it can be queried by both GreenArrow and non-GreenArrow components by sending queries to 127.0.0.1.

Level 1 Cache

Basic Configuration

In most cases, the only DNS cache related configuration required by GreenArrow is to specify upstream DNS servers using nameserver entries in the /etc/resolv.conf configuration file. GreenArrow’s level 1 cache determines its upstream DNS servers by reading from this file.

For example, if you would like to query the Google and Cloudflare public DNS servers, you could populate /etc/resolv.conf with:

echo "nameserver 8.8.8.8
nameserver 8.8.4.4
nameserver 1.1.1.1" > /etc/resolv.conf

If your GreenArrow server uses a network management application that updates the contents of /etc/resolv.conf, then it may also be necessary to update that service’s name server configuration.

The level 1 cache does not conflict with other DNS servers, such as BIND.

Caching Period

The level 1 cache stores entries for a maximum of 6 minutes, so if a problem in the resolver is fixed or a DNS record is changed, it may take up to 6 minutes for the level 1 cache to attempt a new lookup.

Testing

The level 1 cache can be tested by sending an email while the log_dns configuration parameter is enabled.

Level 2 Cache

Basic Configuration

The level 2 cache is disabled by default. You can turn it off or on by adjusting the dns_cache_service_run configuration parameter in /var/hvmail/control/greenarrow.conf, then applying the change by running:

greenarrow_config reload

After applying this change, perform the steps listed in the Testing section below to confirm that the level 2 cache is functioning correctly.

After enabling the level 2 cache, you can configure GreenArrow’s level 1 cache to start using it by adding the following line to the /etc/resolv.conf file:

nameserver 127.0.0.1

In most configurations where the level 2 cache is in use, the above should be the only nameserver line in /etc/resolv.conf, but check with your systems administrator if you’re uncertain.

Caching Period

The level 2 cache can store records for multiple hours. You can purge the level 2 cache by restarting it with the following command:

svc -t /service/hvmail-dnscache

Testing

To verify that level 2 cache is running, run the following command:

hvmail_init status | grep hvmail-dnscache

Once you’ve verified that the level 2 cache is running, you can use the dig command to verify that it’s functioning correctly. For example, to look up the MX record for gmail.com, you would run:

dig mx gmail.com @127.0.0.1

Collocating with BIND

If the level 2 cache is enabled, it binds to 127.0.0.1 on both UDP and TCP port 53. The BIND DNS server binds to all IPs on port 53 by default. This is a conflict which is resolvable in either of the following ways:

Don’t run GreenArrow’s level 2 cache.
Configure BIND not to bind to 127.0.0.1 by updating the listen-on directive. For example, to only bind to 1.2.3.4 and 1.2.3.5, you would include the following in BIND’s configuration:
```
listen-on { 1.2.3.4; 1.2.3.5; };
```

Modes

The level 2 cache has two modes:

Full recursive DNS resolver. This is the default mode. The level 2 cache queries authoritative nameservers directly starting at the root nameservers.

You can enable this mode with three steps. First, run:

echo 0 > /var/hvmail/control/dnscache/env/FORWARDONLY

Second, restore the default list of nameservers by running:

echo "198.41.0.4
199.9.14.201
192.33.4.12
199.7.91.13
192.203.230.10
192.5.5.241
192.112.36.4
198.97.190.53
192.36.148.17
192.58.128.30
193.0.14.129
199.7.83.42
202.12.27.33" > /var/hvmail/control/dnscache/root/servers/@

Third, restart the service by running:

svc -t /service/hvmail-dnscache

Caching DNS server. In this mode, the level 2 cache forwards all requests for which it doesn’t have a cached answer to a recursive nameserver.

You can enable this mode in three steps. First, run:
```
echo 1 > /var/hvmail/control/dnscache/env/FORWARDONLY
```
Second, edit /var/hvmail/control/dnscache/root/servers/@ to contain the IP addresses of the servers you would like to query.

Third, restart the service by running:
```
svc -t /service/hvmail-dnscache
```

After applying changes, perform the steps listed in the Testing section of this document to confirm that the DNS caching server is functioning correctly.