DNS Extension

Warning

async-dns does not support:

Local hosts file e.g. /etc/hosts on Unix systems
The nsswitch.conf file (no plan to 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.

Note

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:

Scala

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

Java

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

Scala

sourceval resolved: Future[Dns.Resolved] = (IO(Dns) ? Dns.Resolve("google.com")).mapTo[Dns.Resolved]

Java

sourcefinal ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, new Dns.Resolve("google.com"), timeout);

Async-DNS API:

Scala

sourceval resolved: Future[DnsProtocol.Resolved] =
  (IO(Dns) ? DnsProtocol.Resolve("google.com")).mapTo[DnsProtocol.Resolved]

Java

sourcefinal 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

Scala

sourceval resolved: Future[DnsProtocol.Resolved] =
  (IO(Dns) ? DnsProtocol.Resolve("your-service", Srv)).mapTo[DnsProtocol.Resolved]

Java

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