Use the Local Configuration Manager

The Local Configuration Manager, or LCM, is the client agent for PowerShell DSC. It runs on each target node, accepts configuration and executes those configurations. You can’t schedule when the LCM will run, but you can schedule some parameters related to how often it runs. That’s what this chapter is all about, along with the LCMs other configuration options.

Checking the Configuration

Run Get-DscLocalConfigurationManager to see the current configuration. Here’s a default Windows 10 computer:

PS C:\> Get-DscLocalConfigurationManager

ActionAfterReboot              : ContinueConfiguration
AgentId                        : 9BE13016-41FD-11EA-8F88-38F9D3507320
AllowModuleOverWrite           : True
CertificateID                  :
ConfigurationDownloadManagers  : {[ConfigurationRepositoryWeb]AWS}
ConfigurationID                :
ConfigurationMode              : ApplyAndAutoCorrect
ConfigurationModeFrequencyMins : 60
Credential                     :
DebugMode                      : {NONE}
DownloadManagerCustomData      :
DownloadManagerName            :
LCMCompatibleVersions          : {1.0, 2.0}
LCMState                       : PendingConfiguration
LCMStateDetail                 :
LCMVersion                     : 2.0
StatusRetentionTimeInDays      : 10
SignatureValidationPolicy      : NONE
SignatureValidations           : {}
MaximumDownloadSizeMB          : 500
PartialConfigurations          :
RebootNodeIfNeeded             : False
RefreshFrequencyMins           : 240
RefreshMode                    : Pull
ReportManagers                 : {[ReportServerWeb]ComplianceServer}
ResourceModuleManagers         : {}
PSComputerName                 :

Lets walk through each of those. But, before we do that, we have to point out that this set of configuration properties is from a Windows computer.

ActionAfterReboot

This determines what the LCM will do after the computer is rebooted. The default, ContinueConfiguration, will let the LCM pick up where it left off and continue processing the current configuration. You can also choose StopConfiguration, which, as the name implies, stops the Configuration from running further. I imagine you’d really only use StopConfiguration in certain troubleshooting or lab situations.

AllowModuleOverWrite

When set to $False - which is the default - the LCM will not download any DSC resource modules that already exist locally. It’s for safety. The presumption is that, once you put a resource onto a node, the node depends on that exact resource in order to run configuration properly. If you change or update a resource, you’re meant to apply a new version to it. Your configuration can then reference that new version, and if properly configured, the LCM will download that new version. This AllowModuleOverwrite setting only applies to downloading new copies of the exact same module. In a test environment, where you’re frequently iterating modules, you’ll probably set this to $True.

Why would you not set this to $True in production? Well… predictability and stability. If an LCM is allowed to overwrite local modules, that can be convenient for you when making ad-hoc changes. But that subverts the entire best practice of code testing, versioning, and so on. Ideally, if configuration A relies on module B version 1.2, you don’t want module B version 1.3 showing up out of the blue. It might not work the way configuration A expects - for example, module B version 1.3 might require different properties or property values, which configuration A doesn’t provide. The correct practice would be to deploy module B v1.3 as a separate thing, living independently of, and side-by-side with, v1.2. You would then author configuration C, which specifically references module B v1.3, and deploy configuration C to your nodes. That way you always know what each node is using, and troubleshooting becomes a lot easier.

CertificateID

This is the certificate thumbprint (which you can obtain by exploring the CERT: drive) of the encryption certificate that the LCM will use to decrypt any encrypted information from its MOF. Most commonly, this is used to decrypt encrypted logon credentials.

ConfigurationDownloadManagers

This is a collection of pull servers - that is, servers from which MOF files will be pulled.

ConfigurationID

This is a Globally Unique Identifier (GUID) that you assign to the LCM. In WMF v4, this was the only way to tell the LCM which MOF to pull from a pull server. In WMF v5, you can also use configuration names. However, when using ConfigurationID, the node will essentially look on the pull server for a MOF file whose filename is the same GUID.

ConfigurationMode

This controls the LCM’s actions. The following values are allowed:

  • Disabled: The LCM does not run. This is perhaps most often used in cases where a third-party management technology, like Chef, is actually running the show. Chef can use DSC resource modules under the hood, but it doesn’t want the actual LCM stepping in and interfering.

  • ApplyOnly: The LCM applies the current configuration, and then stops running until manually run.

  • ApplyAndMonitor: The LCM applies the current configuration, and re-checks it on the ConfigurationModeFrequencyMinutes value. It does not attempt to fix the configuration, but will report a status to a reporting server if so configured.

  • ApplyAndAutoCorrect: The LCM applies the current configuration, and re-checks it on the ConfigurationModeFrequencyMinutes value. It will attempt to fix out-of-compliance configuration settings and, if configured, will report status to a reporting server.

