Fr

Windows PowerShell is a task-based command-line shell

and scripting language designed especially for system
administration. PowerShell DSC is a new management
platform that enables you to deploy and manage
configuration data for software services and manage the
environment in which these services run.
This book begins with an overview of the basics of
PowerShell DSC by covering the architecture and
components of the Desired Sate Configuration. It will
then familiarize you with the set of PowerShell language
extensions and the new PowerShell commands. It will help
you create DSC configurations with the help of practical
examples and DSC custom resources for your custom
applications. Finally, you will learn to deploy a real-world
application using PowerShell DSC. By the end of the
book, you will have better knowledge of the powerful DSC
platform, which helps you achieve continuous delivery,
and efficient management and easy deployment of data
for systems.

This book is intended for system administrators or

engineers who are responsible for configuration
management and automation and wish to learn PowerShell
DSC for the efficient management, configuration, and
deployment of systems and applications.

Understand configuration management and

why you need it
Craft flexible, reusable, and maintainable
configuration scripts for thousands
of servers
Create custom DSC Resources to manage
any application or server setting
Use configuration data to deploy
applications to different environments

professional expertise distilled

pl
e

E x p e r t i s e

D i s t i l l e d

Utilize DSC push deployments to test

your configuration scripts and custom
DSC Resources
Install, configure, and use DSC Pull Servers
Run a Windows MSI package
Deploy a website
$ 49.99 US
31.99 UK

P U B L I S H I N G

Sa

P r o f e s s i o n a l

James Pogran

Who this book is written for

What you will learn from this book

Learning PowerShell DSC

Learning PowerShell DSC

ee

Learning PowerShell DSC

Get started with the fundamentals of PowerShell DSC and
utilize its power to automate the deployment and configuration
of your servers

Prices do not include

local sales tax or VAT
where applicable

Visit www.PacktPub.com for books, eBooks,

code, downloads, and PacktLib.

James Pogran

professional expertise distilled

P U B L I S H I N G

In this package, you will find:

The author biography

A preview chapter from the book, Chapter 5 'Pushing DSC Configurations'
A synopsis of the books content
More information on Learning PowerShell DSC

About the Author

James Pogran has been working with computers in some form or fashion for over

15 years. His first job was systems administration for a large military installation. He
then moved on to develop monitoring software and automate large scale Windows
environments for a major managed services provider. He is currently a software
engineer at Puppet Labs where he helps to make Windows automation even better
with Puppet.

Preface
Windows PowerShell was a transformative event for the Windows management
ecosystem. It marked a shift from the GUI-based administration of "click next,
next, finish" to a composable command line experience that can be scripted and
automated. This methodology was not accepted immediately by the Windows
community, but time has proven the approach viable and PowerShell is now an
integral part of any systems administrator's toolkit.
Windows PowerShell Desired State Configuration (DSC) marks another shift in
Windows administration, but this time, it is a move away from the run-once scripts
that cannot detect the existing state to declarative and repeatable automation without
side effects. While PowerShell enabled an automation paradigm that was previously
unmatched on Windows systems, crafting truly dependable automation took many
lines of boilerplate code of exception catching and state checking. DSC handles this
boilerplate code and gives you a clean and readable way to declare the expected state
of your systems without worrying about how those systems are configured.
Whether you manage a few servers or several thousands of them, the same problems
occur repeatedly. How do you ensure that all the servers under your care are
configured to the exact specifications? How do you write those specifications down
so that not only you and your coworker but also the machine understands them?
This seemingly conflicting set of requirements is the purpose of DSC. Using DSC,
you can write the human-readable desired state of the system you expect, and DSC
ensures that the state of the system is what you desired it to be.

Preface

In this book, we will introduce the configuration management concepts that DSC
uses to accomplish these feats. We then cover the architecture of DSC, which allows
us to specify the state of a target system without having to code the implementation
details ourselves. From there, we will cover how to create files that can be read by
both DSC and humans to ensure that the state of target systems is what we specify.
We will then address how to customize DSC to administer our customized and
unique environments, and then walk through the ways in which we can deploy
these configurations to the target systems using the different deployment models of
DSC. We will wrap up with a walkthrough of a typical deployment cycle of example
software using real-world problems and solutions.

What this book covers

