PowerShell How-To

How To Configure PowerShell's Local Configuration Manager

With multiple ways to accomplish the task, here's how to know the right route to take based on the situation.

• By Adam Bertram
• 10/13/2016

Central to the idea of DevOps is configuration as code, and PowerShell supports it with Desired State Configuration. DSC scripts execute to create Management Object Format or MOF files, but those files don't carry out their own instructions. A Windows server uses its Local Configuration Manager to read the MOF files and implement the configuration.  As you might expect, there are different ways to configure the LCM to determine how it carries out those instructions. Let's take a look at how to do that.

Apply a Configuration
The primary task at hand for the LCM is to read MOF files and implement the configurations they specify. But how often should it check for configuration drift or how often should it pull configurations from a pull server and where is that server? Should the server automatically reboot if required or wait for someone to command a restart?

To set these options, we write a DSC script specifically targeted at the LCM. An example script can be seen below.

 

Configuration FileConfig

  {

  Node $env:COMPUTERNAME

  {

  File 'FileDemo '

  {

  Type = 'File'

  DestinationPath = 'c:\testFile.txt'

  Ensure = 'Present'

  Contents = 'Hello  Configuration!'

  }

  }

  }

Configuration LCMConfig

  {

  Node $env:COMPUTERNAME

  {

  LocalConfigurationManager

  {

  ConfigurationModeFrequencyMins = 30

  ConfigurationMode = "ApplyAndAutocorrect"

  RefreshMode = "Push"

  RebootNodeIfNeeded = $true

  }

  }

  }
# Invoke the DSC  Functions and creat the MOF Files

  LCMConfig -OutputPath "C:\DSCConfigs"

FileConfig -outputPath "C:\DSCConfigs"
# Set the Local Config  Manager to use the new MOF for config

Set-DscLocalConfigurationManager  -Path "C:\DSCConfigs"
# Apply the file config.

Start-DSCConfiguration -Verbose -Wait -Path "C:\DSCConfigs" 

We've created two configurations with the script above. We've created a regular Servername.mof and also created a Servername.meta.mof. The meta MOF is the configuration for the LCM. As you can see the configuration we wrote for the LCM isn't complicated. To make sure that the settings have taken affect we can call the Get-DscLocalConfigurationManager cmdlet as shown below.

With the script above we set the LCM to check on the server's configuration state every 30 minutes (ConfigurationModeFrequencyMins), Automatically correct any configuration drift (ConfigurationMode), and configure the refresh mode to "Push" (RefreshMode).

Refresh Mode
The refresh mode is worth discussing because it's one of the primary functions of the LCM. The refresh mode setting determines how new configurations are loaded into the LCM to be enforced. If we set the LCM to Push mode as we have here, we are responsible for manually initiating a new configuration using the Start-DSCLocalConfiguration Cmdlet and providing the path to a directory where the server can find a valid configuration file for the current node.

You can use a network share as the path to pick up configuration MOF files, but there's a catch. The LCM doesn't run as a standard user account, it will run as the machines own SYSTEM account. This means if the share is hosted on the same machine the LCM is running on, then you must grant "NT Authority\System" READ permission on the share. If the share is hosted on a remote machine then you will need to allow the server's Active Directory Machine Account "Domain\ServerName$" READ permissions to the share on the remote computer.

The other option for RefreshMode is "Pull". In Pull mode the LCM will reach out to the network and check either a web server or an SMB share for new configurations. An example configuration for a web pull server is below.

Configuration  ExamplePullConfig

  {

  param(

  [string]$pullServerName =  "DSCPullServer01"

  )
    Node $env:COMPUTERNAME

  {

  LocalConfigurationManager

  {

  ConfigurationID = "51be79db-5a48-49e5-b006-c48899b286a3"

  ConfigurationModeFrequencyMins = 45

  ConfigurationMode = "ApplyAndAutocorrect"

  RefreshMode = "Pull"

  RefreshFrequencyMins = 90

  DownloadManagerName = "WebDownloadManager"

  DownloadManagerCustomData =  (@{ServerUrl="https://$pullServerName/psdscpullserver.svc"})

  CertificateID = "9217F40164310A1165400CB3DAEDAC01CF23F7E9"

  RebootNodeIfNeeded = $true

  AllowModuleOverwrite = $false

  }

  }

  }
ExamplePullConfig -OutputPath "C:\DSCConfigs"
Set-DscLocalConfigurationManager  -Path "C:\DSCConfigs"

The configuration above checks for configuration drift every 45 minutes and fixes any issues it finds. But it also checks with the remote server for changes to the configuration every 90 minutes. Sometimes those configurations will require the use of credentials encoded in the MOF. The configuration above specifies the thumbprint of a certificate that can be used to decrypt the configuration so that credentials and other sensitive data contained in MOF files are transmitted and stored securely.

Setting up a Pull server isn't as straightforward as just executing configuration scripts to create MOF files on a local server and applying them with Start-DSCConfiguration. This article is about the LCM, but you can read about setting up a pull server by reading one of my articles over on the Pluralsight blog.

The extra work is worth it if you have a large number of nodes to manage. A Pull server gives you a central place to manage all of your nodes' configuration files, and your servers call in on their own to retrieve their configurations. In PowerShell five this process gets easier since configurationID's are replaced by ConfigurationNames and RegistrationKey's.

In this article, we learned that Windows Servers manage Desired State Configuration using a Local Configuration Manager. Like the rest of the system, the Configuration Manager must itself be configured to carry out its tasks, and we do that using meta configurations that we create using DSC configuration scripts.

We've looked at getting started with configuring the LCM, but there's more to learn. This MSDN page has more information about setting up the LCM. PowerShell 5 also gives you the ability to set partial configurations, a powerful new feature in DSC.