iDoc.dev

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Русский

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
한국어
العربية

Тема

DNS ​

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/dns.js

Модуль node:dns обеспечивает разрешение имен. Например, используйте его для поиска IP-адресов имен хостов.

Хотя модуль назван в честь Системы доменных имен (DNS), он не всегда использует протокол DNS для поиска. dns.lookup() использует возможности операционной системы для выполнения разрешения имен. Ему может не потребоваться выполнять какую-либо сетевую связь. Чтобы выполнить разрешение имен так же, как и другие приложения в той же системе, используйте dns.lookup().

js
import dns from 'node:dns';

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
js
const dns = require('node:dns');

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

Все остальные функции в модуле node:dns подключаются к фактическому DNS-серверу для выполнения разрешения имен. Они всегда будут использовать сеть для выполнения DNS-запросов. Эти функции не используют тот же набор файлов конфигурации, что и dns.lookup() (например, /etc/hosts). Используйте эти функции, чтобы всегда выполнять DNS-запросы, минуя другие средства разрешения имен.

js
import dns from 'node:dns';

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err;

  console.log(`addresses: ${JSON.stringify(addresses)}`);

  addresses.forEach((a) => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err;
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
    });
  });
});
js
const dns = require('node:dns');

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err;

  console.log(`addresses: ${JSON.stringify(addresses)}`);

  addresses.forEach((a) => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err;
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
    });
  });
});

См. раздел Соображения по реализации для получения дополнительной информации.

Класс: dns.Resolver ​

Добавлено в версии: v8.3.0

Независимый преобразователь для DNS-запросов.

Создание нового преобразователя использует настройки сервера по умолчанию. Установка серверов, используемых для преобразователя, с помощью resolver.setServers(), не влияет на другие преобразователи:

js
import { Resolver } from 'node:dns';
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер 4.4.4.4, независимо от глобальных настроек.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
});
js
const { Resolver } = require('node:dns');
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер 4.4.4.4, независимо от глобальных настроек.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
});

Доступны следующие методы из модуля node:dns:

Resolver([options]) ​

[История]

ВерсияИзменения
v16.7.0, v14.18.0Объект options теперь принимает параметр tries.
v12.18.3Конструктор теперь принимает объект options. Единственный поддерживаемый параметр - timeout.
v8.3.0Добавлено в версии: v8.3.0

Создать новый преобразователь.

  • options <Object>
    • timeout <integer> Время ожидания запроса в миллисекундах или -1 для использования времени ожидания по умолчанию.
    • tries <integer> Количество попыток, которые преобразователь будет предпринимать для связи с каждым сервером имен, прежде чем сдаться. По умолчанию: 4

resolver.cancel() ​

Добавлено в: v8.3.0

Отменяет все ожидающие DNS-запросы, сделанные этим резолвером. Соответствующие обратные вызовы будут вызваны с ошибкой с кодом ECANCELLED.

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

Добавлено в: v15.1.0, v14.17.0

  • ipv4 <string> Строковое представление IPv4-адреса. По умолчанию: '0.0.0.0'
  • ipv6 <string> Строковое представление IPv6-адреса. По умолчанию: '::0'

Экземпляр резолвера будет отправлять свои запросы с указанного IP-адреса. Это позволяет программам указывать исходящие интерфейсы при использовании в многоадресных системах.

Если адрес v4 или v6 не указан, он устанавливается в значение по умолчанию, и операционная система автоматически выбирает локальный адрес.

Резолвер будет использовать локальный адрес v4 при выполнении запросов к DNS-серверам IPv4 и локальный адрес v6 при выполнении запросов к DNS-серверам IPv6. Тип rrtype запросов разрешения не влияет на используемый локальный адрес.

dns.getServers() ​

Добавлено в: v0.11.3

Возвращает массив строк IP-адресов, отформатированных в соответствии с RFC 5952, которые в настоящее время настроены для разрешения DNS. Строка будет включать раздел порта, если используется пользовательский порт.

js
[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
]

dns.lookup(hostname[, options], callback) ​

[История]

