dnsviz-probe(1)

💖 dnsviz-probe — the manual page, but make it slay 💖

okay bestie, so this is the tea on dnsviz-probe(1), a general commands manual page, and it's literally about issuing diagnostic DNS queries. sit with me, we're gonna get through this together 🫶

---

✨ NAME ✨

dnsviz-probe — issue diagnostic DNS queries. that's it, that's the whole vibe. it runs diagnostic DNS queries. iconic behavior honestly 💅

---

🌈 SYNOPSIS 🌈

dnsviz probe [ options ] [ domain_name... ]

look at her. so simple. so powerful. the way she just probes 🔥

---

🎀 DESCRIPTION 🎀

so here's the whole situation, bestie. dnsviz probe does a whole series of diagnostic queries for the names you specify, and it hits up either recursive DNS servers (that's the default, she's the default for a reason) or authoritative DNS servers. then it takes all those results and serializes them into JSON format. so cute, so structured, so JSON 🦋

and what is that output even for, you ask? it's used to assess the health of DNS deployments, using stuff like dnsviz-grok(1) and dnsviz-graph(1). so like, it's the diagnostics queen and those two are the ones who read her notes. main character energy all around 👑

now, the domain names you want processed? you can hand them over in two ways:

• as command-line arguments, or
• in a file, using the -f option.

and there's a third little trick: when you use the -r option, the domain names can just be implied using the diagnostic query input. like, the input already knows, she doesn't need to be told twice 💜

okay but here's the rules, and you gotta listen, fr fr. domain names get extracted from the diagnostic query input in conjunction with -r only when -f is not used and no domain names are supplied on the command line. and if you do use the -f option? then names may not be specified on the command line. periodt. no mixing. pick a lane 💀

---

🌸 so what even counts as a domain name here 🌸

the domain names you pass as input are fully-qualified domain names, like for real fully qualified. examples, because I know you want them:

• example.com
• www.example.com
• _443._tcp.example.com
• 1.2.0.192.in-addr.arpa
• 8.b.d.0.1.0.0.2.ip6.arpa

and because it's implied that the domain names you specify are fully qualified, you do not need a trailing dot. no dot needed. save the dot for later, she's not required ✨

---

and that's the setup bestie, we're not done yet — more of this page is coming, so don't go anywhere 🎀

✨ OPTIONS ✨

okay bestie, this is the part where it gets good. every flag, every vibe, let's go 💅

• -f, --names-file filename — read names from a file instead, one name per line, instead of grabbing them off the command line. and listen — if you use this, you literally can't also pass names on the command line. pick a lane babe 🎀
• -d, --debug level — set the debug level, anywhere from 0 to 3, and the higher you go the more it yaps. the default is "2", which is the informational-level output. so like, normal amount of talking 📣
• -r, --input-file filename — read diagnostic query input from this file instead of actually querying servers. pass "-" if you want it to read from standard input. stream it, queen 🌊
• -t, --threads threads — issue diagnostic queries for different names in parallel, using however many threads you say. default? totally serial, one at a time, no multitasking energy. give it threads and watch it go ⚡
• -4, --ipv4 — IPv4 only. that's it. that's the whole flag 🫶
• -6, --ipv6 — IPv6 only. slay 🌈
• -b, --source-ip address — use this specific source IPv4 or IPv6 address for your queries instead of letting it figure out the source on its own.

you can stack this option more than once to hand it both an IPv4 and an IPv6 address, no problem.

this one's sometimes a whole necessity when you're on a dual-homed machine and you wanna use the non-default interface for queries. main character interface only 💅

• -u, --looking-glass-url url — issue your queries through the DNS looking glass at this URL (HTTP(S) or SSH). the queries will look like they're coming from the looking glass instead of from your local machine. catfish but make it DNS 🙈

Examples:

Issue DNS queries from www.example.com using the cgi script dnsviz-lg.cgi:

http://www.example.com/cgi-bin/dnsviz-lg.cgi

Same, but use HTTP Basic authentication:

http://username:password@www.example.com/cgi-bin/dnsviz-lg.cgi

Issue DNS queries from host.example.com on which DNSViz is also installed.

ssh://username@host.example.com

heads up bestie: a looking glass that uses https is only supported when you're running python version 2.7.9 or greater. no cap.