ConfigurationModeFrequencyMins

This controls how often the LCM will re-evaluate its current configuration. It defaults to, and has a minimum value of, 15 minutes. This is important, conceptually, because it means the LCM cannot guarantee continuous compliance with your desired configuration. If someone changes something, that change can “last” for 15+ minutes until the next consistency check. So in cases where the “desired configuration” could mean the difference between literal life or death, or someone going to jail or not, DSC might not be the right technology. In many cases, you could extend this to 24 hours or more (calculated in minutes) for cases when you simply need a once-a-day check on configuration compliance.

Credential

This appears to be obsolete, since the individual resource blocks can define this on a per-instance basis.

DebugMode

Whether or not the LCM’s debug mode is on or off ($True or $False).

DownloadManagerCustomData

This appears to be obsolete in v5.

DownloadManagerName

This appears to be obsolete in v5.

LCMCompatibleVersions

The LCM versions that this LCM is compatible with. For example, LCM 2.0, which ships in WMF v5, is compatible with LCM 1.0, meaning it can accept the same configuration documents that the older LCM accepted, in addition to newer, 2.0-only ones.

LCMState

This tells you what the LCM is currently up to:

  • Idle
  • Busy
  • PendingReboot
  • PendingConfiguration

LCMStateDetail

This is usually a more descriptive version of what the LCM is doing right then, like “LCM is applying a new configuration.”

LCMVersion

The version of the LCM.

StatusRetentionTimeInDays

This controls how long the LCM will retain current status information. The default is 10 days.

PartialConfigurations

This doesn’t presently do anything.

RebootNodeIfNeeded

When set to $True, the LCM will automatically restart the target node if a DSC resource indicates that a restart is required to finalize the configuration. This is set to $False by default, on the very reasonable grounds that most people want a little more control over when their servers restart.

RefreshFrequencyMins

This controls how often the LCM will check the pull server for new MOFs. It defaults to 30 minutes, and in WMF v4 must be set to an even multiple of the ConfigurationModeFrequencyMinutes value (15 * 2 = 30, hence the default of 30). This value should always be larger than the ConfigurationModeFrequencyMinutes.

RefreshMode

Push or Pull. As easy as that. This defaults to Push, meaning that the LCM just sits and waits for you to hit it up with a configuration.

ReportManagers

This is a collection of configured reporting servers.

ResourceModuleManagers

This is a collection of pull servers from which modules (DSC resources) can be downloaded.

Changing the Configuration

To change the configuration of an LCM, even the local one, you need a meta-MOF. This is a special MOF that you can create by writing a special PowerShell configuration script. Meta-MOFs are pushed to their nodes, using the Set-DscLocalConfigurationManager cmdlet (which uses CIM sessions for connectivity). A meta-MOF configuration script might look something like the following:

[DSCLocalConfigurationManager()]
configuration LCMConfig
{
    Node Node1
    {
        Settings
        {
            RefreshMode = 'Push'
        }
    }
}

In this case, the [DSCLocalConfigurationManager()] bit tells PowerShell that this is to be a meta-MOF, which is generated somewhat differently than a normal configuration MOF. The name of the configuration, LCMConfig, is arbitrary. You simply need to specify that name - usually at the very bottom of the script file - to run the config and generate the MOF (it’s basically like running a function). W ithin the Settings{} block is where you can put whatever settings you like from the list above.

Deploying the LCM Configuration

The file Node1.meta.mof will be created in a sub-folder named LCMConfig. Once you’ve run that and generated a Node1.meta.mof, you can use Set-DscLocalConfigurationManager to “push” the meta-MOF to Node1.

Set-DscLocalConfigurationManager -Path ./LCMConfig -ComputerName Node1 -verbose

It’s also possible to “inject” the meta-MOF into a node by copying it into the place where the LCM looks for it (C:/Windows/System32/Configuration/metaconfig.mof). For example, this is a great way to help configure the LCM as part of an automated VM build, since you can use things like the Hyper-V integration cmdlets to copy files into the VM.

NOTE: I should point out that there can be a bunch of caveats around “injecting” a MOF by simply copying a file. I’ve found it’s nearly always better to push the meta-MOF to the LCM as part of an automated build process, or just to copy the meta-MOF to an arbitrary local file on the node and have the VM “push” that to itself.

And keep in mind that you can also “sort of push” a meta-MOF into a VM node, even if WS-MAN isn’t enabled on the node, by using integration components like those provided by Hyper-V. If you want to read more on injection, though, have a look at these articles: Injecting PowerShell DSC Meta and Node Configurations and Want to Automatically Configure Your Machines Using DSC at Initial Boot-up?, although those articles refer to WMF v4, so the actual examples are slightly outdated.