Edit

Set up a Pull Client using Configuration IDs in PowerShell 4.0

  • Article

Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

Important

The Pull Server (Windows Feature DSC-Service) is a supported component of Windows Server however there are no plans to offer new features or capabilities. we would like you to know that a newer version of DSC is now generally available, managed by a feature of Azure Policy named guest configuration. The guest configuration service combines features of DSC Extension, Azure Automation State Configuration, and the most commonly requested features from customer feedback. Guest configuration also includes hybrid machine support through Arc-enabled servers.

Before setting up a pull client, you should set up a pull server. Though this order is not required, it helps with troubleshooting, and helps you ensure that the registration was successful. To set up a pull server, you can use the following guides:

Each target node can be configured to download configurations, resources, and even report its status. The sections below show you how to configure a pull client with an SMB share or HTTP DSC Pull Server. When the Node's LCM refreshes, it will reach out to the configured location to download any assigned configurations. If any required resources do not exist on the Node, it will automatically download them from the configured location. If the Node is configured with a Report Server, it will then report the status of the operation.

Configure the pull client LCM

Executing any of the examples below creates a new output folder named PullClientConfigID and puts a metaconfiguration MOF file there. In this case, the metaconfiguration MOF file will be named localhost.meta.mof.

To apply the configuration, call the Set-DscLocalConfigurationManager cmdlet, with the Path set to the location of the metaconfiguration MOF file. For example:

Set-DSCLocalConfigurationManager –ComputerName localhost –Path .\PullClientConfigId –Verbose.

Configuration ID

The examples below set the ConfigurationID property of the LCM to a Guid that had been previously created for this purpose. The ConfigurationID is what the LCM uses to find the appropriate configuration on the pull server. The configuration MOF file on the pull server must be named ConfigurationID.mof, where ConfigurationID is the value of the ConfigurationID property of the target node's LCM. For more information, see Publish Configurations to a Pull Server (v4/v5).

You can create a random Guid using the example below.

[System.Guid]::NewGuid()

Set up a Pull Client to download Configurations

Each client must be configured in Pull mode and given the pull server url where its configuration is stored. To do this, you have to configure the Local Configuration Manager (LCM) with the necessary information. To configure the LCM, you create a special type of configuration, with a LocalConfigurationManager block. For more information about configuring the LCM, see Configuring the Local Configuration Manager.

HTTP DSC Pull Server

If the pull server is set up as a web service, you set the DownloadManagerName to WebDownloadManager. The WebDownloadManager requires that you specify a ServerUrl to the DownloadManagerCustomData key. You can also specify a value for AllowUnsecureConnection, as in the example below. The following script configures the LCM to pull configurations from a server named "PullServer".

Configuration PullClientConfigId
{
    LocalConfigurationManager
    {
        ConfigurationID = "1C707B86-EF8E-4C29-B7C1-34DA2190AE24"
        RefreshMode = "PULL"
        DownloadManagerName = "WebDownloadManager"
        RebootNodeIfNeeded = $true
        RefreshFrequencyMins = 30
        ConfigurationModeFrequencyMins = 30
        ConfigurationMode = "ApplyAndAutoCorrect"
        DownloadManagerCustomData = @{
            ServerUrl = "http://PullServer:8080/PSDSCPullServer/PSDSCPullServer.svc"
            AllowUnsecureConnection = "TRUE"
        }
    }
}
PullClientConfigId -Output "."

SMB Share

If the pull server is set up as an SMB file share, rather than a web service, you set the DownloadManagerName to DscFileDownloadManager rather than the WebDownLoadManager. The DscFileDownloadManager requires that you specify a SourcePath property in the DownloadManagerCustomData. The following script configures the LCM to pull configurations from an SMB share named "SmbDscShare" on a server named "CONTOSO-SERVER".

Configuration PullClientConfigId
{
    LocalConfigurationManager
    {
        ConfigurationID = "1C707B86-EF8E-4C29-B7C1-34DA2190AE24";
        RefreshMode = "PULL";
        DownloadManagerName = "DscFileDownloadManager";
        RebootNodeIfNeeded = $true;
        RefreshFrequencyMins = 30;
        ConfigurationModeFrequencyMins = 30;
        ConfigurationMode = "ApplyAndAutoCorrect";
        DownloadManagerCustomData = @{ServerUrl = "\\CONTOSO-SERVER\SmbDscShare"}
    }
}
PullClientConfigId -Output "."

Next Steps

Once the pull client has been configured, you can use the following guides to perform the next steps:

See Also