DNS

[Stable: 2 - Stable]

Stable: 2 Stabilität: 2 - Stabil

Quellcode: lib/dns.js

Das Modul node:dns ermöglicht die Namensauflösung. Verwenden Sie es beispielsweise, um IP-Adressen von Hostnamen nachzuschlagen.

Obwohl es nach dem Domain Name System (DNS) benannt ist, verwendet es nicht immer das DNS-Protokoll für die Suche. dns.lookup() verwendet die Einrichtungen des Betriebssystems, um die Namensauflösung durchzuführen. Es muss möglicherweise keine Netzwerkkommunikation durchgeführt werden. Um die Namensauflösung so durchzuführen, wie es andere Anwendungen auf demselben System tun, verwenden Sie dns.lookup().

ESM

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

CJS

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

Alle anderen Funktionen im Modul node:dns stellen eine Verbindung zu einem tatsächlichen DNS-Server her, um die Namensauflösung durchzuführen. Sie verwenden immer das Netzwerk, um DNS-Abfragen durchzuführen. Diese Funktionen verwenden nicht denselben Satz von Konfigurationsdateien, die von dns.lookup() verwendet werden (z. B. /etc/hosts). Verwenden Sie diese Funktionen, um immer DNS-Abfragen durchzuführen und andere Namensauflösungseinrichtungen zu umgehen.

ESM

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)}`);
    });
  });
});

CJS

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)}`);
    });
  });
});

Weitere Informationen finden Sie im Abschnitt Überlegungen zur Implementierung.

Klasse: dns.Resolver

Hinzugefügt in: v8.3.0

Ein unabhängiger Resolver für DNS-Anfragen.

Das Erstellen eines neuen Resolvers verwendet die Standardservereinstellungen. Das Setzen der für einen Resolver verwendeten Server mit resolver.setServers() beeinflusst keine anderen Resolver:

ESM

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

// Diese Anfrage verwendet den Server unter 4.4.4.4, unabhängig von den globalen Einstellungen.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
});

CJS

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

// Diese Anfrage verwendet den Server unter 4.4.4.4, unabhängig von den globalen Einstellungen.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
});

Die folgenden Methoden aus dem Modul node:dns sind verfügbar:

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

Resolver([options])

[Verlauf]

Version	Änderungen
v16.7.0, v14.18.0	Das options-Objekt akzeptiert jetzt eine tries-Option.
v12.18.3	Der Konstruktor akzeptiert jetzt ein options-Objekt. Die einzig unterstützte Option ist timeout.
v8.3.0	Hinzugefügt in: v8.3.0

Erstellen Sie einen neuen Resolver.

• options <Object>
  • timeout <integer> Abfrage-Timeout in Millisekunden oder -1, um das Standard-Timeout zu verwenden.
  • tries <integer> Die Anzahl der Versuche, die der Resolver unternehmen wird, um jeden Nameserver zu kontaktieren, bevor er aufgibt. Standard: 4

resolver.cancel()

Hinzugefügt in: v8.3.0

Bricht alle ausstehenden DNS-Abfragen ab, die von diesem Resolver gestellt wurden. Die entsprechenden Rückrufe werden mit einem Fehler mit dem Code ECANCELLED aufgerufen.

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

Hinzugefügt in: v15.1.0, v14.17.0

• ipv4 <string> Eine String-Darstellung einer IPv4-Adresse. Standard: '0.0.0.0'
• ipv6 <string> Eine String-Darstellung einer IPv6-Adresse. Standard: '::0'

Die Resolver-Instanz sendet ihre Anfragen von der angegebenen IP-Adresse. Dies ermöglicht es Programmen, ausgehende Schnittstellen anzugeben, wenn sie auf Multi-Homed-Systemen verwendet werden.

Wenn keine v4- oder v6-Adresse angegeben wird, wird sie auf den Standardwert gesetzt und das Betriebssystem wählt automatisch eine lokale Adresse aus.

Der Resolver verwendet die lokale v4-Adresse, wenn er Anfragen an IPv4-DNS-Server stellt, und die lokale v6-Adresse, wenn er Anfragen an IPv6-DNS-Server stellt. Der rrtype von Auflösungsanfragen hat keinen Einfluss auf die verwendete lokale Adresse.

dns.getServers()

Hinzugefügt in: v0.11.3

• Rückgabe: <string[]>

Gibt ein Array von IP-Adressstrings zurück, die gemäß RFC 5952 formatiert sind und derzeit für die DNS-Auflösung konfiguriert sind. Ein String enthält einen Portabschnitt, wenn ein benutzerdefinierter Port verwendet wird.

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

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

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Die Option verbatim ist jetzt zugunsten der neuen Option order veraltet.
v18.4.0	Für die Kompatibilität mit node:net kann die Option family bei Übergabe eines Options-Objekts der String 'IPv4' oder der String 'IPv6' sein.
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das Argument callback wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v17.0.0	Die verbatim-Optionen sind jetzt standardmäßig true.
v8.5.0	Die Option verbatim wird jetzt unterstützt.
v1.2.0	Die Option all wird jetzt unterstützt.
v0.1.90	Hinzugefügt in: v0.1.90

• hostname <string>

