How to set up your first PowerShell DSC pull server

Windows PowerShell Desired State Configuration (DSC) is a technology introduced in Windows PowerShell v4.0. DSC sets out to save the IT professional time by essentially building scripts ahead of time. These scripts build configurations on machines and enable us to simply “make it so”—rather than worrying about banging out tons of code on our own. DSC is a technology that enables us to not only save time, by leveraging pre-built functionality, but it also includes the capability to keep configurations the way we want them.

DSC is a big topic, and I highly encourage you to check out this TechNet article on the Windows PowerShell DSC Overview. This will give you a good start, but there is plenty of great information out there on this topic. If you’re new to DSC, you should first learn the basics before setting up your own pull server.

DSC can be configured to deliver configurations in two different manners; push and pull. The push method is delivered from a server to a computer, thus “pushing” instructions. This method is generally only used for testing or one-off applications not typically in a production environment. The pull method, on the other hand, is another way of delivering instructions to a computer, but this time the request is initiated from the client rather than the server. A pull server is the method we’ll use here and is the recommended way to deliver configurations to clients. That said, let’s get started on setting up our first Windows PowerShell DSC pull server!

The tutorial

In this tutorial, I'm using two servers: LABDC.LAB.LOCAL and LABDC-2.LAB2.LAB.LOCAL. These two servers represent my pull server and a server to which I’m applying a sample configuration. LABDC.LAB.LOCAL is our pull server, while LABDC-2.LAB2.LAB.LOCAL is the server we’re applying the configuration to. Both of these have Windows Server 2012 R2 installed, but you’re fine as long as you’ve got a couple servers that are capable of running PowerShell v4.0.

There are three different protocols you can use to set up a pull server to communicate with the nodes: HTTP, HTTPS or SMB. In a production environment, I highly recommend spending time to learn how to set up your pull server with HTTPS. Leveraging HTTPS as the transport protocol greatly increases the security of your DSC implementation because it uses certificates to encrypt all communication between the nodes and your pull server. For our pull server, I’m using HTTP. I've done this to keep our example as simple as possible, so you can focus on understanding the concepts—instead of diving into the minutiae that is certificates. I'm not using SMB because, even though it’s available, it’s not the typical method used to configure DSC. And I’d like to give you the most pertinent example possible.

Step No. 1: Download the xPsDesiredStateConfiguration DSC resource

The PowerShell team periodically releases DSC resources. These are modules that the team builds which enable you to change various configuration items on a machine. As a naming convention, the PowerShell team prepends each DSC resource with an x meaning experimental. This means the resource implies no support and, essentially, use at your own risk. However, coming from experience, I’ve yet to encounter any problems with these resources.

Step No. 2: Unzip the module into the %programfiles%\WindowsPowerShell\modules folder

This is the standard module location in which you’ll need to place all of your DSC resources.

Step No. 3: Install the DSC Windows feature on the pull server

The easy way to install DSC is to use the Install-WindowsFeature cmdlet:

Install-WindowsFeature DSC-Service -IncludeManagementTools

This installs the DSC service, Internet Information Services (IIS) and a few other Windows features necessary for DSC to function correctly.

Step No. 4: Enable the WinRM listener with winrm quickconfig

As you can see, Server 2012 R2 is already configured. But if you’re running any prior operating system, this step must happen. DSC relies heavily on WinRM.

Step No. 5: Create and run the script to create the DSC pull server

The process of creating the DSC pull server used to be much harder. Now, with the introduction of the xPsDesiredStateConfiguration DSC resource, things are far easier. I’ve stolen a few scripts from this awesome article about configuring a pull server in DSC from System Center Central. The first one we’ll be running is used to create the DSC server.

You can download a copy of the script here. Without getting into too much detail, we’re ensuring the DSC Windows feature we just installed and creating two websites in IIS; both configured to be used for DSC specifically.

Let’s run it and see what happens.

If you have this script saved on the root of the pull server’s C:\ drive, and the script runs successfully, you’ll see that it creates a file called localhost.mof in the C:\NewPullServer directory. This is the MOF file that we'll need to apply to our pull server to actually enforce this configuration.

You’ll notice line 40 begins with Start-DscConfiguration. This is the line that actually applies the configuration generated from the MOF file. Do you see the message “Applying Configuration” in the previous figure? That tells us Start-DscConfiguration is running.

Step No. 6: Verify that the pull server website is working

After the pull server configuration has run, it’s a good idea to verify the correct websites were created. One way to do that is to simply bring up the website in Internet Explorer on the pull server itself. From there, you can verify that you see some XML output. If you do, you’re all set! If not, something went wrong with your DSC configuration.

The following is an example of the XML output you'll see.

Step No. 7: Create a configuration for a node

Now that the pull server is set up correctly, you can deploy your first configuration to a node. To do this, create another configuration on your pull server. But this time, we’re going to create it for another server on the network.

You can download the sample script for this here. This tiny script contains a Configuration script block that’s ensuring the Windows feature Windows-Server-Backup is installed. Running this script creates the MOF file we need in order to apply this configuration to our other server.

Step No. 8: Run the configuration

After you run this script, you’ll see that another MOF file is created. This time its name isn't localhost but rather the name of the server we’d like to apply this configuration to. The MOF file generated is always the name of the Node inside the Configuration block.

Step No. 9: Rename the server node MOF file to a globally unique identifier (GUID)

This is great and all, but in order for our other server to retrieve this configuration, we must rename the server node MOF file to a GUID. DSC keeps track of nodes by unique GUIDs. Let’s go ahead and rename this MOF to a unique GUID as follows:

Rename-Item -Path C:\WindowsBackup\LABDC-2.LAB2.LAB.LOCAL.mof -NewName "$([guid]::NewGuid()).mof"

Step No. 10: Copy the server node MOF file to the Configuration directory

After it’s renamed, the MOF file then needs to be copied to the DscService\Configuration directory on the pull server to be retrieved by our target server.

Copy-Item C:\WindowsBackup\f91e9587-8013-4714-99d5-8e4ffb2dc23f.mof 'C:\Program Files\WindowsPowerShell\DscService\Configuration'

Step No. 11: Generate a checksum file for the server node MOF file

After pulling a configuration from a pull server, DSC ensures the copy went correctly by verifying a checksum. We now need to create a checksum for our MOF file.

New-DSCChecksum 'C:\Program Files\WindowsPowerShell\DscService\Configuration\f91e9587-8013-4714-99d5-8e4ffb2dc23f.mof'

You’ll see that a file ending with .checksum is now in the Configuration directory.

Step No. 12: Modify the Local Configuration Manager (LCM) settings on the server node

Now that our configuration is set up, we need to configure our test server to point to our new pull server. To do this, we need to run another script on the pull server.

You can download this script here. When run from the pull server, this script connects to our server node, essentially telling the node where to look for its configuration and that it’s ok to use HTTP for the communication.

Step No. 13: Verify the server node’s LCM configuration was changed

You can now see the ServerUrl key is indeed pointing to our DSC pull server and AllowInsecureConnection is set to true. This enables us to use HTTP rather than certificates.

And that’s it! Now you’re going to have to trust me on this one for at least 30 minutes. This is because we have to wait the default 30 minutes for the server node to enforce its configuration before we see the result. This interval is specified in the ConfigurationModeFrequency property on the server node. But I think you’ve had enough learning for one day, so let's save our lesson on how to change that interval for another time.