Desired State Configuration: Setting up of Pull Server

Below is a small excerpt from my book on Powershell Desired State configuration.

There are couple of ways to setup the Pull Server. Microsoft has released a resource of type xDSCWebService that can be used for deploy the Pull server artifacts, create and configure IIS endpoints. One way is to use xDSCWebService resource type in a configuration to create a Pull Server. Another way is to create the pull server manually step by step. The manual way to configure the pull server is definitely more involving and error prone however, errors can be reduced by automating the process of creating the pull server and at the same time provides more control to every aspect of the configuration.

In this section, we will use the second approach and build the entire pull server from scratch bare metal.

There are a sequence of steps that needs to be undertaken to create a Pull Server. We will create the entire pull server using powershell such that the powershell script can be reused to re-create pull servers on need basis.

  1. The first step in creating a Pull server is to login on to the Server that we want to create it as Pull server. Open Server Manager and goto Add Roles and Features. In Windows Server 2012 R2, a new sub-feature named “Windows Powershell Desired State Configuration Service” is available under “Windows Powershell” feature. We have to enable this feature.

    Figure2 Enabling DSC Service

    Before we enable the sub-feature “Windows Powershell Desired State Configuration Service”, there are certain pre-requisite features that needs to be enabled. These includes

    1. Web Server
    2. Windows Powershell
    3. .Net Framework 3.5 and 4.5 features
    4. Management OData IIS Extension

    To enable the above mentioned pre-requisite and “Windows Powershell Desired State Configuration Service” in powershell is shown in Image 3.

    Figure3 Enable features powershell

    In figure 3, we have declared few variables to hold the internal names of all the Windows features. We have also created a variable to hold the computer name. This would help in creating generic script. We will use this variable instead of hardcoded computer name. Install-WindowsFeature cmdlet is used to enable the features. This includes the “DSC-Service” that provides all the Pull server artifacts.

    Enabling this feature deploys multiple files on the file system especially a folder is deployed named “PullServer” under “C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDesiredStateConfiguration” folder. This folder contains the Desired State Configuration module which in turn contains all the DSC cmdlets we have been using so far. We will use these files to create both a pull as well as a compliance server. We will look into compliance server in the next chapter.

    Figure4 file for pull server

  2. DSC Pull server is essentially an IIS Website that accepts configuration requests and responds with configuration details. We will have to build IIS website that will act as DSC Pull server endpoint. It then follows that we will be needing a physical directory mapped to IIS website. An Application pool would be needed to run the website and configure them with appropriate values. In Powershell, we would be created few more variables to hold these values shown in Figure 5. These variables refer to website physical directory path “C:\PSDSCPullServer”, a sub-directory within named “bin” needed by web applications storing assemblies, the name of the application pool “DSCPullServer” to be created and associated with the website, “4.0” as application pool dotnet version, “DSCPullServer” as name of the website and port 8080 as website port number.

    Figure5 variables

  3. Create the physical folder that would be mapped to Website virtual path. In Windows explorer, navigate to C:\ and create a new folder named “C:\PSDSCPullServer”. Also, within this new folder, we create a sub folder named “Bin”. We have choosen here to create a folder directly under C:\. The readers are free to choose any valid file system location. If the location is changed, powershell variables should also be changed appropriately to reflect the change.

    To achieve the same through Powershell, we should execute the command in Image 6.

    Figure6 Folders

    Figure7 PullServer

  4. The next step is to copy the Pull server IIS endpoint related file to the PSDSCPullServer directory and bin folder just created. Through Windows explorer copy the “Microsoft.Powershell.DesiredStateConfiguration.Service.dll” from “C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDesiredStateConfiguration\PullServer” to “C:\PSDSCPullserver\bin” folder. This assembly contains the core functionality and functioning of DSC Pull Server.

    Also, copy “Global.asax”, “PSDSCPullServer.mof”, and “PSDSCPullServer.svc”, “PSDSCPullServer.xml” and “PSDSCPullServer.config” files from “C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDesiredStateConfiguration\PullServer” to “C:\PSDSCPullServer” folder. These are core files needed for a functioning web application.

    The “PSDSCPullServer.config” is actually the web.config file for Pull server website endpoint and should also be renamed to web.config after the copy operation.
    To achieve the same through Powershell, we should execute the command in Image 8.

    Figure8 copying file

    Figure9 Website files

  5. Now, it’s time to create IIS Website and application pool. To create IIS website open Internet Information Service Manager and create a new Application Pool named “DSCPullServer”.

    Figure10 IIS apppools

    Select newly created DSCPullServer application pool and click on advance settings. Within Advance settings, change the identity from “ApplicationPoolIdentity” to “LocalSystem”.

    Figure11 IIS settings

    After the Application Pool is created, it’s time to create the website.

    Click on Sites in IIS Manager and then Add Websites. In the resultant dialog, provide “DSCPullServer” as Website Name. Also choose the earlier created “DSCPullServer” Applocation pool. Provide the physical path “C:\PSDSCPullServer” created earlier. Provide the Port number as 8080. Note that these values are all configurable and the reader can provide their own values.

    Figure12 website creation

    To achieve the same through Powershell, we should execute the commands in Image 13. First, we import the WebAdministration module that provides all the functionality related to IIS.

    It provides a provider “IIS:” through which we can verify whether an application pool and web site exists, If not, it creates a new Application pool and website and related them together. It also configures both application pool and website with relevant information.

    Figure13 Powershell for website

  6. After setting up IIS Website and Application Pool, we have to unlock some of the sections of the web.config file such that they can be changed and updated. By default the parent configuration locks the authentication section. Unlock will help us change the authentication setting in web.config. There is a utility command line tool named “Appcmd” that can be used to manage IIS functionality. We will use this appcmd tool to unlock the web.config sections and also change the Identity of the application Pool.

    This action should only be done through powershell unless we want to change the IIS configuration files manually by hand as shown in Figure 14. $appcmd refers to the command line executable and this executable executes unlock configuration command for authentication section of web.config. It also sets apppool identity to LocalSystem.

    Figure14 Unlocking webconfig sections

  7. In Pull Mode, DSC stores all the configuration information and the target Nodes information in a Database called Devices.mdb. This file is also installed when the DSC-Service was enabled. There is another folder “DSCService” created while enabling “DSC-Service” at folder location “C:\Program Files\WindowsPowershell\”. We will copy and place the Devices.mdb file within the “DscService” folder.

    To achieve the same through Powershell, we should execute the commands in Image 15.

    Figure15 database file

  8. As last step, we need to modify the web.config file for the website to reflect the changes regarding

    a. The new location of Devices.mdb database and also add connectionstring to the database such that DSC service can use this database for its internal management purpose.

    b. The “DscService” folder created in last step also contains two folders named “Configuration” and “Modules”. All Configuration MOF files related to Pull Server should be placed in “Configuration” folder such that Pull server website can access it. The “Modules” should contain all the custom DSC resources and composite configurations. We will cover custom DSC resources and composite configurations in subsequent chapters. The web.config file needs this path to these folders to accessing it.

    c. The database provider to be used for accessing the devices.mdb database file.
    All the changes of Web.config are additions to the section of web.config. This activity can be done manually by typing and adding entries to the AppSettings section as shown in Figure 16.

    Figure16 Webconfig

    As a result, the entire appsettings section in web.config should look like as shown in Image 17.

    Figure17 Web config additions

    To achieve the same through Powershell, we should execute the commands in Image 18. Web.config is essentially an xml file and using xml capabilities of powershell we create a node representing a new key-value section and add then to the appsettings section. Finally, we save the web.config file such that the changes can take effect.

    Figure18 Powershell web config changes

  9. Now, if you have following this chapter exactly as mentioned, you can browse to http://localhost/PSDSCPullServer:8080/PSDSCPullServer.svc through internet explorer and the resultant response should look as shown in image 19. It shows the response from the web server with couple of entities named “Action” and “Module”. We will understand these details in subsequent section in this chapter.

    Figure19 Pull server test

