DNS

DNS lookup and name resolution

The node:dns module enables name resolution for looking up IP addresses of host names.

Import

import dns from 'node:dns';
// or
const dns = require('node:dns');

DNS Resolution Methods

There are two types of DNS resolution in Node.js:

1. dns.lookup() - Uses the operating system’s facilities (e.g., /etc/hosts)
2. dns.resolve*() - Connects directly to DNS servers

dns.lookup()

Basic Usage

import dns from 'node:dns';

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
  // address: "93.184.216.34" family: IPv4
});

With Options

dns.lookup('example.org', {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED
}, (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});

Get All Addresses

const options = {
  all: true
};

dns.lookup('example.org', options, (err, addresses) => {
  console.log('addresses:', addresses);
  // [
  //   { address: '93.184.216.34', family: 4 },
  //   { address: '2606:2800:220:1:248:1893:25c8:1946', family: 6 }
  // ]
});

Parameters

• hostname
• options
  • family 4, 6, or 0 (both)
  • hints getaddrinfo flags
  • all Return all addresses
  • order 'ipv4first', 'ipv6first', or 'verbatim'
• callback
  • err
  • address
  • family

DNS Resolve Methods

dns.resolve4()

Resolve IPv4 addresses (A records).

dns.resolve4('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('addresses:', addresses);
  // ['93.184.216.34']
});

With TTL Information

dns.resolve4('example.org', { ttl: true }, (err, addresses) => {
  console.log(addresses);
  // [
  //   { address: '93.184.216.34', ttl: 21600 }
  // ]
});

dns.resolve6()

Resolve IPv6 addresses (AAAA records).

dns.resolve6('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('IPv6 addresses:', addresses);
});

dns.resolveMx()

Resolve mail exchange records.

dns.resolveMx('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('MX records:', addresses);
  // [
  //   { priority: 10, exchange: 'mx.example.com' },
  //   { priority: 20, exchange: 'mx2.example.com' }
  // ]
});

dns.resolveTxt()

Resolve text records.

dns.resolveTxt('example.org', (err, records) => {
  if (err) throw err;
  console.log('TXT records:', records);
  // [
  //   ['v=spf1 include:_spf.example.com ~all']
  // ]
});

dns.resolveCname()

Resolve canonical name records.

dns.resolveCname('www.example.org', (err, addresses) => {
  if (err) throw err;
  console.log('CNAME records:', addresses);
  // ['example.org']
});

dns.resolveNs()

Resolve name server records.

dns.resolveNs('example.org', (err, addresses) => {
  if (err) throw err;
  console.log('NS records:', addresses);
  // ['ns1.example.com', 'ns2.example.com']
});

dns.resolveSrv()

Resolve service records.

dns.resolveSrv('_http._tcp.example.org', (err, addresses) => {
  if (err) throw err;
  console.log('SRV records:', addresses);
  // [
  //   {
  //     priority: 10,
  //     weight: 5,
  //     port: 80,
  //     name: 'server.example.org'
  //   }
  // ]
});

dns.resolveSoa()

Resolve start of authority record.

dns.resolveSoa('example.org', (err, address) => {
  if (err) throw err;
  console.log('SOA record:', address);
  // {
  //   nsname: 'ns.example.com',
  //   hostmaster: 'root.example.com',
  //   serial: 2013101809,
  //   refresh: 10000,
  //   retry: 2400,
  //   expire: 604800,
  //   minttl: 3600
  // }
});

dns.resolvePtr()

Resolve pointer records (reverse DNS).

dns.resolvePtr('34.216.184.93.in-addr.arpa', (err, addresses) => {
  if (err) throw err;
  console.log('PTR records:', addresses);
});

dns.resolveCaa()

Resolve certification authority authorization records.

dns.resolveCaa('example.org', (err, records) => {
  if (err) throw err;
  console.log('CAA records:', records);
  // [
  //   { critical: 0, iodef: 'mailto:[e-mail]' },
  //   { critical: 128, issue: 'pki.example.com' }
  // ]
});

Reverse DNS Lookup

dns.reverse('8.8.8.8', (err, hostnames) => {
  if (err) throw err;
  console.log('Reverse DNS:', hostnames);
  // ['dns.google']
});

DNS Server Configuration

Get DNS Servers

const servers = dns.getServers();
console.log('DNS servers:', servers);
// ['8.8.8.8', '8.8.4.4']

Set DNS Servers

dns.setServers([
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053'
]);

Class: dns.Resolver

Create independent DNS resolvers with custom settings.

Creating a Resolver

import { Resolver } from 'node:dns';

const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

resolver.resolve4('example.org', (err, addresses) => {
  console.log(addresses);
});

Resolver Options

const resolver = new Resolver({
  timeout: 5000,      // Query timeout in milliseconds
  tries: 4,           // Number of tries per name server
  maxTimeout: 10000   // Max retry timeout
});

Resolver Methods

resolver.setLocalAddress([ipv4][, ipv6])

