Dns Policies: New resources proposal

[ahpooch]

Resource proposal

Proposition

I propose creating a resource for managing DNS Policies.

DNS Policies

DNS Policies specify how incoming resolution queries are handled by a DNS server.
https://learn.microsoft.com/en-us/windows-server/networking/dns/deploy/dns-policies-overview

These policies and their elements can only be created using PowerShell, and maintaining them without DSC (Desired State Configuration) is quite labor-intensive.
Managing these policies through configuration files could significantly simplify the administration of such settings.

This issue will list the policy parameters, but the primary reference for the resource architecture should be the official DNS Policies documentation.

Implementation

To implement DNS Policies resources, a base class needs to be created.

A total of three resources must be implemented based on DNS Policies types.

• Query Resolution Policies (DnsServerQueryResolutionPolicy)
• Recursion Policies (DnsServerRecursionPolicy)
• Zone Transfer Policies (DnsServerZoneTransferPolicy)

Note

It could be that DnsServer prefix for resource names is not the best as it is the same as for DNS Settings resources.
It's probably better to use DnsPol prefix. So the resources would be named like this:

• DnsPolQueryResolutionPolicy
• DnsPolRecursionPolicy
• DnsPolZoneTransferPolicy

Resources can be either server-level or zone-level. The Recursion Policies resource can only be server-level.

For all resources at the server-level, the only available choise of action are deny or ignore.

Challenges requiring discussion

One issue requiring discussion is the Criteria field.