Hope you enjoyed this post and happy pulling DSC configs!!



Powershell Nugget : DSC ISE Snippet

One of cmdlet available within Powershell ISE is New-ISESnippet. This snippet allows us to add new code snippets to the ISE environment which can be used later at multiple places thereby saving overall development time as well as ensuring standards.

Desired State configuration provides a new snippet called “DSC Resource Provider”

On the Script tab of Powershell ISE, Press “Control + J”. A suggestion box appears containing all the registered Powershell snippets on the machine. Alternatively, you can also click on Edit menu and then “Start Snippets” sub-menu item to get the same suggestion box.


You can go to “DSC resource provider” and click on it. It provides a templates for creating custom resources. It provides the template for all the three functions namely: Get-TargetResource, Set-TargetResource and Test-TargetResource.


Makes life a bit easier by not remembering the name of the mandatory DSC functions.


Series: Desired State Configuration – Part 5 : Creating Custom Resources

In this post of the Desired State Configuration series we will look at creating new custom DSC Resource. If you are reading this post and have not read the precious blog post titled “Anatomy of DSC Resource”, I would highly recommend to read that first. It will provide you enough insight on what DSC resources are and the things to be taken care off while creating custom DSC resources.

We will be creating a new custom DSC resource related to Windows Firewall. Firewall is a feature of Windows providing rules that can be enabled and disabled. This custom resource is called “CheckFirewall” and would be responsible for managing the firewall rules i.e. enabling and disabling firewall rules.

