doc: improvements to dns.markdown copy
General improvements to dns.markdown copy and examples PR-URL: https://github.com/nodejs/node/pull/4449 Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
This commit is contained in:
James M Snell
parent
e4c835e1cb
commit
7ee1685d74
@ -2,39 +2,36 @@
|
||||
|
||||
Stability: 2 - Stable
|
||||
|
||||
Use `require('dns')` to access this module.
|
||||
|
||||
This module contains functions that belong to two different categories:
|
||||
The `dns` module contains functions belonging to two different categories:
|
||||
|
||||
1) Functions that use the underlying operating system facilities to perform
|
||||
name resolution, and that do not necessarily do any network communication.
|
||||
name resolution, and that do not necessarily perform any network communication.
|
||||
This category contains only one function: [`dns.lookup()`][]. __Developers
|
||||
looking to perform name resolution in the same way that other applications on
|
||||
the same operating system behave should use [`dns.lookup()`][].__
|
||||
|
||||
Here is an example that does a lookup of `www.google.com`.
|
||||
For example, looking up `nodejs.org`.
|
||||
|
||||
const dns = require('dns');
|
||||
|
||||
dns.lookup('www.google.com', function onLookup(err, addresses, family) {
|
||||
dns.lookup('nodejs.org', (err, addresses, family) => {
|
||||
console.log('addresses:', addresses);
|
||||
});
|
||||
|
||||
2) Functions that connect to an actual DNS server to perform name resolution,
|
||||
and that _always_ use the network to perform DNS queries. This category
|
||||
contains all functions in the `dns` module but [`dns.lookup()`][]. These
|
||||
functions do not use the same set of configuration files than what
|
||||
[`dns.lookup()`][] uses. For instance, _they do not use the configuration from
|
||||
`/etc/hosts`_. These functions should be used by developers who do not want to
|
||||
use the underlying operating system's facilities for name resolution, and
|
||||
instead want to _always_ perform DNS queries.
|
||||
contains all functions in the `dns` module _except_ [`dns.lookup()`][]. These
|
||||
functions do not use the same set of configuration files used by
|
||||
[`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by
|
||||
developers who do not want to use the underlying operating system's facilities
|
||||
for name resolution, and instead want to _always_ perform DNS queries.
|
||||
|
||||
Here is an example which resolves `'www.google.com'` then reverse
|
||||
resolves the IP addresses which are returned.
|
||||
Below is an example that resolves `'nodejs.org'` then reverse resolves the IP
|
||||
addresses that are returned.
|
||||
|
||||
const dns = require('dns');
|
||||
|
||||
dns.resolve4('www.google.com', (err, addresses) => {
|
||||
dns.resolve4('nodejs.org', (err, addresses) => {
|
||||
if (err) throw err;
|
||||
|
||||
console.log(`addresses: ${JSON.stringify(addresses)}`);
|
||||
@ -49,19 +46,19 @@ resolves the IP addresses which are returned.
|
||||
});
|
||||
});
|
||||
|
||||
There are subtle consequences in choosing one or another, please consult the
|
||||
[Implementation considerations section][] for more information.
|
||||
There are subtle consequences in choosing one over the other, please consult
|
||||
the [Implementation considerations section][] for more information.
|
||||
|
||||
## dns.getServers()
|
||||
|
||||
Returns an array of IP addresses as strings that are currently being used for
|
||||
resolution
|
||||
Returns an array of IP address strings that are being used for name
|
||||
resolution.
|
||||
|
||||
## dns.lookup(hostname[, options], callback)
|
||||
|
||||
Resolves a hostname (e.g. `'google.com'`) into the first found A (IPv4) or
|
||||
Resolves a hostname (e.g. `'nodejs.org'`) into the first found A (IPv4) or
|
||||
AAAA (IPv6) record. `options` can be an object or integer. If `options` is
|
||||
not provided, then IP v4 and v6 addresses are both valid. If `options` is
|
||||
not provided, then IPv4 and IPv6 addresses are both valid. If `options` is
|
||||
an integer, then it must be `4` or `6`.
|
||||
|
||||
Alternatively, `options` can be an object containing these properties:
|
||||
@ -79,154 +76,193 @@ Alternatively, `options` can be an object containing these properties:
|
||||
|
||||
All properties are optional. An example usage of options is shown below.
|
||||
|
||||
```
|
||||
{
|
||||
family: 4,
|
||||
hints: dns.ADDRCONFIG | dns.V4MAPPED,
|
||||
all: false
|
||||
}
|
||||
```
|
||||
{
|
||||
family: 4,
|
||||
hints: dns.ADDRCONFIG | dns.V4MAPPED,
|
||||
all: false
|
||||
}
|
||||
|
||||
The callback has arguments `(err, address, family)`. `address` is a string
|
||||
representation of an IP v4 or v6 address. `family` is either the integer 4 or 6
|
||||
and denotes the family of `address` (not necessarily the value initially passed
|
||||
to `lookup`).
|
||||
The `callback` function has arguments `(err, address, family)`. `address` is a
|
||||
string representation of an IPv4 or IPv6 address. `family` is either the
|
||||
integer `4` or `6` and denotes the family of `address` (not necessarily the
|
||||
value initially passed to `lookup`).
|
||||
|
||||
With the `all` option set, the arguments change to `(err, addresses)`, with
|
||||
`addresses` being an array of objects with the properties `address` and
|
||||
`family`.
|
||||
With the `all` option set to `true`, the arguments change to
|
||||
`(err, addresses)`, with `addresses` being an array of objects with the
|
||||
properties `address` and `family`.
|
||||
|
||||
On error, `err` is an [`Error`][] object, where `err.code` is the error code.
|
||||
Keep in mind that `err.code` will be set to `'ENOENT'` not only when
|
||||
the hostname does not exist but also when the lookup fails in other ways
|
||||
such as no available file descriptors.
|
||||
|
||||
`dns.lookup()` doesn't necessarily have anything to do with the DNS protocol.
|
||||
It's only an operating system facility that can associate name with addresses,
|
||||
and vice versa.
|
||||
`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
|
||||
The implementation uses an operating system facility that can associate names
|
||||
with addresses, and vice versa. This implementation can have subtle but
|
||||
important consequences on the behavior of any Node.js program. Please take some
|
||||
time to consult the [Implementation considerations section][] before using
|
||||
`dns.lookup()`.
|
||||
|
||||
Its implementation can have subtle but important consequences on the behavior
|
||||
of any Node.js program. Please take some time to consult the [Implementation
|
||||
considerations section][] before using it.
|
||||
### Supported getaddrinfo flags
|
||||
|
||||
The following flags can be passed as hints to [`dns.lookup()`][].
|
||||
|
||||
- `dns.ADDRCONFIG`: Returned address types are determined by the types
|
||||
of addresses supported by the current system. For example, IPv4 addresses
|
||||
are only returned if the current system has at least one IPv4 address
|
||||
configured. Loopback addresses are not considered.
|
||||
- `dns.V4MAPPED`: If the IPv6 family was specified, but no IPv6 addresses were
|
||||
found, then return IPv4 mapped IPv6 addresses. Note that it is not supported
|
||||
on some operating systems (e.g FreeBSD 10.1).
|
||||
|
||||
## dns.lookupService(address, port, callback)
|
||||
|
||||
Resolves the given address and port into a hostname and service using
|
||||
`getnameinfo`.
|
||||
Resolves the given `address` and `port` into a hostname and service using
|
||||
the operating system's underlying `getnameinfo` implementation.
|
||||
|
||||
The callback has arguments `(err, hostname, service)`. The `hostname` and
|
||||
`service` arguments are strings (e.g. `'localhost'` and `'http'` respectively).
|
||||
|
||||
On error, `err` is an [`Error`][] object, where `err.code` is the error code.
|
||||
|
||||
const dns = require('dns');
|
||||
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
|
||||
console.log(hostname, service);
|
||||
// Prints: localhost ssh
|
||||
});
|
||||
|
||||
## dns.resolve(hostname[, rrtype], callback)
|
||||
|
||||
Resolves a hostname (e.g. `'google.com'`) into an array of the record types
|
||||
specified by rrtype.
|
||||
Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an
|
||||
array of the record types specified by `rrtype`.
|
||||
|
||||
Valid rrtypes are:
|
||||
Valid values for `rrtype` are:
|
||||
|
||||
* `'A'` (IPV4 addresses, default)
|
||||
* `'AAAA'` (IPV6 addresses)
|
||||
* `'MX'` (mail exchange records)
|
||||
* `'TXT'` (text records)
|
||||
* `'SRV'` (SRV records)
|
||||
* `'PTR'` (used for reverse IP lookups)
|
||||
* `'NS'` (name server records)
|
||||
* `'CNAME'` (canonical name records)
|
||||
* `'SOA'` (start of authority record)
|
||||
* `'A'` - IPV4 addresses, default
|
||||
* `'AAAA'` - IPV6 addresses
|
||||
* `'MX'` - mail exchange records
|
||||
* `'TXT'` - text records
|
||||
* `'SRV'` - SRV records
|
||||
* `'PTR'` - used for reverse IP lookups
|
||||
* `'NS'` - name server records
|
||||
* `'CNAME'` - canonical name records
|
||||
* `'SOA'` - start of authority record
|
||||
|
||||
The callback has arguments `(err, addresses)`. The type of each item
|
||||
in `addresses` is determined by the record type, and described in the
|
||||
documentation for the corresponding lookup methods below.
|
||||
The `callback` function has arguments `(err, addresses)`. When successful,
|
||||
`addresses` will be an array. The type of each item in `addresses` is
|
||||
determined by the record type, and described in the documentation for the
|
||||
corresponding lookup methods below.
|
||||
|
||||
On error, `err` is an [`Error`][] object, where `err.code` is
|
||||
one of the error codes listed below.
|
||||
|
||||
|
||||
## dns.resolve4(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for IPv4 queries (`A` records).
|
||||
`addresses` is an array of IPv4 addresses (e.g.
|
||||
Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function
|
||||
will contain an array of IPv4 addresses (e.g.
|
||||
`['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
|
||||
|
||||
## dns.resolve6(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve4()`][] except for IPv6 queries (an `AAAA` query).
|
||||
Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function
|
||||
will contain an array of IPv6 addresses.
|
||||
|
||||
## dns.resolveCname(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for canonical name records (`CNAME`
|
||||
records). `addresses` is an array of the canonical name records available for
|
||||
`hostname` (e.g., `['bar.example.com']`).
|
||||
Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The
|
||||
`addresses` argument passed to the `callback` function
|
||||
will contain an of canonical name records available for the `hostname`
|
||||
(e.g. `['bar.example.com']`).
|
||||
|
||||
## dns.resolveMx(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for mail exchange queries
|
||||
(`MX` records).
|
||||
|
||||
`addresses` is an array of MX records, each with a priority and an exchange
|
||||
attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`).
|
||||
Uses the DNS protocol to resolve mail exchange records (`MX` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function will
|
||||
contain an array of objects containing both a `priority` and `exchange`
|
||||
property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`).
|
||||
|
||||
## dns.resolveNs(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for name server records
|
||||
(`NS` records). `addresses` is an array of the name server records available
|
||||
for `hostname` (e.g., `['ns1.example.com', 'ns2.example.com']`).
|
||||
Uses the DNS protocol to resolve name server records (`NS` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function will
|
||||
contain an array of name server records available for `hostname`
|
||||
(e.g., `['ns1.example.com', 'ns2.example.com']`).
|
||||
|
||||
## dns.resolveSoa(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for start of authority record queries
|
||||
(`SOA` record).
|
||||
Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
|
||||
the `hostname`. The `addresses` argument passed to the `callback` function will
|
||||
be an object with the following properties:
|
||||
|
||||
`addresses` is an object with the following structure:
|
||||
* `nsname`
|
||||
* `hostmaster`
|
||||
* `serial`
|
||||
* `refresh`
|
||||
* `retry`
|
||||
* `expire`
|
||||
* `minttl`
|
||||
|
||||
```
|
||||
{
|
||||
nsname: 'ns.example.com',
|
||||
hostmaster: 'root.example.com',
|
||||
serial: 2013101809,
|
||||
refresh: 10000,
|
||||
retry: 2400,
|
||||
expire: 604800,
|
||||
minttl: 3600
|
||||
}
|
||||
```
|
||||
{
|
||||
nsname: 'ns.example.com',
|
||||
hostmaster: 'root.example.com',
|
||||
serial: 2013101809,
|
||||
refresh: 10000,
|
||||
retry: 2400,
|
||||
expire: 604800,
|
||||
minttl: 3600
|
||||
}
|
||||
|
||||
## dns.resolveSrv(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for service records (`SRV` records).
|
||||
`addresses` is an array of the SRV records available for `hostname`. Properties
|
||||
of SRV records are priority, weight, port, and name (e.g.,
|
||||
`[{'priority': 10, 'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]`).
|
||||
Uses the DNS protocol to resolve service records (`SRV` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function will
|
||||
be an array of objects with the following properties:
|
||||
|
||||
* `priority`
|
||||
* `weight`
|
||||
* `port`
|
||||
* `name`
|
||||
|
||||
{
|
||||
priority: 10,
|
||||
weight: 5,
|
||||
port: 21223,
|
||||
name: 'service.example.com'
|
||||
}
|
||||
|
||||
## dns.resolveTxt(hostname, callback)
|
||||
|
||||
The same as [`dns.resolve()`][], but only for text queries (`TXT` records).
|
||||
`addresses` is a 2-d array of the text records available for `hostname` (e.g.,
|
||||
Uses the DNS protocol to resolve text queries (`TXT` records) for the
|
||||
`hostname`. The `addresses` argument passed to the `callback` function is
|
||||
is a two-dimentional array of the text records available for `hostname` (e.g.,
|
||||
`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
|
||||
one record. Depending on the use case, the could be either joined together or
|
||||
one record. Depending on the use case, these could be either joined together or
|
||||
treated separately.
|
||||
|
||||
## dns.reverse(ip, callback)
|
||||
|
||||
Reverse resolves an ip address to an array of hostnames.
|
||||
Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
|
||||
array of hostnames.
|
||||
|
||||
The callback has arguments `(err, hostnames)`.
|
||||
The `callback` function has arguments `(err, hostnames)`, where `hostnames`
|
||||
is an array of resolved hostnames for the given `ip`.
|
||||
|
||||
On error, `err` is an [`Error`][] object, where `err.code` is
|
||||
one of the error codes listed below.
|
||||
|
||||
## dns.setServers(servers)
|
||||
|
||||
Given an array of IP addresses as strings, set them as the servers to use for
|
||||
resolving
|
||||
Sets the IP addresses of the servers to be used when resolving. The `servers`
|
||||
argument is an array of IPv4 or IPv6 addresses.
|
||||
|
||||
If you specify a port with the address it will be stripped, as the underlying
|
||||
library doesn't support that.
|
||||
If a port specified on the address it will be removed.
|
||||
|
||||
This will throw if you pass invalid input.
|
||||
An error will be thrown if an invalid address is provided.
|
||||
|
||||
The `dns.setServers()` method must not be called while a DNS query is in
|
||||
progress.
|
||||
|
||||
## Error codes
|
||||
|
||||
@ -257,47 +293,36 @@ Each DNS query can return one of the following error codes:
|
||||
- `dns.ADDRGETNETWORKPARAMS`: Could not find GetNetworkParams function.
|
||||
- `dns.CANCELLED`: DNS query cancelled.
|
||||
|
||||
## Supported getaddrinfo flags
|
||||
|
||||
The following flags can be passed as hints to [`dns.lookup()`][].
|
||||
|
||||
- `dns.ADDRCONFIG`: Returned address types are determined by the types
|
||||
of addresses supported by the current system. For example, IPv4 addresses
|
||||
are only returned if the current system has at least one IPv4 address
|
||||
configured. Loopback addresses are not considered.
|
||||
- `dns.V4MAPPED`: If the IPv6 family was specified, but no IPv6 addresses were
|
||||
found, then return IPv4 mapped IPv6 addresses. Note that it is not supported
|
||||
on some operating systems (e.g FreeBSD 10.1).
|
||||
|
||||
## Implementation considerations
|
||||
|
||||
Although [`dns.lookup()`][] and `dns.resolve*()/dns.reverse()` functions have
|
||||
the same goal of associating a network name with a network address (or vice
|
||||
versa), their behavior is quite different. These differences can have subtle but
|
||||
significant consequences on the behavior of Node.js programs.
|
||||
Although [`dns.lookup()`][] and the various `dns.resolve*()/dns.reverse()`
|
||||
functions have the same goal of associating a network name with a network
|
||||
address (or vice versa), their behavior is quite different. These differences
|
||||
can have subtle but significant consequences on the behavior of Node.js
|
||||
programs.
|
||||
|
||||
### dns.lookup
|
||||
### `dns.lookup()`
|
||||
|
||||
Under the hood, [`dns.lookup()`][] uses the same operating system facilities
|
||||
as most other programs. For instance, [`dns.lookup()`][] will almost always
|
||||
resolve a given name the same way as the `ping` command. On most POSIX-like
|
||||
operating systems, the behavior of the [`dns.lookup()`][] function can be
|
||||
tweaked by changing settings in `nsswitch.conf(5)` and/or `resolv.conf(5)`, but
|
||||
be careful that changing these files will change the behavior of all other
|
||||
programs running on the same operating system.
|
||||
modified by changing settings in `nsswitch.conf(5)` and/or `resolv.conf(5)`,
|
||||
but note that changing these files will change the behavior of _all other
|
||||
programs running on the same operating system_.
|
||||
|
||||
Though the call will be asynchronous from JavaScript's perspective, it is
|
||||
implemented as a synchronous call to `getaddrinfo(3)` that runs on libuv's
|
||||
threadpool. Because libuv's threadpool has a fixed size, it means that if for
|
||||
whatever reason the call to `getaddrinfo(3)` takes a long time, other
|
||||
operations that could run on libuv's threadpool (such as filesystem
|
||||
Though the call to `dns.lookup()` will be asynchronous from JavaScript's
|
||||
perspective, it is implemented as a synchronous call to `getaddrinfo(3)` that
|
||||
runs on libuv's threadpool. Because libuv's threadpool has a fixed size, it
|
||||
means that if for whatever reason the call to `getaddrinfo(3)` takes a long
|
||||
time, other operations that could run on libuv's threadpool (such as filesystem
|
||||
operations) will experience degraded performance. In order to mitigate this
|
||||
issue, one potential solution is to increase the size of libuv's threadpool by
|
||||
setting the 'UV_THREADPOOL_SIZE' environment variable to a value greater than
|
||||
4 (its current default value). For more information on libuv's threadpool, see
|
||||
setting the `'UV_THREADPOOL_SIZE'` environment variable to a value greater than
|
||||
`4` (its current default value). For more information on libuv's threadpool, see
|
||||
[the official libuv documentation][].
|
||||
|
||||
### dns.resolve, functions starting with dns.resolve and dns.reverse
|
||||
### `dns.resolve()`, `dns.resolve*()` and `dns.reverse()`
|
||||
|
||||
These functions are implemented quite differently than [`dns.lookup()`][]. They
|
||||
do not use `getaddrinfo(3)` and they _always_ perform a DNS query on the
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user