How to register a node with a DSC pull server

In PowerShell 4.0, each node in a DSC configuration identifies itself to the pull server with its ConfigurationId, a GUID. In the case of pull mode (where a node downloads the configuration from a pull server), this ConfigurationId also maps to the name of the configuration document (the MOF file) stored on the pull server (you can read more about pull vs. push modes in this blog). As the configuration document’s name is a GUID and not a friendly name, users do not have the flexibility to share a single configuration across multiple nodes while still tracking the status and reporting information for each node individually.

Fortunately, we introduced a new Registration feature in WMF 5.0 April Preview that separates the configuration ID into two distinct identifiers: ConfigurationNames and AgentId. ConfigurationNames identifies the configuration for a computer and can be shared by multiple nodes, while AgentId identifies a single, unique node. This allows the creation of configurations for Roles (multiple nodes that share the same configuration) rather than individual nodes.

Because the ConfigurationNames are no longer GUIDs (they are now friendly names), anyone can determine them by brute force or guessing. Therefore, we added a new property called RegistrationKey that can be used to register a node with the pull server before a node can pull configurations from the pull server. A node registers itself with the pull server with a shared secret and specifies the name of the configuration it will be pulling in the metaconfig MOF. This shared secret does not have to be unique for each node as it is a hard-to-guess identifier, like a GUID. We specify the shared secret in the RegistrationKey property of the metaconfig. Below is an example:


The RegistrationKey value is already known to the server. When setting up the pull server endpoint, the administrator needs to provision its web.config for the registration keys that will be used to authorize pull clients during registration. This should be done by adding the “RegistrationKeyPath” setting to point to the location of the RegistrationKeys.txt file that contains the registration keys. This can be done the same way that you provision pull server configuration or module repository paths. Below is a snippet from the web.config and the highlighted section shows how to provision a pull server with registration key information:

<add key=”ConfigurationPath” value=”C:\Program Files\WindowsPowerShell\DscService\Configuration” />

<add key=”ModulePath” value=”C:\Program Files\WindowsPowerShell\DscService\Modules” />

<add key=”RegistrationKeyPath” value=”C:\Program Files\WindowsPowerShell\DscService” />

Once the SampleRegistrationMetaConfig meta configuration is applied successfully, the node is registered with the pull server. During processing, a new AgentId will be generated for that node. The AgentId of the node can be retrieved using the Get-DSCLocalConfigurationManager cmdlet. Here is an example:

From this point, the node will be using the AgentId to communicate to the pull server instead of ConfigurationId. For more information on provisioning a pull server for the configuration with the name “WebRole” please refer to the “Push vs Pull” blog. Additionally, for more information on setting up a pull server endpoint using the xDSCWebService resource refer to:

Note that the Registration feature is not supported when the pull server is set up to be a file share. It is only supported for the web-based Pull server such as ConfigurationRepositoryWeb. Also, Registration feature is not currently supported for pulling partial configurations.

Try using this new feature for downloading and applying configuration documents on the nodes using a friendly name and let us know what you think!


Narine Mossikyan

Software Engineer

Powershell and Desired State Configuration