INSPECTOR(1)

💖 INSPECTOR(1) 💖

okay bestie, this is the DNS-STATS manual page for inspector — header folded in, vibe check passed. 💅

✨ NAME ✨

inspector - convert C-DNS query/response info to PCAP or text. periodt. 💖

🎀 SYNOPSIS 🎀

inspector ['OPTIONS']... ['FILE'...]

💅 DESCRIPTION 💅

okay so inspector reads C-DNS query/response files produced by compactor, and it writes output files using one of two output formats. Optional lil bonus: IP addresses may be pseudo-anonymised. ✨

By default, inspector writes output using PCAP. This generates reconstructed traffic for the query/responses in the C-DNS file. main character output format, honestly. 🔥

Alternatively, inspector can use a templated text output. This generates output based on a text template which specifies the output to be produced for each query/response record. very choose-your-own-adventure. 🎀

inspector also writes a .info file for each output data file written. This is a plain text file, named as the output file but with .info appended. It contains a configuration and statistics summary for the capture. so you get receipts. 🧾

If no input file is given, inspector reads its standard input. In this case, an output file must be specified with the --output option. no input? stdin era. but you must name an output file with --output. 💅

🌈 OPTIONS 🌈

okay, the flags. there are a lot. hydrate before reading. 💖

💖 Generic Program Information 💖

-h, --help — Print a usage message briefly summarising these command-line options and then exit. helpful king. 👑
-v, --version — Print the version number of inspector to the standard output stream and then exit. yes, -v shows up again later under template-specific options — the manpage does that, bestie. I'm not merging them. 🙈
--defaultsfile [arg] — Specify the path to the default_values.conf file. If not specified, the default configuration file /nix/store/d6lld5x1pyrklnxiw4agakzl3zhxk6nb-compactor-1.2.3/etc/dns-stats-compactor/default_values.conf is read if present. path said exactly, no cap. 🫶

🌸 Outputs 🌸

-o, --output FILENAME — Write a single output file named FILENAME containing output generated from all the input files specified. If no output filename is specified, an output file is written for each input file named as the input file with .pcap or .txt appended to the name. In either case, if the file already exists, a counter is appended to the filename (e.g. -1) until a filename is generated that does not exist. If FILENAME is -, output is written to standard output. In this case, no info (configuration and statistics summary) is generated. no .info when you go stdout mode, bestie. 💀
-F, --output-format FORMAT — Write output using the nominated FORMAT. This must be either pcap or template. If not specified, pcap is the default. slay. 🔥
-z, --gzip-output [arg] — Compress data in the output files using gzip(1) format. arg may be true or 1 to enable compression, false or 0 to disable compression. If arg is omitted, it defaults to true. If compression is enabled, an extension .gz is added to the output filename. zip zip. 🎀
-y, --gzip-level [arg] — Compression level to use when producing gzip(1) output. arg must be a single digit 0 to 9. If not specified, the default level is 6. six is the vibe. ✨
-x, --xz-output [arg] — Compress data in the output files using xz(1) format. arg may be true or 1 to enable compression, false or 0 to disable compression. If arg is omitted, it defaults to true. If compression is enabled, an extension .xz is added to the output filename. xz said let me cook. 🍓
-u, --xz-preset [arg] — Compression preset level to use when producing xz(1) output. arg must be a single digit 0 to 9. If not specified, the default level is 6. again, six. consistency icon. 💅
-r., --report-info — Report info (config and statistics summary) to standard output on exit. the original really has that dot after -r — I'm keeping it exactly, bestie. 😭
-D., --relaxed-mode — Warn (instead of error) if unrecognized command line options are found. and yes, the dot after -D is also exactly what the source says. I am not editing the manpage's choices. 🙈
-N, --no-output — Don’t write any output PCAP or template files, just generate any requested ancillary outputs e.g. .info files. no main output, just side quests. 🦋
-O, --no-info — Don’t write any .info files. no receipts. 😭
-X, --excludesfile — For each input, write a .excludesfile file. This is in the format of an exclude hints file as specified to compactor and indicates which data fields in the input file were not collected. tea about what's missing. 🍵
-S, --stats — For each input file, write the number of query/response records converted and the time taken to standard error on completion. stats to stderr, bestie. 📊
-k, --pseudo-anonymisation-key — Key to use during output pseudo-anonymisation. Must be 16 bytes long. sixteen bytes, exactly. 🔑
-P, --pseudo-anonymisation-passphrase — Passphrase to use to generate key for output pseudo-anonymisation. passphrase era. 🫶
-p, --pseudo-anonymise — Pseudo-anonymise output. privacy slay. 💜
--debug-qr — Print a summary of each query/response pair to standard output on reading from the input C-DNS file. debug tea, served hot. ☕

🦋 PCAP-specific options 🦋

-q, --query-only — Write only query messages to the output. queries only, no responses. keep it focused. 🎀

🧚 Template-specific options 🧚

