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!!