Zonema...Config(3pm)

📦 version 1.0.16, in ubuntu jammy

💖 Zonemaster::Config — the config access module for Zonemaster 💖

okay bestie, sit down, hydrate, and let's talk about Zonemaster::Config, which is the part of Zonemaster (the Perl one, yes, this whole page is the User Contributed Perl Documentation era) that handles all the configuration access. she's giving ✨settings girlie✨ and honestly? iconic. 🎀

🌸 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 🦋

so the configuration data gets loaded in several stages, and each stage overlays whatever the previous one did — meaning like, the later one in the list takes priority over the earlier one. periodt.

The very first stage is hardcoded into the source code and gets loaded while it's being compiled, so that there is literally always some basic information available no matter what. no cap, safety first. 🫶

Then, when the configuration object is first used, the system goes looking for a file named config.json in each of a list of directories. If that file exists, is readable, and contains proper JSON data, it gets loaded and overlaid onto the current internal config. The directories, in order from first checked to last:

The Zonemaster perl module installation directory — this is where the installation process drops the default configuration. She is not meant to be modified by the user, and she will be overwritten when the module is upgraded (or reinstalled for any other reason). If you really need to know where she lives, 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 are described further down in this manual page, bestie, keep scrolling. 😌

🌈 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) — loads policy information from the given file and merges 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 to see 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) — loads configuration information from the given file and merges 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. capitalization matters, bestie, don't play. 🙈
BUILD — internal method only mentioned here to please Pod::Coverage. she's shy. 💀
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 that actually send the DNS queries. the main characters of the query world.

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. lowkey the ultimate airplane mode. ✈️

💚 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. it's giving "we know, we know, chill." 😭

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". slay. 🔥

👑 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 holds another hash, where the keys are the tags that the module in question can emit and the values are 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. no skipping the basics, bestie, they're the vibe check. 💅

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. copy, paste, edit, serve. ✨

🫶 that's the whole page, you ate it, you understood it, I'm so proud of you.

this has been Zonemaster::Config from perl v5.32.0, dated 2021-01-06. ily, go configure something gorgeous. 💖🌸🦋

📦 where this page comes from

ubuntu jammy: libzonemaster-perl 1.0.16-2.1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms