Understanding Meta Configuration in Windows PowerShell Desired State Configuration

PowerShell Team

UPDATE 2/6/2018 – The latest information regarding LCM configuration is available in the documentation at the following link: https://docs.microsoft.com/en-us/powershell/dsc/metaconfig

……….

LCM and Meta Configuration

To understand the concept of Meta Configuration, first we need to know what Local Configuration Manager (LCM) is, and what its responsibilities are. In short, LCM is the engine of Windows PowerShell Desired State Configuration (DSC), and it runs on every target node. Whenever we send the DSC configuration document to a node, it’s LCM’s job to parse it and call appropriate resources which will put the machine in the desired state. LCM also makes sure that the node stays in that state, and reconfigures the target machine when it detects configuration drift.

LCM’s behavior can be modified by setting Meta Configuration properties. In this blog post, I’ll discuss what properties we can configure, and what effect they have on LCM, as well as how to set the new Meta Configuration and get the current one.

Getting Meta Configuration

To get the current Meta Configuration, all we need to do is to call the Get-DscLocalConfigurationManager cmdlet. Even if we haven’t previously set any Meta Configuration, we will get the default one which is presented below.

As we see, not all properties are required, and thus not all of them are specified by default. I’ll explain the meaning of every property in the next section.

Meta Configuration properties

Although Meta Configuration can be as simple as the one above, there are many additional properties we might want to set in different situations. Let’s look at all of them.

Configuration mode and refresh frequency

The values of the properties ConfigurationModeFrequencyMins and RefreshFrequencyMins depend on each other, and thus may be confusing at the first sight.

· ConfigurationModeFrequencyMins:

Specifies how often the consistency engine runs and applies the configuration.

· RefreshFrequencyMins:

Specifies how often LCM attempts to pull new configuration from the server (in PULL mode).

Because applying the same configuration again and again makes (usually – let’s not forget about fixing configuration drifts) little sense, there’s a requirement for ConfigurationModeFrequencyMins to be a multiplication of RefreshFrequencyMins. Even if we don’t follow this requirement, LCM automatically rounds the value of ConfigurationModeFrequencyMins up when it is applying the Meta Configuration.

To illustrate this behavior in PULL mode, let’s look at the table below:

In PUSH mode, rounding looks very similar, though the concept of pulling (and therefore the value of RefreshFrequencyMins) doesn’t apply here:

Setting Meta Configuration

Now that we know what Meta Configuration is and what properties it contains, the next step is to create and apply a new Meta Configuration. It can be authored by writing the following PowerShell script:

Configuration DemoConfiguration

{

Node “localhost”

{

LocalConfigurationManager

{

ConfigurationMode = “ApplyAndAutoCorrect”

RefreshFrequencyMins = 30

ConfigurationModeFrequencyMins = 60

RefreshMode = “PUSH”

RebootNodeIfNeeded = $true

}

}

}

As we see, the code above is very similar to a DSC configuration script. We have a named configuration section which contains one node section (or many of them, if we want to prepare multiple Meta Configurations for different nodes). The only new element is a LocalConfigurationManager section, in which we specify Meta Configuration properties, and then assign values to them.

After we prepare a script with Meta Configuration (I named it DemoConfiguration.ps1, and saved it in the C:\test directory), we should import it to our PowerShell session, and then execute the configuration:

As a result, localhost.meta.mof is generated in a new folder with the same name as the configuration (C:\test\DemoConfiguration). The localhost part of the name may be different, depending on the node for which Meta Configuration is generated. You can also explicitly specify in what folder the meta.mof file should be generated by providing an output parameter:

The last step is to apply the Meta Configuration by running the Set-DscLocalConfigurationManager cmdlet, and providing path to the parent directory of the meta.mof file in the path parameter.

If everything was successful, we should be able to see our new configuration after running Get-DscLocalConfigurationManager:

Setting Meta Configuration on remote machine

To apply a Meta Configuration to the remote machine, we need to modify the Node section of the Meta Configuration script (DemoConfiguration.ps1 in our case).

Configuration DemoConfiguration

{

Node “PS3319277565”

{

LocalConfigurationManager

{

ConfigurationMode = “ApplyAndAutoCorrect”

RefreshFrequencyMins = 30

ConfigurationModeFrequencyMins = 60

RefreshMode = “PUSH”

RebootNodeIfNeeded = $true

}

}

}

The only change is to replace localhost with the name of the machine to which we want to apply our Meta Configuration (PS3319277565 in our case).

Once we execute it, PS3319277565.meta.mof is generated. We can apply the MOF by running Set-DscLocalConfigurationManager, and adding the ComputerName parameter:

We could also omit ComputerName, but if we had any additional <NodeName>.meta.mof files in the folder specified by the path parameter, they all would be applied to appropriate machines. Adding the ComputerName parameter is great when we want to make sure that we are applying a Meta Configuration solely to a specific machine.

Summary

In this blog post, I explained Meta Configuration, and what are the purposes of its different properties. I presented how to obtain the current Meta Configuration, as well as create and set a new one. We also looked at the way to apply Meta Configuration to remote machines. My intent wasn’t to cover all possible scenarios we might want to accomplish with Meta Configuration, but rather to give a general overview, and provide a good foundation for further trials. I encourage you to try working with Meta Configurations yourself, and provide feedback in the comments about your experiences.

Karol Kaczmarek

SDET – PowerShell Team

Microsoft

PowerShell Team PowerShell Team, PowerShell

Follow