DNS Extension


async-dns does not support:

Additionally, while search domains are supported through configuration, detection of the system configured Search domains is only supported on systems that provide this configuration through a /etc/resolv.conf file, i.e. it isn’t supported on Windows or OSX, and none of the environment variables that are usually supported on most *nix OSes are supported.


The async-dns API is marked as ApiMayChange as more information is expected to be added to the protocol.

Akka DNS is a pluggable way to interact with DNS. Implementations much implement akka.io.DnsProvider and provide a configuration block that specifies the implementation via provider-object.

To select which DnsProvider to use set akka.io.dns.resolver to the location of the configuration.

There are currently two implementations:

  • inet-address - Based on the JDK’s InetAddress. Using this will be subject to both the JVM’s DNS cache and its built in one.
  • async-dns - A native implemention of the DNS protocol that does not use any JDK classes or caches.

inet-address is the default implementation as it pre-dates async-dns, async-dns will likely become the default in the next major release.

DNS lookups can be done via the DNS extension:

val initial: Option[Dns.Resolved] = Dns(system).cache.resolve("google.com")(system, actorRef)
val cached: Option[Dns.Resolved] = Dns(system).cache.cached("google.com")
Option<Dns.Resolved> initial = Dns.get(system).cache().resolve("google.com", system, actorRef);
Option<Dns.Resolved> cached = Dns.get(system).cache().cached("google.com");

Alternatively the IO(Dns) actor can be interacted with directly. However this exposes the different protocols of the DNS provider. inet-adddress uses Dns.Resolve and Dns.Resolved where as the async-dns uses DnsProtocol.Resolve and DnsProtocol.Resolved. The reason for the difference is inet-address predates async-dns and async-dns exposes additional information such as SRV records and it wasn’t possible to evolve the original API in a backward compatible way.

Inet-Address API:

val resolved: Future[Dns.Resolved] = (IO(Dns) ? Dns.Resolve("google.com")).mapTo[Dns.Resolved]
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, new Dns.Resolve("google.com"), timeout);

Async-DNS API:

val resolved: Future[DnsProtocol.Resolved] = (IO(Dns) ? DnsProtocol.Resolve("google.com")).mapTo[DnsProtocol.Resolved]
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved =
    ask(dnsManager, DnsProtocol.resolve("google.com"), timeout);

The Async DNS provider has the following advantages:

  • No JVM DNS caching. It is expected that future versions will expose more caching related information.
  • No blocking. InetAddress resolving is a blocking operation.
  • Exposes SRV, A and AAAA records.

SRV Records

To get DNS SRV records akka.io.dns.resolver must be set to async-dns and DnsProtocol.Resolve’s requestType must be set to DnsProtocol.Srv

val resolved: Future[DnsProtocol.Resolved] = (IO(Dns) ? DnsProtocol.Resolve("your-service", Srv))
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved =
    ask(dnsManager, DnsProtocol.resolve("google.com", DnsProtocol.srvRequestType()), timeout);

The DnsProtocol.Resolved will contain akka.io.dns.SRVRecords.

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.