Provided by: dnsviz_0.8.0-1_all bug

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 arguments, in a file
       (using the -f option), or simply implied using the diagnostic query input.  The latter  is
       the  preferred  methodology  (and  the  simplest) and is useful, except in cases where the
       input contains diagnostic 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 necessary.

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

OPTIONS

       -f filename
              Read names from a file (one name per line), instead of from command 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 diagnostic 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 "BADCOOKIE" 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 diagnostic 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 specified)  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  information  belongs.
       Each  zone  is labeled with the name of the zone origin 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 delegation 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 corners.  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  representing  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 negative 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 corresponding 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 resolver.  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 establish  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 typically 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 corresponds to an existing DNSKEY.

       invalid digest
              A  solid  red  line  from  DS to DNSKEY indicates that a DNSKEY exists 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 deliberately 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 simply drawn to help identify the cause of  the  otherwise
              non-existent 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, independent 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  denial  of  existence  or  hashed
       authenticated denial of existence, respectively.

       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 negative  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  response  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  absence  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 background.

   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-published before their corresponding
              DNSKEYs, as part of an algorithm 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 ramifications 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 scenarios 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 representing 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 cycles  and
       redundancy created in the graph.

       In  order  to  represent  trust  propagation  in a simplified fashion, eliminating 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.  Additionally, 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 several 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  respective 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 resulting RRset was formed by a wildcard
       expansion.  The server must additionally 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  indicated 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  consistent  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  expired  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 collective set of NSEC and NSEC3 RRs
              is  dependent  on  the status of all the individual NSEC and NSEC3 RRs, the greater
              node is only colored 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  represented  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 displayed in the node.

       Similarly, the error icon is displayed alongside edges whose represented data has errors.

       A warning icon with an italicized label denotes  a  warning  for  a  response  that  isn't
       represented  elsewhere in the graph, such as a referral 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)