GreenArrow Documentation

DNS 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:

  1. 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.
  2. 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

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
nameserver" > /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.


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:


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


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, you would run:

dig mx @

Collocating with BIND

If the level 2 cache is enabled, it binds to 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:

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

    listen-on {;; };


The level 2 cache has two modes:

  1. 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 "" > /var/hvmail/control/dnscache/root/servers/@

    Third, restart the service by running:

    svc -t /service/hvmail-dnscache

  2. 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.