Chapter 1, Introduction to PowerShell DSC, introduces you to PowerShell DSC and
configuration management concepts. It covers the features included in DSC and
briefly introduces the different DSC versions.
Chapter 2, DSC Architecture, covers all three phases of DSC in depth, the two different
DSC deployment models, and the considerations to be made when deploying a Pull
Server or using a push deployment.
Chapter 3, DSC Configuration Files, covers authoring the DSC configuration scripts
and configuration data files from end to end. It also covers how to use them
together effectively.
Chapter 4, DSC Resources, covers the DSC Resource syntax and file structure in both
PowerShell v4 and v5. It shows how to find DSC Resources on the local system as
well as using community and Microsoft-provided online resources.
Chapter 5, Pushing DSC Configurations, gives step-by-step instructions on how to push
DSC configurations to remote target nodes. It also covers the extra steps the user
must take to make push deployments work and discusses the pros and cons of using
push deployments.
Chapter 6, Pulling DSC Configurations, gives step-by-step instructions on how to
set up a DSC Pull Server and your environment to best utilize a pull-based
deployment. It covers the pros and cons of using pull deployments in comparison
to push deployments.
Chapter 7, Example Scenarios, covers the use of DSC in the real world and how to
integrate DSC into not only new environments but also with legacy-style deployments.
This chapter walks us through the thought processes of handling the changing
requests and the requirements of different software deployments using DSC.

Pushing DSC Configurations

We have covered everything there is to know about DSC and its internals at this
point, but we have not fully explained the different ways DSC configurations
actually get to the target nodes. In the first chapters of the book, we learned that
there are two models to DSC: a push and a pull model. In this chapter, we will be
covering the push model. We will first define what the push model is and then move
on to how to use it with DSC configurations. We'll take an example configuration
and apply it to a local target node and a remote target node.
In this chapter, we will cover the following topics:

Tooling

Setting things up

Locally pushing DSC configurations

Remotely pushing DSC configurations

Tooling
DSC supports applying DSC configurations locally and remotely using the
Start-DscConfiguration Cmdlet. This Cmdlet handles both copying the MOF
file to the target node and telling DSC to execute the MOF on the target node.
Start-DscConfiguration can be invoked interactively as well as run in the

background. Interactive executions are run as we are watching and are able to show
us verbose output as each step in the DSC configuration happens. Background
executions are PowerShell jobs that do not block your shell, so that you can do
other things while the job runs. This means you can use this Cmdlet to push a DSC
configuration and then walk away or continue to use your current PowerShell
console session to do other things as it executes on the target node.

[ 153 ]

Pushing DSC Configurations

All output from the DSC configuration execution is logged by DSC, and the StartDscConfiguration Cmdlet can show this information, if configured. By default, it

only displays error and completion information, but it can be configured to yield
verbose output by using the Verbose parameter.

It is important to note that Start-DscConfiguration does not perform the

execution itself; the DSC service does this on the target node. This means nothing is
tied to you, your shell, or your session. Your current console session could stop or go
away and the execution would still run. This allows a "set it and forget it" workflow
where you push a configuration and walk away to do other things while it runs, and
then come back and find the results of the execution ready and waiting for you.

Setting things up
Up until now, you could have gotten away with just looking at the examples in the
book without running them or adapting them slightly to work on your desktop or a
test VM or server. At this point, it is really helpful to have a test VM that you can create
and destroy several times over as you work through the examples. This is especially
true when we try executing DSC configurations remotely later in the chapter.

Test environments
There are several approaches you can take when building and using test
environments. If you have the spare physical machines, you can set up several
machines as test servers to run these configurations. This is the easiest way if you
have the extra hardware lying around, but it becomes difficult when you want to
treat them as disposable machines. Constantly reinstalling the machines will become
tedious without imaging software, so keep in mind the time cost this entails if you go
this route.
A far easier route is Virtual Machines (VM), which are commonplace is today's
world. HyperV, VMware, and Parallels all have options to run VMs on your desktop
or laptop. This allows you to have dependable and repeatable tests on known
configurations so that you can keep testing your DSC configurations until you are
sure they work.

[ 154 ]

Chapter 5