• options <integer> | <Object>

  • family <integer> | <string> Die Datensatzfamilie. Muss 4, 6 oder 0 sein. Aus Gründen der Abwärtskompatibilität werden 'IPv4' und 'IPv6' als 4 bzw. 6 interpretiert. Der Wert 0 gibt an, dass entweder eine IPv4- oder eine IPv6-Adresse zurückgegeben wird. Wenn der Wert 0 mit { all: true } (siehe unten) verwendet wird, werden entweder eine oder beide IPv4- und IPv6-Adressen zurückgegeben, abhängig vom DNS-Resolver des Systems. Standard: 0.
  • hints <number> Eine oder mehrere unterstützte getaddrinfo-Flags. Mehrere Flags können durch bitweises OR ihrer Werte übergeben werden.
  • all <boolean> Wenn true, gibt der Rückruf alle aufgelösten Adressen in einem Array zurück. Andernfalls wird eine einzelne Adresse zurückgegeben. Standard: false.
  • order <string> Wenn verbatim, werden die aufgelösten Adressen unsortiert zurückgegeben. Wenn ipv4first, werden die aufgelösten Adressen sortiert, indem IPv4-Adressen vor IPv6-Adressen platziert werden. Wenn ipv6first, werden die aufgelösten Adressen sortiert, indem IPv6-Adressen vor IPv4-Adressen platziert werden. Standard: verbatim (Adressen werden nicht neu geordnet). Der Standardwert kann mit dns.setDefaultResultOrder() oder --dns-result-order konfiguriert werden.
  • verbatim <boolean> Wenn true, empfängt der Rückruf IPv4- und IPv6-Adressen in der Reihenfolge, in der der DNS-Resolver sie zurückgegeben hat. Wenn false, werden IPv4-Adressen vor IPv6-Adressen platziert. Diese Option wird zugunsten von order veraltet sein. Wenn beides angegeben wird, hat order eine höhere Priorität. Neuer Code sollte nur order verwenden. Standard: true (Adressen werden nicht neu geordnet). Der Standardwert kann mit dns.setDefaultResultOrder() oder --dns-result-order konfiguriert werden.

• callback <Function>

  • err <Error>
  • address <string> Eine String-Darstellung einer IPv4- oder IPv6-Adresse.
  • family <integer> 4 oder 6, was die Familie von address bezeichnet, oder 0, wenn die Adresse keine IPv4- oder IPv6-Adresse ist. 0 ist ein wahrscheinlicher Indikator für einen Fehler im Namensauflösungsdienst, der vom Betriebssystem verwendet wird.

Löst einen Hostnamen (z. B. 'nodejs.org') in den ersten gefundenen A- (IPv4) oder AAAA-Eintrag (IPv6) auf. Alle option-Eigenschaften sind optional. Wenn options eine ganze Zahl ist, muss sie 4 oder 6 sein – wenn options nicht angegeben wird, werden entweder IPv4- oder IPv6-Adressen oder beide zurückgegeben, falls gefunden.

Wenn die Option all auf true gesetzt ist, ändern sich die Argumente für callback in (err, addresses), wobei addresses ein Array von Objekten mit den Eigenschaften address und family ist.

Im Fehlerfall ist err ein Error-Objekt, wobei err.code der Fehlercode ist. Beachten Sie, dass err.code nicht nur dann auf 'ENOTFOUND' gesetzt wird, wenn der Hostname nicht existiert, sondern auch, wenn die Suche auf andere Weise fehlschlägt, z. B. wenn keine verfügbaren Dateideskriptoren vorhanden sind.

dns.lookup() hat nicht unbedingt etwas mit dem DNS-Protokoll zu tun. Die Implementierung verwendet eine Betriebssystemfunktion, die Namen mit Adressen verknüpfen kann und umgekehrt. Diese Implementierung kann subtile, aber wichtige Konsequenzen für das Verhalten eines beliebigen Node.js-Programms haben. Bitte nehmen Sie sich etwas Zeit, um den Abschnitt Implementierungshinweise zu konsultieren, bevor Sie dns.lookup() verwenden.

Beispielhafte Nutzung:

ESM

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

// Wenn options.all true ist, ist das Ergebnis ein 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}]

CJS

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

// Wenn options.all true ist, ist das Ergebnis ein 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}]

Wenn diese Methode als ihre util.promisify()ed-Version aufgerufen wird und all nicht auf true gesetzt ist, gibt sie ein Promise für ein Object mit den Eigenschaften address und family zurück.

Unterstützte getaddrinfo-Flags

[Verlauf]

Version	Änderungen
v13.13.0, v12.17.0	Unterstützung für das dns.ALL-Flag hinzugefügt.

Die folgenden Flags können als Hinweise an dns.lookup() übergeben werden.

• dns.ADDRCONFIG: Beschränkt die zurückgegebenen Adresstypen auf die Typen von Nicht-Loopback-Adressen, die auf dem System konfiguriert sind. Beispielsweise werden IPv4-Adressen nur zurückgegeben, wenn das aktuelle System mindestens eine IPv4-Adresse konfiguriert hat.
• dns.V4MAPPED: Wenn die IPv6-Familie angegeben wurde, aber keine IPv6-Adressen gefunden wurden, werden IPv4-zugeordnete IPv6-Adressen zurückgegeben. Es wird auf einigen Betriebssystemen nicht unterstützt (z. B. FreeBSD 10.1).
• dns.ALL: Wenn dns.V4MAPPED angegeben ist, werden sowohl aufgelöste IPv6-Adressen als auch IPv4-zugeordnete IPv6-Adressen zurückgegeben.

