1# DNS 2 3<!--introduced_in=v0.10.0--> 4 5> Stability: 2 - Stable 6 7<!-- source_link=lib/dns.js --> 8 9The `node:dns` module enables name resolution. For example, use it to look up IP 10addresses of host names. 11 12Although named for the [Domain Name System (DNS)][], it does not always use the 13DNS protocol for lookups. [`dns.lookup()`][] uses the operating system 14facilities to perform name resolution. It may not need to perform any network 15communication. To perform name resolution the way other applications on the same 16system do, use [`dns.lookup()`][]. 17 18```js 19const dns = require('node:dns'); 20 21dns.lookup('example.org', (err, address, family) => { 22 console.log('address: %j family: IPv%s', address, family); 23}); 24// address: "93.184.216.34" family: IPv4 25``` 26 27All other functions in the `node:dns` module connect to an actual DNS server to 28perform name resolution. They will always use the network to perform DNS 29queries. These functions do not use the same set of configuration files used by 30[`dns.lookup()`][] (e.g. `/etc/hosts`). Use these functions to always perform 31DNS queries, bypassing other name-resolution facilities. 32 33```js 34const dns = require('node:dns'); 35 36dns.resolve4('archive.org', (err, addresses) => { 37 if (err) throw err; 38 39 console.log(`addresses: ${JSON.stringify(addresses)}`); 40 41 addresses.forEach((a) => { 42 dns.reverse(a, (err, hostnames) => { 43 if (err) { 44 throw err; 45 } 46 console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); 47 }); 48 }); 49}); 50``` 51 52See the [Implementation considerations section][] for more information. 53 54## Class: `dns.Resolver` 55 56<!-- YAML 57added: v8.3.0 58--> 59 60An independent resolver for DNS requests. 61 62Creating a new resolver uses the default server settings. Setting 63the servers used for a resolver using 64[`resolver.setServers()`][`dns.setServers()`] does not affect 65other resolvers: 66 67```js 68const { Resolver } = require('node:dns'); 69const resolver = new Resolver(); 70resolver.setServers(['4.4.4.4']); 71 72// This request will use the server at 4.4.4.4, independent of global settings. 73resolver.resolve4('example.org', (err, addresses) => { 74 // ... 75}); 76``` 77 78The following methods from the `node:dns` module are available: 79 80* [`resolver.getServers()`][`dns.getServers()`] 81* [`resolver.resolve()`][`dns.resolve()`] 82* [`resolver.resolve4()`][`dns.resolve4()`] 83* [`resolver.resolve6()`][`dns.resolve6()`] 84* [`resolver.resolveAny()`][`dns.resolveAny()`] 85* [`resolver.resolveCaa()`][`dns.resolveCaa()`] 86* [`resolver.resolveCname()`][`dns.resolveCname()`] 87* [`resolver.resolveMx()`][`dns.resolveMx()`] 88* [`resolver.resolveNaptr()`][`dns.resolveNaptr()`] 89* [`resolver.resolveNs()`][`dns.resolveNs()`] 90* [`resolver.resolvePtr()`][`dns.resolvePtr()`] 91* [`resolver.resolveSoa()`][`dns.resolveSoa()`] 92* [`resolver.resolveSrv()`][`dns.resolveSrv()`] 93* [`resolver.resolveTxt()`][`dns.resolveTxt()`] 94* [`resolver.reverse()`][`dns.reverse()`] 95* [`resolver.setServers()`][`dns.setServers()`] 96 97### `Resolver([options])` 98 99<!-- YAML 100added: v8.3.0 101changes: 102 - version: 103 - v16.7.0 104 - v14.18.0 105 pr-url: https://github.com/nodejs/node/pull/39610 106 description: The `options` object now accepts a `tries` option. 107 - version: v12.18.3 108 pr-url: https://github.com/nodejs/node/pull/33472 109 description: The constructor now accepts an `options` object. 110 The single supported option is `timeout`. 111--> 112 113Create a new resolver. 114 115* `options` {Object} 116 * `timeout` {integer} Query timeout in milliseconds, or `-1` to use the 117 default timeout. 118 * `tries` {integer} The number of tries the resolver will try contacting 119 each name server before giving up. **Default:** `4` 120 121### `resolver.cancel()` 122 123<!-- YAML 124added: v8.3.0 125--> 126 127Cancel all outstanding DNS queries made by this resolver. The corresponding 128callbacks will be called with an error with code `ECANCELLED`. 129 130### `resolver.setLocalAddress([ipv4][, ipv6])` 131 132<!-- YAML 133added: 134 - v15.1.0 135 - v14.17.0 136--> 137 138* `ipv4` {string} A string representation of an IPv4 address. 139 **Default:** `'0.0.0.0'` 140* `ipv6` {string} A string representation of an IPv6 address. 141 **Default:** `'::0'` 142 143The resolver instance will send its requests from the specified IP address. 144This allows programs to specify outbound interfaces when used on multi-homed 145systems. 146 147If a v4 or v6 address is not specified, it is set to the default and the 148operating system will choose a local address automatically. 149 150The resolver will use the v4 local address when making requests to IPv4 DNS 151servers, and the v6 local address when making requests to IPv6 DNS servers. 152The `rrtype` of resolution requests has no impact on the local address used. 153 154## `dns.getServers()` 155 156<!-- YAML 157added: v0.11.3 158--> 159 160* Returns: {string\[]} 161 162Returns an array of IP address strings, formatted according to [RFC 5952][], 163that are currently configured for DNS resolution. A string will include a port 164section if a custom port is used. 165 166<!-- eslint-disable semi--> 167 168```js 169[ 170 '4.4.4.4', 171 '2001:4860:4860::8888', 172 '4.4.4.4:1053', 173 '[2001:4860:4860::8888]:1053', 174] 175``` 176 177## `dns.lookup(hostname[, options], callback)` 178 179<!-- YAML 180added: v0.1.90 181changes: 182 - version: v18.4.0 183 pr-url: https://github.com/nodejs/node/pull/43054 184 description: For compatibility with `node:net`, when passing an option 185 object the `family` option can be the string `'IPv4'` or the 186 string `'IPv6'`. 187 - version: v18.0.0 188 pr-url: https://github.com/nodejs/node/pull/41678 189 description: Passing an invalid callback to the `callback` argument 190 now throws `ERR_INVALID_ARG_TYPE` instead of 191 `ERR_INVALID_CALLBACK`. 192 - version: v17.0.0 193 pr-url: https://github.com/nodejs/node/pull/39987 194 description: The `verbatim` options defaults to `true` now. 195 - version: v8.5.0 196 pr-url: https://github.com/nodejs/node/pull/14731 197 description: The `verbatim` option is supported now. 198 - version: v1.2.0 199 pr-url: https://github.com/nodejs/node/pull/744 200 description: The `all` option is supported now. 201--> 202 203* `hostname` {string} 204* `options` {integer | Object} 205 * `family` {integer|string} The record family. Must be `4`, `6`, or `0`. For 206 backward compatibility reasons,`'IPv4'` and `'IPv6'` are interpreted as `4` 207 and `6` respectively. The value `0` indicates that IPv4 and IPv6 addresses 208 are both returned. **Default:** `0`. 209 * `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple 210 flags may be passed by bitwise `OR`ing their values. 211 * `all` {boolean} When `true`, the callback returns all resolved addresses in 212 an array. Otherwise, returns a single address. **Default:** `false`. 213 * `verbatim` {boolean} When `true`, the callback receives IPv4 and IPv6 214 addresses in the order the DNS resolver returned them. When `false`, 215 IPv4 addresses are placed before IPv6 addresses. 216 **Default:** `true` (addresses are not reordered). Default value is 217 configurable using [`dns.setDefaultResultOrder()`][] or 218 [`--dns-result-order`][]. 219* `callback` {Function} 220 * `err` {Error} 221 * `address` {string} A string representation of an IPv4 or IPv6 address. 222 * `family` {integer} `4` or `6`, denoting the family of `address`, or `0` if 223 the address is not an IPv4 or IPv6 address. `0` is a likely indicator of a 224 bug in the name resolution service used by the operating system. 225 226Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or 227AAAA (IPv6) record. All `option` properties are optional. If `options` is an 228integer, then it must be `4` or `6` – if `options` is `0` or not provided, then 229IPv4 and IPv6 addresses are both returned if found. 230 231With the `all` option set to `true`, the arguments for `callback` change to 232`(err, addresses)`, with `addresses` being an array of objects with the 233properties `address` and `family`. 234 235On error, `err` is an [`Error`][] object, where `err.code` is the error code. 236Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when 237the host name does not exist but also when the lookup fails in other ways 238such as no available file descriptors. 239 240`dns.lookup()` does not necessarily have anything to do with the DNS protocol. 241The implementation uses an operating system facility that can associate names 242with addresses and vice versa. This implementation can have subtle but 243important consequences on the behavior of any Node.js program. Please take some 244time to consult the [Implementation considerations section][] before using 245`dns.lookup()`. 246 247Example usage: 248 249```js 250const dns = require('node:dns'); 251const options = { 252 family: 6, 253 hints: dns.ADDRCONFIG | dns.V4MAPPED, 254}; 255dns.lookup('example.com', options, (err, address, family) => 256 console.log('address: %j family: IPv%s', address, family)); 257// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6 258 259// When options.all is true, the result will be an Array. 260options.all = true; 261dns.lookup('example.com', options, (err, addresses) => 262 console.log('addresses: %j', addresses)); 263// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] 264``` 265 266If this method is invoked as its [`util.promisify()`][]ed version, and `all` 267is not set to `true`, it returns a `Promise` for an `Object` with `address` and 268`family` properties. 269 270### Supported getaddrinfo flags 271 272<!-- YAML 273changes: 274 - version: 275 - v13.13.0 276 - v12.17.0 277 pr-url: https://github.com/nodejs/node/pull/32183 278 description: Added support for the `dns.ALL` flag. 279--> 280 281The following flags can be passed as hints to [`dns.lookup()`][]. 282 283* `dns.ADDRCONFIG`: Limits returned address types to the types of non-loopback 284 addresses configured on the system. For example, IPv4 addresses are only 285 returned if the current system has at least one IPv4 address configured. 286* `dns.V4MAPPED`: If the IPv6 family was specified, but no IPv6 addresses were 287 found, then return IPv4 mapped IPv6 addresses. It is not supported 288 on some operating systems (e.g. FreeBSD 10.1). 289* `dns.ALL`: If `dns.V4MAPPED` is specified, return resolved IPv6 addresses as 290 well as IPv4 mapped IPv6 addresses. 291 292## `dns.lookupService(address, port, callback)` 293 294<!-- YAML 295added: v0.11.14 296changes: 297 - version: v18.0.0 298 pr-url: https://github.com/nodejs/node/pull/41678 299 description: Passing an invalid callback to the `callback` argument 300 now throws `ERR_INVALID_ARG_TYPE` instead of 301 `ERR_INVALID_CALLBACK`. 302--> 303 304* `address` {string} 305* `port` {number} 306* `callback` {Function} 307 * `err` {Error} 308 * `hostname` {string} e.g. `example.com` 309 * `service` {string} e.g. `http` 310 311Resolves the given `address` and `port` into a host name and service using 312the operating system's underlying `getnameinfo` implementation. 313 314If `address` is not a valid IP address, a `TypeError` will be thrown. 315The `port` will be coerced to a number. If it is not a legal port, a `TypeError` 316will be thrown. 317 318On an error, `err` is an [`Error`][] object, where `err.code` is the error code. 319 320```js 321const dns = require('node:dns'); 322dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { 323 console.log(hostname, service); 324 // Prints: localhost ssh 325}); 326``` 327 328If this method is invoked as its [`util.promisify()`][]ed version, it returns a 329`Promise` for an `Object` with `hostname` and `service` properties. 330 331## `dns.resolve(hostname[, rrtype], callback)` 332 333<!-- YAML 334added: v0.1.27 335changes: 336 - version: v18.0.0 337 pr-url: https://github.com/nodejs/node/pull/41678 338 description: Passing an invalid callback to the `callback` argument 339 now throws `ERR_INVALID_ARG_TYPE` instead of 340 `ERR_INVALID_CALLBACK`. 341--> 342 343* `hostname` {string} Host name to resolve. 344* `rrtype` {string} Resource record type. **Default:** `'A'`. 345* `callback` {Function} 346 * `err` {Error} 347 * `records` {string\[] | Object\[] | Object} 348 349Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array 350of the resource records. The `callback` function has arguments 351`(err, records)`. When successful, `records` will be an array of resource 352records. The type and structure of individual results varies based on `rrtype`: 353 354| `rrtype` | `records` contains | Result type | Shorthand method | 355| --------- | ------------------------------ | ----------- | ------------------------ | 356| `'A'` | IPv4 addresses (default) | {string} | [`dns.resolve4()`][] | 357| `'AAAA'` | IPv6 addresses | {string} | [`dns.resolve6()`][] | 358| `'ANY'` | any records | {Object} | [`dns.resolveAny()`][] | 359| `'CAA'` | CA authorization records | {Object} | [`dns.resolveCaa()`][] | 360| `'CNAME'` | canonical name records | {string} | [`dns.resolveCname()`][] | 361| `'MX'` | mail exchange records | {Object} | [`dns.resolveMx()`][] | 362| `'NAPTR'` | name authority pointer records | {Object} | [`dns.resolveNaptr()`][] | 363| `'NS'` | name server records | {string} | [`dns.resolveNs()`][] | 364| `'PTR'` | pointer records | {string} | [`dns.resolvePtr()`][] | 365| `'SOA'` | start of authority records | {Object} | [`dns.resolveSoa()`][] | 366| `'SRV'` | service records | {Object} | [`dns.resolveSrv()`][] | 367| `'TXT'` | text records | {string\[]} | [`dns.resolveTxt()`][] | 368 369On error, `err` is an [`Error`][] object, where `err.code` is one of the 370[DNS error codes][]. 371 372## `dns.resolve4(hostname[, options], callback)` 373 374<!-- YAML 375added: v0.1.16 376changes: 377 - version: v18.0.0 378 pr-url: https://github.com/nodejs/node/pull/41678 379 description: Passing an invalid callback to the `callback` argument 380 now throws `ERR_INVALID_ARG_TYPE` instead of 381 `ERR_INVALID_CALLBACK`. 382 - version: v7.2.0 383 pr-url: https://github.com/nodejs/node/pull/9296 384 description: This method now supports passing `options`, 385 specifically `options.ttl`. 386--> 387 388* `hostname` {string} Host name to resolve. 389* `options` {Object} 390 * `ttl` {boolean} Retrieves the Time-To-Live value (TTL) of each record. 391 When `true`, the callback receives an array of 392 `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings, 393 with the TTL expressed in seconds. 394* `callback` {Function} 395 * `err` {Error} 396 * `addresses` {string\[] | Object\[]} 397 398Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the 399`hostname`. The `addresses` argument passed to the `callback` function 400will contain an array of IPv4 addresses (e.g. 401`['74.125.79.104', '74.125.79.105', '74.125.79.106']`). 402 403## `dns.resolve6(hostname[, options], callback)` 404 405<!-- YAML 406added: v0.1.16 407changes: 408 - version: v18.0.0 409 pr-url: https://github.com/nodejs/node/pull/41678 410 description: Passing an invalid callback to the `callback` argument 411 now throws `ERR_INVALID_ARG_TYPE` instead of 412 `ERR_INVALID_CALLBACK`. 413 - version: v7.2.0 414 pr-url: https://github.com/nodejs/node/pull/9296 415 description: This method now supports passing `options`, 416 specifically `options.ttl`. 417--> 418 419* `hostname` {string} Host name to resolve. 420* `options` {Object} 421 * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. 422 When `true`, the callback receives an array of 423 `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of 424 strings, with the TTL expressed in seconds. 425* `callback` {Function} 426 * `err` {Error} 427 * `addresses` {string\[] | Object\[]} 428 429Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the 430`hostname`. The `addresses` argument passed to the `callback` function 431will contain an array of IPv6 addresses. 432 433## `dns.resolveAny(hostname, callback)` 434 435<!-- YAML 436changes: 437 - version: v18.0.0 438 pr-url: https://github.com/nodejs/node/pull/41678 439 description: Passing an invalid callback to the `callback` argument 440 now throws `ERR_INVALID_ARG_TYPE` instead of 441 `ERR_INVALID_CALLBACK`. 442--> 443 444* `hostname` {string} 445* `callback` {Function} 446 * `err` {Error} 447 * `ret` {Object\[]} 448 449Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query). 450The `ret` argument passed to the `callback` function will be an array containing 451various types of records. Each object has a property `type` that indicates the 452type of the current record. And depending on the `type`, additional properties 453will be present on the object: 454 455| Type | Properties | 456| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | 457| `'A'` | `address`/`ttl` | 458| `'AAAA'` | `address`/`ttl` | 459| `'CNAME'` | `value` | 460| `'MX'` | Refer to [`dns.resolveMx()`][] | 461| `'NAPTR'` | Refer to [`dns.resolveNaptr()`][] | 462| `'NS'` | `value` | 463| `'PTR'` | `value` | 464| `'SOA'` | Refer to [`dns.resolveSoa()`][] | 465| `'SRV'` | Refer to [`dns.resolveSrv()`][] | 466| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dns.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | 467 468Here is an example of the `ret` object passed to the callback: 469 470<!-- eslint-disable semi --> 471 472```js 473[ { type: 'A', address: '127.0.0.1', ttl: 299 }, 474 { type: 'CNAME', value: 'example.com' }, 475 { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 }, 476 { type: 'NS', value: 'ns1.example.com' }, 477 { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] }, 478 { type: 'SOA', 479 nsname: 'ns1.example.com', 480 hostmaster: 'admin.example.com', 481 serial: 156696742, 482 refresh: 900, 483 retry: 900, 484 expire: 1800, 485 minttl: 60 } ] 486``` 487 488DNS server operators may choose not to respond to `ANY` 489queries. It may be better to call individual methods like [`dns.resolve4()`][], 490[`dns.resolveMx()`][], and so on. For more details, see [RFC 8482][]. 491 492## `dns.resolveCname(hostname, callback)` 493 494<!-- YAML 495added: v0.3.2 496changes: 497 - version: v18.0.0 498 pr-url: https://github.com/nodejs/node/pull/41678 499 description: Passing an invalid callback to the `callback` argument 500 now throws `ERR_INVALID_ARG_TYPE` instead of 501 `ERR_INVALID_CALLBACK`. 502--> 503 504* `hostname` {string} 505* `callback` {Function} 506 * `err` {Error} 507 * `addresses` {string\[]} 508 509Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The 510`addresses` argument passed to the `callback` function 511will contain an array of canonical name records available for the `hostname` 512(e.g. `['bar.example.com']`). 513 514## `dns.resolveCaa(hostname, callback)` 515 516<!-- YAML 517added: 518 - v15.0.0 519 - v14.17.0 520changes: 521 - version: v18.0.0 522 pr-url: https://github.com/nodejs/node/pull/41678 523 description: Passing an invalid callback to the `callback` argument 524 now throws `ERR_INVALID_ARG_TYPE` instead of 525 `ERR_INVALID_CALLBACK`. 526--> 527 528* `hostname` {string} 529* `callback` {Function} 530 * `err` {Error} 531 * `records` {Object\[]} 532 533Uses the DNS protocol to resolve `CAA` records for the `hostname`. The 534`addresses` argument passed to the `callback` function 535will contain an array of certification authority authorization records 536available for the `hostname` (e.g. `[{critical: 0, iodef: 537'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`). 538 539## `dns.resolveMx(hostname, callback)` 540 541<!-- YAML 542added: v0.1.27 543changes: 544 - version: v18.0.0 545 pr-url: https://github.com/nodejs/node/pull/41678 546 description: Passing an invalid callback to the `callback` argument 547 now throws `ERR_INVALID_ARG_TYPE` instead of 548 `ERR_INVALID_CALLBACK`. 549--> 550 551* `hostname` {string} 552* `callback` {Function} 553 * `err` {Error} 554 * `addresses` {Object\[]} 555 556Uses the DNS protocol to resolve mail exchange records (`MX` records) for the 557`hostname`. The `addresses` argument passed to the `callback` function will 558contain an array of objects containing both a `priority` and `exchange` 559property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). 560 561## `dns.resolveNaptr(hostname, callback)` 562 563<!-- YAML 564added: v0.9.12 565changes: 566 - version: v18.0.0 567 pr-url: https://github.com/nodejs/node/pull/41678 568 description: Passing an invalid callback to the `callback` argument 569 now throws `ERR_INVALID_ARG_TYPE` instead of 570 `ERR_INVALID_CALLBACK`. 571--> 572 573* `hostname` {string} 574* `callback` {Function} 575 * `err` {Error} 576 * `addresses` {Object\[]} 577 578Uses the DNS protocol to resolve regular expression-based records (`NAPTR` 579records) for the `hostname`. The `addresses` argument passed to the `callback` 580function will contain an array of objects with the following properties: 581 582* `flags` 583* `service` 584* `regexp` 585* `replacement` 586* `order` 587* `preference` 588 589<!-- eslint-skip --> 590 591```js 592{ 593 flags: 's', 594 service: 'SIP+D2U', 595 regexp: '', 596 replacement: '_sip._udp.example.com', 597 order: 30, 598 preference: 100 599} 600``` 601 602## `dns.resolveNs(hostname, callback)` 603 604<!-- YAML 605added: v0.1.90 606changes: 607 - version: v18.0.0 608 pr-url: https://github.com/nodejs/node/pull/41678 609 description: Passing an invalid callback to the `callback` argument 610 now throws `ERR_INVALID_ARG_TYPE` instead of 611 `ERR_INVALID_CALLBACK`. 612--> 613 614* `hostname` {string} 615* `callback` {Function} 616 * `err` {Error} 617 * `addresses` {string\[]} 618 619Uses the DNS protocol to resolve name server records (`NS` records) for the 620`hostname`. The `addresses` argument passed to the `callback` function will 621contain an array of name server records available for `hostname` 622(e.g. `['ns1.example.com', 'ns2.example.com']`). 623 624## `dns.resolvePtr(hostname, callback)` 625 626<!-- YAML 627added: v6.0.0 628changes: 629 - version: v18.0.0 630 pr-url: https://github.com/nodejs/node/pull/41678 631 description: Passing an invalid callback to the `callback` argument 632 now throws `ERR_INVALID_ARG_TYPE` instead of 633 `ERR_INVALID_CALLBACK`. 634--> 635 636* `hostname` {string} 637* `callback` {Function} 638 * `err` {Error} 639 * `addresses` {string\[]} 640 641Uses the DNS protocol to resolve pointer records (`PTR` records) for the 642`hostname`. The `addresses` argument passed to the `callback` function will 643be an array of strings containing the reply records. 644 645## `dns.resolveSoa(hostname, callback)` 646 647<!-- YAML 648added: v0.11.10 649changes: 650 - version: v18.0.0 651 pr-url: https://github.com/nodejs/node/pull/41678 652 description: Passing an invalid callback to the `callback` argument 653 now throws `ERR_INVALID_ARG_TYPE` instead of 654 `ERR_INVALID_CALLBACK`. 655--> 656 657* `hostname` {string} 658* `callback` {Function} 659 * `err` {Error} 660 * `address` {Object} 661 662Uses the DNS protocol to resolve a start of authority record (`SOA` record) for 663the `hostname`. The `address` argument passed to the `callback` function will 664be an object with the following properties: 665 666* `nsname` 667* `hostmaster` 668* `serial` 669* `refresh` 670* `retry` 671* `expire` 672* `minttl` 673 674<!-- eslint-skip --> 675 676```js 677{ 678 nsname: 'ns.example.com', 679 hostmaster: 'root.example.com', 680 serial: 2013101809, 681 refresh: 10000, 682 retry: 2400, 683 expire: 604800, 684 minttl: 3600 685} 686``` 687 688## `dns.resolveSrv(hostname, callback)` 689 690<!-- YAML 691added: v0.1.27 692changes: 693 - version: v18.0.0 694 pr-url: https://github.com/nodejs/node/pull/41678 695 description: Passing an invalid callback to the `callback` argument 696 now throws `ERR_INVALID_ARG_TYPE` instead of 697 `ERR_INVALID_CALLBACK`. 698--> 699 700* `hostname` {string} 701* `callback` {Function} 702 * `err` {Error} 703 * `addresses` {Object\[]} 704 705Uses the DNS protocol to resolve service records (`SRV` records) for the 706`hostname`. The `addresses` argument passed to the `callback` function will 707be an array of objects with the following properties: 708 709* `priority` 710* `weight` 711* `port` 712* `name` 713 714<!-- eslint-skip --> 715 716```js 717{ 718 priority: 10, 719 weight: 5, 720 port: 21223, 721 name: 'service.example.com' 722} 723``` 724 725## `dns.resolveTxt(hostname, callback)` 726 727<!-- YAML 728added: v0.1.27 729changes: 730 - version: v18.0.0 731 pr-url: https://github.com/nodejs/node/pull/41678 732 description: Passing an invalid callback to the `callback` argument 733 now throws `ERR_INVALID_ARG_TYPE` instead of 734 `ERR_INVALID_CALLBACK`. 735--> 736 737<!--lint disable no-undefined-references list-item-bullet-indent--> 738 739* `hostname` {string} 740* `callback` {Function} 741 * `err` {Error} 742 * `records` <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">\<string\[]\[]></a> 743 744<!--lint enable no-undefined-references list-item-bullet-indent--> 745 746Uses the DNS protocol to resolve text queries (`TXT` records) for the 747`hostname`. The `records` argument passed to the `callback` function is a 748two-dimensional array of the text records available for `hostname` (e.g. 749`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of 750one record. Depending on the use case, these could be either joined together or 751treated separately. 752 753## `dns.reverse(ip, callback)` 754 755<!-- YAML 756added: v0.1.16 757--> 758 759* `ip` {string} 760* `callback` {Function} 761 * `err` {Error} 762 * `hostnames` {string\[]} 763 764Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an 765array of host names. 766 767On error, `err` is an [`Error`][] object, where `err.code` is 768one of the [DNS error codes][]. 769 770## `dns.setDefaultResultOrder(order)` 771 772<!-- YAML 773added: 774 - v16.4.0 775 - v14.18.0 776changes: 777 - version: v17.0.0 778 pr-url: https://github.com/nodejs/node/pull/39987 779 description: Changed default value to `verbatim`. 780--> 781 782* `order` {string} must be `'ipv4first'` or `'verbatim'`. 783 784Set the default value of `verbatim` in [`dns.lookup()`][] and 785[`dnsPromises.lookup()`][]. The value could be: 786 787* `ipv4first`: sets default `verbatim` `false`. 788* `verbatim`: sets default `verbatim` `true`. 789 790The default is `verbatim` and [`dns.setDefaultResultOrder()`][] have higher 791priority than [`--dns-result-order`][]. When using [worker threads][], 792[`dns.setDefaultResultOrder()`][] from the main thread won't affect the default 793dns orders in workers. 794 795## `dns.getDefaultResultOrder()` 796 797<!-- YAML 798added: v18.17.0 799--> 800 801Get the default value for `verbatim` in [`dns.lookup()`][] and 802[`dnsPromises.lookup()`][]. The value could be: 803 804* `ipv4first`: for `verbatim` defaulting to `false`. 805* `verbatim`: for `verbatim` defaulting to `true`. 806 807## `dns.setServers(servers)` 808 809<!-- YAML 810added: v0.11.3 811--> 812 813* `servers` {string\[]} array of [RFC 5952][] formatted addresses 814 815Sets the IP address and port of servers to be used when performing DNS 816resolution. The `servers` argument is an array of [RFC 5952][] formatted 817addresses. If the port is the IANA default DNS port (53) it can be omitted. 818 819```js 820dns.setServers([ 821 '4.4.4.4', 822 '[2001:4860:4860::8888]', 823 '4.4.4.4:1053', 824 '[2001:4860:4860::8888]:1053', 825]); 826``` 827 828An error will be thrown if an invalid address is provided. 829 830The `dns.setServers()` method must not be called while a DNS query is in 831progress. 832 833The [`dns.setServers()`][] method affects only [`dns.resolve()`][], 834`dns.resolve*()` and [`dns.reverse()`][] (and specifically _not_ 835[`dns.lookup()`][]). 836 837This method works much like 838[resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html). 839That is, if attempting to resolve with the first server provided results in a 840`NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with 841subsequent servers provided. Fallback DNS servers will only be used if the 842earlier ones time out or result in some other error. 843 844## DNS promises API 845 846<!-- YAML 847added: v10.6.0 848changes: 849 - version: v15.0.0 850 pr-url: https://github.com/nodejs/node/pull/32953 851 description: Exposed as `require('dns/promises')`. 852 - version: 853 - v11.14.0 854 - v10.17.0 855 pr-url: https://github.com/nodejs/node/pull/26592 856 description: This API is no longer experimental. 857--> 858 859The `dns.promises` API provides an alternative set of asynchronous DNS methods 860that return `Promise` objects rather than using callbacks. The API is accessible 861via `require('node:dns').promises` or `require('node:dns/promises')`. 862 863### Class: `dnsPromises.Resolver` 864 865<!-- YAML 866added: v10.6.0 867--> 868 869An independent resolver for DNS requests. 870 871Creating a new resolver uses the default server settings. Setting 872the servers used for a resolver using 873[`resolver.setServers()`][`dnsPromises.setServers()`] does not affect 874other resolvers: 875 876```js 877const { Resolver } = require('node:dns').promises; 878const resolver = new Resolver(); 879resolver.setServers(['4.4.4.4']); 880 881// This request will use the server at 4.4.4.4, independent of global settings. 882resolver.resolve4('example.org').then((addresses) => { 883 // ... 884}); 885 886// Alternatively, the same code can be written using async-await style. 887(async function() { 888 const addresses = await resolver.resolve4('example.org'); 889})(); 890``` 891 892The following methods from the `dnsPromises` API are available: 893 894* [`resolver.getServers()`][`dnsPromises.getServers()`] 895* [`resolver.resolve()`][`dnsPromises.resolve()`] 896* [`resolver.resolve4()`][`dnsPromises.resolve4()`] 897* [`resolver.resolve6()`][`dnsPromises.resolve6()`] 898* [`resolver.resolveAny()`][`dnsPromises.resolveAny()`] 899* [`resolver.resolveCaa()`][`dnsPromises.resolveCaa()`] 900* [`resolver.resolveCname()`][`dnsPromises.resolveCname()`] 901* [`resolver.resolveMx()`][`dnsPromises.resolveMx()`] 902* [`resolver.resolveNaptr()`][`dnsPromises.resolveNaptr()`] 903* [`resolver.resolveNs()`][`dnsPromises.resolveNs()`] 904* [`resolver.resolvePtr()`][`dnsPromises.resolvePtr()`] 905* [`resolver.resolveSoa()`][`dnsPromises.resolveSoa()`] 906* [`resolver.resolveSrv()`][`dnsPromises.resolveSrv()`] 907* [`resolver.resolveTxt()`][`dnsPromises.resolveTxt()`] 908* [`resolver.reverse()`][`dnsPromises.reverse()`] 909* [`resolver.setServers()`][`dnsPromises.setServers()`] 910 911### `resolver.cancel()` 912 913<!-- YAML 914added: 915 - v15.3.0 916 - v14.17.0 917--> 918 919Cancel all outstanding DNS queries made by this resolver. The corresponding 920promises will be rejected with an error with the code `ECANCELLED`. 921 922### `dnsPromises.getServers()` 923 924<!-- YAML 925added: v10.6.0 926--> 927 928* Returns: {string\[]} 929 930Returns an array of IP address strings, formatted according to [RFC 5952][], 931that are currently configured for DNS resolution. A string will include a port 932section if a custom port is used. 933 934<!-- eslint-disable semi--> 935 936```js 937[ 938 '4.4.4.4', 939 '2001:4860:4860::8888', 940 '4.4.4.4:1053', 941 '[2001:4860:4860::8888]:1053', 942] 943``` 944 945### `dnsPromises.lookup(hostname[, options])` 946 947<!-- YAML 948added: v10.6.0 949--> 950 951* `hostname` {string} 952* `options` {integer | Object} 953 * `family` {integer} The record family. Must be `4`, `6`, or `0`. The value 954 `0` indicates that IPv4 and IPv6 addresses are both returned. **Default:** 955 `0`. 956 * `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple 957 flags may be passed by bitwise `OR`ing their values. 958 * `all` {boolean} When `true`, the `Promise` is resolved with all addresses in 959 an array. Otherwise, returns a single address. **Default:** `false`. 960 * `verbatim` {boolean} When `true`, the `Promise` is resolved with IPv4 and 961 IPv6 addresses in the order the DNS resolver returned them. When `false`, 962 IPv4 addresses are placed before IPv6 addresses. 963 **Default:** currently `false` (addresses are reordered) but this is 964 expected to change in the not too distant future. Default value is 965 configurable using [`dns.setDefaultResultOrder()`][] or 966 [`--dns-result-order`][]. New code should use `{ verbatim: true }`. 967 968Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or 969AAAA (IPv6) record. All `option` properties are optional. If `options` is an 970integer, then it must be `4` or `6` – if `options` is not provided, then IPv4 971and IPv6 addresses are both returned if found. 972 973With the `all` option set to `true`, the `Promise` is resolved with `addresses` 974being an array of objects with the properties `address` and `family`. 975 976On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` 977is the error code. 978Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when 979the host name does not exist but also when the lookup fails in other ways 980such as no available file descriptors. 981 982[`dnsPromises.lookup()`][] does not necessarily have anything to do with the DNS 983protocol. The implementation uses an operating system facility that can 984associate names with addresses and vice versa. This implementation can have 985subtle but important consequences on the behavior of any Node.js program. Please 986take some time to consult the [Implementation considerations section][] before 987using `dnsPromises.lookup()`. 988 989Example usage: 990 991```js 992const dns = require('node:dns'); 993const dnsPromises = dns.promises; 994const options = { 995 family: 6, 996 hints: dns.ADDRCONFIG | dns.V4MAPPED, 997}; 998 999dnsPromises.lookup('example.com', options).then((result) => { 1000 console.log('address: %j family: IPv%s', result.address, result.family); 1001 // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6 1002}); 1003 1004// When options.all is true, the result will be an Array. 1005options.all = true; 1006dnsPromises.lookup('example.com', options).then((result) => { 1007 console.log('addresses: %j', result); 1008 // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] 1009}); 1010``` 1011 1012### `dnsPromises.lookupService(address, port)` 1013 1014<!-- YAML 1015added: v10.6.0 1016--> 1017 1018* `address` {string} 1019* `port` {number} 1020 1021Resolves the given `address` and `port` into a host name and service using 1022the operating system's underlying `getnameinfo` implementation. 1023 1024If `address` is not a valid IP address, a `TypeError` will be thrown. 1025The `port` will be coerced to a number. If it is not a legal port, a `TypeError` 1026will be thrown. 1027 1028On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` 1029is the error code. 1030 1031```js 1032const dnsPromises = require('node:dns').promises; 1033dnsPromises.lookupService('127.0.0.1', 22).then((result) => { 1034 console.log(result.hostname, result.service); 1035 // Prints: localhost ssh 1036}); 1037``` 1038 1039### `dnsPromises.resolve(hostname[, rrtype])` 1040 1041<!-- YAML 1042added: v10.6.0 1043--> 1044 1045* `hostname` {string} Host name to resolve. 1046* `rrtype` {string} Resource record type. **Default:** `'A'`. 1047 1048Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array 1049of the resource records. When successful, the `Promise` is resolved with an 1050array of resource records. The type and structure of individual results vary 1051based on `rrtype`: 1052 1053| `rrtype` | `records` contains | Result type | Shorthand method | 1054| --------- | ------------------------------ | ----------- | -------------------------------- | 1055| `'A'` | IPv4 addresses (default) | {string} | [`dnsPromises.resolve4()`][] | 1056| `'AAAA'` | IPv6 addresses | {string} | [`dnsPromises.resolve6()`][] | 1057| `'ANY'` | any records | {Object} | [`dnsPromises.resolveAny()`][] | 1058| `'CAA'` | CA authorization records | {Object} | [`dnsPromises.resolveCaa()`][] | 1059| `'CNAME'` | canonical name records | {string} | [`dnsPromises.resolveCname()`][] | 1060| `'MX'` | mail exchange records | {Object} | [`dnsPromises.resolveMx()`][] | 1061| `'NAPTR'` | name authority pointer records | {Object} | [`dnsPromises.resolveNaptr()`][] | 1062| `'NS'` | name server records | {string} | [`dnsPromises.resolveNs()`][] | 1063| `'PTR'` | pointer records | {string} | [`dnsPromises.resolvePtr()`][] | 1064| `'SOA'` | start of authority records | {Object} | [`dnsPromises.resolveSoa()`][] | 1065| `'SRV'` | service records | {Object} | [`dnsPromises.resolveSrv()`][] | 1066| `'TXT'` | text records | {string\[]} | [`dnsPromises.resolveTxt()`][] | 1067 1068On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` 1069is one of the [DNS error codes][]. 1070 1071### `dnsPromises.resolve4(hostname[, options])` 1072 1073<!-- YAML 1074added: v10.6.0 1075--> 1076 1077* `hostname` {string} Host name to resolve. 1078* `options` {Object} 1079 * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. 1080 When `true`, the `Promise` is resolved with an array of 1081 `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings, 1082 with the TTL expressed in seconds. 1083 1084Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the 1085`hostname`. On success, the `Promise` is resolved with an array of IPv4 1086addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). 1087 1088### `dnsPromises.resolve6(hostname[, options])` 1089 1090<!-- YAML 1091added: v10.6.0 1092--> 1093 1094* `hostname` {string} Host name to resolve. 1095* `options` {Object} 1096 * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. 1097 When `true`, the `Promise` is resolved with an array of 1098 `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of 1099 strings, with the TTL expressed in seconds. 1100 1101Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the 1102`hostname`. On success, the `Promise` is resolved with an array of IPv6 1103addresses. 1104 1105### `dnsPromises.resolveAny(hostname)` 1106 1107<!-- YAML 1108added: v10.6.0 1109--> 1110 1111* `hostname` {string} 1112 1113Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query). 1114On success, the `Promise` is resolved with an array containing various types of 1115records. Each object has a property `type` that indicates the type of the 1116current record. And depending on the `type`, additional properties will be 1117present on the object: 1118 1119| Type | Properties | 1120| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | 1121| `'A'` | `address`/`ttl` | 1122| `'AAAA'` | `address`/`ttl` | 1123| `'CNAME'` | `value` | 1124| `'MX'` | Refer to [`dnsPromises.resolveMx()`][] | 1125| `'NAPTR'` | Refer to [`dnsPromises.resolveNaptr()`][] | 1126| `'NS'` | `value` | 1127| `'PTR'` | `value` | 1128| `'SOA'` | Refer to [`dnsPromises.resolveSoa()`][] | 1129| `'SRV'` | Refer to [`dnsPromises.resolveSrv()`][] | 1130| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dnsPromises.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | 1131 1132Here is an example of the result object: 1133 1134<!-- eslint-disable semi --> 1135 1136```js 1137[ { type: 'A', address: '127.0.0.1', ttl: 299 }, 1138 { type: 'CNAME', value: 'example.com' }, 1139 { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 }, 1140 { type: 'NS', value: 'ns1.example.com' }, 1141 { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] }, 1142 { type: 'SOA', 1143 nsname: 'ns1.example.com', 1144 hostmaster: 'admin.example.com', 1145 serial: 156696742, 1146 refresh: 900, 1147 retry: 900, 1148 expire: 1800, 1149 minttl: 60 } ] 1150``` 1151 1152### `dnsPromises.resolveCaa(hostname)` 1153 1154<!-- YAML 1155added: 1156 - v15.0.0 1157 - v14.17.0 1158--> 1159 1160* `hostname` {string} 1161 1162Uses the DNS protocol to resolve `CAA` records for the `hostname`. On success, 1163the `Promise` is resolved with an array of objects containing available 1164certification authority authorization records available for the `hostname` 1165(e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 1166'pki.example.com'}]`). 1167 1168### `dnsPromises.resolveCname(hostname)` 1169 1170<!-- YAML 1171added: v10.6.0 1172--> 1173 1174* `hostname` {string} 1175 1176Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success, 1177the `Promise` is resolved with an array of canonical name records available for 1178the `hostname` (e.g. `['bar.example.com']`). 1179 1180### `dnsPromises.resolveMx(hostname)` 1181 1182<!-- YAML 1183added: v10.6.0 1184--> 1185 1186* `hostname` {string} 1187 1188Uses the DNS protocol to resolve mail exchange records (`MX` records) for the 1189`hostname`. On success, the `Promise` is resolved with an array of objects 1190containing both a `priority` and `exchange` property (e.g. 1191`[{priority: 10, exchange: 'mx.example.com'}, ...]`). 1192 1193### `dnsPromises.resolveNaptr(hostname)` 1194 1195<!-- YAML 1196added: v10.6.0 1197--> 1198 1199* `hostname` {string} 1200 1201Uses the DNS protocol to resolve regular expression-based records (`NAPTR` 1202records) for the `hostname`. On success, the `Promise` is resolved with an array 1203of objects with the following properties: 1204 1205* `flags` 1206* `service` 1207* `regexp` 1208* `replacement` 1209* `order` 1210* `preference` 1211 1212<!-- eslint-skip --> 1213 1214```js 1215{ 1216 flags: 's', 1217 service: 'SIP+D2U', 1218 regexp: '', 1219 replacement: '_sip._udp.example.com', 1220 order: 30, 1221 preference: 100 1222} 1223``` 1224 1225### `dnsPromises.resolveNs(hostname)` 1226 1227<!-- YAML 1228added: v10.6.0 1229--> 1230 1231* `hostname` {string} 1232 1233Uses the DNS protocol to resolve name server records (`NS` records) for the 1234`hostname`. On success, the `Promise` is resolved with an array of name server 1235records available for `hostname` (e.g. 1236`['ns1.example.com', 'ns2.example.com']`). 1237 1238### `dnsPromises.resolvePtr(hostname)` 1239 1240<!-- YAML 1241added: v10.6.0 1242--> 1243 1244* `hostname` {string} 1245 1246Uses the DNS protocol to resolve pointer records (`PTR` records) for the 1247`hostname`. On success, the `Promise` is resolved with an array of strings 1248containing the reply records. 1249 1250### `dnsPromises.resolveSoa(hostname)` 1251 1252<!-- YAML 1253added: v10.6.0 1254--> 1255 1256* `hostname` {string} 1257 1258Uses the DNS protocol to resolve a start of authority record (`SOA` record) for 1259the `hostname`. On success, the `Promise` is resolved with an object with the 1260following properties: 1261 1262* `nsname` 1263* `hostmaster` 1264* `serial` 1265* `refresh` 1266* `retry` 1267* `expire` 1268* `minttl` 1269 1270<!-- eslint-skip --> 1271 1272```js 1273{ 1274 nsname: 'ns.example.com', 1275 hostmaster: 'root.example.com', 1276 serial: 2013101809, 1277 refresh: 10000, 1278 retry: 2400, 1279 expire: 604800, 1280 minttl: 3600 1281} 1282``` 1283 1284### `dnsPromises.resolveSrv(hostname)` 1285 1286<!-- YAML 1287added: v10.6.0 1288--> 1289 1290* `hostname` {string} 1291 1292Uses the DNS protocol to resolve service records (`SRV` records) for the 1293`hostname`. On success, the `Promise` is resolved with an array of objects with 1294the following properties: 1295 1296* `priority` 1297* `weight` 1298* `port` 1299* `name` 1300 1301<!-- eslint-skip --> 1302 1303```js 1304{ 1305 priority: 10, 1306 weight: 5, 1307 port: 21223, 1308 name: 'service.example.com' 1309} 1310``` 1311 1312### `dnsPromises.resolveTxt(hostname)` 1313 1314<!-- YAML 1315added: v10.6.0 1316--> 1317 1318* `hostname` {string} 1319 1320Uses the DNS protocol to resolve text queries (`TXT` records) for the 1321`hostname`. On success, the `Promise` is resolved with a two-dimensional array 1322of the text records available for `hostname` (e.g. 1323`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of 1324one record. Depending on the use case, these could be either joined together or 1325treated separately. 1326 1327### `dnsPromises.reverse(ip)` 1328 1329<!-- YAML 1330added: v10.6.0 1331--> 1332 1333* `ip` {string} 1334 1335Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an 1336array of host names. 1337 1338On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` 1339is one of the [DNS error codes][]. 1340 1341### `dnsPromises.setDefaultResultOrder(order)` 1342 1343<!-- YAML 1344added: 1345 - v16.4.0 1346 - v14.18.0 1347changes: 1348 - version: v17.0.0 1349 pr-url: https://github.com/nodejs/node/pull/39987 1350 description: Changed default value to `verbatim`. 1351--> 1352 1353* `order` {string} must be `'ipv4first'` or `'verbatim'`. 1354 1355Set the default value of `verbatim` in [`dns.lookup()`][] and 1356[`dnsPromises.lookup()`][]. The value could be: 1357 1358* `ipv4first`: sets default `verbatim` `false`. 1359* `verbatim`: sets default `verbatim` `true`. 1360 1361The default is `verbatim` and [`dnsPromises.setDefaultResultOrder()`][] have 1362higher priority than [`--dns-result-order`][]. When using [worker threads][], 1363[`dnsPromises.setDefaultResultOrder()`][] from the main thread won't affect the 1364default dns orders in workers. 1365 1366### `dnsPromises.getDefaultResultOrder()` 1367 1368<!-- YAML 1369added: v18.17.0 1370--> 1371 1372Get the value of `dnsOrder`. 1373 1374### `dnsPromises.setServers(servers)` 1375 1376<!-- YAML 1377added: v10.6.0 1378--> 1379 1380* `servers` {string\[]} array of [RFC 5952][] formatted addresses 1381 1382Sets the IP address and port of servers to be used when performing DNS 1383resolution. The `servers` argument is an array of [RFC 5952][] formatted 1384addresses. If the port is the IANA default DNS port (53) it can be omitted. 1385 1386```js 1387dnsPromises.setServers([ 1388 '4.4.4.4', 1389 '[2001:4860:4860::8888]', 1390 '4.4.4.4:1053', 1391 '[2001:4860:4860::8888]:1053', 1392]); 1393``` 1394 1395An error will be thrown if an invalid address is provided. 1396 1397The `dnsPromises.setServers()` method must not be called while a DNS query is in 1398progress. 1399 1400This method works much like 1401[resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html). 1402That is, if attempting to resolve with the first server provided results in a 1403`NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with 1404subsequent servers provided. Fallback DNS servers will only be used if the 1405earlier ones time out or result in some other error. 1406 1407## Error codes 1408 1409Each DNS query can return one of the following error codes: 1410 1411* `dns.NODATA`: DNS server returned an answer with no data. 1412* `dns.FORMERR`: DNS server claims query was misformatted. 1413* `dns.SERVFAIL`: DNS server returned general failure. 1414* `dns.NOTFOUND`: Domain name not found. 1415* `dns.NOTIMP`: DNS server does not implement the requested operation. 1416* `dns.REFUSED`: DNS server refused query. 1417* `dns.BADQUERY`: Misformatted DNS query. 1418* `dns.BADNAME`: Misformatted host name. 1419* `dns.BADFAMILY`: Unsupported address family. 1420* `dns.BADRESP`: Misformatted DNS reply. 1421* `dns.CONNREFUSED`: Could not contact DNS servers. 1422* `dns.TIMEOUT`: Timeout while contacting DNS servers. 1423* `dns.EOF`: End of file. 1424* `dns.FILE`: Error reading file. 1425* `dns.NOMEM`: Out of memory. 1426* `dns.DESTRUCTION`: Channel is being destroyed. 1427* `dns.BADSTR`: Misformatted string. 1428* `dns.BADFLAGS`: Illegal flags specified. 1429* `dns.NONAME`: Given host name is not numeric. 1430* `dns.BADHINTS`: Illegal hints flags specified. 1431* `dns.NOTINITIALIZED`: c-ares library initialization not yet performed. 1432* `dns.LOADIPHLPAPI`: Error loading `iphlpapi.dll`. 1433* `dns.ADDRGETNETWORKPARAMS`: Could not find `GetNetworkParams` function. 1434* `dns.CANCELLED`: DNS query cancelled. 1435 1436The `dnsPromises` API also exports the above error codes, e.g., `dnsPromises.NODATA`. 1437 1438## Implementation considerations 1439 1440Although [`dns.lookup()`][] and the various `dns.resolve*()/dns.reverse()` 1441functions have the same goal of associating a network name with a network 1442address (or vice versa), their behavior is quite different. These differences 1443can have subtle but significant consequences on the behavior of Node.js 1444programs. 1445 1446### `dns.lookup()` 1447 1448Under the hood, [`dns.lookup()`][] uses the same operating system facilities 1449as most other programs. For instance, [`dns.lookup()`][] will almost always 1450resolve a given name the same way as the `ping` command. On most POSIX-like 1451operating systems, the behavior of the [`dns.lookup()`][] function can be 1452modified by changing settings in nsswitch.conf(5) and/or resolv.conf(5), 1453but changing these files will change the behavior of all other 1454programs running on the same operating system. 1455 1456Though the call to `dns.lookup()` will be asynchronous from JavaScript's 1457perspective, it is implemented as a synchronous call to getaddrinfo(3) that runs 1458on libuv's threadpool. This can have surprising negative performance 1459implications for some applications, see the [`UV_THREADPOOL_SIZE`][] 1460documentation for more information. 1461 1462Various networking APIs will call `dns.lookup()` internally to resolve 1463host names. If that is an issue, consider resolving the host name to an address 1464using `dns.resolve()` and using the address instead of a host name. Also, some 1465networking APIs (such as [`socket.connect()`][] and [`dgram.createSocket()`][]) 1466allow the default resolver, `dns.lookup()`, to be replaced. 1467 1468### `dns.resolve()`, `dns.resolve*()`, and `dns.reverse()` 1469 1470These functions are implemented quite differently than [`dns.lookup()`][]. They 1471do not use getaddrinfo(3) and they _always_ perform a DNS query on the 1472network. This network communication is always done asynchronously and does not 1473use libuv's threadpool. 1474 1475As a result, these functions cannot have the same negative impact on other 1476processing that happens on libuv's threadpool that [`dns.lookup()`][] can have. 1477 1478They do not use the same set of configuration files that [`dns.lookup()`][] 1479uses. For instance, they do not use the configuration from `/etc/hosts`. 1480 1481[DNS error codes]: #error-codes 1482[Domain Name System (DNS)]: https://en.wikipedia.org/wiki/Domain_Name_System 1483[Implementation considerations section]: #implementation-considerations 1484[RFC 5952]: https://tools.ietf.org/html/rfc5952#section-6 1485[RFC 8482]: https://tools.ietf.org/html/rfc8482 1486[`--dns-result-order`]: cli.md#--dns-result-orderorder 1487[`Error`]: errors.md#class-error 1488[`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize 1489[`dgram.createSocket()`]: dgram.md#dgramcreatesocketoptions-callback 1490[`dns.getServers()`]: #dnsgetservers 1491[`dns.lookup()`]: #dnslookuphostname-options-callback 1492[`dns.resolve()`]: #dnsresolvehostname-rrtype-callback 1493[`dns.resolve4()`]: #dnsresolve4hostname-options-callback 1494[`dns.resolve6()`]: #dnsresolve6hostname-options-callback 1495[`dns.resolveAny()`]: #dnsresolveanyhostname-callback 1496[`dns.resolveCaa()`]: #dnsresolvecaahostname-callback 1497[`dns.resolveCname()`]: #dnsresolvecnamehostname-callback 1498[`dns.resolveMx()`]: #dnsresolvemxhostname-callback 1499[`dns.resolveNaptr()`]: #dnsresolvenaptrhostname-callback 1500[`dns.resolveNs()`]: #dnsresolvenshostname-callback 1501[`dns.resolvePtr()`]: #dnsresolveptrhostname-callback 1502[`dns.resolveSoa()`]: #dnsresolvesoahostname-callback 1503[`dns.resolveSrv()`]: #dnsresolvesrvhostname-callback 1504[`dns.resolveTxt()`]: #dnsresolvetxthostname-callback 1505[`dns.reverse()`]: #dnsreverseip-callback 1506[`dns.setDefaultResultOrder()`]: #dnssetdefaultresultorderorder 1507[`dns.setServers()`]: #dnssetserversservers 1508[`dnsPromises.getServers()`]: #dnspromisesgetservers 1509[`dnsPromises.lookup()`]: #dnspromiseslookuphostname-options 1510[`dnsPromises.resolve()`]: #dnspromisesresolvehostname-rrtype 1511[`dnsPromises.resolve4()`]: #dnspromisesresolve4hostname-options 1512[`dnsPromises.resolve6()`]: #dnspromisesresolve6hostname-options 1513[`dnsPromises.resolveAny()`]: #dnspromisesresolveanyhostname 1514[`dnsPromises.resolveCaa()`]: #dnspromisesresolvecaahostname 1515[`dnsPromises.resolveCname()`]: #dnspromisesresolvecnamehostname 1516[`dnsPromises.resolveMx()`]: #dnspromisesresolvemxhostname 1517[`dnsPromises.resolveNaptr()`]: #dnspromisesresolvenaptrhostname 1518[`dnsPromises.resolveNs()`]: #dnspromisesresolvenshostname 1519[`dnsPromises.resolvePtr()`]: #dnspromisesresolveptrhostname 1520[`dnsPromises.resolveSoa()`]: #dnspromisesresolvesoahostname 1521[`dnsPromises.resolveSrv()`]: #dnspromisesresolvesrvhostname 1522[`dnsPromises.resolveTxt()`]: #dnspromisesresolvetxthostname 1523[`dnsPromises.reverse()`]: #dnspromisesreverseip 1524[`dnsPromises.setDefaultResultOrder()`]: #dnspromisessetdefaultresultorderorder 1525[`dnsPromises.setServers()`]: #dnspromisessetserversservers 1526[`socket.connect()`]: net.md#socketconnectoptions-connectlistener 1527[`util.promisify()`]: util.md#utilpromisifyoriginal 1528[supported `getaddrinfo` flags]: #supported-getaddrinfo-flags 1529[worker threads]: worker_threads.md 1530