While each of these vendors' software has the functionality to allow you to perform
an operation and then "roll back" to a known good state, it is sometimes slow and
cumbersome to use these features. They were designed with infrequent use in
mind. We are looking for something that can be brought up in minutes just as easily
as it can be destroyed. A good tool to look into using for this purpose is Vagrant
(https://www.vagrantup.com/). Setting up and using Vagrant is beyond the scope
of this book, but there are a good many resources out there to get you started. It will
make your life a lot easier to use tools like Vagrant, VMware, or HyperV to automate
your development environments.
For the purposes of this book, it is not necessary to have these setups specifically, but
we will assume that you are at least using a test machine on which you can run these
commands time and time again while you get used to these operations.
We are going to build two test computers and call them box1 and box2. We will use
box1 both as the place where we make the DSC configuration and the place where
we execute it from. The second test computer, box2, will be our target node that
receives DSC configurations from us so that we can demonstrate remote operations.
Because of this, both computers need to be able to access each other on the network,
so configure your IP addresses appropriately.

Locally pushing DSC configurations

What do we mean by "pushing DSC configurations locally"? When we apply a DSC
configuration to the computer we are logged into, we are applying or pushing the
DSC configuration onto the computer. We call it "pushing" because we are actively
copying the MOF file and triggering an execution on the target node; we are active
participants in the whole process. The Start-DscConfiguration Cmdlet does the
work for us, but we are actively requesting the operations to be performed. This is
clear when we contrast this with a DSC Pull Server. The DSC engine on the target
node pulls the DSC configuration when an execution run is scheduled, whereas
we push the DSC configuration to the target node when we want to execute it
interactively using Start-DscConfiguration.
The Start-DscConfiguration Cmdlet syntax we will be using is this:
Start-DscConfiguration [-Path] <System.String> [-Wait] [-Force]
[<CommonParameters>] -CimSession <CimSession[]>

It is a modified version of what you would see if you used the Get-Help Cmdlet
because we have omitted extra parameters to better illustrate what we are doing in
this chapter. This is significantly simpler than what we will be dealing with when we
push DSC configuration files remotely, so it is a good place to start.
[ 155 ]

Pushing DSC Configurations

Start-DscConfiguration accepts a -Path variable where the MOF file will be and
a Boolean parameter called -Wait, along with CommonParameters such as Verbose
and Debug. The Wait parameter is the indication that we want the job to run in front

of us and only return when the DSC execution is completed. Any errors during
execution will be presented to us during the execution run, but no other information.
For this reason, when using Wait it is commonplace to use Verbose as well, so that
the running output from the DSC configuration is presented to you as it happens.
We'll be using this combination as we proceed for this very reason, but we may not
include all the output text as it can become quite verbose (pun intended).

Setting up the test environment locally

Besides building the test computer, there is not much setup to do in order to run
things locally.

Compiling configurations for local target

nodes
Our focus in this chapter is on how to push DSC configurations and not how to use
DSC configurations, so our example configuration is simple and short. This reduces
the amount of code we are working with and the amount of logging we output,
which allows us to fit the DSC configurations in our chapter without having
pages of printouts.
At this point, you should be familiar with compiling DSC
configuration scripts into MOF files. In this chapter, we make the
assumption that you have a good grasp of DSC Configuration
block syntax and use and how to author DSC configuration scripts.
If you are skipping around or feel fuzzy on these concepts, please
refer back to these chapters before you continue.

In our example script, we will create a text file on the primary drive with dummy
contents. Again, we are purposely not fancy here in order to focus on how to push
DSC configurations and not the DSC configurations themselves:
###begin script####
Configuration SetupAllTheThings
{
Node "localhost"
{
File CreateFile
[ 156 ]

Chapter 5
{
Ensure

= "Present"

DestinationPath = "c:\test.txt"
Contents

= "Wakka"

}
}
}

SetupAllTheThings -OutputPath ([IO.Path]::Combine($PSScriptRoot,

"SetupAllTheThings"))
###end script####

Compiling the preceding DSC configuration script gives us a valid MOF file that we
can use on the local computer. This should all be straightforward for you by now,
and you should see the following results from the compiling of the MOF file:
PS C:\Users\Administrator> C:\vagrant\SetupAllTheThings.ps1

Directory: C:\vagrant\SetupAllTheThings

Mode

LastWriteTime

Length Name

----

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

------ ----

-----

7/01/2015

3:19 PM

1276 localhost.mof

If that doesn't compile correctly, look at your syntax and ensure it's the same as what
we have laid out here. It may help if you add the Verbose parameter to your DSC
configuration function to see what is going on as the MOF is compiled. If you are
still having trouble, or want to see even more information, then you can set your
$DebugPreference to Continue and receive even more diagnostic information.
Example output is as shown:
DEBUG:

MSFT_PackageResource: ResourceID = [Package]InstallTheThing

DEBUG:

MSFT_PackageResource:

DEBUG:

MSFT_PackageResource:

DEBUG:

MSFT_PackageResource:

DEBUG:

MSFT_PackageResource:

DEBUG:

MSFT_PackageResource:

Processing property 'DependsOn' [

Processing completed 'DependsOn' ]
Processing property 'Ensure' [
Processing completed 'Ensure' ]
Processing property 'Name' [

DEBUG:
MSFT_PackageResource:
'The Thing'
DEBUG:

MSFT_PackageResource:

Canonicalized property 'Name' =

Processing completed 'Name' ]
[ 157 ]

Pushing DSC Configurations

DEBUG:

MSFT_PackageResource:

Processing property 'Path' [

DEBUG:
MSFT_PackageResource:
'c:\allthethings\thing.msi'

Canonicalized property 'Path' =

DEBUG:

MSFT_PackageResource:

Processing completed 'Path' ]

DEBUG:

MSFT_PackageResource:

Processing property 'ProductId' [

DEBUG:
MSFT_PackageResource:
Canonicalized property 'ProductId'
= '{8f665668-7679-4f53-acde-06cf7eab5d73}'

It's sometimes hard to see the exact error in the DSC output, so get used
to using PowerShell to inspect the built-in $error array to drill down
and find the exact information you need, as shown:
[PS]> $error[0] | Format-List -Property * -Force

If we examine the localhost.mof file, we will see that the file resource laid out
applies to a target node named localhost. This means that, although we compile
this MOF file on the computer we are sitting on, this MOF file can be pushed to any
computer, whether locally or remotely, because localhost applies to any computer.
If we wanted to restrict which target nodes used specific MOF files, we would need
to specify their host names in the Node block. We will cover this when we deal with
pushing DSC configurations remotely shortly.

Executing configurations for local target

nodes
Now that we have the MOF file compiled, we can apply it to our local computer
using Start-DscConfiguration. We will use the Verbose, Wait, and Force
parameters to indicate that we want it to execute interactively and output verbose
information to our shell. We use Force to tell DSC to apply the MOF file regardless
of the current state of the target node (whether it has a pending MOF file or not):
PS C:\Users\Administrator> Start-DscConfiguration -Path C:\vagrant\
SetupAllTheThings -Verbose -Wait -Force
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters,
''methodName' =
SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'n
amespaceName' =
root/Microsoft/Windows/DesiredStateConfiguration'.
VERBOSE: An LCM method call arrived from computer BOX1 with user sid
S-1-5-21-1953236517-242735908-2433092285-500.
VERBOSE: [BOX1]: LCM:

[ Start

Set
[ 158 ]

Chapter 5
VERBOSE: [BOX1]: LCM:

[ Start

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ Start

Test

[[File]CreateaFile]

VERBOSE: [BOX1]:
system cannot find the file specified.

[[File]CreateaFile] The

VERBOSE: [BOX1]:
related file/directory is: c:\test.txt.

[[File]CreateaFile] The

VERBOSE: [BOX1]: LCM:

0.0320 seconds.

[ End

Test

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ Start

Set

[[File]CreateaFile]

in

VERBOSE: [BOX1]:
system cannot find the file specified.

[[File]CreateaFile] The

VERBOSE: [BOX1]:
related file/directory is: c:\test.txt.

[[File]CreateaFile] The

VERBOSE: [BOX1]: LCM:

0.0000 seconds.

[ End

Set

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ End

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ End

Set

VERBOSE: [BOX1]: LCM:

[ End

Set

in

in

0.0790 seconds.

VERBOSE: Operation 'Invoke CimMethod' complete.

VERBOSE: Time taken for configuration job to complete is 0.16 seconds
PS C:\Users\Administrator>
PS C:\Users\Administrator> Test-Path C:\test.txt
True

We get a lot of information back, so let's go over what we are seeing. It initially tells
us that it's performing a DSC operation and the methods it's using to invoke. This is
where we see that the Start-DscConfiguration Cmdlet is just a wrapper over the
CIM methods that actually execute the DSC functions. You won't need to know these
CIM methods for everyday use, but it's interesting to see the inner workings shown
here. The next line is telling us that all the subsequent lines come from our target
node box1 and were initiated by a user with this SID. It doesn't look so important
here as we're running on the same box we've compiled the MOF on; however, when
we deal with remote pushes and note which target node had which operations occur
on it, it becomes very important. The rest of the lines tell us that the file did not exist
and that DSC had to create it. Not so hard, is it?

[ 159 ]

Pushing DSC Configurations

Remotely pushing DSC configurations

Once you have mastered pushing DSC configuration files locally, you will find that
there isn't a lot of difference in pushing them remotely. It's pretty much the same
steps but with the addition of creating a remote session on the target host before
pushing. We can either create remote sessions called CimSessions ourselves or allow
Start-DscConfiguration to create them for us in order to pass information and
commands to the remote host.
We would create CimSessions ourselves if we wanted to reuse the sessions for
multiple attempts, as this would save us time connecting, closing, and reconnecting
each time we attempted to push DSC configurations. We also would create
CimSessions if we had a nonstandard WinRM setup, for example HTTPS endpoints
or different authentication methods (Kerberos or basic authentication, and so on).
You will definitely create your own CimSessions in a non-domain or workgroup
environment, as the account you are using to issue the Start-DscConfiguration
command will be local to the computer you are sitting on and not present on the
remote target node. You would also have to configure the authentication methods
in order to have local token policies allow remote use of the administrator account.
Configuring remote sessions is a large topic and varies with environments;
you should look it up in the PowerShell documentation for more information
about special options when connecting with WinRM or PowerShell Remoting.
Some places to start are http://blogs.technet.com/b/heyscriptingguy/
archive/2013/11/29/remoting-week-non-domain-remoting.aspx and http://
blogs.msdn.com/b/wmi/archive/2009/07/24/powershell-remoting-betweentwo-workgroup-machines.aspx.
Before continuing in this section, it is helpful to know what PowerShell
Remoting and PowerShell CimSessions are. These features are used
heavily with the remote use of DSC, so having an understanding of
how they work will be key for you to use it effectively. Explaining
PSRemoting is beyond the scope of this book, but there are several
resources online to follow. A good place to start is on the TechNet
site: http://blogs.technet.com/b/heyscriptingguy/
archive/2014/01/31/comparing-powershell-pssessionsand-cim-sessions.aspx.

[ 160 ]

Chapter 5

You may not be familiar with CimSessions as much as you are with PSSession, but
they both describe remote sessions on a target node. What is important to know for
this chapter is that CimSessions cannot execute arbitrary code like a PSSession can; it
executes specific CIM methods on a remote target node. Start-DscConfiguration
and other DSC Cmdlets are mostly wrappers around CIM methods. This is not a
limitation for CimSessions, as working this way takes up fewer system resources on
the target node.
You create CimSessions by using the New-CimSession Cmdlet and storing the result
in a variable that you can pass to the Start-DscConfiguration Cmdlet:
[PS]> $cred = Get-Credential
[PS]> $session = New-CimSession ComputerName "foo" Credential $cred

As you can see, the New-CimSession Cmdlet accepts a computer name and a
PSCredential object. We can also create many CimSessions at the same time by
passing in an array of computer names, as follows:
[PS]> $session = New-CimSession ComputerName "foo","Bar","baz","wakka"
Credential (Get-Credential)

Now that we know how to connect to a target node, we can start setting up the
environment.

Setting up the test environment remotely

Pushing DSC configurations remotely requires some extra steps. Some of these steps
may not be needed in your environment, depending on how you configured it. We
will note which we're dealing with as we come to each step.
On box1, we run the following commands to allow PSRemoting to connect using
IP addresses. This is not necessary in a production environment and only necessary
when you are using IP addresses and not short domain names or fully qualified
domain names (FQDN). Since here the example test environment is using test VMs
that have no DNS, we have to allow IP addresses to be used:
PS C:\Users\Administrator> Set-Item WSMan:\localhost\Client\TrustedHosts
-Value *
WinRM Security Configuration.
This command modifies the TrustedHosts list for the WinRM client. The
computers in the TrustedHosts list might not be

[ 161 ]

Pushing DSC Configurations

authenticated. The client might send credential information to these
computers. Are you sure that you want to modify
this list?
[Y] Yes

[N] No

[S] Suspend

[?] Help (default is "Y"): y

PS C:\Users\Administrator>

In box2, we run the following commands. Modifying the built-in firewall is only
necessary in a test environment to make life easier, and is not recommended in a
production environment. In a production environment, you would have already
allowed rules in your firewall setup for PSRemoting, so this should not be necessary.
The second command enables PSRemoting. DSC doesn't require PSRemoting exactly;
it requires WinRM to work against remote target nodes. We use the commands to
enable PSRemoting because those commands configure and start up WinRM for
us without any extra effort on our part. Starting with Windows 2012, PSRemoting
comes enabled by default, so it really is not much of an imposition to expect both to
be configured on target nodes.
PS C:\Users\Administrator> Set-NetFirewallProfile -All -Enabled False
PS C:\Users\Administrator> Enable-PSRemoting -Force
WinRM is already set up to receive requests on this computer.
WinRM is already set up for remote management on this computer.

We can test connections from box1 to box2 by creating a CimSession using the
commands we covered earlier:
[PS]> $cred = Get-Credential administrator
[PS]> $session = New-CimSession ComputerName "192.168.0.13" Credential
$cred

If errors occur, then check your network connectivity and permissions. Consult the
PowerShell Remoting documentation for more information on how to troubleshoot
PSRemoting connections.

[ 162 ]

Chapter 5

Compiling configurations for remote target

nodes
If you remember earlier when we were pushing DSC configurations locally, the state
of our test computer (called box1) looks like this:
PS C:\Users\Administrator> C:\vagrant\SetupAllTheThings.ps1

Directory: C:\vagrant\SetupAllTheThings

Mode

LastWriteTime

Length Name

----

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

------ ----

-----

7/01/2015

3:19 PM

1276 localhost.mof

We want to now apply this same DSC configuration to another computer, without
actually logging into that computer ourselves. Creating the CimSession as we did
earlier is not enough. That allows us to connect to the remote host, but we need
a way to tell DSC that we want this DSC configuration file to be executed on that
target node. If we recall our previous chapters on DSC configurations and DSC
configuration data, we know that we can create a configuration data section with
the relevant information on our target nodes and not have to change our DSC
configuration much at all. We'll add a DSC configuration data hash and add the
information for box1 and box2 to it now. Then, we'll modify the Node block and use
the $AllNodes variable to pass the node information to the DSC configuration:
###begin script###
$data = @{
AllNodes = @(
@{ NodeName = 'localhost' },
@{ NodeName = '192.168.0.13' }
)
}

Configuration SetupAllTheThings
{
Node $AllNodes.NodeName
{
File CreateFile
{

[ 163 ]

Pushing DSC Configurations

Ensure

= "Present"

DestinationPath = "c:\test.txt"
Contents

= "Wakka"

}
}
}

SetupAllTheThings -ConfiurationData $data -OutputPath ([IO.

Path]::Combine($PSScriptRoot, "SetupAllTheThings"))
###end script###

Compiling that DSC configuration into an MOF file in box1 results in the
following output:
PS C:\Users\Administrator> C:\vagrant\SetupAllTheThings.ps1

Directory: C:\vagrant\SetupAllTheThings

Mode

LastWriteTime

Length Name

----

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

------ ----

-----

8/1/2015

1:44 AM

1234 localhost.mof

-----

8/1/2015

1:44 AM

1240 192.168.0.13.mof

We now have two MOF files, one for the localhost (box1) and one for 192.168.0.13
(box2). Looking at 192.168.0.13.mof, we see that it has information for box2
inside it. This is the information that Start-DscConfiguration needs in order to
determine which target nodes need to be pushed to the DSC configuration. The
CimSessions give us the transport to the target nodes, but the MOF files give us
the destinations.

Executing configurations for remote target

nodes
Now that we have MOF files and CimSessions and are ready to start pushing DSC
configurations to remote target nodes, we use Start-DscConfiguration just like
we did before, with the addition of using the CimSession parameter and passing our
CimSession that we created previously to it.

[ 164 ]

Chapter 5

Again, we use CimSession here because sometimes you need special credentials,
authentication, or other options in order to connect to remote target nodes. You can
omit creating a separate CimSession here if you so wish:
PS C:\Users\Administrator> Start-DscConfiguration -Path C:\vagrant\
SetupAllTheThings -Verbose -Wait Force CimSession $session
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters,
''methodName' =
SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'n
amespaceName' =
root/Microsoft/Windows/DesiredStateConfiguration'.
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters,
''methodName' =
SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'n
amespaceName' =
root/Microsoft/Windows/DesiredStateConfiguration'.
VERBOSE: An LCM method call arrived from computer BOX1 with user sid S-15-21-1953236517-242735908-2433092285-500.
VERBOSE: An LCM method call arrived from computer BOX1 with user sid S-15-21-1953236517-242735908-2433092285-500.
VERBOSE: [BOX2]: LCM:

[ Start

Set

VERBOSE: [BOX1]: LCM:

[ Start

Set

VERBOSE: [BOX2]: LCM:

[ Start

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX2]: LCM:

[ Start

Test

[[File]CreateaFile]

VERBOSE: [BOX2]:
system cannot find the file specified.

[[File]CreateaFile] The

VERBOSE: [BOX2]:
related file/directory is: c:\test.txt.

[[File]CreateaFile] The

VERBOSE: [BOX2]: LCM:

0.0000 seconds.

[ End

Test

[[File]CreateaFile]

VERBOSE: [BOX2]: LCM:

[ Start

Set

[[File]CreateaFile]

in

VERBOSE: [BOX2]:
system cannot find the file specified.

[[File]CreateaFile] The

VERBOSE: [BOX2]:
related file/directory is: c:\test.txt.

[[File]CreateaFile] The

VERBOSE: [BOX2]: LCM:

0.0000 seconds.

[ End

Set

[[File]CreateaFile]

VERBOSE: [BOX2]: LCM:

[ End

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX2]: LCM:

[ End

Set

VERBOSE: [BOX2]: LCM:

[ End

Set

[ 165 ]

in

0.0000 seconds.

in

Pushing DSC Configurations

VERBOSE: Operation 'Invoke CimMethod' complete.
VERBOSE: [BOX1]: LCM:

[ Start

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ Start

Test

[[File]CreateaFile]

VERBOSE: [BOX1]:
[[File]CreateaFile] The
destination object was found and no action is
required.
VERBOSE: [BOX1]: LCM:
0.0160 seconds.

[ End

Test

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ Skip

Set

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ End

Resource ]

[[File]CreateaFile]

VERBOSE: [BOX1]: LCM:

[ End

Set

VERBOSE: [BOX1]: LCM:

[ End

Set

in

in

0.0630 seconds.

VERBOSE: Operation 'Invoke CimMethod' complete.

VERBOSE: Time taken for configuration job to complete is 0.086 seconds
PS C:\Users\Administrator>

If all went well, you should see the preceding output on your test system. Notice
in the output that both box2 and box1 had DSC configurations applied to them.
You can also see that we have more output for box2 than we have for box1. That is
because the file was not present in box2 while it was present in box1. This is a great
example of the benefit of CM products like DSC; it detected that the file was already
present on box1 and did not need to touch it while noticing that it was not present on
box2 and creating it. Both actions were easily discovered in the log.
Also notice that we get the same format logging as we do when pushing DSC
configurations locally even though we are operating on remote target nodes.
Each log has the node that it is coming from, so it is easy to see which ones are for
which hosts. This is useful for our Verbose messages but even more useful for any
ErrorMessages that come from our executions. If we received an error during
execution, it would look like this:
[PS]> $error[0] | fl * -for

writeErrorStream

: True

PSMessageDetails

OriginInfo

: REMOTE-TEST-COMPUTER

Exception
A configuration is

: Microsoft.Management.Infrastructure.CimException:

...

[ 166 ]

Chapter 5

The OriginInfo property tells us which target node is sending us the error
information. Of course, DSC logs all this information on the remote host, but it is very
useful to receive it interactively as you test and develop your DSC configurations.
Something that we glossed over is that we pointed Start-DscConfiguration to
a folder containing more than one MOF file and it executed each MOF file on the
respective target nodes with the correct credentials. How did it know to do that?
This is a potentially powerful scenario.
Since Start-DscConfiguration uses WinRM as the transport mechanism, it inherits
all the power and flexibility of the command structures provided by WinRM. One
of these is the ability to connect to many target nodes and execute a command at the
same time. While we may have seen the output from box1 and box2 sequentially,
the DSC execution jobs were performed in parallel or on both machines at once.
The amount of work done in the DSC configuration file for each target node will
determine how long the executions take on each node. Notice that box2 finished
earlier because it had less to do than box1. It only seemed like each target node was
operated on sequentially because we used the Wait parameter, which indicated to
Start-DscConfiguration to only return control to the console session when all
jobs have completed. You can imagine the usefulness when you can apply this to
hundreds of machines at the same time.

Things you must consider when pushing

DSC configurations
Our example DSC configuration is pretty simple even though it worked well for
showcasing how to push DSC configurations. When DSC configurations become
more complex, there are things you must take into consideration.
Up until now, we have been configuring settings or enabling software with DSC
Resources that were already present on the target host. What if we tried to use text
files and MSIs that were not present on the target node? In all our examples, we
haven't had to actually do any work to get the files we want onto our target nodes.
And herein lies the main problem with pushing DSC configurations. Nothing is done
for us; we have to copy everything and ensure everything is present and accessible
on the target nodes. So, what do we have to do for ourselves when pushing DSC
configurations?

[ 167 ]

Pushing DSC Configurations

When pushing DSC configurations, DSC does not copy DSC Resources for you.
While you may be annoyed by this, it does make sense when you think about it. DSC
Resources can be placed at several places, and there isn't a file transfer mechanism
that can be used to put them there without involving the user in making a choice or
providing credentials. You also might be wondering why we need to copy over the
DSC modules if we already compiled the MOF locally. The MOF compilation process
produces the manifest that DSC uses to list the things to do on the target node; the DSC
Resource holds the code that implements the decisions and actions to bring the system
to the desired state, so it has to be present on the target node for it to be executed.
The only way to solve this is to copy the DSC Resources over to the target nodes
yourself when pushing DSC configurations. If you are thinking of using DSC to do
this, that's good inventive thinking, but this is not so easy a problem to solve using
DSC. It's a chicken-and-egg scenario. DSC can't do this for you because it uses the
DSC Resources present on the machine to validate that it can execute the incoming
DSC configuration you are pushing to it. It parses the MOF before it executes it and
tries to find out if all the needed DSC Resources are present on the host. If they aren't
present, then it exits with an error.
When copying DSC Resources, you will have to deal with the normal file copying
problems of which transfer method to use (network or SMB shares, credentials,
and so on). If you are copying new DSC Resources, then you may have to deal
with different versions. Each DSC Resource comes with version information in its
manifest file, but may include or remove files at its own discretion. A blind file copy
will not know to remove files or deal with file renames, among other possible version
scenarios. Using PackageManagement (as described in Chapter 4, DSC Resources)
or a file-sync tool will help alleviate this issue somewhat, but at the same time
introduces steps you have to perform on the remote target nodes before you can
push DSC configurations to them. This means setup steps that you have to either
script or manually follow, determine drift, and so on. Dealing with this via scripting
(deleting if present, reading version files, and so on) adds more complexity to your
deployments and makes you have to do the work of detecting drift, when you
started out having DSC do this for you.
This is somewhat alleviated in DSC v5, where different DSC Resource versions can
coexist side-by-side. Details of how this works are still considered experimental,
so whether this will help in pushing DSC configurations or only help Pull Server
scenarios remains to be seen.

[ 168 ]

Chapter 5

The only way to cheat and accomplish this using DSC is to have two separate DSC
configuration script files. One copies the DSC Resources, and the other contains
the real manifest, but the same problems above apply here. In WMF 5, a potential
solution to this problem exists. You can use a DSC Pull Server to distribute DSC
Resources while still pushing DSC configurations directly to the target nodes.
With all these problems, it is evident that this is not meant to be a scalable long-term
operation for you to perform yourself on many thousands of hosts, and that a pull
server was meant to handle this for you.

Summary
And there you have it: pushing DSC configurations! We have covered how to push
them locally and how to use them remotely for both one machine and many. We
looked at how to push DSC configurations sequentially and all at once. We also
covered the potential drawbacks to the push model and the steps you must take in
pushing DSC configurations that you do not have to with DSC Pull Servers.
In the next chapter, we will cover how to set up DSC Pull Servers and how to use
DSC configurations with them.

[ 169 ]

Get more information Learning PowerShell DSC

Where to buy this book

You can buy Learning PowerShell DSC from the Packt Publishing website.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet
book retailers.
Click here for ordering and shipping details.

www.PacktPub.com

Stay Connected: