Crate dns_server 

dns-server

A threaded DNS server library.

Use Cases

• Make your API server its own DNS server. This eliminates the DNS server as a separate point of failure.
• Keep your DNS config in code, next to your server code. Include it in code reviews and integration tests.
• DNS-based domain validation for free ACME certificates. This is useful for servers that don’t listen on port 80. Servers on port 80 can use HTTP for domain validation and don’t need to use this.

Features

• Depends only on std
• forbid(unsafe_code)
• ?% test coverage

Limitations

• Brand new.

Example

use dns_server::DnsRecord;
use permit::Permit;
use signal_hook::consts::{SIGHUP, SIGINT, SIGQUIT, SIGTERM};
use signal_hook::iterator::Signals;

let top_permit = Permit::new();
let permit = top_permit.new_sub();
std::thread::spawn(move || {
    Signals::new([SIGHUP, SIGINT, SIGQUIT, SIGTERM])
        .unwrap()
        .forever()
        .next();
    drop(top_permit);
});
let records = vec![
    DnsRecord::new_a("aaa.example.com", "10.0.0.1").unwrap(),
    DnsRecord::new_aaaa("aaa.example.com", "2606:2800:220:1:248:1893:25c8:1946").unwrap(),
    DnsRecord::new_cname("bbb.example.com", "ccc.example.com").unwrap(),
    DnsRecord::new_ns("sub.example.com", "ns1.sub.example.com").unwrap(),
];
dns_server::Builder::new_port(8053)
    .unwrap()
    .with_permit(permit)
    .serve_static(&records)
    .unwrap();

Related Crates

Cargo Geiger Safety Report

Changelog

• 2025-08-21 v0.2.6
  • TXT records.
  • Rejects malformed A/AAAA/CNAME/NS records with extra unused bytes
• 2025-05-25 v0.2.5 - NS records
• 2024-09-29 v0.2.4 - Update a dependency
• 2024-04-08 v0.2.3 - Remove a dependency
• 2024-04-08 v0.2.2 - Support case randomization.
• 2024-03-27 v0.2.1
  • Dynamic responses
  • Randomize order of static responses
• 2022-04-25 v0.1.0 - Initial version

To Do

• Message compression
• Decide whether to send back error responses.
• Ergonomic constructors that take OsStr, for using environment variables
• Custom TTLs
• NS glue records
• Client
• Caching client
• Recursive resolver

Alternatives

Structs

Builder

DnsMessage

DnsMessageHeader

4.1.1. Header section formatThe header contains the following fields:

DnsName

2.3.1. Preferred name syntaxThe DNS specifications attempt to be as general as possible in the rules for constructing domain names. The idea is that the name of any existing object can be expressed as a domain name with minimal changes.However, when assigning a domain name for an object, the prudent user will select a name which satisfies both the rules of the domain system and any existing rules for the object, whether these rules are published or implied by existing programs.For example, when naming a mail domain, the user should satisfy both the rules of this memo and those in RFC-822. When creating a new host name, the old rules for HOSTS.TXT should be followed. This avoids problems when old software is converted to use domain names.The following syntax will result in fewer problems with manyapplications that use domain names (e.g., mail, TELNET).<domain> ::= <subdomain> | " "<subdomain> ::= <label> | <subdomain> "." <label><label> ::= <letter> [ [ <ldh-str> ] <let-dig> ]<ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str><let-dig-hyp> ::= <let-dig> | "-"<let-dig> ::= <letter> | <digit><letter> ::= any one of the 52 alphabetic characters A through Z in upper case and a through z in lower case<digit> ::= any one of the ten digits 0 through 9Note that while upper and lower case letters are allowed in domain names, no significance is attached to the case. That is, two names with the same spelling but different case are to be treated as if identical.The labels must follow the rules for ARPANET host names. They must start with a letter, end with a letter or digit, and have as interior characters only letters, digits, and hyphen. There are also some restrictions on the length. Labels must be 63 characters or less.For example, the following strings identify hosts in the Internet:A.ISI.EDU XX.LCS.MIT.EDU SRI-NIC.ARPA

DnsQuestion

The question section is used to carry the “question” in most queries, i.e., the parameters that define what is being asked. The section contains QDCOUNT (usually 1) entries, each of the following format:

Enums

DnsClass

CLASS fields appear in resource records. The following CLASS mnemonics and values are defined:IN 1 the InternetCS 2 the CSNET class (Obsolete - used only for examples in some obsolete RFCs)CH 3 the CHAOS classHS 4 Hesiod [Dyer 87]QCLASS fields appear in the question section of a query. QCLASS values are a superset of CLASS values; every CLASS is a valid QCLASS. In addition to CLASS values, the following QCLASSes are defined:* 255 any class

DnsError

DnsOpCode

OPCODE A four bit field that specifies kind of query in this message. This value is set by the originator of a query and copied into the response. The values are:0 a standard query (QUERY)1 an inverse query (IQUERY)2 a server status request (STATUS)3-15 reserved for future use

DnsRecord

4.1.3. Resource record formatThe answer, authority, and additional sections all share the same format: a variable number of resource records, where the number of records is specified in the corresponding count field in the header. Each resource record has the following format:

DnsResponseCode

RCODE Response code - this 4 bit field is set as part of responses. The values have the following interpretation:0 No error condition1 Format error - The name server was unable to interpret the query.2 Server failure - The name server was unable to process this query due to a problem with the name server.3 Name Error - Meaningful only for responses from an authoritative name server, this code signifies that the domain name referenced in the query does not exist.4 Not Implemented - The name server does not support the requested kind of query.5 Refused - The name server refuses to perform the specified operation for policy reasons. For example, a name server may not wish to provide the information to the particular requester, or a name server may not wish to perform a particular operation (e.g., zone transfer) for particular data.6-15 Reserved for future use.

DnsType

TYPE fields are used in resource records. Note that these types are a subset of QTYPEs.

Functions

process_datagram

Errors

process_request

Errors

serve_udp

Errors