The DSC resource would perform the following actions

  1. Check the value within Configuration and call the function Test-TargetResource.
  2. If the value is ‘Absent’, then return ‘True’ if firewall is not already enabled else return ‘False’.
  3. If the value is ‘Present’, then return ‘True’, if the firewall is already enabled else return ‘False’.
  4. If the value returned by Test-TargetResource is “False”, DSC would call “Set-TargetResource” function of the Resource whereas if the Test-TargetResource function returns “True”, DSC would call “Get-TargetResource” function of the resource.
  5. The “Set-TargetResource” function of the resource is generally responsible for checking each property of the target resource and update it according to the provided configuration. However, in our case, we are either enabling or disabling a firewall rule and hence would not be checking any properties provided by Firewall rules.

Create a Resource Provider Folder

Create a Folder called “CheckFirewall” at “<<Your Drive>>\Windows\System32\WindowsPowershell\v1.0\Modules\PSDesiredStateConfiguration\PsProviders\”. In my case the drive is C:\


Create MOF file

The first step in creating the Resource is to create its MOF file. For more details about MOF files, refer to earlier post.

We have named the MOF file as CheckFirewall.Schema.mof and the name of the class is CheckFirewall. Its version number is “1.0.0” and friendly name is also “CheckFirewall”.  Please note that it is this friendly name that is referred within the DSC configuration script. There are just 2 properties for this class

  1. DisplayName: referring to the display name of the firewall rule that needs to be enabled or disabled.
  2. Ensure: flag referring to whether the firewall rule should be enabled or disabled.


The MOF file can also be copied from some existing resource and modified as shown above and this is definitely more convenient and easier.

Create the Powershell Script Module file

In this step, we would create the script file that is the crux of creating the custom resource. The entire brains of the resource lies within this script file because it is here that all the DSC related mandatory functions are implemented namely Set-TargetResource, Get-TargetResource and Test-TargetResource.

Open Powershell ISE and implement the above mentioned three function and save it in CheckFirewall Directory created above as CheckFirewall.psm1 file.

We will use Windows Firewall Powershell cmdlets to determine the current state of the firewall rule and also for enabling and disabling it.

The Test-TargetResource function looks like below. We have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function.


The Get-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.


The Set-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.


Additionally, we also enable or disable the firewall rule using “Enable-NetFirewallRule” or “Disable-NetFirewallRule” depending upon the value of the configuration.

Above, notice that all the three functions defines parameters related to the properties available in the MOF file. Also, some can be mandatory while others could be optional.

Also, both Set-TargetResource and Get-TargetResource returns back a hashtable containing all the properties defined in the MOF file.

Generate the PSD1 file

We can either generate a new PSD1 file using “New-ModuleManifest” or copy some existing psd1 file for existing resource and modify accordingly. I recommend using the first approach of using the “New-ModuleManifest” since this would be less error prone provided you provide correct values. The details about generating this file is available in earlier blog post.

The name of the file should be “CheckFirewall” and should be generated within the above created folder. The sample content looks like below.


Now, this resource can be used in any DSC configuration script. An example is provided below. We have a Configuration node containing a Node for the Server name which in turn contains our new custom resource “CheckFirewall” and is named as “SQLFirewallPresent”. It is setting two available resource property i.e. DisplayName and Ensure. You would see that these are the two properties we have defined in our MOF file.


