At this point, a simple example of the workflow you will use will be helpful to explain what we just covered. We will first create an example DSC configuration file. Then, we will compile it to a MOF file and show an example execution using the push deployment model.
A short note about composing configuration files: if you use the built-in PowerShell Integrated Script Environment (ISE), then you will have intellisense provided as you type. This is useful as you start learning; the popup information can help you as you type things without you having to look back at the documentation. The PowerShell ISE also provides on-demand syntax checking, and will look for errors as you type.
The following text would be saved as a TestExample.ps1 file. You will notice this is a standalone file and contains no configuration data. Let's look at the following code snippet, which is a complete example of a DSC configuration file:
# First we declare the configuration Configuration TestExample { # Then we declare the node we are targeting Node "localhost" { # Then we declare the action we want to perform Log ImportantMessage { Message = "This has done something important" } } } # Compile the Configuration function TestExample
For the sake of simplicity, we have saved more advanced topics like this for Chapter 3, DSC Configuration Files.
We can see the Configuration keyword, which holds all the node statements and DSC Resources statements. Then, the Node keyword is used to declare the target node we are operating on. This can either be hardcoded like in the example or passed in using the configuration data. Finally, the resource declaration for the action we want to take is added. In this example, we will output a message to the DSC event log when this is run on the localhost.
We use the term keyword here to describe Configuration and Node. This is slightly inaccurate, as the actual definitions of Configuration and Node are PowerShell functions in the PSDesiredStateConfiguration module. PowerShell functions can also be defined as Cmdlets. The interchangeability of terms here is partly due to PowerShell's naming flexibility and partly due to informal conventions. It's sometimes a hot topic of contention. For the purposes of this book, substitute your preferred word here.
To compile this DSC configuration file into a MOF, we run the following script from the PowerShell console:
PS C:Examples> .TestExample.ps1 Directory: C:ExamplesTestExample Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 5/20/2015 7:28 PM 1136 localhost.mof
As you can see from the result, compiling the configuration file to a MOF resulted in a folder with the name of the configuration block we just created and with one file called the localhost.mof file.
Let's try the following snippet:
/* @TargetNode='localhost' @GeneratedBy=James @GenerationDate=05/20/2015 19:28:50 @GenerationHost=BLUEBOX */ instance of MSFT_LogResource as $MSFT_LogResource1ref { SourceInfo = "C:\Examples\TestExample.ps1::8::9::Log"; ModuleName = "PSDesiredStateConfiguration"; ModuleVersion = "1.0"; ResourceID = "[Log]ImportantMessage"; Message = "This has done something important"; }; instance of OMI_ConfigurationDocument { Version="1.0.0"; Author="James"; GenerationDate="05/20/2015 19:28:50"; GenerationHost="BLUEBOX"; };
We can see from this MOF that not only do we programmatically state the intent of this configuration (log a message), but we also note the computer it was compiled on as well as the user that did it. This metadata is used by the DSC engine when applying configurations and reporting statuses back to a Pull Server.
Then, we execute this configuration on a target node using the push deployment model by calling the Start-DscConfiguration Cmdlet:
PS C:Examples> Start-DscConfiguration –Path C:ExamplesTestExample –Wait –Verbose VERBOSE: Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = SendConfigurationApply,'className' = MSFT_DSCLocalConfigurationManager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'. VERBOSE: An LCM method call arrived from computer BLUEBOX with user sid ************. VERBOSE: [BLUEBOX]: LCM: [ Start Set ] VERBOSE: [BLUEBOX]: LCM: [ Start Resource ] [[Log]ImportantMessage] VERBOSE: [BLUEBOX]: LCM: [ Start Test ] [[Log]ImportantMessage] VERBOSE: [BLUEBOX]: LCM: [ End Test ] [[Log]ImportantMessage] in 0.0000 seconds. VERBOSE: [BLUEBOX]: LCM: [ Start Set ] [[Log]ImportantMessage] VERBOSE: [BLUEBOX]: [[Log]ImportantMessage] This has done something important VERBOSE: [BLUEBOX]: LCM: [ End Set ] [[Log]ImportantMessage] in 0.0000 seconds. VERBOSE: [BLUEBOX]: LCM: [ End Resource ] [[Log]ImportantMessage] VERBOSE: [BLUEBOX]: LCM: [ End Set ] in 0.3162 seconds. VERBOSE: Operation 'Invoke CimMethod' complete. VERBOSE: Time taken for configuration job to complete is 0.36 seconds
Notice the logging here. We used the Verbose parameter, so we see listed before us every step that DSC took. Each line represents an action DSC is executing, and each has a Start and End word in it, signifying the start and end of each execution, even though an execution may span multiple lines. We will get into how to sort and use these logs more when we address troubleshooting DSC configurations later in this book.
Each INFO, VERBOSE, DEBUG, or ERROR parameter is written both to the console in front of us and to the DSC event log. Everything done is logged for auditing and historical purposes. An important thing to note is that while everything is logged, not everything is logged to the same place. There are several DSC event logs: Microsoft-Windows-DSC/Operational, Microsoft-Windows-DSC/Analytical, and Microsoft-Windows-DSC/Debug. However, only the Microsoft-Windows-DSC/Operational event log is logged to by default; you have to enable the Microsoft-Windows-DSC/Analytical and Microsoft-Windows-DSC/Debug event logs in order to see any events logged there. Any verbose messages are logged in Microsoft-Windows-DSC/Analytical, so beware if you use the Log DSC Resource extensively and intend to find those messages in the logs.