dnsviz-probe(1) User Commands dnsviz-probe(1)
dnsviz-graph - graph the assessment of diagnostic DNS queries
dnsviz graph [ options ] [ domain_name... ]
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.
-f, --names-file 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, --input-file filename
Read diagnostic query input from the specified file, instead
of from standard input.
-t, --trusted-keys-file 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.
-a, --algorithms alg[,alg...]
Support only the DNSSEC algorithms specified. If this option
is used, any algorithms not specified will appear as
"unsupported." The status of any RRSIG records corresponding
to unsupported algorithms will be unknown. Additionally, when
a zone has only DS records with unsupported algorithms, the
zone is treated as "insecure", assuming the DS records are
properly authenticated.
-d, --digest-algorithms digest_alg[,digest_alg...]
Support only the DNSSEC digest algorithms specified. If this
option is used, any digest algorithms not specified will
appear as "unsupported." The status of any DS records
corresponding to unsupported digest algorithms will be
unknown. Additionally, when a zone has only DS records with
unsupported digest algorithms, the zone is treated as
"insecure", assuming the DS records are properly
authenticated.
--ignore-rfc8624
Ignore errors associated with RFC 8624, DNSSEC algorithm
implementation requirements. RFC 8624 designates some DNSSEC
signing algorithms and some DS digest algorithms as prohibited
("MUST NOT") or not recommended for validation and/or signing.
If this option is used, then no warnings will be issued, and
the code will still assess their cryptographic status, rather
than ignoring them.
--ignore-rfc9276
Ignore errors associated with RFC 9276, NSEC3 parameter
settings. RFC 9276 specifies that if NSEC3 is used, the
iterations count must be 0 and the salt length must be 0. If
this option is used, then no warnings will be issued for NSEC3
records that violate this specification.
-C, --enforce-cookies
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.
-P, --allow-private
Allow private IP addresses for authoritative DNS servers. By
default, if the IP address corresponding to an authoritative
server is in IP address space designated as "private", it is
flagged as an error. However, there are some cases where this
is allowed. For example, if the diagnostic queries are issued
to servers in an experimental environment, this might be
permissible.
--trust-cdnskey-cds
Trust all CDNSKEY and CDS records, even if they are not
"signed with a key that is represented in both the current
DNSKEY and DS RRsets" (RFC 7344). This is allowed if "the
Parent uses the CDS or CDNSKEY RRset for initial enrollment;
in that case, the Parent validates the CDS/CDNSKEY through
some other means" (RFC 7344). Because there is no way for
DNSViz to discover the out-of-band means with which the parent
might have validated the CDNSKEY and/or CDS records, this
trust is signaled with the use of the --trust-cdnskey-cds
command-line option.
--multi-signer
Don't issue errors for missing KSKs with DS RRs. Typically an
error is issued if a given DNSKEY is not found in the DNSKEY
RRset returned by one or more servers. If --multi-signer is
specified, then no error is issued, in the case that 1) the
DNSKEY is not signing any non-DNSKEY RRsets (i.e., is a zone-
signing key or ZSK) and 2) the DNSKEY corresponds to a DS
record in the parent. This corresponds to the Model 2 use
case in RFC 8901.
-R, --rr-types 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, --redundant-edges
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, --derive-filename
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, --output-file 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, --output-format 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, --help
Display the usage and exit.
The conventions used in the graphical format are described below.
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.
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 the
delegation is represented by a solid, blue line.
bogus If the delegation is bogus by DNSSEC standards, then the
delegation is represented by a dashed, red line.
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 resulting from CNAME RRs are represented by a black edge from
one RRset (with the alias name) to another (with the canonical name).
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.
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 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 (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.
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 and RFC 6840.
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., signing 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.
CDNSKEY/CDS RRsets
CDNSKEY and CDS records are used by the child zone to signal to its
parent the DS record(s) that it desires to be published, per RFC
7344. The CDNSKEY and CDS RRsets are represented as any other RRset
(see "RRsets"); that is, there is a single node per RRset, as opposed
to a single node per CDNSKEY or CDS record.
CDNSKEY and CDS RRsets are mapped to the DNSKEYs they correspond to
with a gray edge from the CDNSKEY or CDS RRset to the DNSKEY node(s).
If the DNSKEY referenced does not exist, the DNSKEY node is
represented with a dashed gray border (see "DNSKEY RRs" and "DS
RRs").
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.
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.
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.
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.
dnsviz(1), dnsviz-probe(1), dnsviz-grok(1), dnsviz-print(1),
dnsviz-query(1)
0.11.1 21 April 2025 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
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, --names-file 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, --input-file filename
Read diagnostic query input from the specified file, instead
of from standard input.
-t, --trusted-keys-file 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.
-a, --algorithms alg[,alg...]
Support only the DNSSEC algorithms specified. If this option
is used, any algorithms not specified will appear as
"unsupported." The status of any RRSIG records corresponding
to unsupported algorithms will be unknown. Additionally, when
a zone has only DS records with unsupported algorithms, the
zone is treated as "insecure", assuming the DS records are
properly authenticated.
-d, --digest-algorithms digest_alg[,digest_alg...]
Support only the DNSSEC digest algorithms specified. If this
option is used, any digest algorithms not specified will
appear as "unsupported." The status of any DS records
corresponding to unsupported digest algorithms will be
unknown. Additionally, when a zone has only DS records with
unsupported digest algorithms, the zone is treated as
"insecure", assuming the DS records are properly
authenticated.
--ignore-rfc8624
Ignore errors associated with RFC 8624, DNSSEC algorithm
implementation requirements. RFC 8624 designates some DNSSEC
signing algorithms and some DS digest algorithms as prohibited
("MUST NOT") or not recommended for validation and/or signing.
If this option is used, then no warnings will be issued, and
the code will still assess their cryptographic status, rather
than ignoring them.
--ignore-rfc9276
Ignore errors associated with RFC 9276, NSEC3 parameter
settings. RFC 9276 specifies that if NSEC3 is used, the
iterations count must be 0 and the salt length must be 0. If
this option is used, then no warnings will be issued for NSEC3
records that violate this specification.
-C, --enforce-cookies
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.
-P, --allow-private
Allow private IP addresses for authoritative DNS servers. By
default, if the IP address corresponding to an authoritative
server is in IP address space designated as "private", it is
flagged as an error. However, there are some cases where this
is allowed. For example, if the diagnostic queries are issued
to servers in an experimental environment, this might be
permissible.
--trust-cdnskey-cds
Trust all CDNSKEY and CDS records, even if they are not
"signed with a key that is represented in both the current
DNSKEY and DS RRsets" (RFC 7344). This is allowed if "the
Parent uses the CDS or CDNSKEY RRset for initial enrollment;
in that case, the Parent validates the CDS/CDNSKEY through
some other means" (RFC 7344). Because there is no way for
DNSViz to discover the out-of-band means with which the parent
might have validated the CDNSKEY and/or CDS records, this
trust is signaled with the use of the --trust-cdnskey-cds
command-line option.
--multi-signer
Don't issue errors for missing KSKs with DS RRs. Typically an
error is issued if a given DNSKEY is not found in the DNSKEY
RRset returned by one or more servers. If --multi-signer is
specified, then no error is issued, in the case that 1) the
DNSKEY is not signing any non-DNSKEY RRsets (i.e., is a zone-
signing key or ZSK) and 2) the DNSKEY corresponds to a DS
record in the parent. This corresponds to the Model 2 use
case in RFC 8901.
-R, --rr-types 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, --redundant-edges
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, --derive-filename
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, --output-file 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, --output-format 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, --help
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 the
delegation is represented by a solid, blue line.
bogus If the delegation is bogus by DNSSEC standards, 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 and RFC 6840.
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., signing 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.
CDNSKEY/CDS RRsets
CDNSKEY and CDS records are used by the child zone to signal to its
parent the DS record(s) that it desires to be published, per RFC
7344. The CDNSKEY and CDS RRsets are represented as any other RRset
(see "RRsets"); that is, there is a single node per RRset, as opposed
to a single node per CDNSKEY or CDS record.
CDNSKEY and CDS RRsets are mapped to the DNSKEYs they correspond to
with a gray edge from the CDNSKEY or CDS RRset to the DNSKEY node(s).
If the DNSKEY referenced does not exist, the DNSKEY node is
represented with a dashed gray border (see "DNSKEY RRs" and "DS
RRs").
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)
0.11.1 21 April 2025 dnsviz-probe(1)