-t, --template FILENAME — Write output based on the template in the file named FILENAME. template time. ✨
-v, --value NAME=TEXT — Set a value named NAME with value TEXT on the command line. This value can be used in the template. This parameter may be repeated multiple times to specify different values. yes, -v is here too, doing a different job. the manpage said duplicate short option and I said okay bestie. 💀
-g, --geoip-db-dir DIR — inspector can present geographic IP data in the output. This requires the MaxMind GeoLite2 database files, which should be found in directory DIR. If not specified, the default directory /nix/store/d6lld5x1pyrklnxiw4agakzl3zhxk6nb-compactor-1.2.3/var/lib/dns-stats-compactor/GeoIP is checked. inspector needs files GeoLite2-ASN.mmdb and GeoLite2-City.mmdb to be present to enable geographic IP data in the output. both files, or no geo vibes. 🌍

💜 TEMPLATE FILES 💜

A template file describes the output generated by inspector for each query/response item in a C-DNS file. it's giving custom output couture. 🎀

🍓 Template markers 🍓

When output for each query/response item is generated, elements, or markers, like {{NAME}} in the template are replaced with a data item named NAME from the query/response (QR) item. marker magic. ✨🦋

Okay bestie, quick but important heads-up before the item list: if a data item isn't available in the query/response item you're working with, nothing gets output for that marker. Like, it just vanishes. 💨

So for example, "QTYPE {{query_type}}" will output "QTYPE 1" for a query whose question type is QTYPE A, and will output "QTYPE " if there's no query question at all. Empty vibes, but no error. Slay.

Here's the whole roster of things you can drop in 💅

client_address — IP address of client as raw bytes, 4 for IPv4, 16 for IPv6.
client_port — port used by client.
server_address — IP address of server as raw bytes, 4 for IPv4, 16 for IPv6.
server_port — port used by server.
client_hoplimit — value of query client hoplimit. Blank if no query.
dns_flags — DNS flags value. See the C-DNS definition for the actual values, iykyk.
id — query ID, or the response ID if there's no query.
opcode — value of query OPCODE, or response OPCODE if there's no query.
query_name — QNAME in the first Question. Blank if no question.
query_class — numeric QCLASS in the first Question. Blank if no question.
query_type — numeric QTYPE in the first Question. Blank if no question.
query_authoritative_answer — value of query AA flag. Blank if no query.
query_authenticated_data — value of query AD flag. Blank if no query.
query_checking_disabled — value of query CD flag. Blank if no query.
query_checking_recursion_available — value of query RA flag. Blank if no query.
query_checking_recursion_desired — value of query RD flag. Blank if no query.
query_truncated — value of query TC flag. Blank if no query.
query_z — value of query Z flag. Blank if no query.
query_do — value of query EDNS0 DO bit. Blank if no query EDNS0.
query_edns_udp_payload_size — value of query EDNS0 UDP payload size. Blank if no query EDNS0.
query_edns_version — value of query EDNS0 version bit. Blank if no query EDNS0.
query_opt_codes — comma separated list of query EDNS0 OPT codes. Blank if no query EDNS0.
query_len — value of query length on
query_rcode — the value of the query RCODE. Blank if there's no query 🙈
query_qdcount — how many questions got captured from the query. Blank if no query.
query_ancount — how many answer RRs got captured from the query. Blank if no query ✨
query_nscount — how many authority RRs got captured from the query. Blank if no query.
query_arcount — how many additional RRs got captured from the query. Blank if no query 💫
query_response_has_query — 1 if QR contains a query, otherwise 0. no cap.
query_response_has_response — 1 if QR contains a response, otherwise 0.
query_response_query_has_opt — 1 if QR contains a query that has OPT, otherwise 0. Blank if no query 🫶
query_response_query_has_no_question — 0 if QR contains a query that has a question, otherwise 1. Blank if no query. (yes bestie, the logic is inverted on purpose, read it twice 💀)
query_response_response_has_no_question — 0 if QR contains a response that has a question, otherwise 1. Blank if no query.
query_response_response_has_opt — 1 if QR contains a response that has OPT, otherwise 0. Blank if no response 🌸
query_response_flags — the Query/Response flags value. See C-DNS definition for values 👑

okay now we're in response territory, and it's giving "every single DNS flag gets its own little spotlight" ✨

