DNS

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/dns.js

Das Modul node:dns ermöglicht die Namensauflösung. Es kann beispielsweise verwendet werden, 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 Nachschlagevorgänge. dns.lookup() nutzt die Funktionen des Betriebssystems zur Durchführung der Namensauflösung. Eine Netzwerkkommunikation ist möglicherweise nicht erforderlich. 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ösungsfunktionen 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 Implementierungsaspekte.

Klasse: dns.Resolver

Hinzugefügt in: v8.3.0

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

Ein neuer Resolver wird mit den Standardeinstellungen des Servers erstellt. Das Festlegen der für einen Resolver verwendeten Server mithilfe von resolver.setServers() wirkt sich nicht auf andere Resolver aus:

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])

[History]

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 einzige unterstützte Option ist timeout.
v8.3.0	Hinzugefügt in: v8.3.0

Einen neuen Resolver erstellen.

• 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 unternimmt, 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 durchgeführt werden. 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 Zeichenketten-Darstellung einer IPv4-Adresse. Standard: '0.0.0.0'
• ipv6 <string> Eine Zeichenketten-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 eine v4- oder v6-Adresse nicht angegeben ist, wird sie auf den Standardwert gesetzt und das Betriebssystem wählt automatisch eine lokale Adresse aus.

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

dns.getServers()

Hinzugefügt in: v0.11.3

• Rückgabewert: <string[]>

Gibt ein Array von IP-Adresszeichenketten zurück, die gemäß RFC 5952 formatiert sind und derzeit für die DNS-Auflösung konfiguriert sind. Eine Zeichenkette enthält einen Port-Abschnitt, 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, wenn ein Options-Objekt übergeben wird, die Zeichenkette 'IPv4' oder die Zeichenkette 'IPv6' sein.
v18.0.0	Das Übergeben eines ungültigen Rückrufs an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v17.0.0	Die Option verbatim hat jetzt den Standardwert 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 Record-Familie. 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> Ein oder mehrere unterstützte getaddrinfo-Flags. Mehrere Flags können durch bitweises ODER 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, erhält 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 beide angegeben sind, hat order 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 Zeichenketten-Darstellung einer IPv4- oder IPv6-Adresse.
  • family <integer> 4 oder 6, die die Familie von address angeben, oder 0, wenn die Adresse keine IPv4- oder IPv6-Adresse ist. 0 ist ein wahrscheinlicher Hinweis auf 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- (IPv6) Eintrag auf. Alle Eigenschaften von option sind optional. Wenn options eine ganze Zahl ist, muss diese 4 oder 6 sein – wenn options nicht angegeben ist, werden entweder IPv4- oder IPv6-Adressen oder beide zurückgegeben, wenn gefunden.

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

Bei einem Fehler 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 Dateideskriptoren verfügbar sind.

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

Beispielhafte Verwendung:

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()-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 Flag dns.ALL hinzugefügt.

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

• dns.ADDRCONFIG: Schränkt die zurückgegebenen Adresstypen auf die Typen von Nicht-Loopback-Adressen ein, die auf dem System konfiguriert sind. Beispielsweise werden IPv4-Adressen nur zurückgegeben, wenn das aktuelle System mindestens eine konfigurierte IPv4-Adresse besitzt.
• dns.V4MAPPED: Wenn die IPv6-Familie angegeben wurde, aber keine IPv6-Adressen gefunden wurden, dann werden IPv4-zugeordnete IPv6-Adressen zurückgegeben. Dies wird auf einigen Betriebssystemen (z. B. FreeBSD 10.1) nicht unterstützt.
• 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 löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 port in einen Hostnamen und einen Dienst unter Verwendung der zugrunde liegenden getnameinfo-Implementierung des Betriebssystems auf.

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.

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 ein Promise für ein Object mit den Eigenschaften hostname und service zurück.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v0.1.27	Hinzugefügt in: v0.1.27

• hostname <string> Zu lösender Hostname.
• 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 der Ressourceneinträge aufzulösen. Die callback-Funktion hat die Argumente (err, records). Bei Erfolg 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'	Texteintrag	<string[]>	dns.resolveTxt()

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

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

[History]

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> Zu lösender Hostname.

• options <Object>

  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Datensatzes ab. Wenn true, erhält der Callback ein Array von { address: '1.2.3.4', ttl: 60 } Objekten anstatt eines Arrays von Strings, wobei die TTL in Sekunden angegeben ist.

• callback <Function>

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

Verwendet das DNS-Protokoll, um IPv4-Adressen (A-Records) 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)

[History]

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> Zu lösender Hostname.

• options <Object>

  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Datensatzes ab. Wenn true, erhält der Callback ein Array von { address: '0:1:2:3:4:5:6:7', ttl: 60 } Objekten anstatt eines Arrays von Strings, wobei die TTL in Sekunden angegeben ist.

• callback <Function>

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

Verwendet das DNS-Protokoll, um IPv6-Adressen (AAAA-Records) 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 löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.

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

Verwendet das DNS-Protokoll, um alle Einträge (auch bekannt als ANY oder *-Abfrage) aufzulösen. Das an die callback-Funktion übergebene ret-Argument ist ein Array, das verschiedene Arten von Einträgen enthält. Jedes Objekt hat eine Eigenschaft type, die den Typ des aktuellen Eintrags angibt. 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 Eintragstyp 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 sich dafür entscheiden, nicht auf ANY-Abfragen zu antworten. Es kann besser sein, einzelne Methoden wie dns.resolve4(), dns.resolveMx() usw. aufzurufen. Weitere Informationen finden Sie in RFC 8482.

dns.resolveCname(hostname, callback)

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben einer ungültigen Callback-Funktion an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 kanonischen Namensaufzeichnungen, 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 einer ungültigen Callback-Funktion an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 Zertifizierungsstellen-Autorisierungsaufzeichnungen, 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)

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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)

[History]

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

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

Verwendet das DNS-Protokoll, um reguläre Ausdrucksbasierte 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)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 Argument addresses 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)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 Argument addresses ist ein Array von Strings, die die Antwortdatensätze enthalten.

dns.resolveSoa(hostname, callback)

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument callback löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
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 Argument address 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)

[History]

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

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

Verwendet das DNS-Protokoll, um Servicerecords (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)

[History]

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

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

