.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Zonemaster::Engine::Profile 3pm"
.TH Zonemaster::Engine::Profile 3pm "2023-03-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Zonemaster::Engine::Profile \- A simple system for configuring Zonemaster Engine
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This module has two parts:
.IP "\(bu" 4
a \fIprofile\fR representation class
.IP "\(bu" 4
a global profile object (the \fIeffective profile\fR) that configures Zonemaster Engine
.PP
A \fIprofile\fR consists of a collection of named properties.
.PP
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 \*(L"\s-1PROFILE PROPERTIES\*(R"\s0
section.
.PP
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 \*(L"\s-1JSON REPRESENTATION\*(R"\s0 section.
.PP
.Vb 1
\&    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 );
.Ve
.PP
Here is an example for serializing the default profile to \s-1JSON.\s0
.PP
.Vb 1
\&    my $string = Zonemaster::Engine::Profile\->default\->to_json;
.Ve
.PP
For any given profile:
.IP "\(bu" 4
At any moment, each property is either set or unset.
.IP "\(bu" 4
At any moment, every set property has a valid value.
.IP "\(bu" 4
It is possible to set the value of each unset property.
.IP "\(bu" 4
It is possible to update the value of each set property.
.IP "\(bu" 4
It is \s-1NOT\s0 possible to unset the value of any set property.
.SH "CLASS ATTRIBUTES"
.IX Header "CLASS ATTRIBUTES"
.SS "effective"
.IX Subsection "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.
.PP
The effective profile is initialized with the default values declared
in the \*(L"\s-1PROFILE PROPERTIES\*(R"\s0 section.
.PP
For the effective profile, all properties are always set (to valid
values).
This is based on the assumption that \fIdefault.profile\fR specifies a
valid value for each and every property.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "new"
.IX Subsection "new"
A constructor that returns a new profile with all properties unset.
.PP
.Vb 1
\&    my $profile = Zonemaster::Engine::Profile\->new;
.Ve
.SS "default"
.IX Subsection "default"
A constructor that returns a new profile with the default property
values declared in the \*(L"\s-1PROFILE PROPERTIES\*(R"\s0 section.
.PP
.Vb 1
\&    my $default = Zonemaster::Engine::Profile\->default;
.Ve
.SS "from_json"
.IX Subsection "from_json"
A constructor that returns a new profile with values parsed from a \s-1JSON\s0 string.
.PP
.Vb 1
\&    my $profile = Zonemaster::Engine::Profile\->from_json( \*(Aq{ "no_network": true }\*(Aq );
.Ve
.PP
The returned profile has set values for all properties specified in the
given string.
The remaining properties are unset.
.PP
Dies if the given string is illegal according to the \*(L"\s-1JSON REPRESENTATION\*(R"\s0
section or if the property values are illegal according to the \*(L"\s-1PROFILE
PROPERTIES\*(R"\s0 section.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.SS "get"
.IX Subsection "get"
Get the value of a property.
.PP
.Vb 1
\&    my $value = $profile1\->get( \*(Aqnet.ipv6\*(Aq );
.Ve
.PP
Returns value of the given property, or \f(CW\*(C`undef\*(C'\fR if the property is unset.
For boolean properties the returned value is either \f(CW1\fR for true or \f(CW0\fR for
false.
For properties with complex types, the returned value is a
deep copy <https://en.wiktionary.org/wiki/deep_copy#Noun>.
.PP
Dies if the given property name is invalid.
.SS "set"
.IX Subsection "set"
Set the value of a property.
.PP
.Vb 1
\&    $profile1\->set( \*(Aqnet.ipv6\*(Aq, 0 );
.Ve
.PP
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 \f(CW\*(C`undef\*(C'\fR is interpreted as false.
.PP
Dies if the given property name is invalid.
.PP
Dies if the value is \f(CW\*(C`undef\*(C'\fR or otherwise invalid for the given property.
.SS "merge"
.IX Subsection "merge"
Merge the profile data of another profile into this one.
.PP
.Vb 1
\&    $profile1\->merge( $other );
.Ve
.PP
Properties from the other profile take precedence when the same property
name exists in both profiles.
The other profile object remains unmodified.
.SS "to_json"
.IX Subsection "to_json"
Serialize the profile to the \*(L"\s-1JSON REPRESENTATION\*(R"\s0 format.
.PP
.Vb 1
\&    my $string = $profile\->to_json();
.Ve
.PP
Returns a string.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.SS "_get_profile_paths"
.IX Subsection "_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 \f(CW%profile_properties_details\fR.
.PP
.Vb 1
\&    _get_profile_paths(\e%paths, $internal);
.Ve
.SS "_get_value_from_nested_hash"
.IX Subsection "_get_value_from_nested_hash"
Internal method used to get a value in a nested hashes-of-hashes.
.PP
.Vb 1
\&    _get_value_from_nested_hash( $hash_ref, @path );
.Ve
.PP
Where \f(CW$hash_ref\fR is the hash to explore and \f(CW@path\fR are the labels of the property to get.
.PP
.Vb 1
\&   @path = split /\e./,  q{resolver.defaults.usevc};
.Ve
.SS "_set_value_to_nested_hash"
.IX Subsection "_set_value_to_nested_hash"
Internal method used to set a value in a nested hashes-of-hashes.
.PP
.Vb 1
\&    _set_value_from_nested_hash( $hash_ref, $value, @path );
.Ve
.PP
Where \f(CW$hash_ref\fR is the hash to explore and \f(CW@path\fR are the labels of the property to set.
.PP
.Vb 1
\&   @path = split /\e./,  q{resolver.defaults.usevc};
.Ve
.SH "PROFILE PROPERTIES"
.IX Header "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.
.PP
Default values are listed here as specified in the distributed default
profile \s-1JSON\s0 file.
.SS "resolver.defaults.usevc"
.IX Subsection "resolver.defaults.usevc"
A boolean. If true, only use \s-1TCP.\s0 Default false.
.SS "resolver.defaults.retrans"
.IX Subsection "resolver.defaults.retrans"
An integer between 1 and 255 inclusive. The number of seconds between retries.
Default 3.
.SS "resolver.defaults.dnssec"
.IX Subsection "resolver.defaults.dnssec"
A boolean. If true, sets the \s-1DO\s0 flag in queries. Default false.
.SS "resolver.defaults.recurse"
.IX Subsection "resolver.defaults.recurse"
A boolean. If true, sets the \s-1RD\s0 flag in queries. Default false.
.PP
This should almost certainly be kept false.
.SS "resolver.defaults.retry"
.IX Subsection "resolver.defaults.retry"
An integer between 1 and 255 inclusive.
The number of times a query is sent before we give up. Default 2.
.SS "resolver.defaults.igntc"
.IX Subsection "resolver.defaults.igntc"
A boolean. If false, \s-1UDP\s0 queries that get responses with the \f(CW\*(C`TC\*(C'\fR
flag set will be automatically resent over \s-1TCP.\s0 Default false.
.SS "resolver.defaults.fallback"
.IX Subsection "resolver.defaults.fallback"
A boolean. If true, \s-1UDP\s0 queries that get responses with the \f(CW\*(C`TC\*(C'\fR
flag set will be automatically resent over \s-1TCP\s0 or using \s-1EDNS.\s0 Default
true.
.PP
In ldns\-1.7.0 (NLnet Labs), in case of truncated answer when \s-1UDP\s0 is used,
the same query is resent with \s-1EDNS0\s0 and \s-1TCP\s0 (if needed). If you
want the original answer (with \s-1TC\s0 bit set) and avoid this kind of
replay, set this flag to false.
.SS "resolver.source"
.IX Subsection "resolver.source"
A string that is either an \s-1IP\s0 address or the exact string \f(CW"os_default"\fR.
The source address all resolver objects should use when sending queries.
If \f(CW"os_default"\fR, the \s-1OS\s0 default address is used.
Default \f(CW"os_default"\fR.
.SS "net.ipv4"
.IX Subsection "net.ipv4"
A boolean. If true, resolver objects are allowed to send queries over
IPv4. Default true.
.SS "net.ipv6"
.IX Subsection "net.ipv6"
A boolean. If true, resolver objects are allowed to send queries over
IPv6. Default true.
.SS "no_network"
.IX Subsection "no_network"
A boolean. If true, network traffic is forbidden. Default false.
.PP
Use when you want to be sure that any data is only taken from a preloaded
cache.
.SS "asnroots (\s-1DEPRECATED\s0)"
.IX Subsection "asnroots (DEPRECATED)"
An arrayref of domain names. Default \f(CW\*(C`["asnlookup.zonemaster.net",
"asnlookup.iis.se", "asn.cymru.com"]\*(C'\fR.
.PP
The domains will be assumed to be Cymru-style \s-1AS\s0 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.
.SS "asn_db.style"
.IX Subsection "asn_db.style"
A string that is either \f(CW"Cymru"\fR or \f(CW"RIPE"\fR. Defines which method will
be used for \s-1AS\s0 lookup zones.
Default \f(CW"Cymru"\fR.
.SS "asn_db.sources"
.IX Subsection "asn_db.sources"
An arrayref of domain names when asn_db.style is set to \f(CW"Cymru"\fR or whois
servers when asn_db.style is set to \f(CW"RIPE"\fR. Normally only the first item
in the list will be used, the rest are backups in case the earlier ones don't
work.
Default \f(CW"asnlookup.zonemaster.net"\fR.
.SS "logfilter"
.IX Subsection "logfilter"
A complex data structure. Default \f(CW\*(C`{}\*(C'\fR.
.PP
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 \f(CW\*(C`test_levels\*(C'\fR item also specifies tag severity level, but with
coarser granularity and lower precedence.
.PP
The data under the \f(CW\*(C`logfilter\*(C'\fR key should be structured like this:
.PP
.Vb 7
\&   Module
\&      Tag
\&         Array of exceptions
\&             "when"
\&                Hash with conditions
\&             "set"
\&                Severity level to set if all conditions match
.Ve
.PP
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.
.PP
A complete logfilter structure might look like this:
.PP
.Vb 10
\&    {
\&      "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"
\&          }
\&        ]
\&      }
\&    }
.Ve
.PP
This would set the severity level to \f(CW\*(C`INFO\*(C'\fR for any \f(CW\*(C`A_MODULE:SOME_TAG\*(C'\fR
messages that had a \f(CW\*(C`count\*(C'\fR attribute set to 1 and a \f(CW\*(C`type\*(C'\fR attribute
set to either \f(CW\*(C`this\*(C'\fR or \f(CW\*(C`or\*(C'\fR.
This also would set the level to \f(CW\*(C`INFO\*(C'\fR for any \f(CW\*(C`A_MODULE:SOME_TAG\*(C'\fR
messages that had a \f(CW\*(C`count\*(C'\fR attribute set to 128 and a \f(CW\*(C`type\*(C'\fR attribute
set to \f(CW\*(C`that\*(C'\fR.
And this would set the level to \f(CW\*(C`WARNING\*(C'\fR for any \f(CW\*(C`ANOTHER_MODULE:OTHER_TAG\*(C'\fR
messages that had a \f(CW\*(C`bananas\*(C'\fR attribute set to 0.
.SS "test_levels"
.IX Subsection "test_levels"
A complex data structure.
.PP
Specifies the severity level of each tag emitted by a specific module.
The \f(CW\*(C`logfilter\*(C'\fR item also specifies tag severity level, but with finer
granularity and higher precedence.
.PP
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 \f(CW\*(C`Zonemaster::Engine::Test::\*(C'\fR 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.
.PP
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(\*(L"Zonemaster\-Engine\*(R", \*(L"default.profile\*(R").
For messages neither defined in test specifications, nor listed in
\&\f(CW\*(C`default.profile\*(C'\fR, the default severity level is \f(CW\*(C`DEBUG\*(C'\fR.
.PP
\&\fINote:\fR 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.
.SS "test_cases"
.IX Subsection "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.
.PP
Specifies which test cases to consider when a test module is asked
to run of all of its test cases.
.PP
Test cases not included here can still be run individually.
.PP
The test cases \f(CW\*(C`basic00\*(C'\fR, \f(CW\*(C`basic01\*(C'\fR and \f(CW\*(C`basic02\*(C'\fR 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.
.SS "test_cases_vars.dnssec04.REMAINING_SHORT"
.IX Subsection "test_cases_vars.dnssec04.REMAINING_SHORT"
A positive integer value.
Recommended lower bound for signatures' remaining validity time (in seconds) in
test case \s-1DNSSEC04\s0.
Related to the \s-1REMAINING_SHORT\s0 message tag from this test case.
Default \f(CW43200\fR (12 hours in seconds).
.SS "test_cases_vars.dnssec04.REMAINING_LONG"
.IX Subsection "test_cases_vars.dnssec04.REMAINING_LONG"
A positive integer value.
Recommended upper bound for signatures' remaining validity time (in seconds) in
test case \s-1DNSSEC04\s0.
Related to the \s-1REMAINING_LONG\s0 message tag from this test case.
Default \f(CW15552000\fR (180 days in seconds).
.SS "test_cases_vars.dnssec04.DURATION_LONG"
.IX Subsection "test_cases_vars.dnssec04.DURATION_LONG"
A positive integer value.
Recommended upper bound for signatures' lifetime (in seconds) in the test case
\&\s-1DNSSEC04\s0.
Related to the \s-1DURATION_LONG\s0 message tag from this test case.
Default \f(CW15552000\fR (180 days in seconds).
.SS "test_cases_vars.zone02.SOA_REFRESH_MINIMUM_VALUE"
.IX Subsection "test_cases_vars.zone02.SOA_REFRESH_MINIMUM_VALUE"
A positive integer value.
Recommended lower bound for \s-1SOA\s0 refresh values (in seconds) in test case
\&\s-1ZONE02\s0.
Related to the \s-1REFRESH_MINIMUM_VALUE_LOWER\s0 message tag from this test case.
Default \f(CW14400\fR (4 hours in seconds).
.SS "test_cases_vars04.zone.SOA_RETRY_MINIMUM_VALUE"
.IX Subsection "test_cases_vars04.zone.SOA_RETRY_MINIMUM_VALUE"
A positive integer value.
Recommended lower bound for \s-1SOA\s0 retry values (in seconds) in test case
\&\s-1ZONE04\s0.
Related to the \s-1RETRY_MINIMUM_VALUE_LOWER\s0 message tag from this test case.
Default \f(CW3600\fR (1 hour in seconds).
.SS "test_cases_vars.zone05.SOA_EXPIRE_MINIMUM_VALUE"
.IX Subsection "test_cases_vars.zone05.SOA_EXPIRE_MINIMUM_VALUE"
A positive integer value.
Recommended lower bound for \s-1SOA\s0 expire values (in seconds) in test case
\&\s-1ZONE05\s0.
Related to the \s-1EXPIRE_MINIMUM_VALUE_LOWER\s0 message tag from this test case.
Default \f(CW604800\fR (1 week in seconds).
.SS "test_cases_vars.zone06.SOA_DEFAULT_TTL_MINIMUM_VALUE"
.IX Subsection "test_cases_vars.zone06.SOA_DEFAULT_TTL_MINIMUM_VALUE"
A positive integer value.
Recommended lower bound for \s-1SOA\s0 minimum values (in seconds) in test case
\&\s-1ZONE06\s0.
Related to the \s-1SOA_DEFAULT_TTL_MAXIMUM_VALUE_LOWER\s0 message tag from this test case.
Default \f(CW300\fR (5 minutes in seconds).
.SS "test_cases_vars.zone06.SOA_DEFAULT_TTL_MAXIMUM_VALUE"
.IX Subsection "test_cases_vars.zone06.SOA_DEFAULT_TTL_MAXIMUM_VALUE"
A positive integer value.
Recommended upper bound for \s-1SOA\s0 minimum values (in seconds) in test case
\&\s-1ZONE06\s0.
Related to the \s-1SOA_DEFAULT_TTL_MAXIMUM_VALUE_HIGHER\s0 message tag from this test case.
Default \f(CW86400\fR (1 day in seconds).
.SH "JSON REPRESENTATION"
.IX Header "JSON REPRESENTATION"
Property names in \*(L"\s-1PROFILE PROPERTIES\*(R"\s0 section correspond to paths in
a datastructure of nested \s-1JSON\s0 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
\&\s-1JSON\s0 object.
Properties with unset values are omitted in the \s-1JSON\s0 representation.
.PP
For a complete example, refer to the file located by dist_file(
\&\*(L"Zonemaster-Engine\*(R", \*(L"default.profile\*(R" ).
A profile with the only two properties set, \f(CW\*(C`net.ipv4\*(C'\fR = true and
\&\f(CW\*(C`net.ipv6\*(C'\fR = true has this \s-1JSON\s0 representation:
.PP
.Vb 6
\&    {
\&        "net": {
\&            "ipv4": true,
\&            "ipv6": true
\&        }
\&    }
.Ve