Changes to ActiveDirectoryDsc

- New resource ADDomainControllerProperties (issue dsccommunity#301).

CHANGELOG.md

@@ -8,6 +8,7 @@
   - BREAKING CHANGE: ADRecycleBin is replaced by the new resource ADOptionalFeature
     ([issue #162](https://github.com/PowerShell/ActiveDirectoryDsc/issues/162)).
   - New resource ADOptionalFeature ([issue #162](https://github.com/PowerShell/ActiveDirectoryDsc/issues/162)).
+  - New resource ADDomainControllerProperties ([issue #301](https://github.com/PowerShell/ActiveDirectoryDsc/issues/301)).
   - BREAKING CHANGE: Renamed the xActiveDirectory to ActiveDirectoryDsc
     and removed the 'x' from all resource names ([issue #312](https://github.com/PowerShell/ActiveDirectoryDsc/issues/312)).
   - The helper function `Find-DomainController` is exported in the module

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
+}

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;
+};

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.

DSCResources/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)
+'@

DSCResources/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
+        }
+    }
+}
+
+

Examples/Resources/ADDomainControllerProperties/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
+        }
+    }
+}

Modules/ActiveDirectoryDsc.Common/ActiveDirectoryDsc.Common.psm1

@@ -1831,6 +1831,7 @@ function Test-DscPropertyState
             $supportedTypes = @(
                 'String'
                 'Int32'
+                'UInt32'
                 'Int16'
                 'UInt16'
                 'Single'