Zonemaster/doc/ConfigAndPolicy.pod
=head1 OVERVIEW
At the moment, the configuration system is exceedingly simple: it's just a JSON-serialized hash stored as data in the L<Zonemaster::Config> module.
Eventually, this will be changed to loading a file and providing the ability for local overrides of defaults.
The policy data is already distributed as and loaded from an external JSON file. There isn't yet any ability to override policy data, or specify
alternatives.
=head1 CONFIGURATION
The configuration data is a nested hash. These are the keys that will be looked for and used.
=over
=item resolver
These are settings for the resolver objects used to send and receive DNS queries.
=over
=item defaults
These are the default values used when creating new resolver objects.
=over
=item usevc
If this flag is true, queries will be sent over TCP. Defaults to false.
=item retrans
The number of seconds to wait for a response before re-sending a query.
=item dnssec
If this flag is true, the C<DO> flag will be set in outgoing queries.
=item debug
If this flag is true, large amounts of debugging data will be printed.
=item recurse
If this flag is true, the C<RD> flag will be set in outgoing queries.
=item udp_timeout
The number seconds to wait for a response to queries sent over UDP. Defaults to 15.
=item tcp_timeout
The number seconds to wait for a response to queries sent over TCP. Defaults to 15.
=item retry
The number of times a query will be sent before the resolver gives up and returns an error. Defaults to 2.
=item igntc
If this flag is false, UDP queries that get responses with the C<TC> flag set will be automatically resent over TCP.
=back
=back
=back
=head1 POLICY
The policy data is also a nested hash. The top-level keys are upper-case-only versions of test module names, and under them is all the policy data
for that particular module. The keys in the next level down are, with one exception, logger tags. The exception is the special key C<DISABLED>,
which if given a true value will prevent the module from being executed. In the standard configuration, this key is set for the C<Example> module.
The values for the tag keys should be the severity level for that tag. For example, under the C<BASIC> top-level key (for the 'Basic' test module),
there is a key C<NO_GLUE>. That tag will be emitted by the code in the L<Zonemaster::Test::Basic> module if it fails to get NS records for the zone
being tested from its parent zone. Since that is an error that prevents further testing, the message is given the severity level C<CRITICAL>.
=head2 The Severity Levels
Zonemaster uses six severity levels. They are as follows, in order from the most severe to the least severe.
=over
=item CRITICAL
This level is intended for problems that are so severe that their effects is to basically render the zone in question impossible to look up. Zones
with CRITICAL problems do not, for practical purposes, exist.
=item ERROR
This level is intended for problems that can cause problems that directly impact end users. The effect may be an inability to resolve records in
the zone, an inability to cryptographically verify its legitimacy (with DNSSEC) or things in that vein.
=item WARNING
This level is intended for problems that can cause problems that are less noticeable for end users, or that are only noticeable with less common
name resolution software.
=item NOTICE
This level is intended for problems that are unlikely to be noticed by end users. This may bey things like violations of less-used standards,
timing values outside the recommended bounds, and other things along those lines.
=item INFO
This level is for messages that do not indicate problems, but that hold information that may be interesting to the person running the test.
=item DEBUG
This level is for messages that should not normally hold any interest for the person running the test.
=back
=cut