<img height="1" width="1" src="https://www.facebook.com/tr?id=1529264867168163&amp;ev=PageView &amp;noscript=1">

Setting 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 check out this TechNet article on the Windows PowerShell DSC Overview.  This will give you a good start on DSC, but there is also tons of great information out there on this topic as well.  If you’re new to DSC, I highly recommend understanding the basics before you set up your own pull server.  You’ll find that you understand the content better that way, rather than just blindly following instructions.

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 the “pushing” instructions.  This method is generally only used for testing or one-off applications uncommon in a production environment. The pull method on the other hand is another method of delivering instructions to a computer but this time the request is initiated from the client rather than the server.

With 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 servers have Windows Server 2012 R2 installed, but you will be 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 learning 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 #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 #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 #3 - Install the DSC Windows feature on the pull server.

The easy way to install DSC is using the Install-WindowsFeature cmdlet like so:

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 #4 - Enable the WinRM listener with winrm quickconfig

1 resized 600

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 #5 - Create and run the script to create the DSC pull server.

The process of creating the DSC pull server used to be a lot harder.  Now, with the introduction of the xPsDesiredStateConfiguration DSC resource, it is much 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.

2 resized 600

You can download a copy of the script here.  Without getting into too much detail here, 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.

3 resized 600

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 #6 - Verify 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 #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.

5 resized 600

You can download the sample script for this here. This tiny script contains a Configuration script block that ensures 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 #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 #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 #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 #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 #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.

a resized 600

Step #13 - Verify the server node’s LCM configuration was changed.

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

10 resized 600


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.