1dnsviz-probe(1)             General Commands Manual            dnsviz-probe(1)
2
3
4

NAME

6       dnsviz-graph - graph the assessment of diagnostic DNS queries
7

SYNOPSIS

9       dnsviz graph [ options ] [ domain_name... ]
10

DESCRIPTION

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
18       The  source  of  the  diagnostic query input is either a file specified
19       with -r or standard input.
20
21       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
28       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
33       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
39       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
43

OPTIONS

45       -f, --names-file filename
46              Read names from a file (one name per line), instead of from com‐
47              mand line.
48
49              If  this  option is used, then names may not be specified on the
50              command line.
51
52       -r, --input-file filename
53              Read diagnostic query input from the specified file, instead  of
54              from standard input.
55
56       -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
61              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
65              This option may be used multiple times on the command line.
66
67       -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
75       -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
84       -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
93       -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
98       -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
107       -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
112       -e, --redundant-edges
113              Do not remove redundant RRSIG edges from the graph.
114
115              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
119       -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
123              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
127       -o, --output-file filename
128              Write  the  output  to the specified file instead of to standard
129              output, which is the default.
130
131              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
136       -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
141       -h, --help
142              Display the usage and exit.
143
144

OUTPUT

146       The conventions used in the graphical format are described below.
147
148
149   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
154
155   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
161
162       insecure
163              A black, solid line between zones indicates a standard, insecure
164              delegation (i.e., sans DNSSEC).
165
166
167       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
172
173       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
178
179       secure If the delegation is secure by DNSSEC standards, then  then  the
180              delegation is represented by a solid, blue line.
181
182
183       bogus  If  the  delegation  is bogus by DNSSEC standards, then then the
184              delegation is represented by a dashed, red line.
185
186
187   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
194       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
198
199   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
203
204   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
209       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
212
213       valid  A solid, blue line between DNAME node and CNAME  node  indicates
214              that the DNAME expansion was valid.
215
216
217       invalid
218              A  solid,  red  line between DNAME node and CNAME node indicates
219              that the DNAME expansion was invalid.
220
221
222   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
229       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
235
236   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
240       In  DNSViz,  each DNSKEY RR is represented as an elliptical node in the
241       zone to which it belongs.
242
243       Each DNSKEY node is decorated based on the  attributes  of  the  corre‐
244       sponding DNSKEY RR.
245
246
247       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
251              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
256
257       revoke bit
258              A thick border indicates that the revoke bit is set in the flags
259              field of the DNSKEY RR.
260
261              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
269
270       trust anchor
271              A double border indicates that the DNSKEY has been designated as
272              a trust anchor.
273
274              A  trust  anchor  must  be  self-signing (i.e., used to sign the
275              DNSKEY RRset).
276
277
278   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
284       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
289
290       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
294
295       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
300
301       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
306              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
313
314       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
321
322       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
327
328       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
334
335   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
341       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
348       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
352
353       valid  If the edge is solid blue, then the NSEC or NSEC3  RRs  returned
354              prove the validity of the negative response.
355
356
357       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
362
363       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
368       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
372       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
377       NSEC3  records  with the opt-out flag set are colored with a gray back‐
378       ground.
379
380
381   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
388       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
392
393       valid  A solid blue edge indicates that an RRSIG is valid.
394
395
396       invalid signature
397              A solid red edge indicates an RRSIG in which  the  cryptographic
398              signature is invalid.
399
400
401       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
406
407       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
413              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
419
420       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
427
428       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
434
435       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
444
445       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
452       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
459       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
467       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
471       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
476       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
481
482   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
489       DNSViz  represents  wildcards by displaying both the wildcard RRset and
490       the NSEC or NSEC3 proof.
491
492
493   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
504       The status of a node is reflected in the color of its outline.
505
506
507       secure Nodes with blue outline indicate  that  they  are  secure,  that
508              there is an unbroken chain of trust from anchor to RRset.
509
510
511       bogus  Nodes  with  red  outline indicate that they are bogus, that the
512              chain of trust from an anchor has been broken.
513
514              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
524
525       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
531
532   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
536       Similarly, the warning icon is displayed alongside edges  whose  repre‐
537       sented data has warnings.
538
539       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
543       Similarly,  the  error  icon  is displayed alongside edges whose repre‐
544       sented data has errors.
545
546       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
550       An error icon with an italicized label denotes a response error,  e.g.,
551       due to timeout, malformed response, or invalid RCODE.
552
553

EXIT CODES

555       The exit codes are:
556
557       0      Program terminated normally.
558
559       1      Incorrect usage.
560
561       2      Required package dependencies were not found.
562
563       3      There was an error processing the input or saving the output.
564
565       4      Program execution was interrupted, or an unknown error occurred.
566

SEE ALSO

568       dnsviz(1),  dnsviz-probe(1),  dnsviz-grok(1),  dnsviz-print(1), dnsviz-
569       query(1)
570
571
572
5730.9.3                             11 Mar 2021                  dnsviz-probe(1)
Impressum