ВерсияИзменения
v22.1.0, v20.13.0Опция verbatim теперь устарела в пользу новой опции order.
v18.4.0Для совместимости с node:net при передаче объекта опций опция family может быть строкой 'IPv4' или строкой 'IPv6'.
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v17.0.0Опция verbatim теперь по умолчанию имеет значение true.
v8.5.0Теперь поддерживается опция verbatim.
v1.2.0Теперь поддерживается опция all.
v0.1.90Добавлено в: v0.1.90

  • hostname <string>

  • options <integer> | <Object>

    • family <integer> | <string> Семейство записей. Должно быть 4, 6 или 0. По причинам обратной совместимости 'IPv4' и 'IPv6' интерпретируются как 4 и 6 соответственно. Значение 0 указывает, что возвращается либо IPv4, либо IPv6 адрес. Если значение 0 используется с { all: true } (см. ниже), возвращается либо один, либо оба адреса IPv4 и IPv6, в зависимости от DNS-резолвера системы. По умолчанию: 0.
    • hints <number> Один или несколько поддерживаемых флагов getaddrinfo. Несколько флагов можно передать, выполнив побитовое OR их значений.
    • all <boolean> Если true, обратный вызов возвращает все разрешенные адреса в массиве. В противном случае возвращает один адрес. По умолчанию: false.
    • order <string> Когда verbatim, разрешенные адреса возвращаются неотсортированными. Когда ipv4first, разрешенные адреса сортируются путем размещения адресов IPv4 перед адресами IPv6. Когда ipv6first, разрешенные адреса сортируются путем размещения адресов IPv6 перед адресами IPv4. По умолчанию: verbatim (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.
    • verbatim <boolean> Если true, обратный вызов получает адреса IPv4 и IPv6 в том порядке, в котором их вернул DNS-резолвер. Если false, адреса IPv4 помещаются перед адресами IPv6. Этот параметр будет объявлен устаревшим в пользу order. Если указаны оба параметра, order имеет более высокий приоритет. Новый код должен использовать только order. По умолчанию: true (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.

  • callback <Function>

    • err <Error>
    • address <string> Строковое представление IPv4 или IPv6 адреса.
    • family <integer> 4 или 6, обозначающее семейство address, или 0, если адрес не является адресом IPv4 или IPv6. 0 является вероятным индикатором ошибки в службе разрешения имен, используемой операционной системой.

Преобразует имя хоста (например, 'nodejs.org') в первую найденную запись A (IPv4) или AAAA (IPv6). Все свойства option являются необязательными. Если options является целым числом, то оно должно быть 4 или 6 – если options не указано, то возвращаются либо IPv4, либо IPv6 адреса, либо и то, и другое, если они найдены.

Если опция all установлена в true, аргументы для callback изменяются на (err, addresses), где addresses является массивом объектов со свойствами address и family.

В случае ошибки err является объектом Error, где err.code является кодом ошибки. Имейте в виду, что err.code будет установлен в 'ENOTFOUND' не только тогда, когда имя хоста не существует, но и когда поиск завершается неудачей другими способами, например, из-за отсутствия доступных файловых дескрипторов.

dns.lookup() не обязательно имеет какое-либо отношение к протоколу DNS. Реализация использует средство операционной системы, которое может связывать имена с адресами и наоборот. Эта реализация может иметь тонкие, но важные последствия для поведения любой программы Node.js. Пожалуйста, уделите время ознакомлению с разделом Соображения по реализации перед использованием dns.lookup().

Пример использования:

js
import dns from 'node:dns';
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
js
const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

Если этот метод вызывается как его util.promisify()ed версия, и all не установлено в true, он возвращает Promise для Object со свойствами address и family.

Поддерживаемые флаги getaddrinfo ​

[История]

ВерсияИзменения
v13.13.0, v12.17.0Добавлена поддержка флага dns.ALL.

Следующие флаги могут быть переданы в качестве подсказок в dns.lookup().

  • dns.ADDRCONFIG: Ограничивает возвращаемые типы адресов типами не-loopback адресов, настроенных в системе. Например, IPv4-адреса возвращаются только в том случае, если текущая система имеет хотя бы один настроенный IPv4-адрес.
  • dns.V4MAPPED: Если было указано семейство IPv6, но IPv6-адреса не были найдены, возвращаются IPv4-отображенные IPv6-адреса. Не поддерживается в некоторых операционных системах (например, FreeBSD 10.1).
  • dns.ALL: Если указан dns.V4MAPPED, возвращает как разрешенные IPv6-адреса, так и IPv4-отображенные IPv6-адреса.

dns.lookupService(address, port, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь выдает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.11.14Добавлено в версии: v0.11.14

Разрешает заданный address и port в имя хоста и службу, используя базовую реализацию getnameinfo операционной системы.

Если address не является допустимым IP-адресом, будет выдана ошибка TypeError. port будет приведен к числовому типу. Если это недопустимый порт, будет выдана ошибка TypeError.

В случае ошибки err является объектом Error, где err.code — код ошибки.

js
import dns from 'node:dns';
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
});
js
const dns = require('node:dns');
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
});

Если этот метод вызывается как его util.promisify()ed версия, он возвращает Promise для Object со свойствами hostname и service.