Set the IP addresses to use when making DNS requests.

resolver.setLocalAddress('192.168.1.100');

resolver.cancel()

Cancel all outstanding DNS queries.

resolver.cancel();

DNS Promises API

Using Promises

import { promises as dnsPromises } from 'node:dns';

try {
  const addresses = await dnsPromises.resolve4('example.org');
  console.log('Addresses:', addresses);
} catch (err) {
  console.error('DNS error:', err);
}

Lookup with Promises

import { promises as dnsPromises } from 'node:dns';

const { address, family } = await dnsPromises.lookup('example.org');
console.log('address: %j family: IPv%s', address, family);

Resolver with Promises

import { Resolver } from 'node:dns/promises';

const resolver = new Resolver();
resolver.setServers(['1.1.1.1', '8.8.8.8']);

const addresses = await resolver.resolve4('example.org');
console.log(addresses);

Error Handling

Common Error Codes

• ENOTFOUND - Domain name not found
• ENODATA - No data returned from DNS
• ETIMEOUT - DNS query timed out
• ECONNREFUSED - Connection refused
• ECANCELLED - Query was cancelled

Error Handling Example

dns.lookup('nonexistent.invalid', (err, address) => {
  if (err) {
    if (err.code === 'ENOTFOUND') {
      console.error('Domain not found');
    } else if (err.code === 'ETIMEOUT') {
      console.error('DNS query timed out');
    } else {
      console.error('DNS error:', err);
    }
    return;
  }
  console.log('Address:', address);
});

Setting Default Result Order

import dns from 'node:dns';

// Set default ordering for dns.lookup()
dns.setDefaultResultOrder('ipv4first');
// or
dns.setDefaultResultOrder('ipv6first');
// or
dns.setDefaultResultOrder('verbatim');

const order = dns.getDefaultResultOrder();
console.log('Current order:', order);

Example: Complete DNS Tool

import dns from 'node:dns';
import { promisify } from 'node:util';

const lookup = promisify(dns.lookup);
const resolve4 = promisify(dns.resolve4);
const resolve6 = promisify(dns.resolve6);
const resolveMx = promisify(dns.resolveMx);
const reverse = promisify(dns.reverse);

async function dnsLookupAll(hostname) {
  console.log(`\nDNS Lookup for: ${hostname}\n`);
  
  try {
    // Basic lookup
    const { address, family } = await lookup(hostname);
    console.log('Primary IP:', address, `(IPv${family})`);
    
    // IPv4 addresses
    const ipv4 = await resolve4(hostname);
    console.log('IPv4 Addresses:', ipv4);
    
    // IPv6 addresses
    try {
      const ipv6 = await resolve6(hostname);
      console.log('IPv6 Addresses:', ipv6);
    } catch (err) {
      console.log('IPv6: Not available');
    }
    
    // MX records
    try {
      const mx = await resolveMx(hostname);
      console.log('MX Records:', mx);
    } catch (err) {
      console.log('MX: Not available');
    }
    
    // Reverse DNS
    try {
      const hostnames = await reverse(address);
      console.log('Reverse DNS:', hostnames);
    } catch (err) {
      console.log('Reverse DNS: Not available');
    }
    
  } catch (err) {
    console.error('Error:', err.message);
  }
}

// Usage
await dnsLookupAll('example.org');

Example: DNS Caching

import dns from 'node:dns';
import { promisify } from 'node:util';

const lookup = promisify(dns.lookup);

class DNSCache {
  constructor(ttl = 60000) {
    this.cache = new Map();
    this.ttl = ttl;
  }
  
  async lookup(hostname) {
    const cached = this.cache.get(hostname);
    
    if (cached && Date.now() < cached.expires) {
      return cached.address;
    }
    
    const { address } = await lookup(hostname);
    
    this.cache.set(hostname, {
      address,
      expires: Date.now() + this.ttl
    });
    
    return address;
  }
  
  clear() {
    this.cache.clear();
  }
}

// Usage
const dnsCache = new DNSCache(300000); // 5 minutes
const address = await dnsCache.lookup('example.org');

Performance Considerations

1. Use dns.lookup() for simple hostname resolution - It’s faster and uses the OS cache
2. Use dns.resolve*() for DNS-specific queries - Direct DNS server communication
3. Implement DNS caching - Reduce DNS queries for frequently accessed domains
4. Handle errors gracefully - DNS failures are common
5. Use Promise API - Cleaner async/await syntax

Best Practices

// DO: Use promises for cleaner code
const { address } = await dnsPromises.lookup('example.org');

// DO: Handle errors
try {
  const addresses = await dnsPromises.resolve4('example.org');
} catch (err) {
  if (err.code === 'ENOTFOUND') {
    // Handle missing domain
  }
}

// DO: Use custom resolvers for specific DNS servers
const resolver = new Resolver();
resolver.setServers(['1.1.1.1']);

// AVOID: Synchronous operations (not available in dns module)
// AVOID: Too many concurrent DNS requests