In the fourth and final installment of my Windows PowerShell Desired State Configuration (DSC) series, I will explain how you can install a DSC pull server.

By the end of Part 3, you understand the basic mechanics of DSC. Today, we’ll put the proverbial cherry on top of the DSC sundae (so to speak) by installing an HTTP pull server to make DSC deployment and maintenance fully automated.

Our lab environment

I have two servers in my lab:

  • Windows Server 2012 R2 domain controller, DSC administration node, will be our pull server.
  • Windows Server 2012 R2 is the member server.

On each server, I downloaded and installed the latest batch of DSC resources from the TechNet Script Center. If you have any Windows Server 2008 R2 boxes that you want to add to the mix, then you’ll also install the .NET Framework 4.5 and the Windows Management Framework (WMF) 4.0 to support DSC.

How an HTTP pull server works ^

Recall that DSC works in a push scenario, by default, in which you use Start-DSCConfiguration to send a configuration script to one or more target nodes. In turn, these target nodes will re-check their configuration every 15 minutes.

If you’ve been following this series, you also know that we can tweak the Local Configuration Manager (LCM) on target nodes to specify different update settings. We’ll need to do just that in order to instruct my ws2012r2 server to pull configuration from dc1.

The pull server has two HTTP web services that manage (a) the configuration(s) hosted on that server; and (b) DSC compliance, from which we can periodically check whether the configurations of the nodes are in sync with the pull server. These services each listen on an “off” TCP port (in my case, 8080 for the pull server and 9080 for the compliance server).

The target nodes are assigned a globally unique identifier (GUID) that they use to poll and pull configuration from the pull server.

Are you ready? Fasten your seat belt and let’s dive in.

Installing the DSC pull server ^

On dc1, I fired up the Windows PowerShell ISE and built a configuration script named ConfigurePullServer.ps1. Thanks go to PowerShell MVP Don Jones and the rest of the PowerShell community for blueprinting these scripts and configurations. Although DSC is part of a generally available PowerShell release, the documentation is a bit “all over the place,” even today.

