1dnsviz-probe(1) General Commands Manual dnsviz-probe(1)
2
6 dnsviz-graph - graph the assessment of diagnostic DNS queries
7
9 dnsviz graph [ options ] [ domain_name... ]
10
12 Process the results of diagnostic DNS queries previously performed,
13 e.g., using dnsviz-probe(1), to assess the health of the associated DNS
14 deployments for one or more domain names specified. The results of
15 this processing are presented in one of several graphical formats for
16 user diagnostics.
17 The source of the diagnostic query input is either a file specified
19 with -r or standard input.
20 Domain names to be processed may be passed either as command-line argu‐
22 ments, in a file (using the -f option), or simply implied using the di‐
23 agnostic query input. The latter is the preferred methodology (and the
24 simplest) and is useful, except in cases where the input contains diag‐
25 nostic queries for multiple domain names, only a subset of which are to
26 be processed.
27 If -f is not used and no domain names are supplied on the command line,
29 then the domain names to be processed are extracted from the diagnostic
30 query input. If the -f option is used, then names may not be specified
31 on the command line.
32 The domain names passed as input are fully-qualified domain names, such
34 as example.com, www.example.com, _443._tcp.example.com, 1.2.0.192.in-
35 addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa. Because it is implied that
36 specified domain names are fully qualified, no trailing dot is neces‐
37 sary.
38 The graphical output is the image of a directed graph created using
40 dot(1). The "html" format makes this image interactive using java‐
41 script libraries that are distributed with this software.
42
45 -f, --names-file filename
46 Read names from a file (one name per line), instead of from com‐
47 mand line.
48 If this option is used, then names may not be specified on the
50 command line.
51 -r, --input-file filename
53 Read diagnostic query input from the specified file, instead of
54 from standard input.
55 -t, --trusted-keys-file filename
57 Use trusted keys from the specified file when processing diag‐
58 nostic queries. This overrides the default behavior of using
59 the installed keys for the root zone.
60 The format of this file is master zone file format and should
62 contain DNSKEY records that correspond to one more trusted keys
63 for one or more DNS zones.
64 This option may be used multiple times on the command line.
66 -a, --algorithms alg[,alg...]
68 Support only the DNSSEC algorithms specified. If this option is
69 used, any algorithms not specified will appear as "unsupported."
70 The status of any RRSIG records corresponding to unsupported al‐
71 gorithms will be unknown. Additionally, when a zone has only DS
72 records with unsupported algorithms, the zone is treated as "in‐
73 secure", assuming the DS records are properly authenticated.
74 -d, --digest-algorithms digest_alg[,digest_alg...]
76 Support only the DNSSEC digest algorithms specified. If this
77 option is used, any digest algorithms not specified will appear
78 as "unsupported." The status of any DS records corresponding to
79 unsupported digest algorithms will be unknown. Additionally,
80 when a zone has only DS records with unsupported digest algo‐
81 rithms, the zone is treated as "insecure", assuming the DS
82 records are properly authenticated.
83 -b, --validate-prohibited-algs
85 Validate algorithms for which validation is otherwise prohib‐
86 ited. Current DNSSEC specification prohibits validators from
87 validating older, weaker algorithms associated with DNSKEY and
88 DS records (see RFC 8624). If this option is used, then a warn‐
89 ing will be still be issued for DNSSEC records that use these
90 older algorithms, but the code will still assess their crypto‐
91 graphic status, rather than ignoring them.
92 -C, --enforce-cookies
94 Enforce DNS cookies strictly. Require a server to return a "BAD‐
95 COOKIE" response when a query contains a COOKIE option with no
96 server cookie or with an invalid server cookie.
97 -P, --allow-private
99 Allow private IP addresses for authoritative DNS servers. By
100 default, if the IP address corresponding to an authoritative
101 server is in IP address space designated as "private", it is
102 flagged as an error. However, there are some cases where this
103 is allowed. For example, if the diagnostic queries are issued
104 to servers in an experimental environment, this might be permis‐
105 sible.
106 -R, --rr-types type[,type...]
108 Process queries of only the specified type(s) (e.g., A, AAAA).
109 The default is to process all types queried as part of the diag‐
110 nostic input.
111 -e, --redundant-edges
113 Do not remove redundant RRSIG edges from the graph.
114 As described in "RRSIGs", some edges representing RRSIGs made by
116 KSKs are removed from the graph to reduce visual complexity. If
117 this option is used, those edges are preserved.
118 -O, --derive-filename
120 Save the output to a file, whose name is derived from the format
121 (i.e., provided to -T) and the domain name.
122 If this option is used when the diagnostic queries of multiple
124 domain names are being processed, a file will be created for
125 each domain name processed.
126 -o, --output-file filename
128 Write the output to the specified file instead of to standard
129 output, which is the default.
130 If this option is used when the diagnostic queries of multiple
132 domain name are being processed, a single file (the one speci‐
133 fied) will be created, which will contain the collective output
134 for all domain names processed.
135 -T, --output-format format
137 Use the specified output format for the graph, selected from
138 among the following: "dot", "png", "jpg", "svg", and "html".
139 The default is "dot".
140 -h, --help
142 Display the usage and exit.
143
146 The conventions used in the graphical format are described below.
147 Zones
150 Nodes in DNSViz are clustered by the zone to which the represented in‐
151 formation belongs. Each zone is labeled with the name of the zone ori‐
152 gin and the time at which the zone was last analyzed.
153 Delegations
156 Thick lines between zones denote delegations of namespace from one zone
157 to another, as indicated by the presence of NS (name server) resource
158 records (RRs) for the delegated namespace. The status of the delega‐
159 tion is reflected in its color and style of the edge.
160 insecure
163 A black, solid line between zones indicates a standard, insecure
164 delegation (i.e., sans DNSSEC).
165 lame If the designated name servers for a zone cannot not be properly
168 resolved or if the servers do not properly respond to queries,
169 then the delegation is considered lame and is represented by a
170 dashed, yellow line.
171 incomplete
174 If the delegation is incomplete, as indicated by the presence of
175 NS records in the zone itself but not in its parent zone, then
176 the delegation is represented by a dashed, yellow line.
177 secure If the delegation is secure by DNSSEC standards, then then the
180 delegation is represented by a solid, blue line.
181 bogus If the delegation is bogus by DNSSEC standards, then then the
184 delegation is represented by a dashed, red line.
185 RRsets
188 Resource record sets (RRsets) returned in the response (usually in the
189 answer section) are represented as rectangular nodes with rounded cor‐
190 ners. Among the most common record types are SOA (start of authority),
191 A (IPv4 address), AAAA (IPv6 address), MX (mail exchange), and CNAME
192 (canonical name).
193 RRsets that are specific to DNSSEC, such as the DNSKEY, DS, RRSIG, NSEC
195 and NSEC3 RR types, are represented as other node types, as specified
196 elsewhere in this guide.
197 Aliases
200 Aliases resulting from CNAME RRs are represented by a black edge from
201 one RRset (with the alias name) to another (with the canonical name).
202 DNAME
205 A DNAME RR is used to alias an entire namespace into another. DNAME
206 responses include synthesized CNAME RRs for the aliasing directed by
207 the DNAME RR.
208 DNAME records are shown in DNSViz with their respective CNAME records.
210 The status of the CNAME synthesis is reflected color of the edge.
211 valid A solid, blue line between DNAME node and CNAME node indicates
214 that the DNAME expansion was valid.
215 invalid
218 A solid, red line between DNAME node and CNAME node indicates
219 that the DNAME expansion was invalid.
220 Negative Responses
223 If the response to a query is a name error (NXDOMAIN), this negative
224 response is represented by a rectangular node with diagonals drawn at
225 each corner, and with a dashed border, lighter in color. A node repre‐
226 senting the SOA RR returned in the negative response (if any) is also
227 included.
228 If the response to a query has a NOERROR status but contains no answer
230 data (NO DATA) for the type, this negative response is represented by a
231 rectangular node with rounded corners, and with a dashed border,
232 lighter in color. A node representing the SOA RR returned in the nega‐
233 tive response (if any) is also included.
234 DNSKEY RRs
237 DNSKEY RRs include public key and meta information to enable resolvers
238 to validate signatures made by the corresponding private keys.
239 In DNSViz, each DNSKEY RR is represented as an elliptical node in the
241 zone to which it belongs.
242 Each DNSKEY node is decorated based on the attributes of the corre‐
244 sponding DNSKEY RR.
245 SEP bit
248 A gray fill indicates that the Secure Entry Point (SEP) bit is
249 set in the flags field of the DNSKEY RR.
250 This bit is typically used to designate a DNSKEY for usage as a
252 key signing key (KSK), a DNSKEY that is used to sign the DNSKEY
253 RRset of a zone, providing a secure entry point into a zone via
254 DS RRs or a trust anchor at the resolver.
255 revoke bit
258 A thick border indicates that the revoke bit is set in the flags
259 field of the DNSKEY RR.
260 Resolvers which implement the trust anchor rollover procedures
262 documented in RFC 5011 recognize the revoke bit as a signal that
263 the DNSKEY should no longer be used as a trust anchor by the re‐
264 solver. For a DNSKEY to be properly revoked, it must also be
265 self-signing (i.e., used to sign the DNSKEY RRset), which proves
266 that the revocation was made by a party that has access to the
267 private key.
268 trust anchor
271 A double border indicates that the DNSKEY has been designated as
272 a trust anchor.
273 A trust anchor must be self-signing (i.e., used to sign the
275 DNSKEY RRset).
276 DS RRs
279 DS (delegation signer) RRs exist in the parent of a signed zone to es‐
280 tablish a SEP into the zone. Each DS RR specifies an algorithm and key
281 tag corresponding to a DNSKEY RR in the signed zone and includes a
282 cryptographic hash of that DNSKEY RR.
283 In DNSViz DS RRs with the same DNSKEY algorithm and key tag are typi‐
285 cally displayed as a single node since they usually correspond to the
286 same DNSKEY RR with different digest algorithms. The status of the DS
287 RRs is reflected in the color and style of the edge.
288 valid A blue-colored arrow pointing from DS to DNSKEY indicates that
291 the digest contained in each of the DS RRs is valid, and corre‐
292 sponds to an existing DNSKEY.
293 invalid digest
296 A solid red line from DS to DNSKEY indicates that a DNSKEY ex‐
297 ists matching the algorithm and key tag of the DS RR, but the
298 digest of the DNSKEY in the DS RR does not match.
299 indeterminate - no DNSKEY
302 A dashed gray line from DS to a DNSKEY with a dashed gray border
303 indicates that no DNSKEY matching the algorithm and key tag of
304 the DS RR exists in the child zone.
305 Extraneous DS RRs in a parent zone do not, in and of themselves,
307 constitute an error. For example, sometimes they are deliber‐
308 ately pre-published before their corresponding DNSKEYs, as part
309 of a key rollover. However, for every DNSSEC algorithm in the
310 DS RRset for the child zone, a matching DNSKEY must be used to
311 sign the DNSKEY RRset in the child zone, as per RFC 4035.
312 indeterminate - match pre-revoke
315 A special case of a DS with no matching DNSKEY is when the DS
316 matched a DNSKEY prior to its revocation, but the ramifications
317 are the same as if it didn't match any DNSKEY. The line is sim‐
318 ply drawn to help identify the cause of the otherwise non-exis‐
319 tent DNSKEY.
320 indeterminate - unknown algorithm
323 When the algorithm and key tag of a DS RR match those of a
324 DNSKEY RR, but the digest algorithm is unknown or unsupported,
325 then the line between DS and DNSKEY is yellow.
326 invalid
329 When the use of a DS corresponding to a DNSKEY is invalid, inde‐
330 pendent of the correctness of its digest, the line between DS
331 and DNSKEY is red and dashed. An example scenario is when the
332 DNSKEY has the revoke bit set, which is disallowed by RFC 5011.
333 NSEC/NSEC3 RRs
336 NSEC and NSEC3 RRs are used within DNSSEC to prove the legitimacy of a
337 negative response (i.e., NXDOMAIN or NO DATA) using authenticated de‐
338 nial of existence or hashed authenticated denial of existence, respec‐
339 tively.
340 In DNSViz the NSEC or NSEC3 RR(s) returned by a server to authenticate
342 a negative response are represented by a rectangular node with several
343 compartments. The bottom compartment is labeled with either NSEC or
344 NSEC3, depending on the type of record. Each compartment on the top row
345 represents an NSEC or NSEC3 record in the set--there will be between
346 one and three.
347 An edge extends from the NSEC or NSEC3 node to the corresponding nega‐
349 tive response. Its status is reflected in the color and style of the
350 edge.
351 valid If the edge is solid blue, then the NSEC or NSEC3 RRs returned
354 prove the validity of the negative response.
355 invalid
358 A solid red edge from the NSEC or NSEC3 node to the negative re‐
359 sponse indicates that the NSEC or NSEC3 RRs included in in the
360 response do not prove the validity of the negative response.
361 A special case of NSEC/NSEC3 RRs is that in which they serve to prove
364 the non-existence of Delegation Signer (DS) records. The proof of ab‐
365 sence of DS records constitutes an insecure delegation, in which any
366 trust at the parent zone does not propagate to the child zone.
367 The NSEC/NSEC3 proof involving DS records is graphically represented
369 with an edge from the NSEC/NSEC3 node to the box representing the child
370 zone.
371 The opt-out flag is set in NSEC3 RRs to indicate that their presence is
373 only sufficient to prove insecure delegations (i.e., lack of DS
374 records) and nothing more. Thus, a name error (NXDOMAIN) response, for
375 example, cannot be securely proven when the NSEC3 uses opt-out.
376 NSEC3 records with the opt-out flag set are colored with a gray back‐
378 ground.
379 RRSIGs
382 Each RRSIG RR contains the cryptographic signature made by a DNSKEY
383 over an RRset. Using the DNSKEY with the same algorithm and key tag as
384 the RRSIG, the RRset which was signed, and the RRSIG itself, a resolver
385 may determine the correctness of the signature and authenticate the
386 RRset.
387 In DNSViz RRSIGs are represented as directed edges from the DNSKEY that
389 made the signature to the RRset that was signed. The status of the
390 edge is reflected in its color and style.
391 valid A solid blue edge indicates that an RRSIG is valid.
394 invalid signature
397 A solid red edge indicates an RRSIG in which the cryptographic
398 signature is invalid.
399 expired or premature
402 A solid purple edge indicates that an RRSIG is invalid because
403 it is outside its validity period, as defined by the inception
404 and expiration date fields in the RRSIG RR.
405 indeterminate - no DNSKEY
408 A dashed gray line stemming from a DNSKEY with a dashed gray
409 border indicates that no DNSKEY matching the algorithm and key
410 tag of the RRSIG RR could be found in the DNSKEY RRset (or the
411 DNSKEY RRset could not be retrieved).
412 Extraneous RRSIG RRs do not, in and of themselves, constitute an
414 error. For example, sometimes they are deliberately pre-pub‐
415 lished before their corresponding DNSKEYs, as part of an algo‐
416 rithm rollover. However, every RRset must be covered by RRSIGs
417 for every algorithm in the DNSKEY RRset, as per RFC 4035.
418 indeterminate - match pre-revoke
421 A special case of an RRSIG with no matching DNSKEY is when the
422 RRSIG matched a DNSKEY prior to its revocation, but the ramifi‐
423 cations are the same as if it didn't match any DNSKEY. The line
424 is simply drawn to help identify the cause of the otherwise non-
425 existent DNSKEY.
426 indeterminate - unknown algorithm
429 When the algorithm and key tag of an RRSIG RR match those of a
430 DNSKEY RR, but the cryptographic algorithm associated with the
431 RRSIG is unknown or unsupported, then the line stemming from the
432 DNSKEY is yellow.
433 invalid
436 When an RRSIG is invalid, independent of the correctness of its
437 temporal validity period and its cryptographic signature, the
438 line stemming from the DNSKEY is red and dashed. Example sce‐
439 narios might be when the DNSKEY has the revoke bit set or when
440 the signer field in the RRSIG RR does not match the name of the
441 zone apex. Such scenarios are disallowed by RFCs 5011 and 4035,
442 respectively.
443 Just like other RRsets, a DNSKEY RRset is signed as an RRset, which
446 comprises all the collective DNSKEY RRs at the zone apex. Because each
447 DNSKEY RR is represented as a node in DNSViz, a single RRSIG covering
448 the DNSKEY RRset is represented by edges drawn from the node represent‐
449 ing the signing DNSKEY to the nodes representing every DNSKEY RR in the
450 set.
451 In some DNSSEC implementations, multiple DNSKEYs sign the DNSKEY RRset,
453 even though only a subset are designated to provide secure entry into
454 the zone (e.g., via matching DS records in the parent zone). While
455 there is nothing inherently wrong with this configuration, graphically
456 representing such scenarios can be visually complex because of the cy‐
457 cles and redundancy created in the graph.
458 In order to represent trust propagation in a simplified fashion, elimi‐
460 nating graphic redundancies, DNSViz exhibits the following behavior.
461 For every DNSKEY signing the DNSKEY RRset, a self-directed edge is
462 added to the node, indicating that the DNSKEY is self-signing. Addi‐
463 tionally, if the DNSKEY is designated as a (SEP) into the zone, then
464 edges are drawn from its node to nodes representing all other DNSKEY
465 RRs in the DNSKEY RRset.
466 If there is no true SEP, (e.g., no DS RRs in the parent zone), then
468 SEP(s) are inferred based on their signing role (e.g., siging DNSKEY
469 RRset or other RRsets) and properties (e.g., SEP bit).
470 Like the DNSKEY RRset, a single DS RRset might be represented as sev‐
472 eral different nodes. As such a single RRSIG covering the DS RRset is
473 represented by edges drawn from the node representing the signing
474 DNSKEY to the nodes representing every DS RR in the set.
475 Because an NSEC or NSEC3 node represents one or more RRsets and at
477 least one RRSIG per RRset is anticipated, multiple RRSIG edges will be
478 drawn from DNSKEY to NSEC or NSEC3 nodes, each pointing to the respec‐
479 tive compartment corresponding to the NSEC or NSEC3 record.
480 Wildcards
483 When the RRSIG covering an RRset has a labels field with value greater
484 than the number of labels in the name, it is indicative that the re‐
485 sulting RRset was formed by a wildcard expansion. The server must ad‐
486 ditionally include an NSEC or NSEC3 proof that the name to which the
487 wildcard is expanded does not exist.
488 DNSViz represents wildcards by displaying both the wildcard RRset and
490 the NSEC or NSEC3 proof.
491 Node Status
494 Beginning at the DNSKEYs designated as trust anchors, DNSViz traverses
495 the nodes and edges in the graph to classify each node as having one of
496 three DNSSEC statuses, depending on the status of the RRset which it
497 represents: secure, bogus, or insecure. In DNSViz, node status is in‐
498 dicated by the color of the nodes (Note that there isn't always a one-
499 to-one mapping between node and RRset, but the node status will be con‐
500 sistent among all nodes comprising an RRset. An example is the DNSKEY
501 nodes for a zone, which all have the same status even though the DNSKEY
502 RRset is split among different nodes).
503 The status of a node is reflected in the color of its outline.
505 secure Nodes with blue outline indicate that they are secure, that
508 there is an unbroken chain of trust from anchor to RRset.
509 bogus Nodes with red outline indicate that they are bogus, that the
512 chain of trust from an anchor has been broken.
513 Because the NSEC and NSEC3 nodes often represent multiple NSEC
515 or NSEC3 RRs, it is possible that a proper subset of the RRs are
516 secure, while others in the set are not (e.g., missing or ex‐
517 pired RRSIG). In this case, the outline of the compartments
518 representing secure NSEC or NSEC3 RRs will be colored blue,
519 while the others will be red. Because the status of the collec‐
520 tive set of NSEC and NSEC3 RRs is dependent on the status of all
521 the individual NSEC and NSEC3 RRs, the greater node is only col‐
522 ored blue if all the compartments are colored blue.
523 insecure
526 Nodes with black outline indicate that they are insecure, that
527 no chain of trust exists; if any anchors exist then an insecure
528 delegation is demonstrated to prove that no chain should exist
529 from the anchors. This is equivalent to DNS without DNSSEC.
530 Warnings and Errors
533 If one or more warnings are detected with the data represented by a
534 node in the graph, then a warning icon is displayed in the node.
535 Similarly, the warning icon is displayed alongside edges whose repre‐
537 sented data has warnings.
538 If one or more errors (more severe than warnings) are detected with the
540 data represented by a node in the graph, then an error icon is dis‐
541 played in the node.
542 Similarly, the error icon is displayed alongside edges whose repre‐
544 sented data has errors.
545 A warning icon with an italicized label denotes a warning for a re‐
547 sponse that isn't represented elsewhere in the graph, such as a refer‐
548 ral with the authoritative answer flag set.
549 An error icon with an italicized label denotes a response error, e.g.,
551 due to timeout, malformed response, or invalid RCODE.
552
555 The exit codes are:
556 0 Program terminated normally.
558 1 Incorrect usage.
560 2 Required package dependencies were not found.
562 3 There was an error processing the input or saving the output.
564 4 Program execution was interrupted, or an unknown error occurred.
566
568 dnsviz(1), dnsviz-probe(1), dnsviz-grok(1), dnsviz-print(1), dnsviz-
569 query(1)
5700.9.3 11 Mar 2021 dnsviz-probe(1)