This parameter is composite, consisting of a logical operator (AND/OR) and a set of different types of conditions.
To simplify the resource implementation, we could flatten the parameters.
For example. More accurate composite structure could be looked like:
(I'm using Yaml since DSC v3 utilize it for expressing configurations)

Criteria:
  Condition: AND
  CriteriaList:
    ClientSubnet: EQ,Spain,France
    Other_Criterion: Some_value
    ...

However as I'm not aware of any way of achiaving this, we could flatten the sctructure like this:

Condition: AND
CriteriaClientSubnet: EQ,Spain,France
CriteriaOther_Criterion: Some_value
...

As I understand, if in the future someone propose a method to refactor the resource to use composite structure then it will be a breaking change for DnsServerDsc module. So it would be great to implement this right away, but as I said, I don't know the technique to do so.

CmdLets

DnsPolQueryResolutionPolicy

Add-DnsServerQueryResolutionPolicy
Get-DnsServerQueryResolutionPolicy
Set-DnsServerQueryResolutionPolicy
Remove-DnsServerQueryResolutionPolicy

DnsPolRecursionPolicy

Add-DnsServerQueryResolutionPolicy
Get-DnsServerQueryResolutionPolicy
Set-DnsServerQueryResolutionPolicy
Remove-DnsServerQueryResolutionPolicy

DnsPolZoneTransferPolicy

Add-DnsServerZoneTransferPolicy
Get-DnsServerZoneTransferPolicy
Set-DnsServerZoneTransferPolicy
Remove-DnsServerZoneTransferPolicy

Requirements

• Target machine must be running Windows Server 2016 or later.

DnsServerQueryResolutionPolicy

Query Resolution Policy elements

Query Resolution Policy - Name

Policy name

• Up to 256 characters
• Can contain any character valid for a file name

Query Resolution Policy - State

Policy state

• Enable (default)
• Disabled

Query Resolution Policy - Level

Policy level

• Server
• Zone

Query Resolution Policy - Processing order

Once a query is classified by level and applies on, the server finds the first policy for which the query matches the criteria and applies it to query

• Numeric value
• Unique value per policy containing the same level and applies on value

Query Resolution Policy - Action

Action to be performed by DNS server

• Allow (default for zone level)
• Deny (default on server level)
• Ignore

Query Resolution Policy - Criteria

Policy condition (AND/OR) and list of criterion to be met for policy to be applied

• Condition operator (AND/OR)
• List of criteria (see the criterion table below)

Query Resolution Policy - Scope

List of zone scopes and weighted values per scope. Weighted values are used for load balancing distribution. For instance, if this list includes datacenter1 with a weight of 3 and datacenter2 with a weight of 5 the server will respond with a record from datacentre1 three times out of eight requests

• List of zone scopes (by name) and weights

Query Resolution Policy - Criteria field

The DNS policy criteria field is composed of two elements:

• Condition operator (AND/OR)
• List of criteria

Query Resolution Policy Criteria field - Condition

This parameter takes one of the following values:

• OR - the policy evaluates criteria as multiple assertions which are logically combined (OR'd).
• AND - the policy evaluates criteria as multiple assertions which are logically differenced (AND'd).

The default value is AND.

Query Resolution Policy Criteria field - Client Subnet

Name of a predefined client subnet. Used to verify the subnet from which the query was sent.

• EQ,Spain,France - resolves to true if the subnet is identified as either Spain or France
• NE,Canada,Mexico - resolves to true if the client subnet is any subnet other than Canada and Mexico

Query Resolution Policy Criteria field - Transport Protocol

Transport protocol used in the query. Possible entries are UDP and TCP

• EQ,TCP
• EQ,UDP

Query Resolution Policy Criteria field - Internet Protocol

Network protocol used in the query. Possible entries are IPv4 and IPv6

• EQ,IPv4
• EQ,IPv6

Query Resolution Policy Criteria field - Server Interface IP address

IP address for the incoming DNS server network interface

• EQ,10.0.0.1
• EQ,192.168.1.1

Query Resolution Policy Criteria field - FQDN

FQDN of record in the query, with the possibility of using a wild card

• EQ,www.contoso.com - resolves to true only the if the query is trying to resolve the www.contoso.com FQDN
• EQ,.contoso.com,.woodgrove.com - resolves to true if the query is for any record ending in contoso.com OR woodgrove.com

Query Resolution Policy Criteria field - Query Type

Type of record being queried (A, SRV, TXT)

• EQ,TXT,SRV - resolves to true if the query is requesting a TXT OR SRV record
• EQ,MX - resolves to true if the query is requesting an MX record

Query Resolution Policy Criteria field - Time of Day

Time of day the query is received

• EQ,10:00-12:00,22:00-23:00 - resolves to true if the query is received between 10 AM and noon, OR between 10PM and 11PM

DnsServerRecursionPolicy

This policy is a subtype of DnsServerQueryResolutionPolicy.

Recursion Policy - Criteria field

Recursion Policy Criteria field could have all the creteria that Query Resolution Policy have (See DnsServerQueryResolutionPolicy for details).
Recursion Policy have two additional criteria - Apply on recursion and Recursion Scope.

Recursion Policy Criteria field - Apply on recursion

Specifies that this policy should only be used for recursion.

Recursion Policy Criteria field - Recursion Scope

Name of the recursion scope.

DnsServerZoneTransferPolicy

Zone Transfer Policy elements

Zone Transfer Policy - Name

Policy name

• Up to 256 characters
• Can contain any character valid for a file name

Zone Transfer Policy - State

Policy state

• Enable (default)
• Disabled

Zone Transfer Policy - Level

Policy level. Zone Transfer Policy become Zone leveled if -ZoneName provided when Add-DnsServerZoneTransferPolicy is used. Otherwize it is Server leveled.

• Server
• Zone

Zone Transfer Policy - Processing order

Once a query is classified by level and applies on, the server finds the first policy for which the query matches the criteria and applies it to query

• Numeric value
• Unique value per policy containing the same level and applies on value

Zone Transfer Policy - Action

Specifies the action to take if a zone transfer matches this policy. The acceptable values for this parameter are:

• DENY. Respond with SERV_FAIL.
• IGNORE. Do not respond.

Zone Transfer Policy - Criteria field

The DNS policy criteria field is composed of two elements:

• Condition operator (AND/OR)
• List of criteria

Zone Transfer Policy Criteria field - Condition

This parameter takes one of the following values:

• OR - the policy evaluates criteria as multiple assertions which are logically combined (OR'd).
• AND - the policy evaluates criteria as multiple assertions which are logically differenced (AND'd).

The default value is AND.

Zone Transfer Policy Criteria field - Internet Protocol

Network protocol used in the query. Possible entries are IPv4 and IPv6

• EQ,IPv4
• EQ,IPv6

Zone Transfer Policy Criteria field - Server Interface IP address

IP address for the incoming DNS server network interface

• EQ,10.0.0.1
• EQ,192.168.1.1

Zone Transfer Policy Criteria field - Time of Day

Time of day the query is received

• EQ,10:00-12:00,22:00-23:00 - resolves to true if the query is received between 10 AM and noon, OR between 10PM and 11PM

Zone Transfer Policy Criteria field - Transport Protocol

Transport protocol used in the query. Possible entries are UDP and TCP

• EQ,TCP
• EQ,UDP

Zone Transfer Policy Criteria field - ZoneName

Specifies the name of a DNS zone on which this cmdlet creates a zone level policy. The zone must exist on the DNS server.

Zone Transfer Policy Criteria field - ClientSubnet

Specifies the client subnet criterion. For more information, see Add-DnsServerClientSubnet. Specify a criterion in the following format:
operator, value01, value02, . . . , operator, value03, value04, . . .

The operator is either EQ or NE. You can specify no more than one of each operator in a criterion.

The policy treats values that follow the EQ operator as multiple assertions which are logically combined (OR'd). The policy treats values that follow the NE operator as multiple assertions which are logically differenced (AND'd). The criterion is satisfied if the subnet of the zone transfer matches one of the EQ values and does not match any of the NE values.

Example criterion: "EQ,NorthAmerica,Asia,NE,Europe"

Proposed properties

See documentation and issue description. For each resource should be created different Issue with detailed table of properties.

• DnsPolQueryResolutionPolicy
• DnsPolRecursionPolicy
• DnsPolZoneTransferPolicy

Special considerations or limitations

Target server must be running Windows Server 2016 or later.

[ahpooch]

It should be noted that the DnsServerRecursionScope resource is relevant to the proposed DNS Policies resources. In particular, the DnsServerRecursion resource is necessary for specifying the Query Resolution Policy – Recursion Scope (the name of the recursion scope).

[Borgquite]

Just to make sure this is picked up in case my comment on #303 isn't seen

• I wouldn’t try to ‘nest’ the Criteria parameters. This can be a pain in DSC and since the underling Add- cmdlet uses ‘flattened’ information, you’ll have a much easier time. In general try to use the underlying structures of the cmdlets where you can.
• Similarly I would reflect the name of the underlying cmdlets in the resource name (so DnsServerQueryResolutionPolicy) and use this resource to cover both query and recursion policies rather than separate resources. This makes the DSC resource more easily ‘discoverable’ and ‘understandable’ for anyone who wants to migrate to DSC from an existing configuration.

More comments specifically on the QueryResolutionPolicy resource implementation in #303. I have a need for this resource too so let me know if I can offer advice / testing at any time.