Zonema...Profile(3pm)

📦

version 8.001.001 · 5 versions

8.001.001 · ubuntu stonking (latest)
4.7.3 · ubuntu noble
4.6.2 · debian bookworm
8.1.0 · ubuntu resolute
7.1.0 · debian trixie, ubuntu questing

💖 NAME 💖

Zonemaster::Engine::Profile(3pm) — User Contributed Perl Documentation. Zonemaster::Engine::Profile is a simple system for configuring Zonemaster Engine.

✨ SYNOPSIS ✨

Okay so this module has two parts, periodt:

a profile representation class
a global profile object (aka the effective profile) that configures Zonemaster Engine

A profile is just a collection of named properties, no cap.

Those properties decide the configurable behaviors of Zonemaster Engine — like what tests are to be performed, how they are to be performed, and how the results are to be analyzed. For details on available properties, peep the "PROFILE PROPERTIES" section.

Here's an example for updating the effective profile with values from a given file and setting all properties not mentioned in the file to default values. For details on the file format see the "REPRESENTATIONS" section.

use Zonemaster::Engine::Profile;

my $json    = read_file( "/path/to/foo.profile" );
my $foo     = Zonemaster::Engine::Profile->from_json( $json );
my $profile = Zonemaster::Engine::Profile->default;
$profile->merge( $foo );
Zonemaster::Engine::Profile->effective->merge( $profile );

And here's an example for serializing the default profile to JSON:

my $string = Zonemaster::Engine::Profile->default->to_json;

For any given profile:

At any moment, each property is either set or unset.
At any moment, every set property has a valid value.
It is possible to set the value of each unset property.
It is possible to update the value of each set property.
It is NOT possible to unset the value of any set property. (iconic but also a little intense, ngl)

📦 CLASS ATTRIBUTES 📦

effective

A Zonemaster::Engine::Profile. This is the effective profile — it serves as the global runtime configuration for Zonemaster Engine. Update it to change the configuration.

The effective profile is initialized with the default values declared in the "PROFILE PROPERTIES" section.

All properties in the effective profile are always set (to valid values). Slay 💅

🛠️ CLASS METHODS 🛠️

new

A constructor that returns a new profile with all properties unset.

my $profile = Zonemaster::Engine::Profile->new;

default

A constructor that returns a new profile with the default property values declared in the "PROFILE PROPERTIES" section.

my $default = Zonemaster::Engine::Profile->default;

from_json

A constructor that returns a new profile with values parsed from a JSON string.

my $profile = Zonemaster::Engine::Profile->from_json( '{ "no_network": true }' );

The returned profile has set values for all properties specified in the given string. The remaining properties are unset.

Dies if the given string is illegal according to the "JSON REPRESENTATION" section or if the property values are illegal according to the "PROFILE PROPERTIES" section. So don't be messy with your JSON, bestie. 💀

from_yaml

A constructor that returns a new profile with values parsed from a YAML string.

my $profile = Zonemaster::Engine::Profile->from_yaml( <<EOF
no_network: true
EOF
);

The returned profile has set values for all properties specified in the given string. The remaining properties are unset.

Dies if the given string is illegal according to the "YAML REPRESENTATION" section or if the property values are illegal according to the "PROFILE PROPERTIES" section.

💅 INSTANCE METHODS 💅

get

Get the value of a property.

my $value = $profile1->get( 'net.ipv6' );