This concludes the creation of a custom resource for DSC. This is a simplified way of creating of DSC resource and many more aspects like localization and error handling should be part of the overall script.

Hope you liked this post.


Series: Desired State Configuration – Part 4 : Anatomy of DSC Resource

DSC Resources are one of the most important component on the overall architecture of DSC. DSC resources are the key components that are monitored, interacted with and change its state if required depending upon its deviation compared to DSC configuration. Resources are used within the DSC configuration scripts for configuring the environment.

Microsoft already provides out of the box some of the DSC resources like

  1. Environment
  2. File
  3. Group
  4. Log
  5. Package
  6. Process
  7. Registry
  8. Role
  9. Script
  10. Service
  11. User
  12. Archive

However, new DSC resources can also be created. To create a new resource, we need to first understand the building blocks of a resource. We need to know and understand the different components are semantics used to build a new DSC resource.

In this post, we will look into the details of the building blocks of DSC resource.

All the DSC resources are available at following location where the drive could be different in your system. We can also see the out-of –the-box provides resources are also available here.

Even the custom DSC resources needs to be installed here in this directory location before they can be used within DSC configuration script. As visible above, I have created couple of resources for firewall.

For creating custom DSC resource, we need to create a new folder in above location with the name of the Resource represented for example “CheckFirewall”.

For understanding purpose, we can look into any of the out-of-the-box folders and investigate further. For example, if we look into “MSFT_UserResource, we see the following


Here, there is a folder named “en-US” reflecting and containing locale specific information like strings, error message etc. This is an optional component that is needed for multi-lingual development of custom DSC resources. It contains 2 files as shown below, though there can be multiple Powershell data files.

The MFL file is the essentially MOF files that are used in Web based enterprise management (WBEM). If we are not using WBEM, this file is also optional.

The psd1 file is used to store name value pairs of localized data. This file is also optional if localization is not implemented.


If we go back to “MSFT_UserResource”, we can see that there three more files and all these files are important to be implemented for a custom resource.

These files are

  1. <<ResourceName>>.MOF file
  2. <<ResourceName>>.PSM1 file
  3. <<ResourceName>>.PSD1 file

MOF file are Management object notation used with WMI to define the properties of the custom resource.

Below is the example from the MSFT_UserResource


Version reflects the version of the class and FriendlyName reflects the name that should be used within the DSC configuration scripts.

We have to define the class reflecting the resource we want to create. This class is derived from MSFT_BaseResourceConfiguration, base class for all resources. It contains some of the important properties and custom resource must inherit this class.

Within the class, we define the properties that are important for a resource to be tracked including some of the DSC needed properties like

  1. Ensure
  2. Credentials
  3. Password etc.

[Key] reflects that the property value must be provided and should be unique.

[Write] reflects that the property can be written into.

[ValueMap] and [Values] are similar to Enumerations reflects certain valid values. For example Ensure Property can contain “Present” or “Absent” only.

Essentially, the file is based on MOF standards and needs to be saved as <<ResourceName>>.Schema.Mof

The second important file needed is the <<ResourceName>>.psm1 file. This file is the Powershell Script module file that can contain functions and cmdlets among other artifacts.

DSC requires that all the resources must implement at least three functions named

  1. Get-TargetResource
  2. Set-TargetResource
  3. Test-TargetResource

The above three functions needs to be implemented within the psm1 file and should be named as mentioned above although the parameters within these functions should reflect the ones provided within the MOF file. For example, if we have defined a property named Description, we should include it as parameter in Set-TargetResource function such that it can be modified. All the three functions should reflect the parameters defined in the MOF file.

Similarly, the GET function should return a HashTable containing all the values provided by the MOF file.

The TEST function should return true or false.

The SET function should create, update or delete a resource depending on the values provided in Configuration script for “ENSURE” property. If the Ensure property is “Absent”, the resource should be deleted whereas if the Ensure Property is “Present”, the resource should be either provisioned or updated.

The third important file needed is the <<ResourceName>>.psd1. This is the Powershell manifest file containing information about the corresponding module.

This file can be created by coping some existing file and then changing some of its value or can be generated through Powershell cmdlets. For creating a new Manifest file, we can use New-ModuleManifest cmdlet.

The important parameters to be provided to above cmdlets are

Path : reflects the path to generate the new module manifest file at. Filename including extension should be part of the Path.

