Provided by: libzonemaster-perl_4.7.3-1_all 
NAME
Zonemaster::Engine::Profile - A simple system for configuring Zonemaster Engine
SYNOPSIS
This module has two parts:
• a profile representation class
• a global profile object (the effective profile) that configures Zonemaster Engine
A profile consists of a collection of named properties.
The properties determine the configurable behaviors of Zonemaster Engine with regard to
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 see the "PROFILE PROPERTIES" section.
Here is 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 );
Here is 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.
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.
For the effective profile, all properties are always set (to valid values). This is based
on the assumption that default.profile specifies a valid value for each and every
property.
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.
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
check_validity
Verify that the profile does not allow confusing combinations.
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
<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.
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.
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
Each property has a name and is either set or unset. If it is set it has a value that is
valid for that specific property. Here is a listing of all the properties and their
respective sets of valid values.
Default values are listed here as specified in the distributed default profile JSON file.
resolver.defaults.usevc
A boolean. If true, only use TCP. Default false.
resolver.defaults.retrans
An integer between 1 and 255 inclusive. The number of seconds between retries. Default 3.
resolver.defaults.dnssec
*DEPRECATED as of 2023.1. Planned for removal in 2023.2* A boolean. If true, sets the DO
flag in queries. Default false.
resolver.defaults.edns_size
*DEPRECATED as of 2023.1. Planned for removal in 2023.2* An integer. The EDNS0 UDP size
used in EDNS queries. Default 512.
resolver.defaults.recurse
A boolean. If true, sets the RD flag in queries. Default false.
This should almost certainly be kept false.
resolver.defaults.retry
An integer between 1 and 255 inclusive. The number of times a query is sent before we
give up. Default 2.
resolver.defaults.igntc
A boolean. If false, UDP queries that get responses with the "TC" flag set will be
automatically resent over TCP. Default false.
resolver.defaults.fallback
A boolean. If true, UDP queries that get responses with the "TC" flag set will be
automatically resent over TCP or using EDNS. Default true.
In ldns-1.7.0 (NLnet Labs), in case of truncated answer when UDP is used, the same query
is resent with EDNS0 and TCP (if needed). If you want the original answer (with TC bit
set) and avoid this kind of replay, set this flag to false.
resolver.source
Deprecated (planned removal: v2024.1). Use "resolver.source4" and "resolver.source6". A
string that is either an IP address or the exact string "os_default". The source address
all resolver objects should use when sending queries. If "os_default", the OS default
address is used. Default "os_default".
resolver.source4
A string that is an IPv4 address or the empty string or undefined. The source address all
resolver objects should use when sending queries over IPv4. If the empty string or
undefined, use the OS default IPv4 address if available. Default "" (empty string).
resolver.source6
A string that is an IPv6 address or the empty string or undefined. The source address all
resolver objects should use when sending queries over IPv6. If the empty string or
undefined, use the OS default IPv6 address if available. Default "" (empty string).
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.
Use when you want to be sure that any data is only taken from a preloaded cache.
asnroots (DEPRECATED)
An arrayref of domain names. Default "["asnlookup.zonemaster.net", "asnlookup.iis.se",
"asn.cymru.com"]".
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.
asn_db.style
A string that is either "Cymru" or "RIPE". Defines which method will be used for AS lookup
zones. Default "Cymru".
asn_db.sources
An arrayref of domain names when asn_db.style is set to "Cymru" or whois servers when
asn_db.style is set to "RIPE". Normally only the first item in the list will be used, the
rest are backups in case the earlier ones don't work. Default "asnlookup.zonemaster.net".
logfilter
A complex data structure. Default "{}".
Specifies the severity level of each tag emitted by a specific module. The intended use
is to remove known erroneous results. E.g. if you 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 "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 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 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"
}
]
}
}
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". This
also would set the level to "INFO" for any "A_MODULE:SOME_TAG" messages that had a "count"
attribute set to 128 and a "type" attribute set to "that". And this would set the level
to "WARNING" for any "ANOTHER_MODULE:OTHER_TAG" messages that had a "bananas" attribute
set to 0.
test_levels
A complex data structure.
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 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 are mapped to severity
levels.
The various test case specifications define the default severity level for some of the
messages. These specifications are the only authoritative documents on the default
severity level for the various messages. For messages not defined in any of these
specifications please refer to the file located by dist_file("Zonemaster-Engine",
"default.profile"). For messages neither defined in test specifications, nor listed in
"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 they do, it is imperative that all test cases define the same severity
level for the tag.
test_cases
An arrayref of names of implemented test cases as listed in the test case specifications.
Default is an arrayref listing all the test cases.
Specifies which test cases to consider when a test module is asked to run of all of its
test cases.
Test cases not included here can still be run individually.
The test cases "basic00", "basic01" and "basic02" are always considered no matter if
they're excluded from this property. This is because part of their function is to verify
that the given domain name can be tested at all.
test_cases_vars.dnssec04.REMAINING_SHORT
A positive integer value. 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 (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_vars04.zone.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 "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 are 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 uses a YAML format.