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
	      Use  trusted  keys from the specified file when 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.

       -C     Enforce DNS cookies strictly. Require a server to	return a "BAD-
	      COOKIE" response when a query contains a COOKIE option  with  no
	      server cookie or with an invalid server cookie.

       -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.

       -e     Do not remove redundant RRSIG edges from the graph.

	      As described in "RRSIGs",	some edges representing	RRSIGs made by
	      KSKs are removed from the	graph to reduce	visual complexity.  If
	      this option is used, those edges are preserved.

       -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
	      Use the specified	output format for  the	graph,	selected  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 occurred.

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

0.8.2				  12 Mar 2019		       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.2-RELEASE+and+Ports>

home | help