Verwendet das DNS-Protokoll, um Text-Abfragen (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 Text-Records (z. B. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Jedes Unterarray enthält TXT-Abschnitte eines Records. Je nach Anwendungsfall können diese entweder zusammengefügt 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.

Bei einem Fehler 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 Standard-order auf ipv4first.
• ipv6first: setzt den Standard-order auf ipv6first.
• verbatim: setzt den Standard-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() vom Hauptthread 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 standardmäßig auf ipv4first.
• ipv6first: für order standardmäßig auf ipv6first.
• verbatim: für order standardmäßig auf verbatim.

dns.setServers(servers)

Hinzugefügt in: v0.11.3

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

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 Adressen im RFC 5952 Format. 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'])

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

Die Methode dns.setServers() darf nicht aufgerufen werden, während eine DNS-Abfrage ausgeführt wird.

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

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, versucht die resolve()-Methode nicht, mit den nachfolgend angegebenen Servern aufzulösen. Fallback-DNS-Server werden nur verwendet, wenn die vorherigen Zeitüberschreitungen aufweisen oder zu einem anderen Fehler führen.

DNS Promises API

[Verlauf]

Version	Änderungen
v15.0.0	Exportiert als require('dns/promises').
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 zurückgeben, anstatt Callbacks zu verwenden. 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 Standard-Servereinstellungen. 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 den 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 den globalen Einstellungen.
resolver.resolve4('example.org').then(addresses => {
  // ...
})

// Alternativ kann der gleiche Code mit dem async-await-Stil geschrieben werden.
;(async function () {
  const addresses = await resolver.resolve4('example.org')
})()

Die folgenden Methoden 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 dieses Resolvers ab. Die entsprechenden Promises werden mit einem Fehler mit dem Code ECANCELLED zurückgewiesen.

dnsPromises.getServers()

Hinzugefügt in: v10.6.0

• Rückgabewert: <string[]>

Gibt ein Array von IP-Adresszeichenketten zurück, formatiert gemäß RFC 5952, die derzeit für die DNS-Auflösung konfiguriert sind. Eine Zeichenkette enthält einen Port-Abschnitt, 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-Familie. 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 mit { all: true } (siehe unten) verwendet wird, werden je nach System-DNS-Resolver entweder eine oder beide IPv4- und IPv6-Adressen zurückgegeben. Standardwert: 0.
  • hints <number> Ein oder mehrere unterstützte getaddrinfo-Flags. Mehrere Flags können durch bitweises ODER ihrer Werte übergeben werden.
  • all <boolean> Wenn true, wird das Promise mit allen Adressen in einem Array aufgelöst. Andernfalls wird eine einzelne Adresse zurückgegeben. Standardwert: false.
  • order <string> Wenn verbatim, wird das 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. Standardwert: 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 das 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 veraltet sein. Wenn beide angegeben sind, hat order höhere Priorität. Neuer Code sollte nur order verwenden. Standardwert: derzeit false (Adressen werden neu geordnet), aber dies wird sich in nicht allzu ferner Zukunft voraussichtlich ä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 ganze Zahl ist, muss diese 4 oder 6 sein – wenn options nicht angegeben ist, werden entweder IPv4- oder IPv6-Adressen oder beide zurückgegeben, wenn gefunden.

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

Bei einem Fehler wird das Promise mit einem Error-Objekt zurückgewiesen, 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 Filedeskriptoren vorhanden sind.

dnsPromises.lookup() hat nicht unbedingt etwas mit dem DNS-Protokoll zu tun. Die Implementierung verwendet eine Betriebssystemfunktion, die Namen mit Adressen und umgekehrt verknüpfen kann. Diese Implementierung kann subtile, aber wichtige Auswirkungen auf das Verhalten eines beliebigen Node.js-Programms haben. Nehmen Sie sich etwas Zeit, um den Abschnitt Implementierungsüberlegungen zu konsultieren, 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 einen Dienst unter Verwendung der zugrunde liegenden getnameinfo-Implementierung des Betriebssystems auf.

Wenn address keine gültige IP-Adresse ist, wird ein TypeError ausgelöst. Der port wird in eine Zahl umgewandelt. Wenn es kein legaler Port ist, wird ein TypeError ausgelöst.

Bei einem Fehler wird das Promise mit einem Error-Objekt abgelehnt, 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> Aufzulösender Hostname.
• rrtype <string> Ressourceneintragstyp. Standard: 'A'.

Verwendet das DNS-Protokoll, um einen Hostnamen (z. B. 'nodejs.org') in ein Array der Ressourceneinträge aufzulösen. Bei Erfolg wird das Promise mit einem Array von Ressourceneinträgen 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 Einträge	<Object>	dnsPromises.resolveAny()
'CAA'	CA-Autorisierungseinträge	<Object>	dnsPromises.resolveCaa()
'CNAME'	kanonische Namenseinträge	<string>	dnsPromises.resolveCname()
'MX'	Mail-Exchange-Einträge	<Object>	dnsPromises.resolveMx()
'NAPTR'	Name Authority Pointer-Einträge	<Object>	dnsPromises.resolveNaptr()
'NS'	Nameserver-Einträge	<string>	dnsPromises.resolveNs()
'PTR'	Zeigereinträge	<string>	dnsPromises.resolvePtr()
'SOA'	Start of Authority-Einträge	<Object>	dnsPromises.resolveSoa()
'SRV'	Service-Einträge	<Object>	dnsPromises.resolveSrv()
'TXT'	Texteintrag	<string[]>	dnsPromises.resolveTxt()

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

dnsPromises.resolve4(hostname[, options])

Hinzugefügt in: v10.6.0

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

Verwendet das DNS-Protokoll, um IPv4-Adressen (A-Records) 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> Zu lösender Hostname.
• options <Object>
  • ttl <boolean> Ruft den Time-To-Live-Wert (TTL) jedes Datensatzes ab. Wenn true, wird das Promise mit einem Array von { address: '0:1:2:3:4:5:6:7', ttl: 60 } Objekten aufgelöst, anstatt mit einem Array von Strings, wobei die TTL in Sekunden angegeben ist.

Verwendet das DNS-Protokoll, um IPv6-Adressen (AAAA-Records) 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 Datensätze aufzulösen (auch bekannt als ANY oder *-Abfrage). Bei Erfolg wird das Promise mit einem Array aufgelöst, das verschiedene Arten von Datensätzen enthält. Jedes Objekt hat eine Eigenschaft type, die den Typ des aktuellen Datensatzes angibt. 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 Datensatztyp 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 das Promise mit einem Array von Objekten aufgelöst, die die verfügbaren 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 das Promise mit einem Array von kanonischen Namens-Einträ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-Einträge (MX-Einträge) für den hostname aufzulösen. Bei Erfolg wird das 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 das 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 das 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 Pointer-Records (PTR-Records) für den hostname aufzulösen. Bei Erfolg wird das Promise mit einem Array von Strings aufgelöst, die die Antwort-Records enthalten.

dnsPromises.resolveSoa(hostname)

Hinzugefügt in: v10.6.0

• hostname <string>

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

• 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-Records (SRV-Records) für den hostname aufzulösen. Bei Erfolg wird das Promise mit einem Array von Objekten aufgelöst, die die folgenden Eigenschaften besitzen:

• 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 Text-Abfragen (TXT-Records) für den hostname aufzulösen. Bei Erfolg wird das Promise mit einem zweidimensionalen Array der für hostname verfügbaren Text-Records aufgelöst (z. B. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Jedes Unter-Array enthält TXT-Abschnitte eines Records. 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 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 dnsPromises.setDefaultResultOrder() hat eine höhere Priorität als --dns-result-order. Bei Verwendung von Worker-Threads beeinflusst dnsPromises.setDefaultResultOrder() vom Hauptthread nicht die Standard-DNS-Reihenfolge in Workern.

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 Adressen im RFC 5952-Format

Legt die IP-Adresse und den Port der Server fest, die bei der Durchführung der DNS-Auflösung verwendet werden sollen. Das Argument servers ist ein Array von Adressen im RFC 5952-Format. 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 ausgeführt wird.

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, versucht die resolve()-Methode nicht, mit den nachfolgend angegebenen Servern aufzulösen. Fallback-DNS-Server werden nur verwendet, wenn die vorherigen Server ein Timeout haben oder zu einem anderen Fehler führen.

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, die Abfrage sei falsch formatiert.
• dns.SERVFAIL: Der DNS-Server hat einen allgemeinen Fehler zurückgegeben.
• dns.NOTFOUND: Der Domainname wurde nicht gefunden.
• dns.NOTIMP: Der DNS-Server implementiert den angeforderten Vorgang 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: DNS-Server konnten nicht kontaktiert werden.
• dns.TIMEOUT: Timeout beim Kontaktieren von DNS-Servern.
• dns.EOF: Dateiende.
• dns.FILE: Fehler beim Lesen der Datei.
• dns.NOMEM: Speichermangel.
• dns.DESTRUCTION: Kanal wird zerstört.
• dns.BADSTR: Falsch formatierte Zeichenkette.
• dns.BADFLAGS: Ungültige Flags angegeben.
• dns.NONAME: Der angegebene Hostname ist nicht numerisch.
• dns.BADHINTS: Ungültige Hints-Flags angegeben.
• dns.NOTINITIALIZED: c-ares-Bibliotheksinitialisierung noch nicht durchgeführt.
• dns.LOADIPHLPAPI: Fehler beim Laden von iphlpapi.dll.
• dns.ADDRGETNETWORKPARAMS: Funktion GetNetworkParams nicht gefunden.
• dns.CANCELLED: DNS-Abfrage abgebrochen.

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

Implementierungsaspekte

Obwohl dns.lookup() und die verschiedenen Funktionen dns.resolve*()/dns.reverse() das gleiche Ziel haben, einen Netzwerknamen mit einer Netzwerkadresse (oder umgekehrt) zu verknüpfen, ist ihr Verhalten recht 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 Betriebssystemfunktionen wie die meisten anderen Programme. Beispielsweise wird dns.lookup() einen gegebenen Namen fast immer auf die gleiche Weise auflösen wie der Befehl ping. Unter den meisten POSIX-artigen 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 ändert das Verhalten aller anderen Programme, die auf demselben Betriebssystem laufen.

Obwohl der Aufruf von dns.lookup() aus der Sicht von JavaScript asynchron ist, wird er als synchroner Aufruf von getaddrinfo(3) implementiert, der im Threadpool von libuv läuft. Dies kann für einige Anwendungen überraschend negative Auswirkungen auf die Leistung haben, siehe die Dokumentation zu UV_THREADPOOL_SIZE für weitere Informationen.

Verschiedene Netzwerk-APIs rufen intern dns.lookup() auf, um Hostnamen aufzulösen. Wenn dies 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()) ermöglichen es auch, den Standardresolver dns.lookup() zu ersetzen.

dns.resolve(), dns.resolve*(), und 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 Prozesse im Threadpool von libuv haben, die dns.lookup() haben kann.

Sie verwenden nicht denselben Satz von Konfigurationsdateien wie dns.lookup(). Beispielsweise verwenden sie die Konfiguration aus /etc/hosts nicht.