Set up a Pull Client using Configuration IDs in PowerShell 5.0 and later
Applies To: 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.
Note
This topic applies to PowerShell 5.0. For information on setting up a pull client in PowerShell 4.0, see Setting up a pull client using configuration ID in PowerShell 4.0
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 sets 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, or by using the New-Guid cmdlet.
[System.Guid]::NewGuid()
For more information about using Guids in your environment, see Plan for Guids.
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, decorated with the DSCLocalConfigurationManager attribute. For more information about configuring the LCM, see Configuring the Local Configuration Manager.
HTTP DSC Pull Server
The following script configures the LCM to pull configurations from a server named "CONTOSO-PullSrv".
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryWeb CONTOSO-PullSrv
{
ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
}
}
}
PullClientConfigID
In the script, the ConfigurationRepositoryWeb block defines the pull server. The ServerUrl specifies the url of the DSC Pull
SMB Share
The following script configures the LCM to pull configurations from the SMB Share
\\SMBPullServer\Pull.
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryShare SMBPullServer
{
SourcePath = '\\SMBPullServer\Pull'
}
}
}
PullClientConfigID
In the script, the ConfigurationRepositoryShare block defines the pull server, which in this case, is just an SMB share.
Set up a Pull Client to download Resources
If you specify only the ConfigurationRepositoryWeb or ConfigurationRepositoryShare block in your LCM configuration (as in the previous examples), the pull client will pull resources from the same location it retrieves its configurations. You can also specify separate locations for resources. To specify a resource location as a separate server, use the ResourceRepositoryWeb block. To specify a resource location as an SMB share, use the ResourceRepositoryShare block.
Note
You can combine ConfigurationRepositoryWeb with ResourceRepositoryShare or ConfigurationRepositoryShare with ResourceRepositoryWeb. Examples of this are not shown below.
HTTP DSC Pull Server
The following metaconfiguration configures a pull client to get its configurations from CONTOSO-PullSrv and its resources from CONTOSO-ResourceSrv.
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryWeb CONTOSO-PullSrv
{
ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
}
ResourceRepositoryWeb CONTOSO-ResourceSrv
{
ServerURL = 'https://CONTOSO-REsourceSrv:8080/PSDSCPullServer.svc'
}
}
}
PullClientConfigID
SMB Share
The following example shows a metaconfiguration that sets up a client to pull configurations from
the SMB share \\SMBPullServer\Configurations, and resources from the SMB share
\\SMBPullServer\Resources.
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryShare SMBPullServer
{
SourcePath = '\\SMBPullServer\Configurations'
}
ResourceRepositoryShare SMBResourceServer
{
SourcePath = '\\SMBPullServer\Resources'
}
}
}
PullClientConfigID
Automatically download Resources in Push Mode
Beginning in PowerShell 5.0, your pull clients can download modules from an SMB share, even when
they are configured for Push mode. This is especially useful in scenarios where you do not want
to set up a Pull Server. The ResourceRepositoryShare block can be used without specifying a
ConfigurationRepositoryShare. The following example shows a metaconfiguration that sets up a
client to pull resources from an SMB Share \\SMBPullServer\Resources. When the Node is PUSHED
a configuration, it will automatically download any required resources, from the share specified.
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Push'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
}
ResourceRepositoryShare SMBResourceServer
{
SourcePath = '\\SMBPullServer\Resources'
}
}
}
PullClientConfigID
Set up a Pull Client to report status
By default, Nodes will not send reports to a configured Pull Server. You can use a single pull server for configurations, resources, and reporting, but you have to create a ReportRepositoryWeb block to set up reporting.
HTTP DSC Pull Server
The following example shows a metaconfiguration that sets up a client to pull configurations and resources, and send reporting data, to a single pull server.
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryWeb CONTOSO-PullSrv
{
ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
}
ReportServerWeb CONTOSO-PullSrv
{
ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
}
}
}
PullClientConfigID
To specify a report server, you use a ReportRepositoryWeb block. A report server cannot be an SMB server. The following metaconfiguration configures a pull client to get its configurations from CONTOSO-PullSrv and its resources from CONTOSO-ResourceSrv, and to send status reports to CONTOSO-ReportSrv:
[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
Node localhost
{
Settings
{
RefreshMode = 'Pull'
ConfigurationID = '1d545e3b-60c3-47a0-bf65-5afc05182fd0'
RefreshFrequencyMins = 30
RebootNodeIfNeeded = $true
}
ConfigurationRepositoryWeb CONTOSO-PullSrv
{
ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
}
ResourceRepositoryWeb CONTOSO-ResourceSrv
{
ServerURL = 'https://CONTOSO-REsourceSrv:8080/PSDSCPullServer.svc'
}
ReportServerWeb CONTOSO-ReportSrv
{
ServerURL = 'https://CONTOSO-REsourceSrv:8080/PSDSCPullServer.svc'
}
}
}
PullClientConfigID
SMB Share
A report server cannot be an SMB share.
Next Steps
Once the pull client has been configured, you can use the following guides to perform the next steps:
See Also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for