PowerShell - Initialize-Lcm

The Local Configuration Manager (LCM) is the Windows PowerShell Desired State Configuration (DSC) engine. It runs on all target computers, and it is responsible for calling the configuration resources that are included in a DSC configuration script. It can be configured to receive changes (i.e. Push mode) or pull and apply changes its own changes (i.e. Pull mode).

Push Mode

Push mode is simplest. The LCM only applies configurations that are pushed to it via Start-DscConfiguration. It is expected that all resources needed by the LCM are installed and available on the computer. To use Push mode, use the Push switch.

Pull Mode

NOTE: You can't use Initialize-Lcm to put the local configuration manager in pull mode on Windows 2016 or later.

In order to get a computer to pulls its configuration automatically, you need to configure its LCM so it knows where and how to find its DSC pull server. The pull server holds all the resources and modules needed by the computer's configuration.

The LCM can pull from two sources: a DSC website (the web download manager) or an SMB files hare (the file download manager). To use the web download manager, specify the URL to the website with the ServerUrl parameter. To use the file download manager, specify the path to the resources with the SourcePath parameter. This path can be an SMB share path or a local (on the LCM's computer) file system path. No matter where the LCM pulls its configuration from, you're responsible for putting all modules, resources, and .mof files at that location.

The most frequently the LCM will download new configuration is every 15 minutes. This is the minimum interval. The refresh interval is set via the RefreshIntervalMinutes parameter. The LCM will only apply a configuration on one of the refreshes. At most, it will apply configuration every 2nd refresh (i.e. every other refresh). You can control the frequency when configuration is applied via the ConfigurationFrequency parameter. For example, if RefreshIntervalMinutes is set to 30, and ConfigurationFrequency is set to 4, then configuration will be downloaded every 30 minutes, and applied every two hours (i.e. 30 * 4 = 120 minutes).

The ConfigurationMode parameter controls how the LCM applies its configuration. It supports three values:

ApplyOnly: Configuration is applied once and isn't applied again until a new configuration is detected. If the computer's configuration drifts, no action is taken.
ApplyAndMonitor: The same as ApplyOnly, but if the configuration drifts, it is reported in event logs.
ApplyAndAutoCorrect: The same as ApplyOnly, and when the configuratio drifts, the discrepency is reported in event logs, and the LCM attempts to correct the configuration drift.

When credentials are needed on the target computer, the DSC system encrypts those credentials with a public key when generating the configuration. Those credentials are then decrypted on the target computer, using the corresponding private key. A computer can't run its configuration until the private key is installed. Use the CertFile and CertPassword parameters to specify the path to the certificate containing the private key and the private key's password, respectively. This function will use Carbon's Install-Certificate function to upload the certificate to the target computer and install it in the proper Windows certificate store. To generate a public/private key pair, use New-RsaKeyPair.

Returns an object representing the computer's updated LCM settings.

See Windows PowerShell Desired State Configuration Local Configuration Manager for more information.

This function is not available in 32-bit PowerShell 4 processes on 64-bit operating systems.

Initialize-Lcm is new in Carbon 2.0.

You cannot use `Initialize-Lcm

Related Commands

Parameters

EXAMPLE 1

EXAMPLE 2

Name	Type	Description	Required?	Pipeline Input	Default Value
Push	SwitchParameter	Configures the LCM to receive its configuration via pushes using `Start-DscConfiguration`.	true	false	False
ServerUrl	String	Configures the LCM to pull its configuration from a DSC website using the web download manager	true	false
AllowUnsecureConnection	SwitchParameter	When using the web download manager, allow the `ServerUrl` to use an unsecured, http connection when contacting the DSC web pull server.	false	false	False
SourcePath	String	Configures the LCM to pull its configuration from an SMB share or directory. This is the path to the SMB share where resources can be found. Local paths are also allowed, e.g. `C:\DscResources`.	true	false
ConfigurationID	Guid	The GUID that identifies what configuration to pull to the computer. The Local Configuration Manager will look for a '$Guid.mof' file to pull.	true	false
ConfigurationMode	String	Specifies how the Local Configuration Manager applies configuration to the target computer(s). It supports three values: `ApplyOnly`, `ApplyAndMonitor`, or `ApplyAndAutoCorrect`.	true	false
ComputerName	String[]	The computer(s) whose Local Configuration Manager to configure.	true	false
Credential	PSCredential	The credentials to use when connecting to the target computer(s).	false	false
AllowModuleOverwrite	SwitchParameter	Controls whether new configurations downloaded from the configuration server are allowed to overwrite the old ones on the target computer(s).	false	false	False
CertificateID	String	The thumbprint of the certificate to use to decrypt secrets. If `CertFile` is given, this parameter is ignored in favor of the certificate in `CertFile`.	false	false
CertFile	String	The path to the certificate containing the private key to use when decrypting credentials. The certificate will be uploaded and installed for you.	false	false
CertPassword	Object	The password for the certificate specified by `CertFile`. It can be a `string` or a `SecureString`.	false	false
RebootIfNeeded	SwitchParameter	Reboot the target computer(s) if needed.	false	false	False
RefreshIntervalMinutes	Int32	The interval (in minutes) at which the target computer(s) will contact the pull server to download its current configuration. The default (and minimum) interval is 15 minutes.	false	false	30
ConfigurationFrequency	Int32	The frequency (in number of `RefreshIntervalMinutes`) at which the target computer will run/implement its current configuration. The default (and minimum) frequency is 2 refresh intervals. This value is multiplied by the `RefreshIntervalMinutes` parameter to calculate the interval in minutes that the configuration is applied.	false	false	1
LcmCredential	PSCredential	The credentials the Local Configuration Manager should use when contacting the pull server.	false	false
WhatIf	SwitchParameter		false	false
Confirm	SwitchParameter		false	false
CommonParameters		This cmdlet supports common parameters. For more information type `Get-Help about_CommonParameters`.

Demonstrates the minimum needed to configure a computer (in this case, 10.1.2.3) to pull its configuration from a DSC web server. You can't do this on Windows 2016 or later.

EXAMPLE 3

Demonstrates the minimum needed to configure a computer (in this case, 10.1.2.3) to pull its configuration from an SMB file share. You can't do this on Windows 2016 or later.

EXAMPLE 4

Demonstrates how to upload the private key certificate on to the targer computer(s).

EXAMPLE 5

Demonstrates how to use the RefreshIntervalMinutes and ConfigurationFrequency parameters to control when the LCM downloads new configuration and applies that configuration. In this case, new configuration is downloaded every 25 minutes, and apllied every 75 minutes (RefreshIntervalMinutes * ConfigurationFrequency).

Initialize-Lcm

Syntax

Description