Home > Articles > Software Development & Management

  • Print
  • + Share This
This chapter is from the book

Writing Your First Configuration Script

Okay, it’s time to start building out our DSC infrastructure, the first step of which is authoring our configuration script. Remember that although target nodes can apply only one MOF file for a given configuration, you can apply multiple MOFs to a single host as long as you don’t have conflicting configuration definitions. I’m sure that, over time, the Windows PowerShell team will make it easier for administrators to manage these manifold MOF manifests (alliteration alert).

I want you to understand before we get started that creating the MOF files via a PowerShell configuration script represents only one possibility for creating the MOFs. If, perchance, you understood MOF syntax, there’s nothing stopping you from creating your own MOFs from scratch using only a text editor.

In other words, we should start to see MOF authoring tools emerge from independent software vendors (ISVs) and the community at large as we progress over time. Welcome to the world of vendor neutrality and community-driven software architectures.

Spend a moment studying the configuration script code in Figure 18.6, and I’ll walk you through each line. I strongly suggest you write your DSC configuration script in the Windows PowerShell integrated scripting environment (ISE) so that you can take advantage of IntelliSense and the easy script execution controls.

Figure 18.6

Figure 18.6 This DSC configuration script will produce one MOF file that is named after the specified target node.

  • Line 1: We use the Configuration keyword in our script to denote a DSC configuration file. The configuration name is arbitrary.
  • Line 2: The Configuration element is enclosed in top-level curly braces.
  • Line 3: The Node keyword specifies the target node. In this first example, we’re hardcoding the name of a Windows Server 2012 R2 host named dscclient01. In a later example, we’ll parameterize this element with a variable so we can use one config script to target multiple nodes.
  • Line 4: Indenting curly braces is optional, but an excellent practice to minimize the chance of our forgetting to close a script block and generate a runtime script failure.
  • Line 5: The “meat and potatoes” of the configuration script are these subblocks. Here we specify the File DSC resource type, passing in an arbitrary name.
  • Line 6: Another indented curly brace, this time enclosing the File resource script block.
  • Line 7: Each DSC resource contains a number of named parameters. Like anything else in PowerShell, read the resource’s online documentation to learn the acceptable values for each parameter. The Ensure=“Present” line is ubiquitous in DSC configuration scripts, in my experience. This ensures that the policy is enforced.
  • Lines 8-10: Here we plug in the details for our File DSC resource declarations. What we’re doing is copying the scripts shared folder on my deployment server to a local path on the target node. As of this writing, I needed to add the source and destination node computer accounts to the shared folder’s discretionary access control list (DACL) to make a UNC path work.
  • Lines 11–14: Here we close up all the script blocks.
  • Line 15. This is an optional line in which we call the configuration. That way we actually execute the Configuration block when we run the script in the Windows PowerShell ISE.

When you’re ready, run the entire configuration script. If all goes well, you’ll see output that is similar to this:

PS C:\Users\Trainer> C:\Users\Trainer\Desktop\DSC\SampleConfig1.ps1
    Directory: C:\Users\Trainer\SampleConfig1

Mode                LastWriteTime         Length Name

----                -------------         ------ ----

-a----              12/22/2014   8:23 AM  1736 dscclient01.mof

You’ll note that Windows PowerShell does a couple things when you run the DSC configuration script:

  • Creates a directory in the root of the C: drive with the same name as the .ps1 script file
  • Creates one MOF for each node referenced in the script; the MOF files are named with the node’s hostname

Customizing the Local Configuration Manager

Earlier in this hour, I told you that all DSC-enabled Windows nodes have a client component called the Local Configuration Manager (LCM) that is installed as part of WMF v4.

We can (and probably should) push a separate configuration script to our target nodes to customize the deployment parameters. First, let’s run Get-DscLocalConfigurationManager to see what’s what on my dscserver01 machine:

PS C:\> Get-DscLocalConfigurationManager

ActionAfterReboot              : ContinueConfiguration
AllowModuleOverWrite           : False
CertificateID                  :
ConfigurationDownloadManagers  : {}
ConfigurationID                :
ConfigurationMode              : ApplyAndMonitor
ConfigurationModeFrequencyMins : 15
Credential                     :
DebugMode                      : False
DownloadManagerCustomData      :
DownloadManagerName            :
LCMCompatibleVersions          : {1.0, 2.0}
LCMState                       : Ready
LCMVersion                     : 2.0
MaxPendingConfigRetryCount     :
StatusRetentionTimeInDays      : 7
PartialConfigurations          : {}
RebootNodeIfNeeded             : False
RefreshFrequencyMins           : 30
RefreshMode                    : PUSH
ReportManagers                 : {}
ResourceModuleManagers         : {}
PSComputerName                 :

Some of the LCM parameters are more important than others. The ConfigurationMode parameter tells the node what to do in terms of how it applies and refreshes DSC configurations. The options here are as follows:

  • Apply: Applies the configuration once and then doesn’t check for an update or refresh again (one-time application, in other words).
  • ApplyAndMonitor: Applies the configuration and continues to validate that the node is in compliance with the policy. If configuration drift occurs, the node does nothing.
  • ApplyAndAutoCorrect: Applies the configuration, periodically checks for compliance, and reapplies the configuration if something changes within the scope of active configurations.

Note also the RefreshFrequencyMins parameter. In push mode, the node checks for DSC compliance every 30 minutes. This may be far too frequent for your business needs, so let’s deploy a new set of LCM settings to our localhost and dscclient01 nodes.

Once again, take a look at our script shown in Figure 18.7, and I’ll walk you through selected parts:

Figure 18.7

Figure 18.7 By deploying an LCM configuration, we can take fine-grained control over how DSC policies are evaluated and applied by target nodes.

  • Lines 3–5: These lines create an input parameter for our LCM script. Note that the $NodeName parameter is defined as a string array, [], which makes it a snap to target multiple nodes without having to repeat code blocks in the script file.
  • Line 10: Here we specify a 4-hour refresh interval for the LCM policy refresh mode.
  • Line 17: Again for convenience, we run the configuration in-line with the code, specifying two target nodes by hostname. Of course, you can import the script into your runspace by using dot sourcing. However, I like the convenience of calling the function directly in the script file. Your mileage may vary, as I’ve said in this book about a hundred times before.
  • An exhaustive discussion of how to import scripts into your runspace using dot sourcing is included in Hour 19, “Introduction to Windows PowerShell Scripting.”

When you run the LCM config script, you wind up with a single “meta” MOF regardless of how many nodes you target in the script. Likewise, we use a different cmdlet to apply an LCM script: Set-DscLocalConfigurationManager. The -Path parameter points to the directory that contains our LCM script:

Set-DscLocalConfigurationManager -Path “C:\SetupLCM”

Let’s do a Try It Yourself exercise so that you can shore up your Windows PowerShell skills and see how DSC works with your own eyes.

  • + Share This
  • 🔖 Save To Your Account