Returns value of the given property, or undef if the property is unset. For boolean properties the returned value is either 1 for true or 0 for false. For properties with complex types, the returned value is a deep copy (iykyk, the Wiktionary definition lives at https://en.wiktionary.org/wiki/deep_copy#Noun).

Dies if the given property name is invalid.

set

Set the value of a property.

$profile1->set( 'net.ipv6', 0 );

Takes a property name and value and updates the property accordingly. For boolean properties any truthy value is interpreted as true and any falsy value except undef is interpreted as false.

Dies if the given property name is invalid.

Dies if the value is undef or otherwise invalid for the given property.

merge

Merge the profile data of another profile into this one.

$profile1->merge( $other );

Properties from the other profile take precedence when the same property name exists in both profiles. The other profile object remains unmodified. No mutating your bestie's profile, periodt.

to_json

Serialize the profile to the "JSON REPRESENTATION" format.

my $string = $profile->to_json();

Returns a string.

to_yaml

Serialize the profile to the "JSON REPRESENTATION" format.

my $string = $profile->to_yaml();

Returns a string.

(Yes, bestie, it says "JSON REPRESENTATION" for to_yaml too — I'm just keeping it 100 with what the page says. 🙈)

all_properties

Get the names of all properties.

Returns a sorted list of strings.

🧚 SUBROUTINES 🧚

_get_profile_paths

Internal method used to get all the paths of a nested hashes-of-hashes. It creates a hash where keys are dotted keys of the nested hashes-of-hashes that exist in %profile_properties_details.

_get_profile_paths(\%paths, $internal);

_get_value_from_nested_hash

Internal method used to get a value in a nested hashes-of-hashes.

_get_value_from_nested_hash( $hash_ref, @path );

Where $hash_ref is the hash to explore and @path are the labels of the property to get.

@path = split /\./,  q{resolver.defaults.usevc};

_set_value_to_nested_hash

Internal method used to set a value in a nested hashes-of-hashes.

_set_value_from_nested_hash( $hash_ref, $value, @path );

Where $hash_ref is the hash to explore and @path are the labels of the property to set.

@path = split /\./,  q{resolver.defaults.usevc};

🫶 PROFILE PROPERTIES 🫶

So every property has a name, right, and it's either set or unset. If it's set, it has a value, and that value has to be Actually Valid for that specific property — no chaos allowed. Here's the whole lineup, bestie, every property and the values it will accept. 👑

`resolver.defaults.retrans`

An integer, and it's gotta be between 1 and 255, inclusive. It's the number of seconds between retries. Default is 3. ⏱️

`resolver.defaults.retry`

Another integer, also between 1 and 255 inclusive. This is the number of times a query gets sent before we're like "okay we give up bestie". Default is 2. 😮‍💨

`resolver.defaults.fallback`

A boolean. If it's true, then UDP queries that come back with the "TC" flag set get automatically re-sent over TCP or using EDNS. Default is true.

In ldns-1.7.0 (NLnet Labs), when a UDP answer is truncated, the same query gets resent with EDNS0 and TCP (if needed). So if you want the original answer (the one with the TC bit set) and you don't want that replay behaviour, set this flag to false. 🎭

`resolver.source4`

A string that's either the string representation of an IPv4 address, or the empty string. It's the source address that every resolver object should use when sending queries over IPv4.

If you set it to "" (empty string), the OS default IPv4 address is used instead.

Default: "" (empty string).

`resolver.source6`

Same energy, but IPv6. A string representation of an IPv6 address, or the empty string. It's the source address for all resolver objects sending queries over IPv6.

If it's "" (empty string), the OS default IPv6 address gets used.

Default: "" (empty string).

`resolver.defaults.igntc`

A boolean. Default false. Ignored. Deprecated and planned for removal in v2026.1. Remove it from your profile file, bestie, it's giving cobwebs. 🕸️

`resolver.defaults.recurse`

A boolean. Default false. Ignored. Deprecated and planned for removal in v2026.1. Remove it from your profile file.

`resolver.defaults.usevc`

A boolean. Default false. Ignored. Deprecated and planned for removal in v2026.1. Remove it from your profile file.

`net.ipv4`

A boolean. If true, resolver objects are allowed to send queries over IPv4. Default true. ✨

`net.ipv6`

A boolean. If true, resolver objects are allowed to send queries over IPv6. Default true. ✨

`no_network`

A boolean. If true, network traffic is forbidden. Default false.

You use this when you wanna be sure that any data is only taken from a preloaded cache. No sneaky network calls, periodt. 🚫🌐

`asn_db.style`

A string that's either "Cymru" or "RIPE" (case-insensitive).

It defines which service gets used for AS lookup zones.

Default is "Cymru".

`asn_db.sources`

A hash of arrayrefs of strings. The keys it currently supports are "Cymru" or "RIPE" (case-insensitive).

For "Cymru", the strings are domain names. For "RIPE", they're WHOIS servers. Normally only the first item in the list gets used — the rest are backups in case the previous ones didn't work. 😌

Default: {Cymru: [ "asnlookup.zonemaster.net", "asn.cymru.com" ], RIPE: [ "riswhois.ripe.net" ]}.

`cache`

A hash of hashes. The only key currently supported is "redis". Default {}.

redis

A hashref. The keys it currently supports are "server" and "expire".

It specifies the address of the Redis server used to do global caching (cache.redis.server) and an optional expire time (cache.redis.expire).

cache.redis.server has to be a string in the form host:port. cache.redis.expire has to be a non-negative integer and it defines a time in seconds. Default is 300 seconds. ⏳

`logfilter`

A complex data structure. Default {}.

This one specifies the severity level of each tag emitted by a specific module. The intended use? Removing known erroneous results. Like, say you know a certain name server is recursive and for some reason it should be — you can use this to lower the severity of the complaint about it to a lower level than normal. The test_levels item also specifies tag severity level, but with coarser granularity and lower precedence.

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

Module
   Tag
      Array of exceptions
          "when"
             Hash with conditions
          "set"
             Severity level to set if all conditions match

The hash with conditions should have keys that match the attributes of the log entry being filtered (go check the translation files to see what they are 👀). The values for those 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 logfilter structure might look like this:

{
  "A_MODULE": {
    "SOME_TAG": [
      {
        "when": {
          "count": 1,
          "type": [
            "this",
            "or"
          ]
        },
        "set": "INFO"
      },
      {
        "when": {
          "count": 128,
          "type": [
            "that"
          ]
        },
        "set": "INFO"
      }
    ]
  },
  "ANOTHER_MODULE": {
    "OTHER_TAG": [
      {
        "when": {
          "bananas": 0
        },
        "set": "WARNING"
      }
    ]
  }
}

So this would set the severity level to "INFO" for any A_MODULE:SOME_TAG messages that had a count attribute set to 1 and a type attribute set to either "this" or "or". It also sets the level to "INFO" for any A_MODULE:SOME_TAG messages with a count attribute set to 128 and a type attribute set to "that". And it would set the level to "WARNING" for any ANOTHER_MODULE:OTHER_TAG messages with a bananas attribute set to 0. 🍌✨

`test_levels`

A complex data structure.

It specifies the severity level of each tag emitted by a specific module. The logfilter item also specifies tag severity level — but with finer granularity and higher precedence.

At the top level of this data structure there are two levels of nested hashrefs. The keys of the top level hash are names of test implementation modules (without the Zonemaster::Engine::Test:: prefix). The keys of the second level hashes are tags that the respective modules emit. The values of the second level hashes get mapped to severity levels.

The various test case specifications define the default severity level for some of the messages. Those specifications are the only authoritative documents on the default severity level for the various messages. For messages that aren't defined in any of these specifications, you can use this command to query the default severity level directly from the actual default profile:

sh perl -MZonemaster::Engine::Test -E 'say Zonemaster::Engine::Profile->default->to_json' | jq -S .test_levels

For messages that are neither defined in test specifications nor listed in the default profile, the default severity level is "DEBUG".

Note: sometimes multiple test cases within the same test module define messages for the same tag. When that happens, it is imperative that all test cases define the same severity level for the tag. No wiggle room, bestie. 💅

`test_cases`

An arrayref of names of implemented test cases (all in lower-case) as listed in the test case specifications at https://github.com/zonemaster/zonemaster/tree/master/docs/specifications/tests/ImplementedTestCases.md. Default is an arrayref listing all the test cases.

It specifies which test cases can be run by the testing suite.

`test_cases_vars.dnssec04.REMAINING_SHORT`

A positive integer value. It's the recommended lower bound for signatures' remaining validity time (in seconds) in test case DNSSEC04. Related to the REMAINING_SHORT message tag from this test case. Default 43200 (which is 12 hours in seconds).

`test_cases_vars.dnssec04.REMAINING_LONG`

A positive integer value. Recommended upper bound for signatures' remaining validity time (in seconds) in test case DNSSEC04. Related to the REMAINING_LONG message tag from this test case. Default 15552000 (180 days in seconds).

`test_cases_vars.dnssec04.DURATION_LONG`

A positive integer value. Recommended upper bound for signatures' lifetime (in seconds) in the test case DNSSEC04. Related to the DURATION_LONG message tag from this test case. Default 15552000 (180 days in seconds).

`test_cases_vars.zone02.SOA_REFRESH_MINIMUM_VALUE`

A positive integer value. Recommended lower bound for SOA refresh values (in seconds) in test case ZONE02. Related to the REFRESH_MINIMUM_VALUE_LOWER message tag from this test case. Default 14400 (4 hours in seconds).

`test_cases_vars.zone04.SOA_RETRY_MINIMUM_VALUE`

A positive integer value. Recommended lower bound for SOA retry values (in seconds) in test case ZONE04. Related to the RETRY_MINIMUM_VALUE_LOWER message tag from this test case. Default 3600 (1 hour in seconds).

`test_cases_vars.zone05.SOA_EXPIRE_MINIMUM_VALUE`

A positive integer value. Recommended lower bound for SOA expire values (in seconds) in test case ZONE05. Related to the EXPIRE_MINIMUM_VALUE_LOWER message tag from this test case. Default 604800 (1 week in seconds).

`test_cases_vars.zone06.SOA_DEFAULT_TTL_MINIMUM_VALUE`

A positive integer value. Recommended lower bound for SOA minimum values (in seconds) in test case ZONE06. Related to the SOA_DEFAULT_TTL_MAXIMUM_VALUE_LOWER message tag from this test case. Default 300 (5 minutes in seconds).

`test_cases_vars.zone06.SOA_DEFAULT_TTL_MAXIMUM_VALUE`

A positive integer value. Recommended upper bound for SOA minimum values (in seconds) in test case ZONE06. Related to the SOA_DEFAULT_TTL_MAXIMUM_VALUE_HIGHER message tag from this test case. Default 86400 (1 day in seconds).

🌈 REPRESENTATIONS 🌈

JSON REPRESENTATION

Property names in the PROFILE PROPERTIES section correspond to paths in a datastructure of nested JSON objects. Property values are stored at their respective paths. Paths are formed from property names by splitting them at dot characters (U+002E). The left-most path component corresponds to a key in the top-most JSON object. Properties with unset values get omitted in the JSON representation. 🫥

For a complete example, refer to the file located by dist_file( "Zonemaster-Engine", "default.profile" ). A profile with the only two properties set, net.ipv4 = true and net.ipv6 = true, has this JSON representation:

{
    "net": {
        "ipv4": true,
        "ipv6": true
    }
}

YAML REPRESENTATION

Similar to the JSON REPRESENTATION but it uses a YAML format. 🧚

And that's a wrap, babe — this is from perl v5.40.1, dated 2026-03-21, the Zonema...Profile(3pm) page itself. Go forth and profile iconically. 👑💖

📦 where this page comes from

ubuntu stonking: libzonemaster-perl 8.001.001-1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms