Understanding Meta Configuration in Windows PowerShell Desired State Configuration

Understanding Meta Configuration in Windows PowerShell Desired State Configuration

Rate This
  • Comments 2

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.

clip_image001

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.

Property

Description

AllowModuleOverwrite

Specifies whether new modules that are downloaded from a pull server overwrite the old ones. The property can be set to true or false.

CertificateID

GUID of the certificate.

ConfigurationID

GUID which is used to get the configuration from the server when in PULL mode (see ConfigurationMode).

ConfigurationMode

Specifies how LCM should apply the configuration. Valid values are:

· ApplyOnly: Configuration isapplied once.

· ApplyAndMonitor: Configuration isapplied, and LCM monitors whether any changes occur. If configuration drift is detected, it isreported in logs.

· ApplyAndAutoCorrect: Configuration is applied, and LCM monitors whether changes occur. If configuration drift is detected, LCM reapplies the configuration.

ConfigurationModeFrequencyMins

Specifies how often (in minutes) LCM ensures that the configuration is in the desired state.

Credential

Credentials to access remote resources.

DownloadManagerCustomData

Specifies additional data to send to the download manager.

DownloadManagerName

Specifies which download manager to use. By default, there are two download managers available: WebDownloadManager and DscFileDownloadManager.

RebootNodeIfNeeded

Specifies whether the target node is automatically restarted when configuration requires it (for example, the machine might need to be restarted when adding or removing server roles and features).

Accepted values: True or False.

RefreshFrequencyMins

Specifies how often (in minutes) LCM attempts to obtain the configuration from the pull server. If configuration on the pull server differs from the current one on the target node, it is copied to the pending store and applied.

RefreshMode

Refresh mode, which can accept one of two values:

· PUSH – Configuration is sent (pushed) to the node by running the Start-DscConfiguration cmdlet (from the same or remote node).

· PULL – Node periodically checks for configuration updates on the pull server, and gets (pulls) it when available. The pull server from which to pull the configuration is specified by values in DownloadManagerName and DownloadManagerCustomData properties.

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:

 

Value in Meta Configuration

Value after Meta Configuration is applied

How often pull happens [mins]

How often configuration is applied [mins]

ConfigurationModeFrequencyMins

50

60

20

60

RefreshFrequencyMins

20

20

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

 

Value in Meta Configuration

Value after Meta Configuration is applied

How often configuration is applied [mins]

ConfigurationModeFrequencyMins

50

60

60

RefreshFrequencyMins

20

20

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:

clip_image002

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:

clip_image003

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.

clip_image004

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

clip_image005

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:

clip_image007

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

Leave a Comment
  • Please add 3 and 6 and type the answer here:
  • Post
Page 1 of 1 (2 items)