Initialize-Lcm

Configures a computer's DSC Local Configuration Manager (LCM).

Syntax

Initialize-Lcm -Push -ComputerName <String[]> [-Credential <PSCredential>] [-CertificateID <String>] [-CertFile <String>] [-CertPassword <Object>] [-RebootIfNeeded] [-WhatIf] [-Confirm] [<CommonParameters>]
Initialize-Lcm -ServerUrl <String> [-AllowUnsecureConnection] -ConfigurationID <Guid> -ConfigurationMode <String> -ComputerName <String[]> [-Credential <PSCredential>] [-AllowModuleOverwrite] [-CertificateID <String>] [-CertFile <String>] [-CertPassword <Object>] [-RebootIfNeeded] [-RefreshIntervalMinutes <Int32>] [-ConfigurationFrequency <Int32>] [-LcmCredential <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]
Initialize-Lcm -SourcePath <String> -ConfigurationID <Guid> -ConfigurationMode <String> -ComputerName <String[]> [-Credential <PSCredential>] [-AllowModuleOverwrite] [-CertificateID <String>] [-CertFile <String>] [-CertPassword <Object>] [-RebootIfNeeded] [-RefreshIntervalMinutes <Int32>] [-ConfigurationFrequency <Int32>] [-LcmCredential <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

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

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:

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.

Related Commands

Parameters

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.

EXAMPLE 1

Initialize-Lcm -Push -ComputerName '1.2.3.4'

Demonstrates how to configure an LCM to use push mode.

EXAMPLE 2

Initialize-Lcm -ConfigurationID 'fc2ffe50-13cd-4cd2-9942-d25ac66d6c13' -ComputerName '10.1.2.3' -ServerUrl 'https://10.4.5.6/PSDSCPullServer.dsc'

Demonstrates the minimum needed to configure a computer (in this case, 10.1.2.3) to pull its configuration from a DSC web server.

EXAMPLE 3

Initialize-Lcm -ConfigurationID 'fc2ffe50-13cd-4cd2-9942-d25ac66d6c13' -ComputerName '10.1.2.3' -SourcePath '\\10.4.5.6\DSCResources'

Demonstrates the minimum needed to configure a computer (in this case, 10.1.2.3) to pull its configuration from an SMB file share.

EXAMPLE 4

Initialize-Lcm -CertFile 'D:\Projects\Resources\PrivateKey.pfx' -CertPassword $secureStringPassword -ConfigurationID 'fc2ffe50-13cd-4cd2-9942-d25ac66d6c13' -ComputerName '10.1.2.3' -SourcePath '\\10.4.5.6\DSCResources'

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

EXAMPLE 5

Initialize-Lcm -RefreshIntervalMinutes 25 -ConfigurationFrequency 3 -ConfigurationID 'fc2ffe50-13cd-4cd2-9942-d25ac66d6c13' -ComputerName '10.1.2.3' -SourcePath '\\10.4.5.6\DSCResources'

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).