ADDomainControllerProperties: New resource (#474)

- Changes to ActiveDirectoryDsc - New resource ADDomainControllerProperties (issue #301).
dsccommunity · Aug 8, 2019 · a5f4127 · a5f4127
1 parent 57b5aa3
commit a5f4127
Show file tree

Hide file tree

Showing 16 changed files with 792 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Changes to ActiveDirectoryDsc
+  - New resource ADDomainControllerProperties ([issue #301](https://github.com/PowerShell/ActiveDirectoryDsc/issues/301)).
+
 ## 4.0.0.0
 
 - Changes to ActiveDirectoryDsc

diff --git a/DSCResources/MSFT_ADDomainController/en-US/about_ADDomainController.help.txt b/DSCResources/MSFT_ADDomainController/en-US/about_ADDomainController.help.txt
@@ -15,7 +15,10 @@
     >the account for the parameter `Credential`.
 
     The parameter `FlexibleSingleMasterOperationRole` is ignored until
-    the node has been provisioned as a domain controller.
+    the node has been provisioned as a domain controller. Take extra care
+    to make sure the Flexible Single Master Operation (FSMO) roles are moved
+    accordingly to avoid that two domain controller try to get to be the
+    owner of the same role (potential "ping-pong"-behavior).
 
     >The resource does not support seizing of Flexible Single Master Operation
     >(FSMO) roles

diff --git a/DSCResources/MSFT_ADDomainControllerProperties/MSFT_ADDomainControllerProperties.psm1 b/DSCResources/MSFT_ADDomainControllerProperties/MSFT_ADDomainControllerProperties.psm1
@@ -0,0 +1,197 @@
+$script:resourceModulePath = Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent
+$script:modulesFolderPath = Join-Path -Path $script:resourceModulePath -ChildPath 'Modules'
+
+$script:localizationModulePath = Join-Path -Path $script:modulesFolderPath -ChildPath 'ActiveDirectoryDsc.Common'
+Import-Module -Name (Join-Path -Path $script:localizationModulePath -ChildPath 'ActiveDirectoryDsc.Common.psm1')
+
+$script:localizedData = Get-LocalizedData -ResourceName 'MSFT_ADDomainControllerProperties'
+
+<#
+    .SYNOPSIS
+        Returns the current state of the properties of the domain controller.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+#>
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance
+    )
+
+    Write-Verbose -Message (
+        $script:localizedData.RetrievingProperties -f $env:COMPUTERNAME
+    )
+
+    $getTargetResourceReturnValue = @{
+        IsSingleInstance = $IsSingleInstance
+        ContentFreshness = 0
+    }
+
+    $getCimInstanceParameters = @{
+        Namespace = 'ROOT/MicrosoftDfs'
+        Query = 'select MaxOfflineTimeInDays from DfsrMachineConfig'
+    }
+
+    $getTargetResourceReturnValue['ContentFreshness'] = (Get-CimInstance @getCimInstanceParameters).MaxOfflineTimeInDays
+
+    return $getTargetResourceReturnValue
+}
+
+<#
+    .SYNOPSIS
+        Determines if the properties are in the desired state.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+
+    .PARAMETER ContentFreshness
+        Specifies the Distributed File System Replication (DFSR) server threshold
+        after the number of days its content is considered stale (MaxOfflineTimeInDays)
+        Once the content is considered stale, the Distributed File System Replication
+        (DFSR) server will no longer be able to replicate.
+#>
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.UInt32]
+        $ContentFreshness
+    )
+
+    Write-Verbose -Message (
+        $script:localizedData.TestConfiguration -f $env:COMPUTERNAME
+    )
+
+    $compareTargetResourceStateResult = Compare-TargetResourceState @PSBoundParameters
+
+    if ($false -in $compareTargetResourceStateResult.InDesiredState)
+    {
+        Write-Verbose -Message $script:localizedData.DomainControllerNotInDesiredState
+
+        $testTargetResourceReturnValue = $false
+    }
+    else
+    {
+        Write-Verbose -Message $script:localizedData.DomainControllerInDesiredState
+
+        $testTargetResourceReturnValue = $true
+    }
+
+    return $testTargetResourceReturnValue
+}
+
+<#
+    .SYNOPSIS
+        Sets the properties on the Active Directory domain controller.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+
+    .PARAMETER ContentFreshness
+        Specifies the Distributed File System Replication (DFSR) server threshold
+        after the number of days its content is considered stale (MaxOfflineTimeInDays)
+        Once the content is considered stale, the Distributed File System Replication
+        (DFSR) server will no longer be able to replicate.
+#>
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.UInt32]
+        $ContentFreshness
+    )
+
+    $compareTargetResourceStateResult = Compare-TargetResourceState @PSBoundParameters
+
+    # Get all properties that are not in desired state.
+    $propertiesNotInDesiredState = $compareTargetResourceStateResult | Where-Object -FilterScript {
+        -not $_.InDesiredState
+    }
+
+    if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'ContentFreshness' }))
+    {
+        Write-Verbose -Message (
+            $script:localizedData.ContentFreshnessUpdated -f $ContentFreshness
+        )
+
+        $setCimInstanceParameters = @{
+            Namespace = 'ROOT/MicrosoftDfs'
+            Query = 'select MaxOfflineTimeInDays from DfsrMachineConfig'
+            Property = @{
+                MaxOfflineTimeInDays = $ContentFreshness
+            }
+
+        }
+
+        $null = Set-CimInstance @setCimInstanceParameters
+    }
+}
+
+<#
+    .SYNOPSIS
+        Compares the properties in the current state with the properties of the
+        desired state and returns a hashtable with the comparison result.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+
+    .PARAMETER ContentFreshness
+        Specifies the Distributed File System Replication (DFSR) server threshold
+        after the number of days its content is considered stale (MaxOfflineTimeInDays)
+        Once the content is considered stale, the Distributed File System Replication
+        (DFSR) server will no longer be able to replicate.
+#>
+function Compare-TargetResourceState
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.UInt32]
+        $ContentFreshness
+    )
+
+    $getTargetResourceParameters = @{
+        IsSingleInstance = $IsSingleInstance
+    }
+
+    $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters
+
+    $compareTargetResourceStateParameters = @{
+        CurrentValues = $getTargetResourceResult
+        DesiredValues = $PSBoundParameters
+        Properties    = @('ContentFreshness')
+    }
+
+    return Compare-ResourcePropertyState @compareTargetResourceStateParameters
+}
diff --git a/DSCResources/MSFT_ADDomainControllerProperties/MSFT_ADDomainControllerProperties.schema.mof b/DSCResources/MSFT_ADDomainControllerProperties/MSFT_ADDomainControllerProperties.schema.mof
@@ -0,0 +1,6 @@
+[ClassVersion("1.0.0.0"), FriendlyName("ADDomainControllerProperties")]
+class MSFT_ADDomainControllerProperties : OMI_BaseResource
+{
+    [Key, Description("Specifies the resource is a single instance, the value must be 'Yes'."), ValueMap{"Yes"}, Values{"Yes"}] String IsSingleInstance;
+    [Write, Description("Specifies the Distributed File System Replication (DFSR) server threshold after the number of days its content is considered stale (MaxOfflineTimeInDays). Once the content is considered stale, the Distributed File System Replication (DFSR) server will no longer be able to replicate.")] UInt32 ContentFreshness;
+};
diff --git a/DSCResources/MSFT_ADDomainControllerProperties/README.md b/DSCResources/MSFT_ADDomainControllerProperties/README.md
@@ -0,0 +1,8 @@
+# Description
+
+This resource enforces the single instance properties of a domain controller.
+*Properties that must always have a value, but the value can be changed.*
+
+## Requirements
+
+* Target machine must be running Windows Server 2008 R2 or later.
diff --git a/...es/MSFT_ADDomainControllerProperties/en-US/MSFT_ADDomainControllerProperties.strings.psd1 b/...es/MSFT_ADDomainControllerProperties/en-US/MSFT_ADDomainControllerProperties.strings.psd1
@@ -0,0 +1,8 @@
+# culture="en-US"
+ConvertFrom-StringData @'
+    RetrievingProperties = Retrieving the properties for the domain controller '{0}'. (ADDCP0001)
+    TestConfiguration = Determining the current state of the properties on the domain controller '{0}'. (ADDCP0002)
+    DomainControllerInDesiredState = The domain controller is in the desired state. (ADDCP0003)
+    DomainControllerNotInDesiredState = The domain controller is not in the desired state. (ADDCP0004)
+    ContentFreshnessUpdated = The content freshness property (MaxOfflineTimeInDays) will be updated to {0} days. (ADDCP0005)
+'@
diff --git a/...urces/MSFT_ADDomainControllerProperties/en-US/about_ADDomainControllerProperties.help.txt b/...urces/MSFT_ADDomainControllerProperties/en-US/about_ADDomainControllerProperties.help.txt
@@ -0,0 +1,39 @@
+.NAME
+    ADDomainControllerProperties
+
+.DESCRIPTION
+    This resource enforces the single instance properties of a domain controller.
+    *Properties that must always have a value, but the value can be changed.*
+
+    ## Requirements
+
+    * Target machine must be running Windows Server 2008 R2 or later.
+
+.PARAMETER IsSingleInstance
+    Key - String
+    Allowed values: Yes
+    Specifies the resource is a single instance, the value must be 'Yes'.
+
+.PARAMETER ContentFreshness
+    Write - UInt32
+    Specifies the Distributed File System Replication (DFSR) server threshold after the number of days its content is considered stale (MaxOfflineTimeInDays). Once the content is considered stale, the Distributed File System Replication (DFSR) server will no longer be able to replicate.
+
+.EXAMPLE 1
+
+This configuration will set the content freshness to 100 days.
+
+Configuration ADDomainControllerProperties_SetContentFreshness_Config
+{
+    Import-DscResource -ModuleName ActiveDirectoryDsc
+
+    node localhost
+    {
+        ADDomainControllerProperties 'ContentFreshness'
+        {
+            IsSingleInstance = 'Yes'
+            ContentFreshness = 100
+        }
+    }
+}
+
+
diff --git a/Examples/README.md b/Examples/README.md
@@ -10,6 +10,7 @@ These are the links to the examples for each individual resource:
 - [ADComputer](Resources/ADComputer)
 - [ADDomain](Resources/ADDomain)
 - [ADDomainController](Resources/ADDomainController)
