dog(1)

📦
version 0.1.0 · 3 versions
, in opensuse-leap 16.0

🐶 dog(1) — like, the manual page, bestie

okay so this is the manual page for dog, a command-line DNS client, and honestly? she's iconic. colourful output, DNS-over-TLS and DNS-over-HTTPS support, and she can even emit JSON. we're gonna go through the whole thing together, no skips, no cap 💅

✨ NAME ✨

dog — a command-line DNS client 🐕

🌸 SYNOPSIS 🌸

dog [options] [domains...]

dog is a command-line DNS client. It has colourful output, supports the DNS-over-TLS and DNS-over-HTTPS protocols, and can emit JSON. Literally all of that. In one little binary. 🎀

💖 EXAMPLES 💖

  • dog example.net — Query the A record of a domain using default settings. the classic starter pack 🫶
  • dog example.net MX — ...looking up MX records instead. glow up, different record type ✨
  • dog example.net MX @1.1.1.1 — ...using a specific nameserver instead. picking your own fave resolver, we love agency 👑
  • dog example.net MX @1.1.1.1 -T — ...using TCP rather than UDP. switching it up 💅
  • dog -q example.net -t MX -n 1.1.1.1 -T — As above, but using explicit arguments. the "I like to be precise about things" version, and honestly? valid.

🦋 QUERY OPTIONS 🦋

okay bestie, these are the main character options — the ones that decide what you're even asking:

  • -q, --query=HOST — Host name or domain name to query. the thing you're actually curious about 💜
  • -t, --type=TYPE — Type of the DNS record being queried (A, MX, NS...) — pick your fighter ⭐
  • -n, --nameserver=ADDR — Address of the nameserver to send packets to. who's getting your question 🎀
  • --class=CLASS — Network class of the DNS record being queried (IN, CH, HS). yes these exist, yes they're a vibe 🌈

By default, dog will request A records using the system default resolver. At least one domain name must be passed — dog will not automatically query the root nameservers. so don't come crying to her with zero arguments, she's not doing that 😭

Query options can be passed in using a command-line option, such as --query lookup.dog or --type MX, or as plain arguments, such as lookup.dog or MX. dog will make an intelligent guess as to what plain arguments mean (MX is quite clearly a type), which makes it easier to compose ad-hoc queries quickly. If precision is desired, use the long-form options. she's smart but she's not gonna read your mind forever 🧚

If more than one domain, type, nameserver, or class is specified, dog will perform one query for each combination, and display the combined results in a table. For example, passing three type arguments and two domain name arguments will send six requests. math is mathing, she's booked and busy 🔥

DNS traditionally uses port 53 for both TCP and UDP. To use a resolver with a different port, include the port number after a colon (:) in the nameserver address. iykyk 🩷

🎀 SENDING OPTIONS 🎀

  • --edns=SETTING — Whether to opt in to DNS. This can be disable, hide, or show. three whole choices, pick wisely 💫
  • --txid=NUMBER — Set the transaction ID to a specific value. for the control freaks (affectionate) 🙈
  • -Z=TWEAKS — Set uncommon protocol-level tweaks. the secret menu, lowkey 🔮

🚀 TRANSPORT OPTIONS 🚀

  • -U, --udp — Use the DNS protocol over UDP.
  • -T, --tcp — Use the DNS protocol over TCP.
  • -S, --tls — Use the DNS-over-TLS protocol.
  • -H, --https — Use the DNS-over-HTTPS protocol.

By default, dog will use the UDP protocol, automatically re-sending the request using TCP if the response indicates that the message is too large for UDP. Passing --udp will only use UDP and will fail in this case; passing --tcp will use TCP by default. so like, --udp is committed to the bit, for better or worse 💀

The DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH) protocols are available with the --tls and --https options. Bear in mind that the system default resolver is unlikely to respond to requests using these protocols — so don't be shocked, she warned you 🫶

