NAME

       Zonemaster::Config - configuration access module for Zonemaster

SYNOPSIS

           Zonemaster->config->no_network(1); # Forbid network traffic

           my $value = Zonemaster::Config->get->{key}{subkey}; # Not really recommended way to access config data

LOADING CONFIGURATION

       Configuration data is loaded in several stages, each one overlaying the result from the
       previous one (that is, the later in the list take priority over the earlier). The first
       stage is hardcoded into the source code and loaded while it is being compiled, to make
       sure that there will always be some basic information available. Later, when the
       configuration object is first used, the system will look for a file named config.json in
       each of a list of directories. If the file exists, is readable and contains proper JSON
       data, it will be loaded and overlaid on the current internal config. The directories are,
       in order from first checked to last:

       The Zonemaster perl module installation directory
           This is where the installation process puts the default configuration. It is not meant
           to be modified by the user, and it will be overwritten when the module is upgraded (or
           reinstalled for any other reason). If you really need to know where it is, you can
           either check the log message left when loading it or run this command to find the
           path:

               perl -MFile::ShareDir=dist_dir -E 'say dist_dir( "Zonemaster" )'

       /etc/zonemaster
           Intended to hold system-global configuration changes.

       /usr/local/etc/zonemaster
           Basically the same as the previous one, but for those who like to keep their locally
           installed software inside /usr/local.

       ~/.zonemaster
           That is, a .zonemaster directory in the home directory of the current user.  Intended,
           obviously, for configuration changes local to one particular user.

       The possible contents of the JSON data is described further down in this manual page.

METHODS FOR CONFIGURATION ITEMS

       no_network([$value])
           Returns the value of the "no_network" flag. If given a defined value, sets the value
           to that value.

       ipv4_ok([$value])
           Returns the value of the "ipv4" flag. If given a defined value, sets the value to that
           value.

       ipv6_ok([$value])
           Returns the value of the "ipv6" flag. If given a defined value, sets the value to that
           value.

       resolver_defaults()
           Returns a reference to the resolver_defaults hash.

       resolver_source([$addr])
           Returns the source address all resolver objects should use when sending queries, if
           one is set. If given an argument, sets the source address to the argument.

       logfilter()
           Returns a reference to the logfilter hash.

       asnroots()
           Returns a reference to the list of ASN lookup domains.

METHODS

       get()
           Returns a reference to a hash with configuration values.

       policy()
           Returns a reference to the current policy data. The format of that data is described
           further down in this document.

       load_policy_file($filename)
           Load policy information from the given file and merge it into the pre-loaded policy.
           Information from the loaded file overrides the pre-loaded information when the same
           keys exist in both places.

           If the given name does not lead directly to a readable file, each of the usual
           directories will be checked if the name is there. If the plain name isn't, the suffix
           ".json" will be appended and another try will be done. For example, a file
           $HOME/.zonemaster/Example.json may be loaded by calling this method with the string
           "Example".

       load_config_file($filename)
           Load configuration information from the given file and merge it into the pre-loaded
           config. Information from the loaded file overrides the pre-loaded information when the
           same keys exist in both places.

       load_module_policy($module)
           Loads policy data included in a test module. The argument must be the short form
           (without the initial "Zonemaster::Test::") and correctly capitalized.

       BUILD
           Internal method only mentioned here to please Pod::Coverage.

       should_run($name)
           Given a test case name, it returns true if that test case should be included in a test
           run according to the currently active policy or false if not.

CONFIGURATION DATA

       The configuration data is stored internally in a nested hash (possibly with arrays as
       values in places). As of this writing, the file format used is JSON.

       The interesting keys are as follows.

   resolver
       defaults

       These are the default flag and timing values used for the resolver objects used to
       actually send DNS queries.

       usevc
           If set, only use TCP. Default not set.

       retrans
           The number of seconds between retries. Default 3.

       dnssec
           If set, sets the DO flag in queries. Default not set.

       recurse
           If set, sets the RD flag in queries. Default not set (and almost certainly should
           remain that way).

       retry
           The number of times a query is sent before we give up. Can be set to zero, although
           that's not very useful (since no queries will be sent at all). Defaults to 2.

       igntc
           If set, queries that get truncated UDP responses will be automatically retried over
           TCP. Default not set.

   net
       ipv4
           If set, resolver objects are allowed to send queries over IPv4. Default set.

       ipv6
           If set, resolver objects are allowed to send queries over IPv6. Default set.

   no_network
       If set to a true value, network traffic is forbidden. Use when you want to be sure that
       any data is only taken from a preloaded cache.

   asnroots
       This key must be a list of domain names. The domains will be assumed to be Cymru-style AS
       lookup zones. Normally only the first name in the list will be used, the rest are backups
       in case the earlier ones don't work.

   logfilter
       By using this key, the log level of messages can be set in a much more fine-grained way
       than by the policy file. The intended use is to remove known erroneous results. If you,
       for example, know that a certain name server is recursive and for some reason should be,
       you can use this functionality to lower the severity of the complaint about it to a lower
       level than normal.

       The the data under the "logfilter" key should be structured like this:

          Module
             Tag
                "when"
                   Hash with conditions
                "set"
                   Level to set if all conditions match

       The hash with conditions should have keys matching the attributes of the log entry that's
       being filtered (check the translation files to see what they are). The values for the keys
       should be either a single value that the attribute should be, or an array of values any
       one of which the attribute should be.

       A complete entry might could look like this:

              "SYSTEM": {
                  "FILTER_THIS": {
                      "when": {
                          "count": 1,
                          "type": ["this", "or"]
                      },
                      "set": "INFO"
                  }
              }

       This would set the level to "INFO" for any "SYSTEM:FILTER_THIS" messages that had a
       "count" attribute set to 1 and a "type" attribute set to either "this" or "or".

POLICY DATA

       Like the configuration data, policy data is stored in JSON format. Structurally, it's a
       bit less complex. All the keys on the top level, with one exception, are names of test
       implementation modules (without the "Zonemaster::Test::" prefix). Each of those keys hold
       another hash, where the keys are the tags that the module in question can emit and the
       values are the the severity levels that should apply to the tags. Any tags that are not
       found in the policy data will default to level "DEBUG".

       The one exception is a top-level key "__testcases__". The value of that must be a hash
       where the keys are names of test cases from the test specifications, and the corresponding
       values are booleans specifying if the test case in question should be executed or not. Any
       missing test cases are treated as if they had the value "true" set. The test cases
       "basic00", "basic01" and "basic02" will be executed even if their values are set to
       "false", since part of their function is to verify that the given name can be tested at
       all. The values here only apply when test modules are asked to run all their tests. A test
       case that is set to "false" here will still run if asked for specifically.

       The easiest way to create a modified policy is to copy the default one and change the
       relevant values.