Profile Settings Reference

The engine profile is the source of truth for how runs behave: resolver timing, the IP stack, slow-server controls, response caching, and per-testcase severity. A run starts from the built-in default and applies sparse overrides on top.

How overrides are applied:

• CLI: gonemaster --profile PATH (JSON or YAML), merged over the default.
• Server: a process-wide profile_path, stored profiles, and per-job overrides. See server/configuration.md .

Inspect the effective profile for a run with gonemaster --dump-profile (CLI), or the recorded effective profile on a job (server).

resolver.defaults

The resolver tuning knobs. Defaults are the built-in values; ranges are the accepted bounds.

The debug, igntc, recurse, and usevc keys are no longer profile properties. Stored profiles that still contain them load without error and the keys are ignored; per-query transport (TCP and the RD bit) is decided by the engine and individual testcases, and the query trace is enabled by gonemaster --debug-queries.

Source addresses live alongside the defaults, under resolver:

Other profile sections

These are part of the profile but configured elsewhere:

• net.ipv4 / net.ipv6 - enable or disable an IP stack (CLI --no-ipv4, --no-ipv6, --ipv6).
• net.allow_non_global_targets - default false. When false (the default), the engine refuses to send queries or zone transfers to nameserver addresses that are not globally reachable (loopback, RFC1918, CGNAT, link-local, ULA, documentation, benchmarking, and similar IANA special-purpose ranges, multicast, the deprecated site-local fec0::/10 and IPv4-compatible ::/96 ranges, and NAT64 forms of such IPv4 addresses), even when learned from glue or DNS resolution, and emits a NON_GLOBAL_QUERY_BLOCKED notice instead. The same rule applies to the RIPE whois sources of asndb: a source address that is not globally reachable is skipped without a notice, as an unreachable source is. Set true (CLI --allow-non-global) on private/internal instances that test such zones. Addresses an operator pins explicitly via --ns name/IP (undelegated tests) are always queried regardless of this flag. Note: enabling the guard by default is a behavior change - delegated tests against a private nameserver now need --allow-non-global.
• test_levels - the severity level emitted per message tag, per module. Largely generated; see the test specifications .
• test_cases_vars - per-testcase thresholds (for example SOA timer minimums).
• asndb - ASN lookup backend and sources.
• badkeys - badkeys blocklist path.

Example: a sparse override

Only the keys that differ from the default are needed:

{
  "resolver": {
    "defaults": {
      "nameserver_max_total_ms": 60000
    }
  }
}

Inheritance and wholesale replacement

A property the override does not set is inherited from the default, so sparse overrides are safe and restating a default value changes nothing.

Two properties are the exception: test_cases and test_levels replace the default table as a whole rather than merging into it.

• A testcase absent from an overridden test_cases list does not run.
• A tag absent from an overridden test_levels module resolves to DEBUG, which keeps it out of reports and out of the score.

That makes a full restatement of the defaults a maintenance liability: when a release adds a testcase or a tag, the override silently keeps the old set. The test_cases_vars tunables are individual properties, so omitting one there just inherits it.

Testcase selection

The testcases of a run are selected in three steps:

1. The test_cases list of the effective profile.
2. --module or --testcase, when given, replaces that list.
3. --exclude removes testcases from the result.

--exclude takes a testcase id or a module name. It is repeatable and accepts a comma-separated list. On the server the list comes from exclude in the configuration file, GONEMASTER_EXCLUDE, or --exclude. A stored profile, a job override or a tag default cannot re-enable an excluded testcase.

A run fails when an exclusion names an unknown testcase or module, when --testcase or --module names an excluded testcase, or when no testcase remains. The server rejects a job, batch or public job whose tests list names an excluded testcase with HTTP 400 and code testcase_excluded.

Dependent testcases

Some testcases run only on the outcome of an earlier testcase in the same module. A testcase that is not selected, in any of the three steps, has no outcome:

An operator SHOULD exclude basic01, basic02 or dnssec07 only when every tested zone is known to be delegated and, for dnssec07, signed.

Comparing a profile against the defaults

POST /api/v1/profiles/diff compares a profile config against the current engine defaults and reports, for every property the config sets, whether it deviates from the default or merely restates it, plus the missing and unknown keys inside overridden maps. The config travels in the request body, so an unsaved draft can be compared without being stored.

The admin UI profile editor shows this above the config editor: a summary line, an expandable per-property table, and a “Strip redundant overrides” action that removes the properties which restate the default. Stripping never changes the merged profile the engine runs, and it never prunes individual keys out of a wholesale-replace map.

Review state

A stored profile carries a schema_version: the engine version it was last saved or reviewed against. When it matches the running engine, the profile is reviewed - its remaining gaps are treated as deliberate and reported as waived_issues rather than open issues, and the editor names them instead of staying silent. “Check again” (the clear_reviewed patch op) drops the stamp so the full check runs again and the gaps return as open issues.