NestedModule: reflects the name of the module that we want to run in the module session state. We can provide the name of our ps1 file here

ModulesToProcess: reflects the name of the module that we want to run in the global session state. We should provide the name of our psm1 file here.

PowershellVersion:  should be set to 4.0 or 3.0

FunctionsToExport: The value could be “*” means all functions within the module or can specify the names of the specific functions to be visible. We need to ensure that the value is either “*” or all the above mentioned three functions names are provided here in an array format.

Rest of the values can be set but are also optional. A typical PSD1 file looks like below.


Once the PSD1 file is generated, we can use the resource in our Configuration scripts.

In the next post we will create a new resource using the above provided information.


Series: Desired State Configuration – Part 3 : Pushing Configuration to Targets

This is the third part of the Series on Desired State Configuration. In this part we will look at how to create a configuration and push the same to the target servers. In the part, we will look at steps for bringing a target server to the expected state using the configuration.

We will use the same configuration that we created during the first part of the series. For sake of recalling, adding the same Configuration script below.


In the above Configuration script, I have the top level Configuration element named “EnableFeatures”. Within this parent node, I have two nodes namely “WIN-PETR4TD7LAA” and “SCR2i”. These are the two servers which I want bring them into expected state i.e. to enable “Web-Server” feature on “WIN-PETR4TD7LAA” and “XPS-Viewer” on “SCR2i”. Above within the server nodes we have resource type “WindowsFeature” named “web-server” and “XPS”. These names could be any name that logically identifies it. Name within the resource reflects the name of the resource that we want to either add/remove from the environment or change its existing state if already added. “Ensure” reflects whether the resource should be installed or uninstalled depending on its value i.e. “Present” or “Absent”.

I would reflect the initial state of both the server with regard to their windows features and Roles.

Within the above Configuration, Server WIN-PETR4TD7LAA should have “Web-Server” Feature/Role available as its desired state and Server SCR2i should have “XPS-Viewer” Feature/Role removed from the server if it is already available.

Below is the screenshot for the server “WIN-PETR4TD7LAA” where Web Server is not installed


And the screenshot for the server “SCR2i” where XPS-Viewer is already installed.


So far we were looking at the environment that needs to adhere to the expected Configuration and also looked at the Configuration that needs to be reflected on the target servers. Now, we will look at steps to make the magic happens i.e. to run the configuration on individual target servers and change their state based on the configuration.

Step 1: Create the Configuration File.

We have already created this step and do not need to do it again. We will use the above Configuration file.

Step 2: Save the Configuration File to an appropriate location on file system.

Within Powershell ISE, while the configuration script is visible, select Menu-> Save as and save the configuration as ps1 file on file system. In my case, I have stored the file at “C:\“.


 Step 3: dot-source ps1 file and load it in current session.

This step will enable to load the Test.ps1 file and keep in its scope the configuration data and function. If we do not dot-source it, the configuration would be loaded and unloaded immediately and would not be available to use in subsequent steps.


Step 4: Execute the Configuration

In last step we loaded the file containing the configuration script “EnableFeatures”. In this step, we will execute the same configuration “EnableFeatures” to generate the Management Object Format (MOF) files one for each server.

Executing a Configuration is similar to executing a cmdlet or calling a function. Just call it by its name!


Executing the Configuration would result in creating of one MOF file for each server containing all of its related resource types and configuration like name, ensure etc. These MOF Files would be generated within a folder created by executing the above configuration. The name of the folder is same of that of the configuration.

Step 5: Push the Configuration to the target server and execute


Start-DscConfiguration is a Powershell cmdlet provided by the Desired State Configuration module installed with Powershell 4.0. This Cmdlet is responsible for pushing the configuration to the target machines.

-wait lets the Powershell host wait until the cmdlet has finished executing

-verbose provides detailed actions executed by desired state configuration engine.

-force is self-explanatory.

Below is the screenshot while DSC Engine is bringing the target machine according to its configuration file.

And below is the verbose output while executing the configuration through Start-DscConfiguration.


Now, let’s check the result of executing the configuration.



Note: If you have different servers in your configuration either you can use the credentials property of individual resource or use the credential property of Start-DscConfiguration to run the configuration remotely.

In the next part, we will look into the anatomy of creating a new DSC resources.