DNS packets

Packets

All DNS requests and responses have the same basic format, though obviously not the same content.


Request packets usually only have questions -- the three other areas of the packet are usually empty, though they may contain some OPT records.


Response packets always contain the question(s) to which they are responding, plus a combination of answer, name server, and additional records entries. Name servers and Additional records have the same format as answers.


For (much) more information, consult the Wikipedia entry for DNS, which will point you to most of the relevant RFCs.

Properties and methods

Each packet has the following:

  • transactionId (number) : an arbitrary number set by the client, and returned by the server, so the client can know which request is being responded to. Do not change this unless you're doing something unusual.

  • isQuery (boolean) : if true, this packet is a request, otherwise it's a response

  • opcode (number) : the desired operation for this packet. This is usually 0 (meaning query). The complete list is available here.

  • opcodeName (string): the name corresponding to the opcode.

  • authoritative (boolean): if true in a response packet, the server is an authority for the name(s) in the question section.

  • truncated (boolean): if true in a response packet, the server was not able to fit its full answer into a single packet.

  • recursionDesired (boolean): if true in a request packet, the client requests that the server make further inquiries to answer all questions.

  • recursionAvailable (boolean): if true in a response packet, the server is able to do recursion.

  • responseCode (number) : the status of the response, 0 if OK. The complete list is available here.

  • responseCodeName (string) : the name corresponding to the responseCode. This is read-only.

  • questions (array of Questions) : returns the questions in this packet

  • answers (array of Answers) : returns the answers in this packet

  • nameServers (array of Answers) : returns the name servers in this packet

  • additionalRecords (array of Answers) : returns the additional records in this packet

  • addQuestion() : returns a new question added to the packet

  • addAnswer(String answerType): returns a new answer of the specified type (e.g. "MX" or "PTR"), and adds it to the packet

  • addNameServer(String answerType): returns a new name server entry of the specified type, and adds it to the packet

  • addAdditionalRecord(String answerType): returns a new additional record of the specified type, and adds it to the packet

Questions

A request packet always has at least one question, which consists of:

  • cls (number): the class of the request, normally always 1 (meaning IN - TCP/IP)

  • type (number): the type of the question, e.g. A, MX, NS, etc... A complete list is available here.

  • name (string): the name for which this request needs an answer

A single request may contain more than one question.

A response packet will always contain the question(s) to which it is responding.

Answers

An answer contains the server's response to a question. Each answer has the following properties:

  • cls (number): the class of the answer, normally always 1 (meaning TCP/IP)

  • type (number): the type of the answer, e.g. A, MX, NS, etc... A complete list is available here.

  • ttl (number) : the time to live for this answer, in seconds

  • name (string): the name being resolved

In addition, depending on the type attribute, the following additional attributes will be available:

Type A

  • ipAddress (array of 4 bytes): the IP4 address for the name

Type AAAA

  • ipAddress (array of 16 bytes): the IP6 address for the name

Type CNAME

  • aliasName (string) : the alias for the name

Type HINFO

  • cpu (string) : the type of the CPU

  • os (string) : the name of the operating system

Type MX

  • exchange (string) : the name of the mail server for the given domain

  • preference (number) : the priority for that exchange

Type NS

  • serverName (string) : the name of the server for the given name

Type PTR

  • pointerDomainName (string) : the domain name for the given address

Type SOA

  • masterName (string) : primary master name server for the given domain

  • responsibleName (string) : email address of the administrator -- note: the @ is replaced with a period

  • serialNumber (number) : used to determine who has the latest version of this record

  • refreshInterval (number) : recommended number of seconds after which this record should be re-fetched

  • retryInterval (number) : recommended number of seconds to wait before retrying if the request is not successful

  • expireInterval (number) : number of seconds after which, if no answer can be obtained from the main server, this domain should be considered dead

  • negativeCachingTTL (number) : number of seconds to cache negative answers

Type TXT

  • txts (list of strings) : arbitrary


Note that all types are not directly supported -- see Generic answers below.

Name servers and additional records

The name servers and additional records have the same format as the answers section, though obviously with a different meaning.

Answer API

Generic answers

Generic answers are created using addAnswer(string), addNameServer(string) or addAdditionalRecord(string) with a parameter of "" (empty string).

Generic answers are useful for the types of answers that are not covered otherwise, but they are much less convenient, since you have to read or write the payload directly using getData() and setData() (see the examples page).