• -k, --insecure — do NOT verify the server-side TLS certificate for an HTTPS-based DNS looking glass that you specified with -u. living dangerously, i see 😭
• -a, --ancestor ancestor — issue diagnostic queries for each domain name through the specified ancestor. default for recursive mode is "." (like, go all the way to the root, babe). default for authoritative mode (aka when you're using -A) is the domain name itself.
• -R, --rr-types type[,type...] — only issue diagnostic queries for these specific type(s), like A, AAAA, etc. the default is to be smart about it and pick query types based on the nature of the name (think: how many labels it has, whether it's a subdomain of .arpa, labels indicating association to TLSA or SRV records, etc.) plus whether there are NS records detected (i.e., it's a zone). it's giving psychic 🔮
• -s, --recursive-servers server[,server...] — query these specific recursive resolver(s) instead of whatever's sitting in /etc/resolv.conf.

each server can be an address (IPv4 or IPv6), a domain name (which gets resolved to an address through the standard resolution process), or both, using the syntax name=address. and real talk: when you give both a name and an address (name=address), the name is only for identification purposes — it doesn't matter whether the name resolves to the corresponding address, or at all, honestly. IPv6 addresses gotta be wrapped in square brackets, like "[2001:db8::1]".

each server value can optionally have a numeric port suffixed to it, telling you which port to hit. if you don't specify, the standard DNS port, 53, is used.

here's what example server values look like:

ns1.example.com
ns1.example.com:5333
ns1.example.com=192.0.2.1
ns1.example.com=[2001:db8::1]
ns1.example.com=[2001:db8::1]:5333
192.0.2.1

this option cannot be used in conjunction with -A. they do not coexist, periodt.

• -A, --authoritative-analysis — query authoritative servers, instead of (the default) recursive servers. switching up the whole energy 👑
• -x, --authoritative-servers domain[+]:server[,server...] — treat these servers as authoritative for a domain, instead of learning authoritative servers by following delegations. this option dictates which servers get queried for a domain, BUT the servers you specify won't be used to check NS or glue record consistency with the child — for that behavior, see -N.

default behavior is to identify and query servers authoritative for ancestors of the specified domain, if other options so dictate. however, if the domain ends in "+", then queries aren't issued for servers authoritative for ancestor domains of the domain. for example, with this command:

dnsviz probe -A -x example.com:ns1.example.com example.com

the com servers will be queried for DS records for example.com. but if you use this instead:

dnsviz probe -A -x example.com+:ns1.example.com example.com

no queries are performed at com servers or above, including DS records for example.com. bye bye ancestors 🦋

see -s for the syntax used for designating servers. BUT unlike -s, a zone file may be specified in lieu of a server name and/or address — in which case an instance of named(8) is started, the zone is served from that instance, and queries for the domain get directed to the local instance of named(8) serving that zone. for example, if example.com.zone is a file containing the contents of the example.com zone, you could use this command to say "yeah use the zone file":

dnsviz probe -A -x example.com:example.com.zone example.com

this option may be used multiple times on the command line. stack it, bestie ✨

this option can only be used in conjunction with -A. don't try it solo, it will not work.

• -N, --delegation-information domain:server[,server...] — use this delegation information for a domain, i.e., the NS and glue records for the domain, which would be served by the domain's parent. this is for testing new delegations or testing a potential change to a delegation. very "trying on outfits before the party" of you 🎀

this option has similar usage to -x. the major difference? the server names you supply comprise the NS record set, and the addresses you supply represent glue records. so if there are discrepancies between the authoritative responses for the NS RRset and glue and what you supplied on the command line, an error will be reported when the output is subsequently assessed, e.g., using dnsviz-grok(1). drama will be detected 💀

in lieu of specifying the record data itself on the command line, a file may be specified, which contains the delegation NS and glue records for the domain.

• -D, --ds domain:ds[,ds...] — use these delegation signer (DS) records for a domain. this is used in conjunction with the -N option for testing the introduction or change of DS records.

the DS records themselves are specified using the textual representation of their record data. for example, these DS records for example.com:

31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
31589 8 2 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03E576343C

would be specified by passing this value to -D:

"31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE, 31589 8 2 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03E576343C"

in lieu of specifying the record data itself on the command line, a file may be specified, which contains the DS records. for example:

dnsviz probe -D example.com:dsset-example.com.

this option must be used in conjunction with the -N option. they're a package deal, fr fr.

• -n, --nsid — use the NSID EDNS option with every DNS query issued. every single one. consistent queen 💅
• -e, --client-subnet subnet[:prefix_len] — use the EDNS Client Subnet option with every DNS query issued, using the specified subnet and prefix_len as values. if the prefix isn't specified, the prefix is the length of the entire address. defaults are doing their thing 🫶
• -c, --cookie cookie — send this specific DNS client cookie with every DNS query issued. the value specified is for a client cookie only and thus should be exactly 64 bits long. it's specified using hexadecimal representation, e.g., deadbeef1580f00d. cute hex 🍓

if the -c option isn't used, the default behavior is for a DNS client cookie to be generated randomly and sent with queries. if an empty string is specified, then DNS cookies are disabled. your call, babe.

• -E, --edns — issue queries to check EDNS compatibility of servers.

if this option is used, each server probed will be queried with "future" EDNS settings, and the respective responses can later be assessed for proper behavior. these settings include future EDNS versions (i.e., > 0), unknown options, and unknown flags. sending servers into the future, lowkey iconic ⭐

• -o, --output-file filename — write the output to this file instead of to standard output, which is the default. redirect that energy 💖
• -p, --pretty-output — output "pretty" instead of minimal JSON output, i.e., using indentation and newlines. note that this is the default when the output is a TTY. glow-up for your JSON ✨
• -h — display the usage and exit. help, bestie! 🙋

---

🚪 EXIT CODES 🚪

the exit codes are:

• 0 — program terminated normally. we ate and left no crumbs 👑
• 1 — incorrect usage. you did the syntax wrong, babes 😭
• 2 — the network was unavailable for diagnostic queries. no wifi, no vibes 💀
• 3 — there was an error processing the input or saving the output. something broke on the way in or out 🫠
• 4 — program execution was interrupted, or an unknown error occurred. rude. mysterious. chaotic 🙈
• 5 — no recursive resolvers found in resolv.conf nor given on command line. nobody to talk to, bestie 🥲

---

👀 SEE ALSO 👀

go read the whole friend group:

• dnsviz(1)
• dnsviz-grok(1)
• dnsviz-graph(1)
• dnsviz-print(1)
• dnsviz-query(1)

---

and that's the whole page, bestie 🫶 this one's from version 0.11.1, dated 21 April 2025, and it's the dnsviz-probe(1) manual — now go probe something and slay 💅🌸