Function myFunction {
Get-Content d:\iso\en_windows_8_enterprise_x64_dvd_917522.iso | myFunction
Configuration ConfigurePullServer
     [string[]]$ComputerName = "localhost"

   Import-DSCResource -ModuleName xPSDesiredStateConfiguration

   Node $ComputerName
     WindowsFeature DSCServiceFeature
       Ensure = "Present"
       Name  = "DSC-Service"

     xDscWebService PSDSCPullServer
       Ensure                 = "Present"
       EndpointName           = "PSDSCPullServer"
       Port                   = 8080
       PhysicalPath           = "$env:SystemDrive\inetpub\wwwroot\PSDSCPullServer"
       CertificateThumbPrint  = "AllowUnencryptedTraffic"
       ModulePath             = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules"
       ConfigurationPath      = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration"
       State                  = "Started"
       DependsOn              = "[WindowsFeature]DSCServiceFeature"

     xDscWebService PSDSCComplianceServer
       Ensure                 = "Present"
       EndpointName           = "PSDSCComplianceServer"
       Port                   = 9080
       PhysicalPath           = "$env:SystemDrive\inetpub\wwwroot\PSDSCComplianceServer"
       CertificateThumbPrint  = "AllowUnencryptedTraffic"
       State                  = "Started"
       IsComplianceServer     = $true
       DependsOn              = ("[WindowsFeature]DSCServiceFeature","[xDSCWebService]PSDSCPullServer")



ConfigurePullServer -ComputerName

Do you see what this configuration script does? Three things:

  • Installs the DSC service on the localhost
  • Creates a pull server web service
  • Creates a compliance server web service

Remember that we need to run Start-DSCConfiguration to “make it so”:

PS C:\>Start-DSCConfiguration -Path "C:\ConfigurePullServer" -Wait -Verbose

NOTE: I initially had problems running the pull server configuration script (errors and such) on my Windows Server 2012 R2 computer. To fix this, I installed KB2883200, rebooted, and ran Start-DSCConfiguration again with the -Force switch parameter. Success!

Creating a pull configuration

I’ll create a simple sample DSC configuration that installs the Windows Server Backup tool on target nodes. Here is my InstallBackup.ps1 configuration script:

Configuration InstallBackup {
     param (
     [string[]]$ComputerName = "localhost"
     Node $ComputerName {
         WindowsFeature Backup {
             Ensure = "Present"
             Name   = "Windows-Server-Backup"
InstallBackup -ComputerName

After running the above script, I had a folder in the path C:\InstallBackup with a Managed Object Format (MOF) file named Unfortunately, the pull server won’t accept this file. Instead, we need to generate a GUID, rename the config file, and move it to the appropriate DSC pull server folder.

First, we invoke the NewGuid() function of the GUID .NET type accelerator to make the GUID:

PS C:\> $guid = [guid]::NewGuid()
PS C:\> $guid


Second, we rename the original MOF file and move it to the following path on the pull server:

C:\Program Files\WindowsPowerShell\DscService\Configuration

A GUID is the key that matches a target node to a configuration MOF on the pull server

A GUID is the key that matches a target node to a configuration MOF on the pull server.

For client-side file integrity checking, we also need a checksum file in the DSC service’s configuration folder. We use New-DscCheckSum for that:

PS C:\>New-DscCheckSum -ConfigurationPath "C:\Program Files\WindowsPowerShell\DscService\Configuration"

The previous command created a new file in my DSC pull configuration folder:


Deploying the pull configuration to the target node

We’re almost done, I promise. 🙂 Here is my SetPullMode configuration script for our ws2012r2 target node:

Configuration SetPullMode
     # param([string]$guid)

             ConfigurationMode = "ApplyAndAutoCorrect"
             ConfigurationModeFrequencyMins = 15
             ConfigurationID = "caa3357b-7ec4-417d-b9d4-a5c508edbc56"
             RefreshMode = 'Pull'
             DownloadManagerName = 'WebDownloadManager'
             DownloadManagerCustomData = @{
                 ServerUrl = '';
                 AllowUnsecureConnection = 'true' }

Set-DSCLocalConfigurationManager -Computer -Path "C:\SetPullMode" -Verbose 

Here are some notes regarding the previous script:

  • I commented out the parameter because I chose to hard-code the GUID.
  • I’m using the ApplyAndAutoCorrect configuration mode to strongly enforce DSC configuration.
  • I reduced the ConfigurationModeFrequencyMins interval to 10 minutes to see changes faster in my lab.
  • For simplicity, I’m using HTTP instead of HTTPS (denoted by the true value for AllowUnsecureConnection).

Testing the push configuration ^

After you run the previous script, Windows PowerShell remoting and web services take over, and the target node will ingest the configuration and take off running. Before I sent the script, however, I wanted to ensure that ws2012r2 didn’t have Backup already installed:

PS C:\> Get-WindowsFeature -Name *backup*

Display Name                                            Name
------------                                            ----
     [ ] Windows Server Backup                           Windows-Server-Backup

After sending the LCM config to the target, I verified that its settings were accurate and current:

PS C:\> Get-DscLocalConfigurationManager

ActionAfterReboot              : ContinueConfiguration
AllowModuleOverwrite           : False
CertificateID                  :
ConfigurationID                : caa3357b-7ec4-417d-b9d4-a5c508edbc56
ConfigurationMode              : ApplyAndAutoCorrect
ConfigurationModeFrequencyMins : 15
Credential                     :
DebugMode                      : {NONE}
DownloadManagerCustomData      : {MSFT_KeyValuePair (key = "ServerUrl"),
                                  MSFT_KeyValuePair (key =
DownloadManagerName            : WebDownloadManager
LCMCompatibleVersions          : {1.0}
LCMState                       : Idle
LCMVersion                     : 1.0
RebootNodeIfNeeded             : False
RefreshFrequencyMins           : 30
RefreshMode                    : Pull

And, yes, the Windows Server Backup tool was installed. Cool beans!

PS C:\> Get-WindowsFeature -Name *backup*

Display Name                                            Name
------------                                            ----
[X] Windows Server Backup                               Windows-Server-Backup

Sweeping up the shavings ^

Multiple DSC target nodes can “share” the same GUID if they need to receive an identical configuration. Configuring DSC pull to work over HTTPS isn’t too difficult. Finally, you can use Server Message Blocks (SMBs) as an alternative to HTTP(S) pull. For all this information and more, check out Don’s The DSC Book. I hope you found this article useful. More power to the shell!

Articles in series

PowerShell Desired State Configuration

  1. Peter 6 years ago

    NewDscCheckSum code sample is missing the dash after New

  2. Peter, thanks for the hint! I corrected it now.

  3. Henry 5 years ago

    Great Article!!!
    3 quick questions:
    #1 Does PowerShell DSC have the Report Server that shows the status, executed results etc of target nodes?
    #2 Does one PowerShell DSC manage thousands of client target nodes?
    #3 Must one target client node map to only mof file that is configured on the Pull Server by the UUID key? In the other words, Does more than one target client node used the same <UUID>.mof file on the DSC pull server?

Leave a reply

Please enclose code in pre tags

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2021


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account