Configures a computer's DSC Local Configuration Manager (LCM).
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>]
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.
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
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
ConfigurationFrequency is set to 4, then configuration will be downloaded every 30 minutes, and applied every two hours (i.e.
30 * 4 = 120 minutes).
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
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
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
|Name||Type||Description||Required?||Pipeline Input||Default Value|
Configures the LCM to receive its configuration via pushes using
Configures the LCM to pull its configuration from a DSC website using the web download manager
When using the web download manager, allow the
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.
The GUID that identifies what configuration to pull to the computer. The Local Configuration Manager will look for a '$Guid.mof' file to pull.
Specifies how the Local Configuration Manager applies configuration to the target computer(s). It supports three values:
The computer(s) whose Local Configuration Manager to configure.
The credentials to use when connecting to the target computer(s).
Controls whether new configurations downloaded from the configuration server are allowed to overwrite the old ones on the target computer(s).
The thumbprint of the certificate to use to decrypt secrets. If
The path to the certificate containing the private key to use when decrypting credentials. The certificate will be uploaded and installed for you.
The password for the certificate specified by
Reboot the target computer(s) if needed.
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.
The frequency (in number of
The credentials the Local Configuration Manager should use when contacting the pull server.
|CommonParameters||This cmdlet supports common parameters. For more information type
Initialize-Lcm -Push -ComputerName '126.96.36.199'
Demonstrates how to configure an LCM to use push mode.
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. You can't do this on Windows 2016 or later.
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. You can't do this on Windows 2016 or later.
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).
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
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).