PowerShell Desired State Configuration: Pull Mode

Automated configuration management is simpler with Desired State Configuration (DSC) and Push mode, but what is the best way to use DSC to automate deployments on your machines? 'Push' mode or 'Pull' mode? How can you reduce configuration-drift over time? Nicolas Prigent describes the second DSC deployment mode: Pull mode.

DSC has two configuration modes: “Push” or “Pull”. Each mode allows users to ensure that the servers and workstations in their care to acquire and retain the correct configuration. In the terms used by DSC, they allow you to apply a desired configuration-state over a target node. I’ve already described the Push mode in the first two parts of this series. In the Push mode, the configuration is pushed manually on target nodes and it is unidirectional. In the “Pull” mode, however, nodes are configured to get their desired configuration from the ‘pull’ server. This mode is better when machines must be created quickly, or if they need to be done ‘on demand’ for occasionally-connected nodes such as mobile devices or IOT nodes. I suggest you read both parts in order to understand the basics and decide which DSC mode you need to implement so as to fit your particular requirements.

Pull mode

In order to use the pull mode, it is necessary to have a server that has the Windows DSC feature installed. This server is called ‘Pull Server’ in the DSC jargon. In my environment, I dedicate a server to host this feature but you can use an existing server equally well.

A pull server must have Windows Management Framework 4 (WMF) installed, but this is the only prerequisite.

So in this article, the technical environment is the following:

  • DSC01: Pull server
  • ADM01 and ADM11: Two nodes


Figure 1: Pull mode

This mode is the most complex to implement, but also the easiest to maintain. One example: In push mode, if a node happens to be offline, then deployment will fail. Sysadmin have to regularly try again to ‘push’ the configuration. In the pull mode, the operation is much more dynamic. Whatever the status of the node is, the configuration will be applied when it will be back online.

What is pull server?

A pull server is just an Internet Information Services (IIS) Web server that will contain the MOF files for your nodes. It will also respond to requests from each node’s Local Configuration Manager (LCM) to distribute configurations. Thus, the node requests its configuration file from the pull server (Arrow n°1), which then returns with the associated DSC resources. This is the biggest advantage of the pull mode; the DSC resources are downloaded automatically from the pull server on to each node (Arrow n°2). Then, at regular intervals, the nodes will send their status to the pull server to check for changes to configuration.

The pull server is a central repository for the MOF files and the DSC resources.

A pull server can distribute the MOF files via two protocols:

  • Server Message Block (SMB): This method uses shared folders on a file server. However, if you need to manage machines in several networks separated by a firewall, then your network port management will be more complex. In addition, the security permissions will have to be managed properly. The biggest advantage of this method is redundancy. In order to have high availability, you can use a replication service between two file servers via Distributed File System Replication (DFS-R) protocol. I will not detail this method in this article.
  • HyperText Transfer Protocol (http/https): This is the method we are going to study because it is the easiest way to manage machines located in different networks. It uses http protocol and just requires an IIS server for communications.

Installation of the Pull Server

To install a Pull server, you will need to add the “Desired State Configuration” Windows feature and configure two Web Services. The first web service will allow nodes to download their configuration and the second is called “Compliance Server” to avoid configuration-drift on the nodes.

The pull server can be configured with DSC! It is a very good way of learning DSC, so we will use the following PowerShell script:

Note: You must install the “DSC resources kit” in order to use the resource xDscWebService contained in the xPSDesiredStateConfiguration module. For more explanations, I refer you to the first part of the series “The Basics”, in “The DSC resources” section.

Figure 2: CreatePullServer.ps1

Let’s take a look at this script to understand its content.

This first section will create a configuration called “CreatePullServer”. An array is created to contain the nodes that will be configured.

Import-DSCResource is a keyword that is only available within a configuration. This keyword imports DSC resources that will then be used in the configuration. Here we need the xDscWebService resource contained inside the xPSDesiredStateConfiguration module.

Note: This is a keyword and not a cmdlet. You will get an error if you use it in a PowerShell console. I will explain in detail in next article.

Here we use the array mentioned in the beginning of the script.

The keyword “WindowsFeature” indicates that we want to configure a Windows feature. Yes, I know that it is obvious! Here, we add two properties: Name followed by “DSC-Service” which is the name as used in Windows and Ensure with the value “Present” which mean that we want to install it.

This part configures the first Web service through which the nodes will get their configuration. You can change all the values except the last one DependsOn because DSC feature is mandatory.

Finally, part 6 configures the second Web service “Compliance Server” which will control drift configuration on target nodes. Several properties are used in this script, here is their description:

  • Ensure: Name of the web service.
  • EndpointName: Port used to communicate with the web service.
  • Port: Defines the content location.
  • PhysicalPath: Defines the content location.
  • CertificateThumbPrint: Indicates the thumbprint to use with https protocol. Here, we will indicate that traffic will not be encrypted.
  • State: Indicates that the web service is active or not.
  • IsComplianceServer: This property activates the compliance feature.
  • DependsOn: Indicates which resource is mandatory before creating the web service.

