dns(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 dns(n) — Tcl Domain Name Service Client 💖

okay bestie, sit down, hydrate, because we're about to talk about the dns manual page and honestly? it's giving networking main character energy. this is the dns(n) page, aka the Tcl Domain Name Service Client. let's go ✨

🌈 SYNOPSIS 🌈

package require Tcl 8.5 9

package require dns ?1.6.1?

::dns::resolve query ?options?

::dns::configure ?options?

::dns::name token

::dns::address token

::dns::cname token

::dns::result token

::dns::status token

::dns::error token

::dns::reset token

::dns::wait token

::dns::cleanup token

::dns::nameservers

🦋 DESCRIPTION 🦋

so the dns package is a Domain Name Service client that's written in pure Tcl. if you wanna know the actual DNS protocol tea, go read references (1) and (2), or check out resolver(3) to see how the C library handles resolving domain names. no cap.

the whole point of this package, the vibe it's serving, is to protect your Tcl scripts from the drama of the system library resolver when name servers are slow 😭. and honestly? it may or may not be of practical use. we said what we said 💅

internet name resolution is a whole complex situation and DNS is only one piece of the resolver puzzle. you might actually be supposed to be using hosts files, NIS, or WINS, just to name a few other systems. so like, this package is not a substitute for the C library resolver — but it does implement name resolution over DNS, and that's iconic.

the package also extends the uri package to support DNS URIs (4) in this form:

dns:what.host.com
dns://my.nameserver/what.host.com

and dns::resolve can handle DNS URIs or plain domain names as a query. versatile queen 👑

Note: the package defaults to using DNS over TCP connections. if you wanna use UDP you're gonna need the tcludp package installed, and it has to be a version that correctly handles binary data (> 1.0.4). it's available at http://tcludp.sourceforge.net/. and if the udp package is present, then UDP gets used by default. plot twist 🫶
Note: the package supports DNS over TLS (RFC 7858) for enhanced privacy of DNS queries. using this feature requires the TLS package. private and protected, we love to see it 🔒✨

👑 COMMANDS 👑

::dns::resolve query ?options?

resolve a domain name using the DNS protocol, bestie. query is the domain name you're looking up — it should be either a fully qualified domain name or a DNS URI.

  • -nameserver hostname or -server hostname — specify an alternative name server just for this request.
  • -protocol tcp|udp — pick the network protocol for this request. can be one of tcp or udp.
  • -port portnum — specify an alternative port.
  • -search domainlist — (that's it, that's the entry 🎀)
  • -timeout milliseconds — override the default timeout.
  • -type TYPE — specify which kind of DNS record you're interested in. valid values are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. see RFC1035 for the details about the return values. see http://spf.pobox.com/ about SPF. see (3) about AAAA records and RFC2782 for the details of SRV records.
  • -class CLASS — specify the class of domain name. this is usually IN, but it may be one of IN for internet domain names, CS, CH, HS or * for any class.
  • -recurse boolean — set it to false if you do not want the name server to recursively act upon your request. normally set to true.
  • -command procname — set a procedure to be called when the request completes. the procedure gets the token passed to it as its only argument.
  • -usetls boolean — set it to true to use DNS over TLS. this forces the use of TCP and changes the default port to 853. certificate validation is required, so you have to provide a source of trusted certificate authority certificates using -cafile or -cadir.
  • -cafile filepath — specify a file containing a collection of trusted certificate authority certificates. see the update-ca-certificates command manual page for details, or the -CAfile option help from openssl.
  • -cadir dirpath — specify a directory containing trusted certificate authority certificates. this must be provided if -cafile is not specified, for certificate validation to work when -usetls is enabled. see the openssl documentation for the required structure of this directory.

::dns::configure ?options?

the ::dns::configure command is how you set the dns package up. the server to query, the protocol, and the domain search path are all set right here. if you give it no arguments, you get back a list of all the current settings. if you give it only one argument, then that argument has to be the name of an option, and you get the value for that option back.

  • -nameserver hostname — set the default name server used by all queries. the default is localhost.
  • -protocol tcp|udp — set the default network protocol. default is tcp.
  • -port portnum — set the default port to use on the name server. the default is 53.
  • -search domainlist — set the domain search list. this is currently not used. (it's just there, being decorative 💅)
  • -timeout milliseconds — set the default timeout value for DNS lookups. default is 30 seconds.
  • -loglevel level — set the log level used for emitting diagnostic messages from this package. the default is warn. see the log package for the details of the available levels.
  • -cafile filepath — set the default file path used for the -cafile option to dns::resolve.
  • -cadir dirpath — set the default directory path used for the -cadir option to dns::resolve.

::dns::name token

returns a list of all the domain names that came back as an answer to your query. the full roster, bestie 📋

::dns::address token

returns a list of the address records that match your query.

::dns::cname token

returns a list of canonical names (usually just one) matching your query.

::dns::result token

returns a list of all the decoded answer records provided for your query. this is the one that lets you extract the result for more unusual query types. for the girlies with niche needs 🎀

::dns::status token

returns the status flag. for a successfully completed query this will be ok. it may be error or timeout or eof. see also ::dns::error.

::dns::error token

returns the error message provided for requests whose status is error. if there is no error message then you get an empty string back. (an empty string. the silence. the audacity. 💀)

::dns::reset token

reset or cancel a DNS query. be free 🦋

::dns::wait token

wait for a DNS query to complete, and return the status when it's done.

::dns::cleanup token

remove all the state variables associated with the request. tidy queen ✨

::dns::nameservers

attempts to return a list of the nameservers currently configured for the user's system. on a unix machine this parses the /etc/resolv.conf file for nameservers (if it exists), and on Windows systems it examines certain parts of the registry. if no nameserver can be found, then the loopback address (127.0.0.1) is used as a default.

🌸 EXAMPLES 🌸

% set tok [dns::resolve www.tcl.tk]
::dns::1
% dns::status $tok
ok
% dns::address $tok
199.175.6.239
% dns::name $tok
www.tcl.tk
% dns::cleanup $tok

using DNS URIs as queries:

% set tok [dns::resolve "dns:tcl.tk;type=MX"]
% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]

reverse address lookup:

% set tok [dns::resolve 127.0.0.1]
::dns::1
% dns::name $tok
localhost
% dns::cleanup $tok

using DNS over TLS (RFC 7858):

% set tok [dns::resolve www.tcl.tk -nameserver dns-tls.bitwiseshift.net  -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt]
::dns::12
% dns::wait $tok
ok
% dns::address $tok
104.25.119.118 104.25.120.118

📚 REFERENCES 📚

  1. Mockapetris, P., "Domain Names - Concepts and Facilities", RFC 1034, November 1987. (http://www.ietf.org/rfc/rfc1034.txt)
  2. Mockapetris, P., "Domain Names - Implementation and Specification", RFC 1035, November 1087. (http://www.ietf.org/rfc/rfc1035.txt)
  3. Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", RFC 1886, December 1995. (http://www.ietf.org/rfc/rfc1886.txt)
  4. Josefsson, S., "Domain Name System Uniform Resource Identifiers", Internet-Draft, October 2003, (http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt)
  5. Gulbrandsen, A., Vixie, P. and Esibov, L., "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000, (http://www.ietf.org/rfc/rfc2782.txt)
  6. Ohta, M. "Incremental Zone Transfer in DNS", RFC 1995, August 1996, (http://www.ietf.org/rfc/rfc1995.txt)
  7. Hu, Z., etc al. "Specification for DNS over Transport Layer Security (TLS)", RFC 7858, May 2016, (http://www.ietf.org/rfc/rfc7858.txt)
yes, reference 2 says November 1087. we are not the ones who wrote it, we are simply the ones who report it 🫠

💜 AUTHORS 💜

Pat Thoyts — the icon, the legend, the moment 👑

🍓 BUGS, IDEAS, FEEDBACK 🍓

this document, and the package it describes, will undoubtedly contain bugs and other problems. like, that's just the deal. please report such in the category dns of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them, fr fr.

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

⭐ SEE ALSO ⭐

resolver(5)

🎀 KEYWORDS 🎀

DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886, rfc 7858

🌈 CATEGORY 🌈

Networking

Copyright (c) 2002, Pat Thoyts

and that's the whole page bestie, no notes 💅 this little beauty ships with tcllib, version 1.6.1, in the dns(n) manual — go forth and resolve responsibly, mwah 🫶💖

📦 where this page comes from