Table of contents
TOC
Collapse the table of content
Expand the table of content

Configuring the Local Configuration Manager

Eric Slesar|Last Updated: 6/17/2016
|
2 Contributors

Applies To: Windows PowerShell 5.0

The Local Configuration Manager (LCM) is the engine of Windows PowerShell Desired State Configuration (DSC). The LCM runs on every target node, and is responsible for parsing and enacting configurations that are sent to the node. It is also responsible for a number of other aspects of DSC, including the following.

  • Determining refresh mode (push or pull).
  • Specifying how often a node pulls and enacts configurations.
  • Associating the node with pull servers.
  • Specifying partial configurations.

You use a special type of configuration to configure the LCM to specify each of these behaviors. The following sections describe how to configure the LCM.

Note: This topic applies to the LCM introduced in Windows PowerShell 5.0. For information about configuring the LCM in Windows PowerShell 4.0, see Windows PowerShell 4.0 Desired State Configuration Local Configuration Manager.

Writing and enacting an LCM configuration

To configure the LCM, you create and run a special type of configuration. To specify an LCM configuration, you use the DscLocalConfigurationManager attribute. The following shows a simple configuration that sets the LCM to push mode.

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

You call and run the configuration to create the configuration MOF, just as you would a normal configuration (for information on creating the configuration MOF, see Compiling the configuration). Unlike normal configurations, you do not enact an LCM configuration by calling the Start-DscConfiguration cmdlet. Instead, you call the Set-DscLocalConfigurationManager cmdlet, supplying the path to the configuration MOF as a parameter. After you enact the configuration, you can see the properties of the LCM by calling the Get-DscLocalConfigurationManager cmdlet.

An LCM configuration can contain blocks only for a limited set of resources. In the previous example, the only resource called is Settings. The other available resources are:

  • ConfigurationRepositoryWeb: specifies an HTTP pull server for configurations.
  • ConfigurationRepositoryShare: specifies an SMB pull server for configurations.
  • ResourceRepositoryWeb: specifies an HTTP pull server for modules.
  • ResourceRepositoryShare: specifies an SMB pull server for modules.
  • ReportServerWeb: specifies an HTTP pull server to which reports are sent.
  • PartialConfiguration: specifies partial configurations.

Basic settings

Other than specifying pull servers and partial configurations, all of the properties of the LCM are configured in a Settings block. The following properties are available in a Settings block.

PropertyTypeDescription
ConfigurationModeFrequencyMinsUInt32How often, in minutes, the current configuration is checked and applied. This property is ignored if the ConfigurationMode property is set to ApplyOnly. The default value is 15.
Note: Either the value of this property must be a multiple of the value of the RefreshFrequencyMins property, or the value of the RefreshFrequencyMins property must be a multiple of the value of this property.
RebootNodeIfNeededboolSet this to $true to automatically reboot the node after a configuration that requires reboot is applied. Otherwise, you will have to manually reboot the node for any configuration that requires it. The default value is $false.
ConfigurationModestringSpecifies how the LCM actually applies the configuration to the target nodes. Possible values are "ApplyOnly","ApplyandMonitior"(default), and "ApplyandAutoCorrect".
  • ApplyOnly: DSC applies the configuration and does nothing further unless a new configuration is pushed to the target node or when a new configuration is pulled from a server. After initial application of a new configuration, DSC does not check for drift from a previously configured state.
  • ApplyAndMonitor: This is the default value. The LCM applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs.
  • ApplyAndAutoCorrect: DSC applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs, and then re-applies the current configuration.
ActionAfterRebootstringSpecifies what happens after a reboot during the application of a configuration. The possible values are "ContinueConfiguration(default)" and "StopConfiguration".
  • ContinueConfiguration: Continue applying the current configuration after machine reboot.
  • StopConfiguration: Stop the current configuration after machine reboot.
RefreshModestringSpecifies how the LCM gets configurations. The possible values are "Disabled", "Push(default)", and "Pull".
  • Disabled: DSC configurations are disabled for this node.
  • Push: Configurations are initiated by calling the Start-DscConfiguration cmdlet. The configuration is applied immediately to the node. This is the default value.
  • Pull: The node is configured to regularly check for configurations from a pull server. If this property is set to Pull, you must specify a pull server in a ConfigurationRepositoryWeb or ConfigurationRepositoryShare block. For more information about pull servers, see Setting up a DSC pull server.
CertificateIDstringA GUID that specifies a certificate used to secure credentials for access to the configuration. For more information see Want to secure credentials in Windows PowerShell Desired State Configuration?.
ConfigurationIDstringA GUID that identifies the configuration file to get from a pull server in pull mode. The node will pull configurations on the pull sever if the name of the configuration MOF is named ConfigurationID.mof.
Note: If you set this property, registering the node with a pull server by using RegistrationKey does not work. For more information, see Setting up a pull client with configuration names.
RefreshFrequencyMinsUint32The time interval, in minutes, at which the LCM checks a pull server to get updated configurations. This value is ignored if the LCM is not configured in pull mode. The default value is 30.
Note: Either the value of this property must be a multiple of the value of the ConfigurationModeFrequencyMins property, or the value of the ConfigurationModeFrequencyMins property must be a multiple of the value of this property.
AllowModuleOverwritebool$TRUE if new configurations downloaded from the configuration server are allowed to overwrite the old ones on the target node. Otherwise, $FALSE.
DebugModestringPossible values are None(Default), ForceModuleImport, and All.
  • Set to None to use cached resources. This is the default and should be used in production scenarios.
  • Setting to ForceModuleImport, causes the LCM to reload any DSC resource modules, even if they have been previously loaded and cached. This impacts the performance of DSC operations as each module is reloaded on use. Typically you would use this value while debugging a resource
  • In this release, All is same as ForceModuleImport
