Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dnsviz-probe(1)		    General Commands Manual	       dnsviz-probe(1)

NAME
       dnsviz-graph - graph the	assessment of diagnostic DNS queries

SYNOPSIS
       dnsviz graph [ options ]	[ domain_name... ]

DESCRIPTION
       Process	the  results  of  diagnostic DNS queries previously performed,
       e.g., using dnsviz-probe(1), to assess the health of the	associated DNS
       deployments  for	 one  or  more domain names specified.	The results of
       this processing are presented in	one of several graphical  formats  for
       user diagnostics.

       The  source  of	the  diagnostic	query input is either a	file specified
       with -r or standard input.

       Domain names to be processed may	be passed either as command-line argu-
       ments, in a file	(using the -f option), or simply implied using the di-
       agnostic	query input.  The latter is the	preferred methodology (and the
       simplest) and is	useful,	except in cases	where the input	contains diag-
       nostic queries for multiple domain names, only a	subset of which	are to
       be processed.

       If -f is	not used and no	domain names are supplied on the command line,
       then the	domain names to	be processed are extracted from	the diagnostic
       query input.  If	the -f option is used, then names may not be specified
       on the command line.

       The domain names	passed as input	are fully-qualified domain names, such
       as  example.com,	 www.example.com, _443._tcp.example.com, 1.2.0.192.in-
       addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa.	Because	 it  is	 implied  that
       specified  domain  names	are fully qualified, no	trailing dot is	neces-
       sary.

       The graphical output is the image of a  directed	 graph	created	 using
       dot(1).	 The  "html"  format  makes this image interactive using java-
       script libraries	that are distributed with this software.

OPTIONS
       -f filename
	      Read names from a	file (one name per line), instead of from com-
	      mand line.

	      If  this	option is used,	then names may not be specified	on the
	      command line.

       -r filename
	      Read diagnostic query input from the specified file, instead  of
	      from standard input.

       -t filename
	      Specify  a  file that contains trusted keys for processing diag-
	      nostic queries.  This overrides the default  behavior  of	 using
	      the installed keys for the root zone.

	      The  format  of  this file is master zone	file format and	should
	      contain DNSKEY records that correspond to	one more trusted  keys
	      for one or more DNS zones.

	      This option may be used multiple times on	the command line.

       -R type[,type...]
	      Process  queries	of only	the specified type(s) (e.g., A,	AAAA).
	      The default is to	process	all types queried as part of the diag-
	      nostic input.

       -O     Save the output to a file, whose name is derived from the	format
	      (i.e., provided to -T) and the domain name.

	      If this option is	used when the diagnostic queries  of  multiple
	      domain  names  are  being	 processed, a file will	be created for
	      each domain name processed.

       -o filename
	      Write the	output to the specified	file instead  of  to  standard
	      output, which is the default.

	      If  this	option is used when the	diagnostic queries of multiple
	      domain name are being processed, a single	file (the  one	speci-
	      fied)  will be created, which will contain the collective	output
	      for all domain names processed.

       -T format
	      Specify the format of  the  format  from	among  the  following:
	      "dot", "png", "jpg", "svg", and "html".  The default is "dot".

       -h     Display the usage	and exit.