Running this configuration generates a “localhost.mof” file:

Now, we just have to run the following command to configure our Pull Server:


Figure 3: Setting up the Pull Server

Let us verify that everything went well. Firstly, is the DSC feature installed?

Secondly, were two Web Services created?

Everything seems fine. Last check using the Get-DscConfiguration cmdlet that will display the current DSC configuration (remember the “current.mof” file. This cmdlet will query this file).

We can validate the proper functioning of the web service from any node through a web browser: https://dsc01:8080/PSDSCPullServer


Figure 4: Check the web service

Manual installation of the Pull Server

For those who do not wish to use DSC to configure the Pull Server, we’ll have to start by adding the DSC feature:



Figure 5: Add DSC Windows Feature

Then we go to the Web server settings (IIS Manager) to configure the two sites with the same properties listed in the DSC configuration. This requires some basic IIS skills, which is why I recommend using the DSC script.


Figure 6: IIS Sites

Nodes configuration

By default, the LCM is configured in Push mode on each node. We have to change this setting.

Note: In pull mode, the name of the MOF file will no longer be the name of the node, e.g. “ADM01.mof” but it will contain a Globally Unique Identifier (GUID) that we will generate.

Firstly, we will generate two GUID:

Then, we will create the metaconfiguration that will be applied to the LCM of ADM01 and ADM11. Please check the previous article for more information about metaconfiguration.

This configuration uses two parameters: The name of the machine to be configured, followed by its GUID. We set the DownloadManagerName property with the value “WebDownloadManager”. If you use SMB protocol for your Pull Server, then the value must be replaced by ‘DSCFileDownloadManager’. The second DownloadManagerCustomData property contains the URL to access our server. In SMB mode, this value should contain the path of the shared folder.

Two MOF files are generated:


Figure 7: Two MOF files

Now, we can apply the metaconfiguration on the nodes:

What remains is to verify if changes are applied on both nodes. Everything seems ok.

Let’s check that the pull server’s URL is correct:

How to deploy a configuration?

Now we’ll use the following example: verify that the audio service is in automatic mode and is started. The nodes were previously configured to correct any unwanted changes. So the service will remain always started.

Here is the configuration that we will be using:

Nothing too complicated here. The keyword “Service” is followed by a friendly name and by these three properties:

  • Name: Name of the service as used in Windows
  • StartupType: Corresponds to the startup mode in Windows
  • State: Status of the service

You can get the properties and their values with the following command:

Two files were generated but we need to rename them with their respective GUID:

Note: Using the GUID instead of the hostname complicates the management of MOF files a little more. We will see later how to manage them to reduce this disadvantage. In this article, I recommend using a txt or csv file and specify the following pair “hostname = GUID“.

The next step is to generate a checksum file to ensure the authenticity and integrity of configurations. If you need to update an existing configuration, it will be mandatory to generate a new checksum file. Otherwise, the configuration will not be applied for security reason. This avoids any unwanted changes. The New-DSCChecksum cmdlet will automatically create two checksum files:

It is almost over. We need to move the files in the directory that we have indicated in our CreatePullServer configuration with the following property:

These two PowerShell lines allows us to publish them in order to make them available for the nodes:


Figure 8: Publish MOF files

Well, it’s over! The nodes will now get their configuration in the next fifteen minutes. Finally, what have we achieved? I created the following diagram to summarize all the steps:


Figure 9: Step-by-step publishing process

We will discuss in next article how to automate these steps.

To go further

Ok, at this time our nodes are configured properly. Several days pass, and you want to ensure that they are still configured properly. How are you going to do that?

  • Could you log each node? That is tedious!
  • Can you use Get-DscConfiguration cmdlet through a CIM session? Yes, but if the configuration is long or complex, then you will have difficulty trying to troubleshoot in this manner.

There is a cmdlet dedicated for this purpose: Test-DscConfiguration that displays True/False depending on the status. In my example below, I verify the status of my two nodes that are valid, and then I stop the Audio service on ADM01. The Test-DscConfiguration cmdlet indicates to me that the desired configuration is not applied at that time.

I can now use the Get-DscConfiguration cmdlet in order to troubleshoot the problem and find that the Audio Service has been stopped manually:

The LCM present on each node verifies its configuration regularly, thanks to a scheduled task named “Consistency”. The execution of this task will check the configuration without waiting for the next cycle.

To correct the configuration of ADM01, I run the “Consistency” task to apply the desired configuration using the Start-ScheduledTask cmdlet:


PowerShell’s Desired State Configuration (DSC) system has two distinct modes of use, the ‘push’ mode and the ‘pull’ mode. They are both useful, but are intended for different requirements. The ‘Pull’ Mode of Desired State Configuration (DSC) is more complex to implement than the ‘push’ mode, but is usually far better suited to an environment with many machines to manage. The ‘push’ mode is better suited to a scheduled operation, where configuration needs to happen at a particular time, but the ‘Pull’ mode is going to be of more general use. Now that you know the two DSC modes that can be implemented, you can now select which of the modes will suit your needs and constraints.