== Host name resolution

Vert.x uses an an address resolver for resolving host name into IP addresses instead of
the JVM built-in blocking resolver.

An host name resolves to an IP address using:

- the _hosts_ file of the operating system
- otherwise DNS queries against a list of servers

By default it will use the list of the system DNS server addresses from the environment, if that list cannot be
retrieved it will use Google's public DNS servers `"8.8.8.8"` and `"8.8.4.4"`.

DNS servers can be also configured when creating a `link:../../apidocs/io/vertx/core/Vertx.html[Vertx]` instance:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().
            addServer("192.168.0.1").
            addServer("192.168.0.2:40000"))
);
----

The default port of a DNS server is `53`, when a server uses a different port, this port can be set
using a colon delimiter: `192.168.0.2:40000`.

NOTE: sometimes it can be desirable to use the JVM built-in resolver, the JVM system property
_-Dvertx.disableDnsResolver=true_ activates this behavior

=== Failover

When a server does not reply in a timely manner, the resolver will try the next one from the list, the search
is limited by `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setMaxQueries-int-[setMaxQueries]` (the default value is `4` queries).

A DNS query is considered as failed when the resolver has not received a correct answer within
`link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#getQueryTimeout--[getQueryTimeout]` milliseconds (the default value is `5` seconds).

=== Server list rotation

By default the dns server selection uses the first one, the remaining servers are used for failover.

You can configure `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setRotateServers-boolean-[setRotateServers]` to `true` to let
the resolver perform a round-robin selection instead. It spreads the query load among the servers and avoids
all lookup to hit the first server of the list.

Failover still applies and will use the next server in the list.

=== Hosts mapping

The _hosts_ file of the operating system is used to perform an hostname lookup for an ipaddress.

An alternative _hosts_ file can be used instead:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().
            setHostsPath("/path/to/hosts"))
);
----

=== Search domains

By default the resolver will use the system DNS search domains from the environment. Alternatively an explicit search domain
list can be provided:

[source,java]
----
Vertx vertx = Vertx.vertx(new VertxOptions().
    setAddressResolverOptions(
        new AddressResolverOptions().addSearchDomain("foo.com").addSearchDomain("bar.com"))
);
----

When a search domain list is used, the threshold for the number of dots is `1` or loaded from `/etc/resolv.conf`
on Linux, it can be configured to a specific value with `link:../../apidocs/io/vertx/core/dns/AddressResolverOptions.html#setNdots-int-[setNdots]`.

=== MacOS configuration

MacOS has a specific native extension to get the name server configuration of the system based on
<a href="https://opensource.apple.com/tarballs/mDNSResponder/">Apple's open source mDNSResponder</a>. When this extension is not present,
Netty logs the following warning.

----
[main] WARN io.netty.resolver.dns.DnsServerAddressStreamProviders - Can not find io.netty.resolver.dns.macos.MacOSDnsServerAddressStreamProvider in the classpath, fallback to system defaults. This may result in incorrect DNS resolutions on MacOS.
----

This extension is not required as its absence does not prevent Vert.x to execute, yet is *recommended*.

You can use add it to your classpath to improve the integration and remove the warning.

[source,xml]
----
<profile>
 <id>mac</id>
 <activation>
   <os>
     <family>mac</family>
   </os>
 </activation>
 <dependencies>
   <dependency>
     <groupId>io.netty</groupId>
     <artifactId>netty-resolver-dns-native-macos</artifactId>
     <classifier>osx-x86_64</classifier>
     <!--<version>Should align with netty version that Vert.x uses</version>-->
   </dependency>
 </dependencies>
</profile>
----