ConfigurationDownloadManagersCimInstance[]Obsolete. Use ConfigurationRepositoryWeb and ConfigurationRepositoryShare blocks to define configuration pull servers.
ResourceModuleManagersCimInstance[]Obsolete. Use ResourceRepositoryWeb and ResourceRepositoryShare blocks to define resource pull servers.
ReportManagersCimInstance[]Obsolete. Use ReportServerWeb blocks to define report pull servers.
PartialConfigurationsCimInstanceNot implemented. Do not use.
StatusRetentionTimeInDaysUInt32The number of days the LCM keeps the status of the current configuration.

Pull servers

A pull server is either an OData web service or an SMB share that is used as a central location for DSC files. LCM configuration supports defining the following types of pull servers:

  • Configuration server: A repository for DSC configurations. Define configuration severs by using ConfigurationRepositoryWeb (for web-based servers) and ConfigurationRepositoryShare (for SMB-based servers) blocks.
  • Resource server—A repository for DSC resources, packaged as PowerShell modules. Define resource severs by using ResourceRepositoryWeb (for web-based servers) and ResourceRepositoryShare (for SMB-based servers) blocks.
  • Report server—A service that DSC sends report data to. Define report servers by using ReportServerWeb blocks. A report server must be a web service.

For information about setting up and using pull servers, see Setting up a DSC pull server.

Configuration server blocks

To define a web-based configuration sever, you create a ConfigurationRepositoryWeb block. A ConfigurationRepositoryWeb defines the following properties.

PropertyTypeDescription
AllowUnsecureConnectionboolSet to $TRUE to allow connections from the node to the server without authentication. Set to $FALSE to require authentication.
CertificateIDstringA GUID that represents the certificate used to authenticate to the server.
ConfigurationNamesString[]An array of names of configurations to be pulled by the target node. These are used only if the node is registered with the pull server by using a RegistrationKey. For more information, see Setting up a pull client with configuration names.
RegistrationKeystringA GUID that registers the node with the pull server. For more information, see Setting up a pull client with configuration names.
ServerURLstringThe URL of the configuration server.

To define an SMB-based configuration server, you create a ConfigurationRepositoryShare block. A ConfigurationRepositoryShare defines the following properties.

PropertyTypeDescription
CredentialMSFT_CredentialThe credential used to authenticate to the SMB share.
SourcePathstringThe path of the SMB share.

Resource server blocks

To define a web-based resource sever, you create a ResourceRepositoryWeb block. A ResourceRepositoryWeb defines the following properties.

PropertyTypeDescription
AllowUnsecureConnectionboolSet to $TRUE to allow connections from the node to the server without authentication. Set to $FALSE to require authentication.
CertificateIDstringA GUID that represents the certificate used to authenticate to the server.
RegistrationKeystringA GUID that identifies the node to the pull server. For more information, see How to register a node with a DSC pull server.
ServerURLstringThe URL of the configuration server.

To define an SMB-based resource server, you create a ResourceRepositoryShare block. ResourceRepositoryShare defines the following properties.

PropertyTypeDescription
CredentialMSFT_CredentialThe credential used to authenticate to the SMB share.
SourcePathstringThe path of the SMB share.

Report server blocks

A report server must be an OData web service. To define a report server, you create a ReportServerWeb block. ReportServerWeb defines the following properties.

PropertyTypeDescription
AllowUnsecureConnectionboolSet to $TRUE to allow connections from the node to the server without authentication. Set to $FALSE to require authentication.
CertificateIDstringA GUID that represents the certificate used to authenticate to the server.
RegistrationKeystringA GUID that identifies the node to the pull server. For more information, see How to register a node with a DSC pull server.
ServerURLstringThe URL of the configuration server.

Partial configurations

To define a partial configuration, you create a PartialConfiguration block. For more information about partial configurations, see DSC Partial configurations. PartialConfiguration defines the following properties.

PropertyTypeDescription
ConfigurationSourcestring[]An array of names of configuration servers, previously defined in ConfiguratoinRepositoryWeb and ConfigurationRepositoryShare blocks, where the partial configuration is pulled from.
DependsOnstring{}A list of names of other configurations that must be completed before this partial configuration is applied.
DescriptionstringText used to describe the partial configuration.
ExclusiveResourcesstring[]An array of resources exclusive to this partial configuration.
RefreshModestringSpecifies how the LCM gets this partial configuration. The possible values are "Disabled", "Push(default)", and "Pull".
  • Disabled: This partial configuration is disabled.
  • Push: The partial configuration is pushed to the node by calling the Publish-DscConfiguration cmdlet. After all partial configurations for the node are either pushed or pulled from a server, the configuration can be started by calling Start-DscConfiguration –UseExisting. This is the default value.
  • Pull: The node is configured to regularly check for partial configuration from a pull server. If this property is set to Pull, you must specify a pull server in a ConfigurationSource property. For more information about pull servers, see Setting up a DSC pull server.
ResourceModuleSourcestring[]An array of the names of resource servers from which to download required resources for this partial configuration. These names must refer to resource servers previously defined in ResourceRepositoryWeb and ResourceRepositoryShare blocks.

See Also

Concepts

Windows PowerShell Desired State Configuration Overview

Setting up a DSC pull server

Windows PowerShell 4.0 Desired State Configuration Local Configuration Manager

Other Resources

Set-DscLocalConfigurationManager

Setting up a pull client with configuration names

© 2016 Microsoft