OUTPUT
       The conventions used in the graphical format are	described below.

   Zones
       Nodes  in DNSViz	are clustered by the zone to which the represented in-
       formation belongs.  Each	zone is	labeled	with the name of the zone ori-
       gin and the time	at which the zone was last analyzed.

   Delegations
       Thick lines between zones denote	delegations of namespace from one zone
       to another, as indicated	by the presence	of NS (name  server)  resource
       records	(RRs)  for the delegated namespace.  The status	of the delega-
       tion is reflected in its	color and style	of the edge.

       insecure
	      A	black, solid line between zones	indicates a standard, insecure
	      delegation (i.e.,	sans DNSSEC).

       lame   If the designated	name servers for a zone	cannot not be properly
	      resolved or if the servers do not	properly respond  to  queries,
	      then  the	 delegation is considered lame and is represented by a
	      dashed, yellow line.

       incomplete
	      If the delegation	is incomplete, as indicated by the presence of
	      NS  records  in the zone itself but not in its parent zone, then
	      the delegation is	represented by a dashed, yellow	line.

       secure If the delegation	is secure by DNSSEC standards, then  then  the
	      delegation is represented	by a solid, blue line.

       bogus  If  the  delegation  is bogus by DNSSEC standards, then then the
	      delegation is represented	by a dashed, red line.

   RRsets
       Resource	record sets (RRsets) returned in the response (usually in  the
       answer  section)	are represented	as rectangular nodes with rounded cor-
       ners.  Among the	most common record types are SOA (start	of authority),
       A  (IPv4	 address),  AAAA (IPv6 address), MX (mail exchange), and CNAME
       (canonical name).

       RRsets that are specific	to DNSSEC, such	as the DNSKEY, DS, RRSIG, NSEC
       and  NSEC3  RR types, are represented as	other node types, as specified
       elsewhere in this guide.

   Aliases
       Aliases resulting from CNAME RRs	are represented	by a black  edge  from
       one RRset (with the alias name) to another (with	the canonical name).

   DNAME
       A  DNAME	 RR  is	used to	alias an entire	namespace into another.	 DNAME
       responses include synthesized CNAME RRs for the	aliasing  directed  by
       the DNAME RR.

       DNAME  records are shown	in DNSViz with their respective	CNAME records.
       The status of the CNAME synthesis is reflected color of the edge.

       valid  A	solid, blue line between DNAME node and	CNAME  node  indicates
	      that the DNAME expansion was valid.

       invalid
	      A	 solid,	 red  line between DNAME node and CNAME	node indicates
	      that the DNAME expansion was invalid.

   Negative Responses
       If the response to a query is a name error  (NXDOMAIN),	this  negative
       response	 is  represented by a rectangular node with diagonals drawn at
       each corner, and	with a dashed border, lighter in color.	 A node	repre-
       senting	the  SOA RR returned in	the negative response (if any) is also
       included.

       If the response to a query has a	NOERROR	status but contains no	answer
       data (NO	DATA) for the type, this negative response is represented by a
       rectangular node	with  rounded  corners,	 and  with  a  dashed  border,
       lighter in color.  A node representing the SOA RR returned in the nega-
       tive response (if any) is also included.

   DNSKEY RRs
       DNSKEY RRs include public key and meta information to enable  resolvers
       to validate signatures made by the corresponding	private	keys.

       In  DNSViz,  each DNSKEY	RR is represented as an	elliptical node	in the
       zone to which it	belongs.

       Each DNSKEY node	is decorated based on the  attributes  of  the	corre-
       sponding	DNSKEY RR.

       SEP bit
	      A	 gray  fill indicates that the Secure Entry Point (SEP)	bit is
	      set in the flags field of	the DNSKEY RR.

	      This bit is typically used to designate a	DNSKEY for usage as  a
	      key  signing key (KSK), a	DNSKEY that is used to sign the	DNSKEY
	      RRset of a zone, providing a secure entry	point into a zone  via
	      DS RRs or	a trust	anchor at the resolver.

       revoke bit
	      A	thick border indicates that the	revoke bit is set in the flags
	      field of the DNSKEY RR.

	      Resolvers	which implement	the trust anchor  rollover  procedures
	      documented in RFC	5011 recognize the revoke bit as a signal that
	      the DNSKEY should	no longer be used as a trust anchor by the re-
	      solver.	For  a	DNSKEY to be properly revoked, it must also be
	      self-signing (i.e., used to sign the DNSKEY RRset), which	proves
	      that  the	 revocation was	made by	a party	that has access	to the
	      private key.

       trust anchor
	      A	double border indicates	that the DNSKEY	has been designated as
	      a	trust anchor.

	      A	 trust	anchor	must  be  self-signing (i.e., used to sign the
	      DNSKEY RRset).

   DS RRs
       DS (delegation signer) RRs exist	in the parent of a signed zone to  es-
       tablish a SEP into the zone.  Each DS RR	specifies an algorithm and key
       tag corresponding to a DNSKEY RR	in the	signed	zone  and  includes  a
       cryptographic hash of that DNSKEY RR.

       In  DNSViz  DS RRs with the same	DNSKEY algorithm and key tag are typi-
       cally displayed as a single node	since they usually correspond  to  the
       same  DNSKEY RR with different digest algorithms.  The status of	the DS
       RRs is reflected	in the color and style of the edge.

       valid  A	blue-colored arrow pointing from DS to DNSKEY  indicates  that
	      the  digest contained in each of the DS RRs is valid, and	corre-
	      sponds to	an existing DNSKEY.

       invalid digest
	      A	solid red line from DS to DNSKEY indicates that	a  DNSKEY  ex-
	      ists  matching  the  algorithm and key tag of the	DS RR, but the
	      digest of	the DNSKEY in the DS RR	does not match.

       indeterminate - no DNSKEY
	      A	dashed gray line from DS to a DNSKEY with a dashed gray	border
	      indicates	 that  no DNSKEY matching the algorithm	and key	tag of
	      the DS RR	exists in the child zone.

	      Extraneous DS RRs	in a parent zone do not, in and	of themselves,
	      constitute  an  error.  For example, sometimes they are deliber-
	      ately pre-published before their corresponding DNSKEYs, as  part
	      of  a  key rollover.  However, for every DNSSEC algorithm	in the
	      DS RRset for the child zone, a matching DNSKEY must be  used  to
	      sign the DNSKEY RRset in the child zone, as per RFC 4035.

       indeterminate - match pre-revoke
	      A	 special  case	of a DS	with no	matching DNSKEY	is when	the DS
	      matched a	DNSKEY prior to	its revocation,	but the	 ramifications
	      are the same as if it didn't match any DNSKEY.  The line is sim-
	      ply drawn	to help	identify the cause of the otherwise  non-exis-
	      tent DNSKEY.

       indeterminate - unknown algorithm
	      When  the	 algorithm  and	 key  tag  of a	DS RR match those of a
	      DNSKEY RR, but the digest	algorithm is unknown  or  unsupported,
	      then the line between DS and DNSKEY is yellow.

       invalid
	      When the use of a	DS corresponding to a DNSKEY is	invalid, inde-
	      pendent of the correctness of its	digest,	the  line  between  DS
	      and  DNSKEY  is red and dashed.  An example scenario is when the
	      DNSKEY has the revoke bit	set, which is disallowed by RFC	5011.

   NSEC/NSEC3 RRs
       NSEC and	NSEC3 RRs are used within DNSSEC to prove the legitimacy of  a
       negative	 response  (i.e., NXDOMAIN or NO DATA) using authenticated de-
       nial of existence or hashed authenticated denial	of existence,  respec-
       tively.

       In  DNSViz the NSEC or NSEC3 RR(s) returned by a	server to authenticate
       a negative response are represented by a	rectangular node with  several
       compartments.  The  bottom  compartment	is labeled with	either NSEC or
       NSEC3, depending	on the type of record. Each compartment	on the top row
       represents  an  NSEC  or	NSEC3 record in	the set--there will be between
       one and three.

       An edge extends from the	NSEC or	NSEC3 node to the corresponding	 nega-
       tive  response.	 Its status is reflected in the	color and style	of the
       edge.

       valid  If the edge is solid blue, then the NSEC or NSEC3	 RRs  returned
	      prove the	validity of the	negative response.

       invalid
	      A	solid red edge from the	NSEC or	NSEC3 node to the negative re-
	      sponse indicates that the	NSEC or	NSEC3 RRs included in  in  the
	      response do not prove the	validity of the	negative response.

       A  special  case	of NSEC/NSEC3 RRs is that in which they	serve to prove
       the non-existence of Delegation Signer (DS) records.  The proof of  ab-
       sence  of  DS  records constitutes an insecure delegation, in which any
       trust at	the parent zone	does not propagate to the child	zone.

       The NSEC/NSEC3 proof involving DS records  is  graphically  represented
       with an edge from the NSEC/NSEC3	node to	the box	representing the child
       zone.

       The opt-out flag	is set in NSEC3	RRs to indicate	that their presence is
       only  sufficient	 to  prove  insecure  delegations  (i.e.,  lack	 of DS
       records)	and nothing more.  Thus, a name	error (NXDOMAIN) response, for
       example,	cannot be securely proven when the NSEC3 uses opt-out.

       NSEC3  records  with the	opt-out	flag set are colored with a gray back-
       ground.

   RRSIGs
       Each RRSIG RR contains the cryptographic	signature  made	 by  a	DNSKEY
       over an RRset.  Using the DNSKEY	with the same algorithm	and key	tag as
       the RRSIG, the RRset which was signed, and the RRSIG itself, a resolver
       may  determine  the  correctness	 of the	signature and authenticate the
       RRset.

       In DNSViz RRSIGs	are represented	as directed edges from the DNSKEY that
       made  the  signature  to	 the RRset that	was signed.  The status	of the
       edge is reflected in its	color and style.

       valid  A	solid blue edge	indicates that an RRSIG	is valid.

       invalid signature
	      A	solid red edge indicates an RRSIG in which  the	 cryptographic
	      signature	is invalid.

       expired or premature
	      A	 solid	purple edge indicates that an RRSIG is invalid because
	      it is outside its	validity period, as defined by	the  inception
	      and expiration date fields in the	RRSIG RR.

       indeterminate - no DNSKEY
	      A	 dashed	 gray  line  stemming from a DNSKEY with a dashed gray
	      border indicates that no DNSKEY matching the algorithm  and  key
	      tag  of  the RRSIG RR could be found in the DNSKEY RRset (or the
	      DNSKEY RRset could not be	retrieved).

	      Extraneous RRSIG RRs do not, in and of themselves, constitute an
	      error.  For  example,  sometimes	they are deliberately pre-pub-
	      lished before their corresponding	DNSKEYs, as part of  an	 algo-
	      rithm  rollover.	However, every RRset must be covered by	RRSIGs
	      for every	algorithm in the DNSKEY	RRset, as per RFC 4035.

       indeterminate - match pre-revoke
	      A	special	case of	an RRSIG with no matching DNSKEY is  when  the
	      RRSIG  matched a DNSKEY prior to its revocation, but the ramifi-
	      cations are the same as if it didn't match any DNSKEY.  The line
	      is simply	drawn to help identify the cause of the	otherwise non-
	      existent DNSKEY.

       indeterminate - unknown algorithm
	      When the algorithm and key tag of	an RRSIG RR match those	 of  a
	      DNSKEY  RR,  but the cryptographic algorithm associated with the
	      RRSIG is unknown or unsupported, then the	line stemming from the
	      DNSKEY is	yellow.

       invalid
	      When  an RRSIG is	invalid, independent of	the correctness	of its
	      temporal validity	period and its	cryptographic  signature,  the
	      line  stemming  from the DNSKEY is red and dashed.  Example sce-
	      narios might be when the DNSKEY has the revoke bit set  or  when
	      the  signer field	in the RRSIG RR	does not match the name	of the
	      zone apex.  Such scenarios are disallowed	by RFCs	5011 and 4035,
	      respectively.

       Just  like  other  RRsets,  a DNSKEY RRset is signed as an RRset, which
       comprises all the collective DNSKEY RRs at the zone apex.  Because each
       DNSKEY  RR  is represented as a node in DNSViz, a single	RRSIG covering
       the DNSKEY RRset	is represented by edges	drawn from the node represent-
       ing the signing DNSKEY to the nodes representing	every DNSKEY RR	in the
       set.

       In some DNSSEC implementations, multiple	DNSKEYs	sign the DNSKEY	RRset,
       even  though  only a subset are designated to provide secure entry into
       the zone	(e.g., via matching DS records in  the	parent	zone).	 While
       there  is nothing inherently wrong with this configuration, graphically
       representing such scenarios can be visually complex because of the  cy-
       cles and	redundancy created in the graph.

       In order	to represent trust propagation in a simplified fashion,	elimi-
       nating graphic redundancies, DNSViz exhibits  the  following  behavior.
       For  every  DNSKEY  signing  the	 DNSKEY	RRset, a self-directed edge is
       added to	the node, indicating that the DNSKEY is	 self-signing.	 Addi-
       tionally,  if  the  DNSKEY is designated	as a (SEP) into	the zone, then
       edges are drawn from its	node to	nodes representing  all	 other	DNSKEY
       RRs in the DNSKEY RRset.

       If  there  is  no  true SEP, (e.g., no DS RRs in	the parent zone), then
       SEP(s) are inferred based on their signing role	(e.g.,	siging	DNSKEY
       RRset or	other RRsets) and properties (e.g., SEP	bit).

       Like  the  DNSKEY RRset,	a single DS RRset might	be represented as sev-
       eral different nodes.  As such a	single RRSIG covering the DS RRset  is
       represented  by	edges  drawn  from  the	 node representing the signing
       DNSKEY to the nodes representing	every DS RR in the set.

       Because an NSEC or NSEC3	node represents	one  or	 more  RRsets  and  at
       least  one RRSIG	per RRset is anticipated, multiple RRSIG edges will be
       drawn from DNSKEY to NSEC or NSEC3 nodes, each pointing to the  respec-
       tive compartment	corresponding to the NSEC or NSEC3 record.

   Wildcards
       When  the RRSIG covering	an RRset has a labels field with value greater
       than the	number of labels in the	name, it is indicative	that  the  re-
       sulting	RRset was formed by a wildcard expansion.  The server must ad-
       ditionally include an NSEC or NSEC3 proof that the name	to  which  the
       wildcard	is expanded does not exist.

       DNSViz  represents  wildcards by	displaying both	the wildcard RRset and
       the NSEC	or NSEC3 proof.

   Node	Status
       Beginning at the	DNSKEYs	designated as trust anchors, DNSViz  traverses
       the nodes and edges in the graph	to classify each node as having	one of
       three DNSSEC statuses, depending	on the status of the  RRset  which  it
       represents:  secure, bogus, or insecure.	 In DNSViz, node status	is in-
       dicated by the color of the nodes (Note that there isn't	always a  one-
       to-one mapping between node and RRset, but the node status will be con-
       sistent among all nodes comprising an RRset.  An	example	is the	DNSKEY
       nodes for a zone, which all have	the same status	even though the	DNSKEY
       RRset is	split among different nodes).

       The status of a node is reflected in the	color of its outline.

       secure Nodes with blue outline indicate	that  they  are	 secure,  that
	      there is an unbroken chain of trust from anchor to RRset.

       bogus  Nodes  with  red	outline	indicate that they are bogus, that the
	      chain of trust from an anchor has	been broken.

	      Because the NSEC and NSEC3 nodes often represent	multiple  NSEC
	      or NSEC3 RRs, it is possible that	a proper subset	of the RRs are
	      secure, while others in the set are not (e.g.,  missing  or  ex-
	      pired  RRSIG).   In  this	 case, the outline of the compartments
	      representing secure NSEC or NSEC3	 RRs  will  be	colored	 blue,
	      while the	others will be red.  Because the status	of the collec-
	      tive set of NSEC and NSEC3 RRs is	dependent on the status	of all
	      the individual NSEC and NSEC3 RRs, the greater node is only col-
	      ored blue	if all the compartments	are colored blue.

       insecure
	      Nodes with black outline indicate	that they are  insecure,  that
	      no  chain	of trust exists; if any	anchors	exist then an insecure
	      delegation is demonstrated to prove that no chain	 should	 exist
	      from the anchors.	 This is equivalent to DNS without DNSSEC.

   Warnings and	Errors
       If  one	or  more  warnings are detected	with the data represented by a
       node in the graph, then a warning icon is displayed in the node.

       Similarly, the warning icon is displayed	alongside edges	 whose	repre-
       sented data has warnings.

       If one or more errors (more severe than warnings) are detected with the
       data represented	by a node in the graph,	then an	 error	icon  is  dis-
       played in the node.

       Similarly,  the	error  icon  is	displayed alongside edges whose	repre-
       sented data has errors.

       A warning icon with an italicized label denotes a  warning  for	a  re-
       sponse  that isn't represented elsewhere	in the graph, such as a	refer-
       ral with	the authoritative answer flag set.

       An error	icon with an italicized	label denotes a	response error,	 e.g.,
       due to timeout, malformed response, or invalid RCODE.

EXIT CODES
       The exit	codes are:

       0      Program terminated normally.

       1      Incorrect	usage.

       2      Required package dependencies were not found.

       3      There was	an error processing the	input or saving	the output.

       4      Program execution	was interrupted, or an unknown error ocurred.

SEE ALSO
       dnsviz(1),  dnsviz-probe(1),  dnsviz-grok(1),  dnsviz-print(1), dnsviz-
       query(1)

0.6.5				  18 Nov 2016		       dnsviz-probe(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT | EXIT CODES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dnsviz-graph&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help