dns.lookupService(address, port, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.11.14	Hinzugefügt in: v0.11.14

• address <string>
• port <number>
• callback <Function>
  • err <Error>
  • hostname <string> z.B. example.com
  • service <string> z.B. http

Löst die angegebene address und den port in einen Hostnamen und einen Dienst auf, indem die zugrunde liegende getnameinfo-Implementierung des Betriebssystems verwendet wird.

Wenn address keine gültige IP-Adresse ist, wird ein TypeError ausgelöst. Der port wird zu einer Zahl konvertiert. Wenn es sich nicht um einen zulässigen Port handelt, wird ein TypeError ausgelöst.

Bei einem Fehler ist err ein Error-Objekt, wobei err.code der Fehlercode ist.

ESM

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

CJS

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

Wenn diese Methode als ihre util.promisify()-Version aufgerufen wird, gibt sie eine Promise für ein Object mit den Eigenschaften hostname und service zurück.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.1.27	Hinzugefügt in: v0.1.27

• hostname <string> Hostname, der aufgelöst werden soll.
• rrtype <string> Ressourceneintragstyp. Standard: 'A'.
• callback <Function>
  • err <Error>
  • records <string[]> | <Object[]> | <Object>

Verwendet das DNS-Protokoll, um einen Hostnamen (z. B. 'nodejs.org') in ein Array von Ressourceneinträgen aufzulösen. Die callback-Funktion hat die Argumente (err, records). Wenn erfolgreich, ist records ein Array von Ressourceneinträgen. Der Typ und die Struktur der einzelnen Ergebnisse variieren je nach rrtype:

rrtype	records enthält	Ergebnistyp	Kurzmethode
'A'	IPv4-Adressen (Standard)	<string>	dns.resolve4()
'AAAA'	IPv6-Adressen	<string>	dns.resolve6()
'ANY'	beliebige Einträge	<Object>	dns.resolveAny()
'CAA'	CA-Autorisierungseinträge	<Object>	dns.resolveCaa()
'CNAME'	kanonische Namenseinträge	<string>	dns.resolveCname()
'MX'	Mail Exchange-Einträge	<Object>	dns.resolveMx()
'NAPTR'	Name Authority Pointer-Einträge	<Object>	dns.resolveNaptr()
'NS'	Nameserver-Einträge	<string>	dns.resolveNs()
'PTR'	Pointer-Einträge	<string>	dns.resolvePtr()
'SOA'	Start of Authority-Einträge	<Object>	dns.resolveSoa()
'SRV'	Service-Einträge	<Object>	dns.resolveSrv()
'TXT'	Text-Einträge	<string[]>	dns.resolveTxt()

Bei einem Fehler ist err ein Error-Objekt, wobei err.code einer der DNS-Fehlercodes ist.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v7.2.0	Diese Methode unterstützt jetzt das Übergeben von options, insbesondere options.ttl.
v0.1.16	Hinzugefügt in: v0.1.16

• hostname <string> Hostname, der aufgelöst werden soll.

• options <Object>

  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Eintrags ab. Wenn true, empfängt der Callback ein Array von { address: '1.2.3.4', ttl: 60 }-Objekten anstelle eines Arrays von Strings, wobei die TTL in Sekunden ausgedrückt wird.

• callback <Function>

  • err <Error>
  • addresses <string[]> | <Object[]>

Verwendet das DNS-Protokoll, um IPv4-Adressen (A-Einträge) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von IPv4-Adressen (z. B. ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v7.2.0	Diese Methode unterstützt jetzt das Übergeben von options, insbesondere options.ttl.
v0.1.16	Hinzugefügt in: v0.1.16

• hostname <string> Hostname, der aufgelöst werden soll.

• options <Object>

  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Eintrags ab. Wenn true, empfängt der Callback ein Array von { address: '0:1:2:3:4:5:6:7', ttl: 60 }-Objekten anstelle eines Arrays von Strings, wobei die TTL in Sekunden ausgedrückt wird.

• callback <Function>

  • err <Error>
  • addresses <string[]> | <Object[]>

Verwendet das DNS-Protokoll, um IPv6-Adressen (AAAA-Einträge) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von IPv6-Adressen.

dns.resolveAny(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.

• hostname <string>
• callback <Funktion>
  • err <Error>
  • ret <Objekt[]>

Verwendet das DNS-Protokoll, um alle Records aufzulösen (auch bekannt als ANY- oder *-Abfrage). Das an die callback-Funktion übergebene ret-Argument ist ein Array, das verschiedene Arten von Records enthält. Jedes Objekt hat eine Eigenschaft type, die den Typ des aktuellen Records angibt. Und abhängig vom type sind zusätzliche Eigenschaften im Objekt vorhanden:

Typ	Eigenschaften
'A'	address / ttl
'AAAA'	address / ttl
'CNAME'	value
'MX'	Siehe dns.resolveMx()
'NAPTR'	Siehe dns.resolveNaptr()
'NS'	value
'PTR'	value
'SOA'	Siehe dns.resolveSoa()
'SRV'	Siehe dns.resolveSrv()
'TXT'	Dieser Record-Typ enthält eine Array-Eigenschaft namens entries, die auf dns.resolveTxt() verweist, z. B. { entries: ['...'], type: 'TXT' }

Hier ist ein Beispiel für das an den Callback übergebene ret-Objekt:

[ { 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-Serverbetreiber können wählen, nicht auf ANY-Abfragen zu antworten. Es ist möglicherweise besser, einzelne Methoden wie dns.resolve4(), dns.resolveMx() usw. aufzurufen. Weitere Informationen finden Sie unter RFC 8482.

dns.resolveCname(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.3.2	Hinzugefügt in: v0.3.2

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Verwendet das DNS-Protokoll, um CNAME-Einträge für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von Canonical Name Records, die für den hostname verfügbar sind (z. B. ['bar.example.com']).

dns.resolveCaa(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v15.0.0, v14.17.0	Hinzugefügt in: v15.0.0, v14.17.0

• hostname <string>
• callback <Function>
  • err <Error>
  • records <Object[]>

Verwendet das DNS-Protokoll, um CAA-Einträge für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von Certification Authority Authorization Records, die für den hostname verfügbar sind (z. B. [{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]).

dns.resolveMx(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.1.27	Hinzugefügt in: v0.1.27

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Verwendet das DNS-Protokoll, um Mail Exchange Records (MX Records) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von Objekten, die sowohl eine priority- als auch eine exchange-Eigenschaft enthalten (z. B. [{priority: 10, exchange: 'mx.example.com'}, ...]).

dns.resolveNaptr(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.9.12	Hinzugefügt in: v0.9.12

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Verwendet das DNS-Protokoll, um reguläre Ausdrucks-basierte Records (NAPTR Records) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von Objekten mit den folgenden Eigenschaften:

• flags
• service
• regexp
• replacement
• order
• preference

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

dns.resolveNs(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.1.90	Hinzugefügt in: v0.1.90

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Verwendet das DNS-Protokoll, um Nameserver-Einträge (NS-Einträge) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument enthält ein Array von Nameserver-Einträgen, die für hostname verfügbar sind (z. B. ['ns1.example.com', 'ns2.example.com']).

dns.resolvePtr(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v6.0.0	Hinzugefügt in: v6.0.0

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Verwendet das DNS-Protokoll, um Pointer-Einträge (PTR-Einträge) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument ist ein Array von Strings, das die Antwort-Einträge enthält.

dns.resolveSoa(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.11.10	Hinzugefügt in: v0.11.10

• hostname <string>
• callback <Function>
  • err <Error>
  • address <Object>

Verwendet das DNS-Protokoll, um einen Start-of-Authority-Eintrag (SOA-Eintrag) für den hostname aufzulösen. Das an die callback-Funktion übergebene address-Argument ist ein Objekt mit den folgenden Eigenschaften:

• 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
}

dns.resolveSrv(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.1.27	Hinzugefügt in: v0.1.27

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Verwendet das DNS-Protokoll, um Service Records (SRV Records) für den hostname aufzulösen. Das an die callback-Funktion übergebene addresses-Argument ist ein Array von Objekten mit den folgenden Eigenschaften:

• priority
• weight
• port
• name

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

dns.resolveTxt(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.1.27	Hinzugefügt in: v0.1.27

• hostname <string>
• callback <Function>
  • err <Error>
  • records <string[][]>

Verwendet das DNS-Protokoll, um Textabfragen (TXT Records) für den hostname aufzulösen. Das an die callback-Funktion übergebene records-Argument ist ein zweidimensionales Array der für hostname verfügbaren Textrecords (z. B. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Jedes Sub-Array enthält TXT-Chunks eines Records. Je nach Anwendungsfall können diese entweder zusammengeführt oder separat behandelt werden.

dns.reverse(ip, callback)

Hinzugefügt in: v0.1.16

• ip <string>
• callback <Function>
  • err <Error>
  • hostnames <string[]>

Führt eine Reverse-DNS-Abfrage durch, die eine IPv4- oder IPv6-Adresse in ein Array von Hostnamen auflöst.

Im Fehlerfall ist err ein Error-Objekt, wobei err.code einer der DNS-Fehlercodes ist.

dns.setDefaultResultOrder(order)

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Der Wert ipv6first wird jetzt unterstützt.
v17.0.0	Standardwert auf verbatim geändert.
v16.4.0, v14.18.0	Hinzugefügt in: v16.4.0, v14.18.0

• order <string> muss 'ipv4first', 'ipv6first' oder 'verbatim' sein.

Legt den Standardwert von order in dns.lookup() und dnsPromises.lookup() fest. Der Wert kann sein:

• ipv4first: setzt den Standardwert von order auf ipv4first.
• ipv6first: setzt den Standardwert von order auf ipv6first.
• verbatim: setzt den Standardwert von order auf verbatim.

Der Standardwert ist verbatim und dns.setDefaultResultOrder() hat eine höhere Priorität als --dns-result-order. Bei Verwendung von Worker-Threads wirkt sich dns.setDefaultResultOrder() aus dem Haupt-Thread nicht auf die Standard-DNS-Reihenfolge in Workern aus.

dns.getDefaultResultOrder()

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Der Wert ipv6first wird jetzt unterstützt.
v20.1.0, v18.17.0	Hinzugefügt in: v20.1.0, v18.17.0

Ruft den Standardwert für order in dns.lookup() und dnsPromises.lookup() ab. Der Wert kann sein:

• ipv4first: für order, das standardmäßig auf ipv4first gesetzt ist.
• ipv6first: für order, das standardmäßig auf ipv6first gesetzt ist.
• verbatim: für order, das standardmäßig auf verbatim gesetzt ist.

dns.setServers(servers)

Hinzugefügt in: v0.11.3

• servers <string[]> Array von RFC 5952 formatierten Adressen

Setzt die IP-Adresse und den Port der Server, die bei der DNS-Auflösung verwendet werden sollen. Das servers-Argument ist ein Array von RFC 5952 formatierten Adressen. Wenn der Port der IANA-Standard-DNS-Port (53) ist, kann er weggelassen werden.

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

Es wird ein Fehler ausgelöst, wenn eine ungültige Adresse angegeben wird.

Die Methode dns.setServers() darf nicht aufgerufen werden, während eine DNS-Abfrage läuft.

Die Methode dns.setServers() wirkt sich nur auf dns.resolve(), dns.resolve*() und dns.reverse() aus (und insbesondere nicht auf dns.lookup()).

Diese Methode funktioniert ähnlich wie resolve.conf. Das heißt, wenn der Versuch der Auflösung mit dem ersten angegebenen Server zu einem NOTFOUND-Fehler führt, wird die Methode resolve() nicht versuchen, mit nachfolgenden angegebenen Servern aufzulösen. Fallback-DNS-Server werden nur verwendet, wenn bei den früheren Servern ein Timeout auftritt oder ein anderer Fehler auftritt.

DNS Promises API

[Verlauf]

Version	Änderungen
v15.0.0	Als require('dns/promises') verfügbar gemacht.
v11.14.0, v10.17.0	Diese API ist nicht mehr experimentell.
v10.6.0	Hinzugefügt in: v10.6.0

Die dns.promises-API bietet einen alternativen Satz asynchroner DNS-Methoden, die Promise-Objekte anstelle von Callbacks zurückgeben. Die API ist über require('node:dns').promises oder require('node:dns/promises') zugänglich.

Klasse: dnsPromises.Resolver

Hinzugefügt in: v10.6.0

Ein unabhängiger Resolver für DNS-Anfragen.

Das Erstellen eines neuen Resolvers verwendet die Standardservereinstellungen. Das Festlegen der für einen Resolver verwendeten Server mit resolver.setServers() wirkt sich nicht auf andere Resolver aus:

ESM

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

// Diese Anfrage verwendet den Server unter 4.4.4.4, unabhängig von globalen Einstellungen.
const addresses = await resolver.resolve4('example.org');

CJS

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

// Diese Anfrage verwendet den Server unter 4.4.4.4, unabhängig von globalen Einstellungen.
resolver.resolve4('example.org').then((addresses) => {
  // ...
});

// Alternativ kann derselbe Code im Async-Await-Stil geschrieben werden.
(async function() {
  const addresses = await resolver.resolve4('example.org');
})();

Die folgenden Methoden aus der dnsPromises-API sind verfügbar:

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

resolver.cancel()

Hinzugefügt in: v15.3.0, v14.17.0

Bricht alle ausstehenden DNS-Abfragen ab, die von diesem Resolver durchgeführt wurden. Die entsprechenden Promises werden mit einem Fehler mit dem Code ECANCELLED abgelehnt.

dnsPromises.getServers()

Hinzugefügt in: v10.6.0

• Gibt zurück: <string[]>

Gibt ein Array von IP-Adresszeichenketten zurück, das gemäß RFC 5952 formatiert ist und derzeit für die DNS-Auflösung konfiguriert ist. Eine Zeichenkette enthält einen Portabschnitt, wenn ein benutzerdefinierter Port verwendet wird.

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

dnsPromises.lookup(hostname[, options])

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Die Option verbatim ist jetzt zugunsten der neuen Option order veraltet.
v10.6.0	Hinzugefügt in: v10.6.0

• hostname <string>
• options <integer> | <Object>
  • family <integer> Die Record Family. Muss 4, 6 oder 0 sein. Der Wert 0 gibt an, dass entweder eine IPv4- oder eine IPv6-Adresse zurückgegeben wird. Wenn der Wert 0 zusammen mit { all: true } verwendet wird (siehe unten), werden entweder eine oder beide IPv4- und IPv6-Adressen zurückgegeben, abhängig vom DNS-Resolver des Systems. Standard: 0.
  • hints <number> Ein oder mehrere unterstützte getaddrinfo-Flags. Mehrere Flags können durch bitweises OR ihrer Werte übergeben werden.
  • all <boolean> Wenn true, wird die Promise mit allen Adressen in einem Array aufgelöst. Andernfalls wird eine einzelne Adresse zurückgegeben. Standard: false.
  • order <string> Wenn verbatim, wird die Promise mit IPv4- und IPv6-Adressen in der Reihenfolge aufgelöst, in der der DNS-Resolver sie zurückgegeben hat. Wenn ipv4first, werden IPv4-Adressen vor IPv6-Adressen platziert. Wenn ipv6first, werden IPv6-Adressen vor IPv4-Adressen platziert. Standard: verbatim (Adressen werden nicht neu geordnet). Der Standardwert kann mit dns.setDefaultResultOrder() oder --dns-result-order konfiguriert werden. Neuer Code sollte { order: 'verbatim' } verwenden.
  • verbatim <boolean> Wenn true, wird die Promise mit IPv4- und IPv6-Adressen in der Reihenfolge aufgelöst, in der der DNS-Resolver sie zurückgegeben hat. Wenn false, werden IPv4-Adressen vor IPv6-Adressen platziert. Diese Option wird zugunsten von order als veraltet angesehen. Wenn beide angegeben sind, hat order eine höhere Priorität. Neuer Code sollte nur order verwenden. Standard: derzeit false (Adressen werden neu geordnet), aber dies wird sich voraussichtlich in nicht allzu ferner Zukunft ändern. Der Standardwert kann mit dns.setDefaultResultOrder() oder --dns-result-order konfiguriert werden.

Löst einen Hostnamen (z. B. 'nodejs.org') in den ersten gefundenen A (IPv4)- oder AAAA (IPv6)-Record auf. Alle option-Eigenschaften sind optional. Wenn options eine Ganzzahl ist, muss sie 4 oder 6 sein - wenn options nicht angegeben wird, werden entweder IPv4- oder IPv6-Adressen oder beide zurückgegeben, falls gefunden.

Wenn die Option all auf true gesetzt ist, wird die Promise mit addresses als Array von Objekten mit den Eigenschaften address und family aufgelöst.

Im Fehlerfall wird die Promise mit einem Error-Objekt abgelehnt, wobei err.code der Fehlercode ist. Beachten Sie, dass err.code nicht nur auf 'ENOTFOUND' gesetzt wird, wenn der Hostname nicht existiert, sondern auch, wenn die Suche auf andere Weise fehlschlägt, z. B. wenn keine verfügbaren Dateideskriptoren vorhanden sind.

dnsPromises.lookup() hat nicht unbedingt etwas mit dem DNS-Protokoll zu tun. Die Implementierung verwendet eine Betriebssystemfunktion, die Namen Adressen zuordnen kann und umgekehrt. Diese Implementierung kann subtile, aber wichtige Auswirkungen auf das Verhalten eines jeden Node.js-Programms haben. Bitte nehmen Sie sich etwas Zeit, um den Abschnitt Implementierungshinweise zu lesen, bevor Sie dnsPromises.lookup() verwenden.

Beispielhafte Verwendung:

ESM

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
});

// Wenn options.all true ist, ist das Ergebnis ein 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}]
});

CJS

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
});

// Wenn options.all true ist, ist das Ergebnis ein 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)

Hinzugefügt in: v10.6.0

• address <string>
• port <number>

Löst die angegebene address und port in einen Hostnamen und Dienst auf, indem die zugrunde liegende getnameinfo-Implementierung des Betriebssystems verwendet wird.

Wenn address keine gültige IP-Adresse ist, wird ein TypeError ausgelöst. Der port wird in eine Zahl umgewandelt. Wenn es sich nicht um einen zulässigen Port handelt, wird ein TypeError ausgelöst.

Im Fehlerfall wird das Promise mit einem Error-Objekt verworfen, wobei err.code der Fehlercode ist.

ESM

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

console.log(result.hostname, result.service); // Gibt aus: localhost ssh

CJS

const dnsPromises = require('node:dns').promises;
dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
  console.log(result.hostname, result.service);
  // Gibt aus: localhost ssh
});

dnsPromises.resolve(hostname[, rrtype])

Hinzugefügt in: v10.6.0

• hostname <string> Hostname, der aufgelöst werden soll.
• rrtype <string> Resource Record Type. Standard: 'A'.

Verwendet das DNS-Protokoll, um einen Hostnamen (z. B. 'nodejs.org') in ein Array von Resource Records aufzulösen. Wenn erfolgreich, wird das Promise mit einem Array von Resource Records aufgelöst. Der Typ und die Struktur der einzelnen Ergebnisse variieren je nach rrtype:

rrtype	records enthält	Ergebnistyp	Kurzmethode
'A'	IPv4-Adressen (Standard)	<string>	dnsPromises.resolve4()
'AAAA'	IPv6-Adressen	<string>	dnsPromises.resolve6()
'ANY'	beliebige Records	<Object>	dnsPromises.resolveAny()
'CAA'	CA-Autorisierungs-Records	<Object>	dnsPromises.resolveCaa()
'CNAME'	Canonical Name Records	<string>	dnsPromises.resolveCname()
'MX'	Mail Exchange Records	<Object>	dnsPromises.resolveMx()
'NAPTR'	Name Authority Pointer Records	<Object>	dnsPromises.resolveNaptr()
'NS'	Name Server Records	<string>	dnsPromises.resolveNs()
'PTR'	Pointer Records	<string>	dnsPromises.resolvePtr()
'SOA'	Start of Authority Records	<Object>	dnsPromises.resolveSoa()
'SRV'	Service Records	<Object>	dnsPromises.resolveSrv()
'TXT'	Text Records	<string[]>	dnsPromises.resolveTxt()
Im Fehlerfall wird das Promise mit einem Error-Objekt verworfen, wobei err.code einer der DNS-Fehlercodes ist.

dnsPromises.resolve4(hostname[, options])

Hinzugefügt in: v10.6.0

• hostname <string> Hostname, das aufgelöst werden soll.
• options <Object>
  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Eintrags ab. Wenn true, wird das Promise mit einem Array von { address: '1.2.3.4', ttl: 60 }-Objekten anstelle eines Arrays von Strings aufgelöst, wobei die TTL in Sekunden angegeben wird.

Verwendet das DNS-Protokoll, um IPv4-Adressen (A-Einträge) für den hostname aufzulösen. Bei Erfolg wird das Promise mit einem Array von IPv4-Adressen aufgelöst (z. B. ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dnsPromises.resolve6(hostname[, options])

Hinzugefügt in: v10.6.0

• hostname <string> Hostname, das aufgelöst werden soll.
• options <Object>
  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Eintrags ab. Wenn true, wird das Promise mit einem Array von { address: '0:1:2:3:4:5:6:7', ttl: 60 }-Objekten anstelle eines Arrays von Strings aufgelöst, wobei die TTL in Sekunden angegeben wird.

Verwendet das DNS-Protokoll, um IPv6-Adressen (AAAA-Einträge) für den hostname aufzulösen. Bei Erfolg wird das Promise mit einem Array von IPv6-Adressen aufgelöst.

dnsPromises.resolveAny(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um alle Einträge aufzulösen (auch bekannt als ANY- oder *-Abfrage). Bei Erfolg wird das Promise mit einem Array aufgelöst, das verschiedene Arten von Einträgen enthält. Jedes Objekt hat eine Eigenschaft type, die den Typ des aktuellen Eintrags angibt. Und abhängig vom type sind zusätzliche Eigenschaften im Objekt vorhanden:

Typ	Eigenschaften
'A'	address / ttl
'AAAA'	address / ttl
'CNAME'	value
'MX'	Siehe dnsPromises.resolveMx()
'NAPTR'	Siehe dnsPromises.resolveNaptr()
'NS'	value
'PTR'	value
'SOA'	Siehe dnsPromises.resolveSoa()
'SRV'	Siehe dnsPromises.resolveSrv()
'TXT'	Dieser Eintragstyp enthält eine Array-Eigenschaft namens entries, die auf dnsPromises.resolveTxt() verweist, z. B. { entries: ['...'], type: 'TXT' }

Hier ist ein Beispiel für das Ergebnisobjekt:

[ { 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)

Hinzugefügt in: v15.0.0, v14.17.0

• hostname <string>

Verwendet das DNS-Protokoll, um CAA-Einträge für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Objekten aufgelöst, die verfügbare Zertifizierungsstellen-Autorisierungseinträge für den hostname enthalten (z. B. [{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]).

dnsPromises.resolveCname(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um CNAME-Einträge für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von kanonischen Namenseinträgen aufgelöst, die für den hostname verfügbar sind (z. B. ['bar.example.com']).

dnsPromises.resolveMx(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um Mail Exchange Records (MX-Einträge) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Objekten aufgelöst, die sowohl eine priority- als auch eine exchange-Eigenschaft enthalten (z. B. [{priority: 10, exchange: 'mx.example.com'}, ...]).

dnsPromises.resolveNaptr(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um reguläre Ausdrucks-basierte Einträge (NAPTR-Einträge) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Objekten mit den folgenden Eigenschaften aufgelöst:

• flags
• service
• regexp
• replacement
• order
• preference

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

dnsPromises.resolveNs(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um Nameserver-Einträge (NS-Einträge) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Nameserver-Einträgen aufgelöst, die für hostname verfügbar sind (z. B. ['ns1.example.com', 'ns2.example.com']).

dnsPromises.resolvePtr(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um Zeigerdatensätze (PTR-Datensätze) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Zeichenketten aufgelöst, das die Antwortdatensätze enthält.

dnsPromises.resolveSoa(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um einen Start of Authority-Datensatz (SOA-Datensatz) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Objekt mit den folgenden Eigenschaften aufgelöst:

• 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
}

dnsPromises.resolveSrv(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um Service-Datensätze (SRV-Datensätze) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem Array von Objekten mit den folgenden Eigenschaften aufgelöst:

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

Verwendet das DNS-Protokoll, um Textabfragen (TXT-Datensätze) für den hostname aufzulösen. Bei Erfolg wird die Promise mit einem zweidimensionalen Array der für hostname verfügbaren Textdatensätze aufgelöst (z. B. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Jedes Sub-Array enthält TXT-Blöcke eines Datensatzes. Je nach Anwendungsfall können diese entweder zusammengefügt oder separat behandelt werden.

dnsPromises.reverse(ip)

Hinzugefügt in: v10.6.0

• ip <string>

Führt eine Reverse-DNS-Abfrage durch, die eine IPv4- oder IPv6-Adresse in ein Array von Hostnamen auflöst.

Bei einem Fehler wird das Promise mit einem Error-Objekt abgelehnt, wobei err.code einer der DNS-Fehlercodes ist.

dnsPromises.setDefaultResultOrder(order)

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Der Wert ipv6first wird jetzt unterstützt.
v17.0.0	Standardwert auf verbatim geändert.
v16.4.0, v14.18.0	Hinzugefügt in: v16.4.0, v14.18.0

• order <string> muss 'ipv4first', 'ipv6first' oder 'verbatim' sein.

Legt den Standardwert von order in dns.lookup() und dnsPromises.lookup() fest. Der Wert kann sein:

• ipv4first: setzt order standardmäßig auf ipv4first.
• ipv6first: setzt order standardmäßig auf ipv6first.
• verbatim: setzt order standardmäßig auf verbatim.

Der Standardwert ist verbatim und dnsPromises.setDefaultResultOrder() hat eine höhere Priorität als --dns-result-order. Bei Verwendung von Worker-Threads hat dnsPromises.setDefaultResultOrder() aus dem Haupt-Thread keine Auswirkungen auf die standardmäßigen DNS-Reihenfolgen in Worker-Threads.

dnsPromises.getDefaultResultOrder()

Hinzugefügt in: v20.1.0, v18.17.0

Ruft den Wert von dnsOrder ab.

dnsPromises.setServers(servers)

Hinzugefügt in: v10.6.0

• servers <string[]> Array von RFC 5952 formatierten Adressen

Legt die IP-Adresse und den Port der Server fest, die bei der DNS-Auflösung verwendet werden sollen. Das Argument servers ist ein Array von RFC 5952 formatierten Adressen. Wenn der Port der IANA-Standard-DNS-Port (53) ist, kann er weggelassen werden.

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

Es wird ein Fehler ausgegeben, wenn eine ungültige Adresse angegeben wird.

Die Methode dnsPromises.setServers() darf nicht aufgerufen werden, während eine DNS-Abfrage läuft.

Diese Methode funktioniert ähnlich wie resolve.conf. Das heißt, wenn der Versuch, mit dem ersten angegebenen Server aufzulösen, zu einem NOTFOUND-Fehler führt, wird die Methode resolve() nicht versuchen, mit nachfolgenden angegebenen Servern aufzulösen. Fallback-DNS-Server werden nur verwendet, wenn bei den früheren Servern ein Timeout auftritt oder ein anderer Fehler auftritt.

Fehlercodes

Jede DNS-Abfrage kann einen der folgenden Fehlercodes zurückgeben:

• dns.NODATA: Der DNS-Server hat eine Antwort ohne Daten zurückgegeben.
• dns.FORMERR: Der DNS-Server behauptet, dass die Abfrage falsch formatiert war.
• dns.SERVFAIL: Der DNS-Server hat einen allgemeinen Fehler zurückgegeben.
• dns.NOTFOUND: Der Domänenname wurde nicht gefunden.
• dns.NOTIMP: Der DNS-Server implementiert die angeforderte Operation nicht.
• dns.REFUSED: Der DNS-Server hat die Abfrage abgelehnt.
• dns.BADQUERY: Falsch formatierte DNS-Abfrage.
• dns.BADNAME: Falsch formatierter Hostname.
• dns.BADFAMILY: Nicht unterstützte Adressfamilie.
• dns.BADRESP: Falsch formatierte DNS-Antwort.
• dns.CONNREFUSED: Es konnte keine Verbindung zu den DNS-Servern hergestellt werden.
• dns.TIMEOUT: Zeitüberschreitung beim Kontaktieren der DNS-Server.
• dns.EOF: Dateiende.
• dns.FILE: Fehler beim Lesen der Datei.
• dns.NOMEM: Nicht genügend Speicher.
• dns.DESTRUCTION: Der Kanal wird zerstört.
• dns.BADSTR: Falsch formatierte Zeichenkette.
• dns.BADFLAGS: Illegale Flags angegeben.
• dns.NONAME: Angegebener Hostname ist nicht numerisch.
• dns.BADHINTS: Illegale Hinweisfelder angegeben.
• dns.NOTINITIALIZED: Die Initialisierung der c-ares-Bibliothek wurde noch nicht durchgeführt.
• dns.LOADIPHLPAPI: Fehler beim Laden von iphlpapi.dll.
• dns.ADDRGETNETWORKPARAMS: Die Funktion GetNetworkParams konnte nicht gefunden werden.
• dns.CANCELLED: DNS-Abfrage abgebrochen.

Die dnsPromises-API exportiert auch die oben genannten Fehlercodes, z. B. dnsPromises.NODATA.

Implementierungsüberlegungen

Obwohl dns.lookup() und die verschiedenen dns.resolve*()/dns.reverse()-Funktionen das gleiche Ziel haben, einen Netzwerk-Namen mit einer Netzwerkadresse zu verknüpfen (oder umgekehrt), ist ihr Verhalten sehr unterschiedlich. Diese Unterschiede können subtile, aber signifikante Auswirkungen auf das Verhalten von Node.js-Programmen haben.

dns.lookup()

Unter der Haube verwendet dns.lookup() die gleichen Betriebssystemeinrichtungen wie die meisten anderen Programme. Zum Beispiel wird dns.lookup() einen gegebenen Namen fast immer auf die gleiche Weise auflösen wie der ping-Befehl. Auf den meisten POSIX-ähnlichen Betriebssystemen kann das Verhalten der Funktion dns.lookup() durch Ändern der Einstellungen in nsswitch.conf(5) und/oder resolv.conf(5) geändert werden, aber das Ändern dieser Dateien wird das Verhalten aller anderen Programme ändern, die auf dem gleichen Betriebssystem laufen.

Obwohl der Aufruf von dns.lookup() aus der JavaScript-Perspektive asynchron ist, wird er als synchroner Aufruf von getaddrinfo(3) implementiert, der im Threadpool von libuv ausgeführt wird. Dies kann überraschende negative Auswirkungen auf die Leistung einiger Anwendungen haben, siehe die Dokumentation UV_THREADPOOL_SIZE für weitere Informationen.

Verschiedene Netzwerk-APIs rufen dns.lookup() intern auf, um Hostnamen aufzulösen. Wenn das ein Problem darstellt, sollten Sie den Hostnamen mit dns.resolve() in eine Adresse auflösen und die Adresse anstelle eines Hostnamens verwenden. Einige Netzwerk-APIs (wie socket.connect() und dgram.createSocket()) erlauben auch, den Standard-Resolver, dns.lookup(), zu ersetzen.

dns.resolve(), dns.resolve*() 和 dns.reverse()

Diese Funktionen sind ganz anders implementiert als dns.lookup(). Sie verwenden nicht getaddrinfo(3) und führen immer eine DNS-Abfrage im Netzwerk durch. Diese Netzwerkkommunikation erfolgt immer asynchron und verwendet nicht den Threadpool von libuv.

Daher können diese Funktionen nicht die gleichen negativen Auswirkungen auf andere Verarbeitungsprozesse haben, die im Threadpool von libuv stattfinden, wie dns.lookup().

Sie verwenden nicht die gleichen Konfigurationsdateien wie dns.lookup(). Zum Beispiel verwenden sie nicht die Konfiguration aus /etc/hosts.