dns.resolve(hostname[, rrtype], callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова аргументу callback теперь выдает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.1.27Добавлено в версии: v0.1.27

Использует протокол DNS для разрешения имени хоста (например, 'nodejs.org') в массив ресурсных записей. Функция callback имеет аргументы (err, records). При успешном выполнении records будет массивом ресурсных записей. Тип и структура отдельных результатов зависят от rrtype:

rrtyperecords содержитТип результатаСокращенный метод
'A'IPv4-адреса (по умолчанию)<string>dns.resolve4()
'AAAA'IPv6-адреса<string>dns.resolve6()
'ANY'любые записи<Object>dns.resolveAny()
'CAA'записи авторизации ЦС<Object>dns.resolveCaa()
'CNAME'записи канонического имени<string>dns.resolveCname()
'MX'записи почтового обмена<Object>dns.resolveMx()
'NAPTR'записи указателей полномочий имен<Object>dns.resolveNaptr()
'NS'записи сервера имен<string>dns.resolveNs()
'PTR'записи указателя<string>dns.resolvePtr()
'SOA'записи начала зоны полномочий<Object>dns.resolveSoa()
'SRV'записи службы<Object>dns.resolveSrv()
'TXT'текстовые записи<string[]>dns.resolveTxt()

При ошибке err является объектом Error, где err.code - один из кодов ошибок DNS.

dns.resolve4(hostname[, options], callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v7.2.0Этот метод теперь поддерживает передачу options, в частности options.ttl.
v0.1.16Добавлено в версии: v0.1.16

  • hostname <string> Имя хоста для разрешения.

  • options <Object>

    • ttl <boolean> Получает значение Time-To-Live (TTL) каждой записи. Если true, обратный вызов получает массив объектов { address: '1.2.3.4', ttl: 60 } вместо массива строк, при этом TTL выражается в секундах.

  • callback <Function>

Использует протокол DNS для разрешения IPv4-адресов (записи A) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив IPv4-адресов (например, ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dns.resolve6(hostname[, options], callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова аргументу callback теперь вызывает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v7.2.0Этот метод теперь поддерживает передачу options, в частности options.ttl.
v0.1.16Добавлено в версии: v0.1.16

  • hostname <string> Имя хоста для разрешения.

  • options <Object>

    • ttl <boolean> Получает значение Time-To-Live (TTL) каждой записи. Если true, обратный вызов получает массив объектов { address: '0:1:2:3:4:5:6:7', ttl: 60 } вместо массива строк, при этом TTL выражается в секундах.

  • callback <Function>

Использует протокол DNS для разрешения IPv6-адресов (записи AAAA) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив IPv6-адресов.

dns.resolveAny(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргументе callback теперь вызывает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.

Использует протокол DNS для разрешения всех записей (также известных как ANY или * запрос). Аргумент ret, переданный в функцию callback, будет массивом, содержащим различные типы записей. Каждый объект имеет свойство type, которое указывает тип текущей записи. И в зависимости от type, в объекте будут присутствовать дополнительные свойства:

ТипСвойства
'A'address / ttl
'AAAA'address / ttl
'CNAME'value
'MX'См. dns.resolveMx()
'NAPTR'См. dns.resolveNaptr()
'NS'value
'PTR'value
'SOA'См. dns.resolveSoa()
'SRV'См. dns.resolveSrv()
'TXT'Этот тип записи содержит свойство массива под названием entries, которое ссылается на dns.resolveTxt(), например, { entries: ['...'], type: 'TXT' }
Вот пример объекта ret, переданного в обратный вызов:
js
[ { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  { type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60 } ]

Операторы DNS-серверов могут предпочесть не отвечать на ANY запросы. Может быть лучше вызывать отдельные методы, такие как dns.resolve4(), dns.resolveMx() и т. д. Для получения более подробной информации см. RFC 8482.

dns.resolveCname(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.3.2Добавлено в: v0.3.2

Использует протокол DNS для разрешения CNAME записей для hostname. Аргумент addresses, переданный в функцию callback, будет содержать массив записей канонических имен, доступных для hostname (например, ['bar.example.com']).

dns.resolveCaa(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.0.0, v14.17.0Добавлено в: v15.0.0, v14.17.0

Использует протокол DNS для разрешения CAA записей для hostname. Аргумент addresses, переданный в функцию callback, будет содержать массив записей авторизации центра сертификации, доступных для hostname (например, [{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]).

dns.resolveMx(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительной функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.1.27Добавлено в: v0.1.27

Использует протокол DNS для разрешения записей почтового обмена (MX records) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив объектов, содержащих свойства priority и exchange (например, [{priority: 10, exchange: 'mx.example.com'}, ...] ).

dns.resolveNaptr(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительной функции обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.9.12Добавлено в: v0.9.12

Использует протокол DNS для разрешения записей на основе регулярных выражений (NAPTR records) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив объектов со следующими свойствами:

  • flags
  • service
  • regexp
  • replacement
  • order
  • preference
js
{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

dns.resolveNs(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргументе callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.1.90Добавлено в версии: v0.1.90

Использует протокол DNS для разрешения записей сервера имен (NS записей) для hostname. Аргумент addresses, переданный в функцию callback, будет содержать массив записей сервера имен, доступных для hostname (например, ['ns1.example.com', 'ns2.example.com']).

dns.resolvePtr(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргументе callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v6.0.0Добавлено в версии: v6.0.0

Использует протокол DNS для разрешения записей указателя (PTR записей) для hostname. Аргумент addresses, переданный в функцию callback, будет массивом строк, содержащих записи ответа.

dns.resolveSoa(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недействительного обратного вызова в аргументе callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.11.10Добавлено в версии: v0.11.10

Использует протокол DNS для разрешения записи начала зоны (SOA записи) для hostname. Аргумент address, переданный в функцию callback, будет объектом со следующими свойствами:

  • nsname
  • hostmaster
  • serial
  • refresh
  • retry
  • expire
  • minttl
js
{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

dns.resolveSrv(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недопустимой функции обратного вызова в аргумент callback теперь выдает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.1.27Добавлено в: v0.1.27

Использует протокол DNS для разрешения записей служб (SRV records) для hostname. Аргумент addresses, передаваемый функции callback, будет массивом объектов со следующими свойствами:

  • priority
  • weight
  • port
  • name
js
{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

dns.resolveTxt(hostname, callback) ​

[История]

ВерсияИзменения
v18.0.0Передача недопустимой функции обратного вызова в аргумент callback теперь выдает ошибку ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v0.1.27Добавлено в: v0.1.27

Использует протокол DNS для разрешения текстовых запросов (TXT records) для hostname. Аргумент records, передаваемый функции callback, представляет собой двумерный массив текстовых записей, доступных для hostname (например, [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Каждый подмассив содержит TXT-фрагменты одной записи. В зависимости от варианта использования, их можно либо объединить вместе, либо рассматривать отдельно.

dns.reverse(ip, callback) ​

Added in: v0.1.16

Выполняет обратный DNS-запрос, который преобразует адрес IPv4 или IPv6 в массив имен хостов.

В случае ошибки err является объектом Error, где err.code является одним из кодов ошибок DNS.

dns.setDefaultResultOrder(order) ​

[История]

ВерсияИзменения
v22.1.0, v20.13.0Теперь поддерживается значение ipv6first.
v17.0.0Изменено значение по умолчанию на verbatim.
v16.4.0, v14.18.0Добавлено в: v16.4.0, v14.18.0
  • order <string> должно быть 'ipv4first', 'ipv6first' или 'verbatim'.

Устанавливает значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Значение может быть:

  • ipv4first: устанавливает значение order по умолчанию равным ipv4first.
  • ipv6first: устанавливает значение order по умолчанию равным ipv6first.
  • verbatim: устанавливает значение order по умолчанию равным verbatim.

Значение по умолчанию — verbatim, и dns.setDefaultResultOrder() имеет более высокий приоритет, чем --dns-result-order. При использовании рабочих потоков, dns.setDefaultResultOrder() из основного потока не повлияет на порядок DNS по умолчанию в рабочих потоках.

dns.getDefaultResultOrder() ​

[История]

ВерсияИзменения
v22.1.0, v20.13.0Теперь поддерживается значение ipv6first.
v20.1.0, v18.17.0Добавлено в: v20.1.0, v18.17.0

Получает значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Значение может быть:

  • ipv4first: для order, принимающего по умолчанию значение ipv4first.
  • ipv6first: для order, принимающего по умолчанию значение ipv6first.
  • verbatim: для order, принимающего по умолчанию значение verbatim.

dns.setServers(servers) ​

Добавлено в версии: v0.11.3

  • servers <string[]> массив адресов, отформатированных в соответствии с RFC 5952

Устанавливает IP-адрес и порт серверов, которые будут использоваться при выполнении разрешения DNS. Аргумент servers является массивом адресов, отформатированных в соответствии с RFC 5952. Если порт является портом DNS по умолчанию IANA (53), его можно опустить.

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

Если предоставлен недопустимый адрес, будет выдана ошибка.

Метод dns.setServers() нельзя вызывать во время выполнения запроса DNS.

Метод dns.setServers() влияет только на dns.resolve(), dns.resolve*() и dns.reverse() (и не на dns.lookup()).

Этот метод работает так же, как resolve.conf. То есть, если попытка разрешения с первым предоставленным сервером приводит к ошибке NOTFOUND, метод resolve() не будет пытаться выполнить разрешение со следующими предоставленными серверами. Резервные DNS-серверы будут использоваться только в том случае, если у предыдущих серверов истечет время ожидания или возникнет какая-либо другая ошибка.

DNS promises API ​

[История]

ВерсияИзменения
v15.0.0Предоставлено как require('dns/promises').
v11.14.0, v10.17.0Этот API больше не является экспериментальным.
v10.6.0Добавлено в версии: v10.6.0

API dns.promises предоставляет альтернативный набор асинхронных методов DNS, которые возвращают объекты Promise вместо использования обратных вызовов. Доступ к API осуществляется через require('node:dns').promises или require('node:dns/promises').

Класс: dnsPromises.Resolver ​

Добавлено в версии: v10.6.0

Независимый резолвер для DNS-запросов.

Создание нового резолвера использует настройки сервера по умолчанию. Установка серверов, используемых для резолвера, с помощью resolver.setServers() не влияет на другие резолверы:

js
import { Resolver } from 'node:dns/promises';
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер 4.4.4.4, независимо от глобальных настроек.
const addresses = await resolver.resolve4('example.org');
js
const { Resolver } = require('node:dns').promises;
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер 4.4.4.4, независимо от глобальных настроек.
resolver.resolve4('example.org').then((addresses) => {
  // ...
});

// В качестве альтернативы тот же код можно записать в стиле async-await.
(async function() {
  const addresses = await resolver.resolve4('example.org');
})();

Доступны следующие методы из API dnsPromises:

resolver.cancel() ​

Добавлено в: v15.3.0, v14.17.0

Отменяет все незавершенные DNS-запросы, сделанные этим резолвером. Соответствующие промисы будут отклонены с ошибкой с кодом ECANCELLED.

dnsPromises.getServers() ​

Добавлено в: v10.6.0

Возвращает массив строк IP-адресов, отформатированных в соответствии с RFC 5952, которые в настоящее время настроены для разрешения DNS. Строка будет включать раздел порта, если используется пользовательский порт.

js
[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
]

dnsPromises.lookup(hostname[, options]) ​

[История]

ВерсияИзменения
v22.1.0, v20.13.0Параметр verbatim теперь устарел в пользу нового параметра order.
v10.6.0Добавлено в: v10.6.0
  • hostname <string>
  • options <integer> | <Object>
    • family <integer> Семейство записей. Должно быть 4, 6 или 0. Значение 0 указывает, что возвращается либо IPv4, либо IPv6 адрес. Если значение 0 используется с { all: true } (см. ниже), возвращается один или оба адреса IPv4 и IPv6, в зависимости от DNS-резолвера системы. По умолчанию: 0.
    • hints <number> Один или несколько поддерживаемых флагов getaddrinfo. Несколько флагов могут быть переданы путем побитового OR их значений.
    • all <boolean> Если true, Promise разрешается со всеми адресами в массиве. В противном случае возвращает один адрес. По умолчанию: false.
    • order <string> Если verbatim, Promise разрешается с адресами IPv4 и IPv6 в том порядке, в котором их вернул DNS-резолвер. Если ipv4first, адреса IPv4 помещаются перед адресами IPv6. Если ipv6first, адреса IPv6 помещаются перед адресами IPv4. По умолчанию: verbatim (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order. В новом коде следует использовать { order: 'verbatim' }.
    • verbatim <boolean> Если true, Promise разрешается с адресами IPv4 и IPv6 в том порядке, в котором их вернул DNS-резолвер. Если false, адреса IPv4 помещаются перед адресами IPv6. Этот параметр будет объявлен устаревшим в пользу order. Если указаны оба параметра, order имеет более высокий приоритет. Новый код должен использовать только order. По умолчанию: в настоящее время false (адреса переупорядочиваются), но ожидается, что это изменится в не очень отдаленном будущем. Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.

Разрешает имя хоста (например, 'nodejs.org') в первую найденную запись A (IPv4) или AAAA (IPv6). Все свойства option являются необязательными. Если options является целым числом, то оно должно быть 4 или 6 - если options не предоставлено, то возвращаются либо IPv4, либо IPv6 адреса, либо оба, если они найдены.

Если для параметра all установлено значение true, Promise разрешается с addresses, представляющим собой массив объектов со свойствами address и family.

В случае ошибки Promise отклоняется с объектом Error, где err.code является кодом ошибки. Имейте в виду, что err.code будет установлено в 'ENOTFOUND' не только в том случае, если имя хоста не существует, но и в том случае, если поиск завершается неудачей другими способами, например, из-за отсутствия доступных файловых дескрипторов.

dnsPromises.lookup() не обязательно имеет какое-либо отношение к протоколу DNS. Реализация использует средство операционной системы, которое может связывать имена с адресами и наоборот. Эта реализация может иметь тонкие, но важные последствия для поведения любой программы Node.js. Пожалуйста, потратьте некоторое время на изучение раздела Соображения по реализации перед использованием dnsPromises.lookup().

Пример использования:

js
import dns from 'node:dns';
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});
js
const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});

dnsPromises.lookupService(address, port) ​

Добавлено в: v10.6.0

Преобразует заданный address и port в имя хоста и сервис, используя базовую реализацию getnameinfo операционной системы.

Если address не является допустимым IP-адресом, будет выброшена ошибка TypeError. port будет приведён к числу. Если это недопустимый порт, будет выброшена ошибка TypeError.

В случае ошибки Promise отклоняется с объектом Error, где err.code является кодом ошибки.

js
import dnsPromises from 'node:dns/promises';
const result = await dnsPromises.lookupService('127.0.0.1', 22);

console.log(result.hostname, result.service); // Выводит: localhost ssh
js
const dnsPromises = require('node:dns').promises;
dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
  console.log(result.hostname, result.service);
  // Выводит: localhost ssh
});

dnsPromises.resolve(hostname[, rrtype]) ​

Добавлено в: v10.6.0

  • hostname <string> Имя хоста для разрешения.
  • rrtype <string> Тип записи ресурса. По умолчанию: 'A'.

Использует протокол DNS для разрешения имени хоста (например, 'nodejs.org') в массив записей ресурсов. При успешном выполнении Promise разрешается массивом записей ресурсов. Тип и структура отдельных результатов зависят от rrtype:

rrtyperecords содержитТип результатаСокращённый метод
'A'IPv4-адреса (по умолчанию)<string>dnsPromises.resolve4()
'AAAA'IPv6-адреса<string>dnsPromises.resolve6()
'ANY'любые записи<Object>dnsPromises.resolveAny()
'CAA'записи авторизации ЦС<Object>dnsPromises.resolveCaa()
'CNAME'канонические имена<string>dnsPromises.resolveCname()
'MX'записи почтового обмена<Object>dnsPromises.resolveMx()
'NAPTR'записи указателя полномочий имени<Object>dnsPromises.resolveNaptr()
'NS'записи сервера имён<string>dnsPromises.resolveNs()
'PTR'записи указателя<string>dnsPromises.resolvePtr()
'SOA'записи начала зоны полномочий<Object>dnsPromises.resolveSoa()
'SRV'записи сервиса<Object>dnsPromises.resolveSrv()
'TXT'текстовые записи<string[]>dnsPromises.resolveTxt()

В случае ошибки Promise отклоняется с объектом Error, где err.code является одним из кодов ошибок DNS.

dnsPromises.resolve4(hostname[, options]) ​

Добавлено в версии: v10.6.0

  • hostname <string> Имя хоста для разрешения.
  • options <Object>
    • ttl <boolean> Получить значение Time-To-Live (TTL) каждой записи. Если true, Promise разрешается с массивом объектов { address: '1.2.3.4', ttl: 60 }, а не с массивом строк, при этом TTL выражается в секундах.

Использует протокол DNS для разрешения IPv4-адресов (записи A) для hostname. При успехе Promise разрешается с массивом IPv4-адресов (например, ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dnsPromises.resolve6(hostname[, options]) ​

Добавлено в версии: v10.6.0

  • hostname <string> Имя хоста для разрешения.
  • options <Object>
    • ttl <boolean> Получить значение Time-To-Live (TTL) каждой записи. Если true, Promise разрешается с массивом объектов { address: '0:1:2:3:4:5:6:7', ttl: 60 }, а не с массивом строк, при этом TTL выражается в секундах.

Использует протокол DNS для разрешения IPv6-адресов (записи AAAA) для hostname. При успехе Promise разрешается с массивом IPv6-адресов.

dnsPromises.resolveAny(hostname) ​

Добавлено в версии: v10.6.0

Использует протокол DNS для разрешения всех записей (также известных как запросы ANY или *). При успехе Promise разрешается с массивом, содержащим различные типы записей. Каждый объект имеет свойство type, которое указывает тип текущей записи. И в зависимости от type, в объекте будут присутствовать дополнительные свойства:

ТипСвойства
'A'address / ttl
'AAAA'address / ttl
'CNAME'value
'MX'См. dnsPromises.resolveMx()
'NAPTR'См. dnsPromises.resolveNaptr()
'NS'value
'PTR'value
'SOA'См. dnsPromises.resolveSoa()
'SRV'См. dnsPromises.resolveSrv()
'TXT'Этот тип записи содержит свойство массива под названием entries, которое относится к dnsPromises.resolveTxt() , например { entries: ['...'], type: 'TXT' }
Вот пример результирующего объекта:
js
[ { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  { type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60 } ]

dnsPromises.resolveCaa(hostname) ​

Добавлено в: v15.0.0, v14.17.0

Использует протокол DNS для разрешения CAA записей для hostname. В случае успеха Promise разрешается с массивом объектов, содержащих доступные записи авторизации центра сертификации для hostname (например, [{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]).

dnsPromises.resolveCname(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения CNAME записей для hostname. В случае успеха Promise разрешается с массивом канонических имен, доступных для hostname (например, ['bar.example.com']).

dnsPromises.resolveMx(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения записей почтового обмена (записей MX) для hostname. В случае успеха Promise разрешается с массивом объектов, содержащих свойства priority и exchange (например, [{priority: 10, exchange: 'mx.example.com'}, ...]).

dnsPromises.resolveNaptr(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения записей на основе регулярных выражений (записей NAPTR) для hostname. В случае успеха Promise разрешается с массивом объектов со следующими свойствами:

  • flags
  • service
  • regexp
  • replacement
  • order
  • preference
js
{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

dnsPromises.resolveNs(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения записей серверов имен (записей NS) для hostname. В случае успеха Promise разрешается с массивом записей серверов имен, доступных для hostname (например, ['ns1.example.com', 'ns2.example.com']).

dnsPromises.resolvePtr(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения записей указателя (PTR records) для hostname. При успехе Promise разрешается массивом строк, содержащих записи ответа.

dnsPromises.resolveSoa(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения записи начала зоны (SOA record) для hostname. При успехе Promise разрешается объектом со следующими свойствами:

  • nsname
  • hostmaster
  • serial
  • refresh
  • retry
  • expire
  • minttl
js
{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

dnsPromises.resolveSrv(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения сервисных записей (SRV records) для hostname. При успехе Promise разрешается массивом объектов со следующими свойствами:

  • priority
  • weight
  • port
  • name
js
{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

dnsPromises.resolveTxt(hostname) ​

Добавлено в: v10.6.0

Использует протокол DNS для разрешения текстовых запросов (TXT records) для hostname. При успехе Promise разрешается двумерным массивом текстовых записей, доступных для hostname (например, [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Каждый подмассив содержит TXT-фрагменты одной записи. В зависимости от варианта использования, их можно либо объединить вместе, либо обрабатывать отдельно.

dnsPromises.reverse(ip) ​

Добавлено в версии: v10.6.0

Выполняет обратный DNS-запрос, который разрешает IPv4 или IPv6 адрес в массив имен хостов.

При ошибке Promise отклоняется с объектом Error, где err.code является одним из кодов ошибок DNS.

dnsPromises.setDefaultResultOrder(order) ​

[История изменений]

ВерсияИзменения
v22.1.0, v20.13.0Теперь поддерживается значение ipv6first.
v17.0.0Значение по умолчанию изменено на verbatim.
v16.4.0, v14.18.0Добавлено в версии: v16.4.0, v14.18.0
  • order <string> должно быть 'ipv4first', 'ipv6first' или 'verbatim'.

Устанавливает значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Значение может быть:

  • ipv4first: устанавливает order по умолчанию в ipv4first.
  • ipv6first: устанавливает order по умолчанию в ipv6first.
  • verbatim: устанавливает order по умолчанию в verbatim.

По умолчанию используется verbatim, и dnsPromises.setDefaultResultOrder() имеет более высокий приоритет, чем --dns-result-order. При использовании рабочих потоков, dnsPromises.setDefaultResultOrder() из основного потока не влияет на порядок DNS по умолчанию в рабочих потоках.

dnsPromises.getDefaultResultOrder() ​

Добавлено в версии: v20.1.0, v18.17.0

Получает значение dnsOrder.

dnsPromises.setServers(servers) ​

Добавлено в версии: v10.6.0

Устанавливает IP-адрес и порт серверов, которые будут использоваться при выполнении DNS-разрешения. Аргумент servers является массивом адресов в формате RFC 5952. Если порт является стандартным портом DNS IANA (53), его можно опустить.

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

Если предоставлен недействительный адрес, будет выдана ошибка.

Метод dnsPromises.setServers() не должен вызываться во время выполнения DNS-запроса.

Этот метод работает так же, как resolve.conf. То есть, если попытка разрешения с использованием первого предоставленного сервера приводит к ошибке NOTFOUND, метод resolve() не будет пытаться выполнить разрешение с использованием последующих предоставленных серверов. Резервные DNS-серверы будут использоваться только в том случае, если первые серверы истекли по времени или привели к какой-либо другой ошибке.

Коды ошибок ​

Каждый DNS-запрос может вернуть один из следующих кодов ошибок:

  • dns.NODATA: DNS-сервер вернул ответ без данных.
  • dns.FORMERR: DNS-сервер утверждает, что запрос был неправильно отформатирован.
  • dns.SERVFAIL: DNS-сервер вернул общую ошибку.
  • dns.NOTFOUND: Доменное имя не найдено.
  • dns.NOTIMP: DNS-сервер не реализует запрошенную операцию.
  • dns.REFUSED: DNS-сервер отклонил запрос.
  • dns.BADQUERY: Неправильно отформатированный DNS-запрос.
  • dns.BADNAME: Неправильно отформатированное имя хоста.
  • dns.BADFAMILY: Неподдерживаемое семейство адресов.
  • dns.BADRESP: Неправильно отформатированный DNS-ответ.
  • dns.CONNREFUSED: Не удалось связаться с DNS-серверами.
  • dns.TIMEOUT: Истекло время ожидания при обращении к DNS-серверам.
  • dns.EOF: Конец файла.
  • dns.FILE: Ошибка чтения файла.
  • dns.NOMEM: Недостаточно памяти.
  • dns.DESTRUCTION: Канал уничтожается.
  • dns.BADSTR: Неправильно отформатированная строка.
  • dns.BADFLAGS: Указаны недопустимые флаги.
  • dns.NONAME: Указанное имя хоста не является числовым.
  • dns.BADHINTS: Указаны недопустимые флаги подсказок.
  • dns.NOTINITIALIZED: Инициализация библиотеки c-ares еще не выполнена.
  • dns.LOADIPHLPAPI: Ошибка загрузки iphlpapi.dll.
  • dns.ADDRGETNETWORKPARAMS: Не удалось найти функцию GetNetworkParams.
  • dns.CANCELLED: DNS-запрос отменен.

API dnsPromises также экспортирует вышеуказанные коды ошибок, например, dnsPromises.NODATA.

Замечания по реализации ​

Хотя dns.lookup() и различные функции dns.resolve*()/dns.reverse() преследуют одну и ту же цель - связать сетевое имя с сетевым адресом (или наоборот), их поведение существенно отличается. Эти различия могут иметь тонкие, но значительные последствия для поведения программ Node.js.

dns.lookup() ​

Под капотом dns.lookup() использует те же возможности операционной системы, что и большинство других программ. Например, dns.lookup() почти всегда будет разрешать данное имя так же, как и команда ping. В большинстве POSIX-подобных операционных систем поведение функции dns.lookup() можно изменить, изменив настройки в nsswitch.conf(5) и/или resolv.conf(5), но изменение этих файлов изменит поведение всех других программ, работающих в той же операционной системе.

Хотя вызов dns.lookup() будет асинхронным с точки зрения JavaScript, он реализован как синхронный вызов getaddrinfo(3), который выполняется в пуле потоков libuv. Это может иметь неожиданные негативные последствия для производительности некоторых приложений, см. документацию по UV_THREADPOOL_SIZE для получения дополнительной информации.

Различные сетевые API будут вызывать dns.lookup() внутри себя для разрешения имен хостов. Если это проблема, рассмотрите возможность разрешения имени хоста в адрес с помощью dns.resolve() и использования адреса вместо имени хоста. Кроме того, некоторые сетевые API (такие как socket.connect() и dgram.createSocket()) позволяют заменить резолвер по умолчанию, dns.lookup().

dns.resolve(), dns.resolve*(), и dns.reverse() ​

Эти функции реализованы совершенно иначе, чем dns.lookup(). Они не используют getaddrinfo(3) и всегда выполняют DNS-запрос в сети. Эта сетевая коммуникация всегда выполняется асинхронно и не использует пул потоков libuv.

В результате, эти функции не могут оказывать такое же негативное влияние на другие процессы, происходящие в пуле потоков libuv, как dns.lookup().

Они не используют тот же набор конфигурационных файлов, что и dns.lookup(). Например, они не используют конфигурацию из /etc/hosts.