Note that if a hostname or domain name is given as a nameserver, rather than an IP address, the resolution of that host is performed by the operating system, not by dog. she's outsourcing that one, respectfully 🌸

Unlike the others, the HTTPS transport type requires an entire URL, complete with protocol, domain name, and path. full lewk required, no half measures 👑

💅 OUTPUT OPTIONS 💅

  • -1, --short — Short mode: display nothing but the first result. minimalism era ✨
  • -J, --json — Display the output as JSON. for the devs 🧚
  • --color, --colour=WHEN — When to colourise the output. This can be always, automatic, or never. (both spellings, she's inclusive 🏳️‍🌈)
  • --seconds — Do not format durations as hours and minutes; instead, display them as seconds. raw numbers, no frills 💫
  • --time — Print how long the response took to arrive. the "how long did u take" of it all 😭

⭐ META OPTIONS ⭐

  • --help — Displays an overview of the command-line options. your lil map 🗺️
  • --version — Displays the version of dog being invoked. identity check 🪞

💜 ENVIRONMENT VARIABLES 💜

dog responds to the following environment variables:

🌟 DOG_DEBUG

Set this to any non-empty value to have dog emit debugging information to standard error. For more in-depth output, set this to the exact string trace. yes, literally trace. she said what she said 🔍

🍓 RECORD TYPES 🍓

dog understands and can interpret the following record types:

  • A — IPv4 addresses
  • AAAA — IPv6 addresses
  • CAA — permitted certificate authorities
  • CNAME — canonical domain aliases
  • HINFO — system information and, sometimes, forbidden request explanations
  • LOC — location information
  • MX — e-mail server addresses
  • NAPTR — DDDS rules
  • NS — domain name servers
  • OPT — extensions to the DNS protocol
  • PTR — pointers to canonical names, usually for reverse lookups
  • SOA — administrative information about zones
  • SRV — IP addresses with port numbers
  • SSHFP — SSH key fingerprints
  • TLSA — TLS certificates, public keys, and hashes
  • TXT — arbitrary textual information

When a response DNS packet contains a record of one of these known types, dog will display it in a table containing the type name and a human-readable summary of its contents. readable and cute, we stan 💖

Records with a type number that does not map to any known record type will still be displayed. As they cannot be interpreted, their contents will be displayed as a series of numbers instead. she's not ignoring them, she just doesn't speak that language 🙈

dog also contains a list of record type names that it knows the type number of, but is not able to interpret, such as IXFR or ANY or AFSDB. These are acceptable as command-line arguments, meaning you can send an AFSDB request with dog AFSDB. However, their response contents will still be displayed as numbers. They may be supported in future versions of dog. future era, not yet 👀

🔧 PROTOCOL TWEAKS 🔧

The -Z command-line argument can be used one or more times to set some protocol-level options in the DNS queries that get sent. It accepts the following values:

  • aa — Sets the AA (Authoritative Answers) bit in the query.
  • ad — Sets the AD (Authentic Data) bit in the query.
  • bufsize=NUM — Sets the UDP payload size field in the OPT field in the query. This has no effect if EDNS is diabled. (yes, that's how it's spelled in the original, she's keeping it fr fr 😭)
  • cd — Sets the CD (Checking Disabled) bit in the query.

🚨 EXIT STATUSES 🚨

  • 0 — If everything goes OK. slay 💅
  • 1 — If there was a network, I/O, or TLS error during operation. rough.
  • 2 — If there is no result from the server when running in short mode. This can be any received server error, not just NXDOMAIN. so don't assume, bestie 💀
  • 3 — If there was a problem with the command-line arguments. we've all been there 🫠

👑 AUTHOR 👑

dog is maintained by Benjamin ogham Sago. the icon behind the icon ✨

and that's the whole page, bestie 🎀 this was dog, version v0.1.0, living in the General Commands Manual — go query something iconic and remember: the vibe changes, the facts do not. mwah 💋🐶

📦 where this page comes from