Configuring a Desired State Configuration Client

Once we have our pull server in place and we're starting to create configurations, we need to set up our client nodes to be able to connect to the pull server and how we want the node to behave.

The High Points

Examining the Local Configuration Manager

The Desired State Configuration agent included in Windows Management Framework 4 (or natively on Server 2012 R2 / Windows 8.1) is exposed through the Local Configuration Manager.

PS> Get-DscLocalConfigurationManager

AllowModuleOverwrite           : False
CertificateID                  :
ConfigurationID                :
ConfigurationMode              : ApplyAndMonitor
ConfigurationModeFrequencyMins : 30
Credential                     :
DownloadManagerCustomData      :
DownloadManagerName            :
RebootNodeIfNeeded             : False
RefreshFrequencyMins           : 15
RefreshMode                    : PUSH
PSComputerName                 :

This is where we can configure the behavior of DSC for a particular node.  So, how do we configure it?  With DSC of course!

There is a configuration option LocalConfigurationManager that allows us to set values for the Local Configuration Manager.  A sample configuration looks something like this:

configuration LetsGetConfiguring
    param ($NodeId, $PullServer)    

        AllowModuleOverwrite = 'True'
        ConfigurationID = $NodeId
        ConfigurationModeFrequencyMins = 60 
        ConfigurationMode = 'ApplyAndAutoCorrect'
        RebootNodeIfNeeded = 'True'
        RefreshMode = 'PULL' 
        DownloadManagerName = 'WebDownloadManager'
        DownloadManagerCustomData = (@{ServerUrl = "https://$PullServer/psdscpullserver.svc"})

While this configuration looks similar to other configurations we might create, we need to apply it with a different command - Set-DscLocalConfigurationManager.

LetsGetConfiguring -NodeId 71defb7f-232b-4213-b289-08c3d424e162 -PullServer
Set-DscLocalConfigurationManager -path LetsGetConfiguring

The Local Configuration Manager offers a number of options, which we'll examine.


This one is pretty straight-forward and only impacts configurations where you are using a pull server.  If you allow module overwrite, newer versions of modules can replace existing modules.  If you don't enable this, you'll have to manually remove modules if you want a new copy to pull down.


CertficateID is a thumbprint of a certificate in the machine certificate store that will be used to decrypt any secrets present in the configuration.  DSC allows PSCredential objects to be marshaled through a MOF file, but requires them (without explicit authorization) to be encrypted. (There is another option as well, if you use the ConfigurationData feature, you can also supply the path to a certificate file to use - I'll be blogging that scenario later when I cover some more advanced scenarios.)


The ConfigurationID is a GUID which uniquely identifies what configuration a node should retrieve from a pull server.  If you haven't had to generate GUIDs before, a really easy way to do so is:

PS> [guid]::NewGuid().Guid


ConfigurationMode defines how the DSC client operates.  There are three valid values:

  • Apply
  • ApplyAndMonitor
  • ApplyAndAutoCorrect

(NOTE:  These descriptions of functionality are based on limited testing - the TechNet documentation is not up to date yet, but should be in the near future.)

Apply will apply the configuration once and after a successful run is logged, it will stop attempting to apply configuration or checking the configuration.  ApplyAndMonitor will apply a configuration as in Apply, but will continue to validate that a node is configured as described.  No corrective action will take place if there is configuration drift.  Finally, ApplyAndAutoCorrect is what most of us think of when looking at DSC as a configuration management tool.  This setting applies a configuration and checks it regularly.  If configuration drift is detected, the configuration manager will attempt to return the machine to the desired state (see how I worked the product name in there..).


This setting determines how frequently the configured method (the RefreshMode) will be run.  In the case of a pull server, this is how frequently the pull server will be checked for updated configurations.  The minimum value for this is 30.  This value needs to be a multiple of the RefreshFrequencyMins.  If it is not, the engine will treat it as if it was a multiple (rounded up).


The Credential supplied can be used for accessing remote resources.


DownloadManagerCustomData is a hashtable of values that is passed to the specified download manager.  In the case of a a pull server, the two possible keys are ServerUrl and AllowUnsecureConnection.


Here is where we specify which download manager to use.  DSC ships with two options, the WebDownloadManager (for the web-based pull server) and the DSCFileDownloadManager (for using an SMB share).


Here's another pretty self-explanatory setting.  DSC offers a method for resources to request a reboot.  If this setting is $true, then DSC will reboot the node when it is requested.  If it is set to $false, DSC will notify (via the verbose stream and the DSC log) that a reboot is required, but not actually reboot the node.


The RefreshFrequencyMins setting determines how often DSC runs an integrity check against the cached configuration value (or if the check falls on the ConfigurationModeFrequencyMins interval against the pull server if one is configured).  The minimum value for this setting is 15 minutes.


RefreshMode is either PUSH or PULL.  If you set the RefreshMode to PULL, you'll need to configure a download manager (via DownloadManagerName).

Next up, we'll look at how we can build custom resources.


  1. Looking forward to hearing more about the Credential option. I tried to figure it out for use with a custom resource but in the end resorted to passing a credential to each resource in the resource's parameters.

  2. I have gotten a pull server to work 🙂 , but now I need to understand how to create the required zip file. Basically I have a configuration which will install a Windows feature, so the .mof was all that was needed. What is all of the discussion of creating zip files for a pull server, and how do I do this? Thanks for sharing all of your work Steven!

    • You only need ZIP files if you're deploying modules in the pull server. And you create them the same way you create any other ZIP file - right-click, Send to Compressed Folder :). ZIP files are how you get the pull server to deploy DSC resources that don't already exist on the managed node. For WindowsFeature, you don't need a ZIP.

  3. I have to ask; is it possible to define two configuration GUIDs on the Pull Server?
    My thinking is that I would have one configuration that installs and patches the Server application.
    And a second configuration that configures the Server application it for a specific case.
    Thus I can keep reusing the installation configuration GUID and only maintain a cross-reference of the application configuration. Reducing the total combination of configurations that I have to keep track of, and maximizing re-use.

  4. When setting the RebootNodeIfNeeded property of the LCM to True, will this still work in a PUSH mode? I want to push a couple packages to an SQL server that require reboots in between. The node reboots after the first package install but nothing happens after the reboot. Both packages will install if I reboot manually and run resource again. Am I missing something here?

    • So, not every resource properly notifies the LCM to restart. The LCM only reboots the system if the LCM gets a particular notification from a resource - it's not watching for other things that may indicate a reboot is required.

  5. VERBOSE: [USER1]: LCM: [ Start Set ]
    VERBOSE: [USER1]: LCM: [ Start Resource ] [[File]DSCDirectory]
    VERBOSE: [USER1]: LCM: [ End Set ]
    The Local Configuration Manager is not configured with a certificate. Resource '
    [File]DSCDirectory' in configuration 'MyWebConfig' cannot be processed.
    VERBOSE: Operation 'Invoke CimMethod' complete.
    VERBOSE: Time taken for configuration job to complete is 0.94 seconds

    I can't seem to get passed this error, any help out there?

    I have LocalConfigurationManager {
    CertificateID = $Allnodes.NodeName.ThumbPrint
    ConfigData contains
    CertificateFile = 'C:\project.cer'
    ThumbPrint = 'G71d08f8583de9672345a5560bd0bee7axxxxx'
    This seem to hang up once the config is transferred to the remote LCM. What do I look for to be sure it is configured?

Leave a Reply

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