+- [ADDomainControllerProperties](Resources/ADDomainControllerProperties)
 - [ADDomainDefaultPasswordPolicy](Resources/ADDomainDefaultPasswordPolicy)
 - [ADDomainTrust](Resources/ADDomainTrust)
 - [ADForestProperties](Resources/ADForestProperties)

diff --git a/...DDomainControllerProperties/1-ADDomainControllerProperties_SetContentFreshness_Config.ps1 b/...DDomainControllerProperties/1-ADDomainControllerProperties_SetContentFreshness_Config.ps1
@@ -0,0 +1,36 @@
+<#PSScriptInfo
+.VERSION 1.0.0
+.GUID 924568d9-9764-4277-ab85-5a03b818bf6d
+.AUTHOR Microsoft Corporation
+.COMPANYNAME Microsoft Corporation
+.COPYRIGHT (c) Microsoft Corporation. All rights reserved.
+.TAGS DSCConfiguration
+.LICENSEURI https://github.com/PowerShell/ActiveDirectoryDsc/blob/master/LICENSE
+.PROJECTURI https://github.com/PowerShell/ActiveDirectoryDsc
+.ICONURI
+.EXTERNALMODULEDEPENDENCIES
+.REQUIREDSCRIPTS
+.EXTERNALSCRIPTDEPENDENCIES
+.RELEASENOTES First version.
+.PRIVATEDATA 2016-Datacenter,2016-Datacenter-Server-Core
+#>
+
+#Requires -module ActiveDirectoryDsc
+
+<#
+    .DESCRIPTION
+        This configuration will set the content freshness to 100 days.
+#>
+Configuration ADDomainControllerProperties_SetContentFreshness_Config
+{
+    Import-DscResource -ModuleName ActiveDirectoryDsc
+
+    node localhost
+    {
+        ADDomainControllerProperties 'ContentFreshness'
+        {
+            IsSingleInstance = 'Yes'
+            ContentFreshness = 100
+        }
+    }
+}
diff --git a/Modules/ActiveDirectoryDsc.Common/ActiveDirectoryDsc.Common.psm1 b/Modules/ActiveDirectoryDsc.Common/ActiveDirectoryDsc.Common.psm1
@@ -1831,6 +1831,7 @@ function Test-DscPropertyState
             $supportedTypes = @(
                 'String'
                 'Int32'
+                'UInt32'
                 'Int16'
                 'UInt16'
                 'Single'