response_authoritative_answer — the value of the response AA flag. Blank if no response.
response_authenticated_data — the value of the response AD flag. Blank if no response 💜
response_checking_disabled — the value of the response CD flag. Blank if no response.
response_checking_recursion_available — the value of the response RA flag. Blank if no response 🦋
response_checking_recursion_desired — the value of the response RD flag. Blank if no response.
response_truncated — the value of the response TC flag. Blank if no response.
response_z — the value of the response Z flag. Blank if no response 🌈
response_len — the value of the response length on the wire. Blank if no response.
response_rcode — the value of the response RCODE. Blank if no response ⭐
response_qdcount — the count of questions captured from the response. Blank if no …
response_ancount — how many answer RRs got captured from the response. Blank if there's no response at all. 💅
response_nscount — how many authority RRs got captured from the response. Blank when there's no response.
response_arcount — how many additional RRs got captured from the response. Also blank if there's no response, bestie.
response_delay_nanosecs — the gap, in nano-seconds, between the query timestamp and the response timestamp. It's 0 if there's no query or no response. 😭
timestamp_secs — QR timestamp, in seconds since epoch.
timestamp_microsecs — QR timestamp, in micro-seconds since epoch.
timestamp_nanosecs — QR timestamp, in nano-seconds since epoch.
transport_flags — the transport flags value. For the actual values, see the C-DNS definition, iykyk. 📖
transaction_type — the transaction type value. Again: see the C-DNS definition for values.
transport_ipv6 — literally, quote-unquote: "1 if the IPv4 used, 0 if IPv4." That's what the page says, bestie, we don't make the rules 🫶
transport_tcp — 1 if the transport used was TCP, 0 if it was UDP. Easy.

🎀 Template section 🎀

Okay so a template is allowed to optionally contain a section start marker:

and a section end marker:

If those markers are present, everything between them gets output before the first query/response output record. So it's like the little intro text that shows up once, at the top, before the actual data starts. Cute, right? ✨

🏷️ Template marker modifiers 🏷️

Okay bestie, so a marker modifier is literally just a filter that gets applied at template-expansion time — it swoops in, tweaks the value of the marker, and then the output happens. You write one by putting a colon after the marker name and then the modifier name, like this:

{{client_address:x-ipaddr}}

Iconic. Now here's the whole lineup, no skips, no cuts:

x-cstring — spits out binary input data using C string style escapes, e.g. Hello, world\n\0. Any non-printable character that doesn't have a defined escape gets output as \xaa.
x-array — wraps your input data up in square parenthesis. Cute little present. 🎁
x-csvescape — outputs input data escaped for use with CSV, exactly as described in RFC4180 <https://tools.ietf.org/html/rfc4180>, e.g. "Hello, ""quotes""".
x-hexstring — outputs binary input data as hex characters. A 0 byte comes out as \0, and every other value comes out as \xaa.
x-ipaddr — outputs the text representation of an IPv4 or IPv6 address, depending on whether the filter input was 4 bytes or 16 bytes.
x-ip6addr — outputs an IPv4 or IPv6 address as the IPv6 printable address representation. IPv4 addresses get output as ::ffff:192.0.2.25.
x-ip6addr-bin — outputs IPv4 or IPv6 addresses as a 16 byte binary IPv6 address. IPv4 addresses come out as 0x00000000000000000000ffffc0000219.
x-ipaddr-geo-location — give it an IPv4 or IPv6 address and it outputs the location ID that the MaxMind database reports for that address. The city ID gets reported if it's found, otherwise the country ID if that's found, otherwise the continent ID if that's found, otherwise 0. It'll error out if no MaxMind database files are found, so like… make sure they're there. 🫠
x-ipaddr-geo-asn — give it an IPv4 or IPv6 address and it outputs the ASN reported by the MaxMind database for that address, or 0 if it's not found. Error if no MaxMind database files are found.
x-ipaddr-geo-as-netmask — give it an IPv4 or IPv6 address and it outputs the netmask reported by the MaxMind database for the AS network that contains that address, or 0 if it's not found. Error if no MaxMind database files are found. Yes, same warning, three times — that's just how it is. 💅
x-date — outputs a timestamp in seconds as a UTC date in ISO601 format (YYYY-MM-DD).
x-datefmt=<fmt> — outputs a timestamp in seconds as a UTC date and time in whatever format you specify. The string <fmt> must be a valid strftime(3) format string, no cap.
x-datetime — outputs a timestamp in seconds as a UTC date and time in ISO601 format (YYYY-MM-DD HH:MM:SS).

There are also other predefined modifiers that are designed for use with HTML output — those ones are available too. Go see the documentation for the ctemplate library at https://github.com/OlafvdSpek/ctemplate for the deets. ✨

🚦 EXIT STATUS 🚦

The exit status is 1 if any error occurred. A successful run ends with an exit status of 0. That's it, that's the whole vibe check. 🟢

💀 LIMITATIONS 💀

So here's a thing. The design of C-DNS allows blocks with different storage and collection parameters to be present in the same C-DNS file. When does that even happen? Bestie, it can arise when two separate C-DNS files get merged.

At the time of writing, no tool exists to actually do that merging. And inspector has not been tested on such inputs — so if you hand it a file like that, it may not exhibit correct behaviour. You've been warned, love you. 🙈

🔗 RESOURCES 🔗

https://github.com/dns-stats/compactor/wiki

Free use of this software is granted under the terms of the Mozilla Public Licence, version 2.0. See the source for full details.

👑 AUTHOR 👑

Sinodun Internet Technologies

That's the whole page, bestie! This one's from DNS-STATS, dated 1980-01-01, and it's INSPECTOR(1) — go forth and inspect responsibly. 🦋💖🎀

📦 where this page comes from

nixpkgs unstable: compactor 1.2.3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms