DNS Name Resolution

DNS turns a name such as www.netburner.com into an IP address your application can connect to. The NetBurner API offers a blocking call for simple cases and a non-blocking pair for applications built around select().

This page covers what a lookup actually does, so you can size timeouts, read a packet capture, and choose between the two interfaces.

Choosing an Interface

Blocking                        Non-blocking
┌────────────────────┐          ┌──────────────────────┐
│ GetHostByName()    │          │ fd_dns_part1()       │
│                    │   vs     │ select()             │
│ returns an address │          │ fd_dns_processresult()│
└────────────────────┘          └──────────────────────┘
 Simple, blocks the task         Fits an existing select loop,
                                 you implement the retry policy

Use GetHostByName() unless your task already runs a select() loop and cannot afford to block. The non-blocking pair gives you the socket file descriptor so you can add it to your own fd_set.

Record Types

By default a lookup asks for both an IPv4 address and an IPv6 address, and returns whichever the host publishes. On an IPv4 only build it asks for IPv4 alone. This suits most applications, which simply want a usable address.

The TYPE and TYPE2 parameters narrow the request. Pass the same type twice to ask for one record type:

// IPv4 only
int rv = GetHostByName("www.netburner.com", &ipAddress, IPADDR::NullIP(),
                       TICKS_PER_SECOND * 10, DNS_A, DNS_A);

Pass DNS_AAAA as both types to ask for IPv6 alone. The available record types are listed under DNS Record Types.

The same two parameters apply to fd_dns_part1(), and the types passed there must match the types passed to fd_dns_processresult().

Timeouts and Retries

The timeout you pass is a total timeout for the whole lookup, not a per-query value. Within that budget the resolver retransmits an outstanding query on a backoff, so a query lost in transit is re-sent rather than costing the entire timeout.

Size the budget for the round trip you expect plus room for at least one retry. Ten seconds is reasonable for a public resolver, less for one on the LAN.

IPADDR ipAddress;
ipAddress.SetNull();
 
int rv = GetHostByName("www.netburner.com", &ipAddress, IPADDR::NullIP(),
                       TICKS_PER_SECOND * 10);
if (rv == DNS_OK)
{
    // ipAddress is valid
}

Return Codes

Code	Meaning
DNS_OK	A usable address was returned.
DNS_NOSUCHNAME	The server answered, and the name has no record of the requested type.
DNS_TIMEOUT	No usable answer arrived within the budget. The server may be unreachable, or the name may be unresolvable.
DNS_ERR	The request could not be made, for example a null name.

The distinction between DNS_NOSUCHNAME and DNS_TIMEOUT is worth reading carefully when diagnosing a failure. DNS_NOSUCHNAME means something replied. DNS_TIMEOUT means the timeout expired.

Before the First Lookup

DNS needs more than a link. The interface needs an active link and a DNS server address. It needs a gateway address as well if the DNS server is on another subnet.

WaitForActiveNetwork() waits for link only. An application that resolves a name immediately after startup should check the rest:

bool CanInterfaceDoDNS(int ifNumber)
{
    if (!InterfaceLinkActive(ifNumber)) return false;
    if (InterfaceDNS(ifNumber).IsNull()) return false;
 
    // A DNS server on this subnet is reached directly.
    if (IsLocal4(InterfaceDNS(ifNumber), ifNumber)) return true;
 
    // Anything further away needs a gateway.
    return InterfaceGate(ifNumber).NotNull();
}

Note: Check these prerequisites rather than a fixed delay. A device using a static configuration is ready to resolve names much sooner after boot than one waiting on a DHCP lease, so a delay tuned for one is wrong for the other.

Choosing the Server

Pass IPADDR::NullIP() to use the DNS server the interface already has, whether it came from DHCP or static configuration. This is what most applications want.

// Use the interface's configured DNS server
GetHostByName(name, &ip, IPADDR::NullIP(), TICKS_PER_SECOND * 10);
 
// Ask a specific server instead
IPADDR server;
server.SetFromAscii("8.8.8.8");
GetHostByName(name, &ip, server, TICKS_PER_SECOND * 10);

GetHostByNameViaIfNum() restricts the query to one interface on a multi-homed device.

The Response Cache

Successful lookups are cached, so a repeated lookup of the same name returns immediately without network traffic. Entries expire according to the TTL supplied by the DNS server.

A name resolved a moment ago costs nothing to resolve again, so applications are free to call GetHostByName() at the point of use rather than caching the address themselves.

An IP address written as text needs no lookup at all. GetHostByName("10.1.1.50", ...) returns that address directly, so a setting that accepts either a name or an address can be passed straight through.

The cache is enabled by DNS_CACHE in predef.h, and its size is set by NUM_DNS_CACHE in constants.h.

Names Ending in .local

A name ending in .local is not sent to your DNS server. It is resolved by multicast DNS: the query goes to the multicast group 224.0.0.251 on port 5353, and any host on the local network that owns the name answers.

This means .local lookups work with no DNS server configured at all, and equally that a correctly configured DNS server has no effect on them. Only IPv4 .local lookups are supported.

Non-blocking Lookups

fd_dns_part1() sends the query and returns a file descriptor to add to your fd_set. When select() reports the descriptor readable, fd_dns_processresult() parses whatever arrived and returns true once it has an address.

int fd = fd_dns_part1(name, IPADDR::NullIP(), DNS_A, DNS_AAAA);
if (fd >= 0)
{
    fd_set rd;
    FD_ZERO(&rd);
    FD_SET(fd, &rd);
 
    if (select(FD_SETSIZE, &rd, (fd_set *)0, (fd_set *)0, timeout) != 0)
    {
        IPADDR result;
        if (fd_dns_processresult(fd, name, result, DNS_A, DNS_AAAA))
        {
            // result is valid
        }
    }
    close(fd);
}

Three responsibilities move to you with this interface:

Close the descriptor. Every path out, including failure, must close() it.
Implement the timeout. Nothing bounds how long you wait; your application must decide when time out.
Match the record types. Pass the same TYPE and TYPE2 to both calls, or you will parse for records you never requested.

Note: fd_dns_processresult() returns true only when it has an address. A false return does not distinguish "still waiting" from "the server said no", so your timeout is what decides when to stop.

When a Lookup Fails

Start with the interface.** CanInterfaceDoDNS() above tests the prerequisites. A missing DNS server address is the common cause, followed by a missing gateway when the DNS server is on another subnet.

Read the return code.** DNS_TIMEOUT points at reachability, DNS_NOSUCHNAME means a server answered and the record does not exist.

Test with a name you have not resolved yet,** so the answer comes from the network rather than the cache.

Narrow the request to one record type** with DNS_A, DNS_A to confirm IPv4 resolution on its own.