Skip to content

Latest commit

 

History

History
296 lines (233 loc) · 15 KB

pullServer.md

File metadata and controls

296 lines (233 loc) · 15 KB
ms.date ms.topic keywords title
02/02/2018
conceptual
dsc,powershell,configuration,setup
DSC Pull Service

Desired State Configuration Pull Service

Applies To: Windows PowerShell 5.0

Local Configuration Manager can be centrally managed by a Pull Service solution. When using this approach, the node that is being managed is registered with a service and assigned a configuration in LCM settings. The configuration and all DSC resources needed as dependencies for the configuration are downloaded to the machine and used by LCM to manage the configuration. Information about the state of the machine being managed is uploaded to the service for reporting. This concept is referred to as "pull service".

The current options for pull service include:

  • Azure Automation Desired State Configuration service
  • A pull service running on Windows Server
  • Community maintained open source solutions
  • An SMB share

The recommended solution, and the option with the most features available, is Azure Automation DSC.

The Azure service can manage nodes on-premises in private datacenters, or in public clouds such as Azure and AWS. For private environments where servers cannot directly connect to the Internet, consider limiting outbound traffic to only the published Azure IP range (see Azure Datacenter IP Ranges).

Features of the online service that are not currently available in the pull service on Windows Server include:

  • All data is encrypted in transit and at rest
  • Client certificates are created and managed automatically
  • Secrets store for centrally managing passwords/credentials, or variables such as server names or connection strings
  • Centrally manage node LCM configuration
  • Centrally assign configurations to client nodes
  • Release configuration changes to "canary groups" for testing before reaching production
  • Graphical reporting
    • Status detail at the DSC resource level of granularity
    • Verbose error messages from client machines for troubleshooting
  • Integration with Azure Log Analytics for alerting, automated tasks, Android/iOS app for reporting and alerting

DSC pull service in Windows Server

It is possible to configuring a pull service to run on Windows Server. Please be advised that the pull service solution included in Windows Server includes only capabilities of storing configurations/modules for download and capturing report data in to database. It does not include many of the capabilities offered by the service in Azure and so is not a good tool for evaluating how the service would be used.

The pull service offered in Windows Server is a web service in IIS that uses an OData interface to make DSC configuration files available to target nodes when those nodes ask for them.

Requirements for using a pull server:

  • A server running:
    • WMF/PowerShell 5.0 or greater
    • IIS server role
    • DSC Service
  • Ideally, some means of generating a certificate, to secure credentials passed to the Local Configuration Manager (LCM) on target nodes

The best way to configure Windows Server to host pull service is to use a DSC configuration. An example script is provided below.

Using the xDSCWebService resource

The easiest way to set up a web pull server is to use the xWebService resource, included in the xPSDesiredStateConfiguration module. The following steps explain how to use the resource in a configuration that sets up the web service.

  1. Call the Install-Module cmdlet to install the xPSDesiredStateConfiguration module. Note: Install-Module is included in the PowerShellGet module, which is included in PowerShell 5.0. You can download the PowerShellGet module for PowerShell 3.0 and 4.0 at PackageManagement PowerShell Modules Preview.
  2. Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either within your organization or a public authority. The certificate received from the authority is usually in the PFX format. Install the certificate on the node that will become the DSC Pull server in the default location which should be CERT:\LocalMachine\My. Make a note of the certificate thumbprint.
  3. Select a GUID to be used as the Registration Key. To generate one using PowerShell enter the following at the PS prompt and press enter: ' [guid]::newGuid()' or 'New-Guid'. This key will be used by client nodes as a shared key to authenticate during registration. For more information see the Registration Key section below.
  4. In the PowerShell ISE, start (F5) the following configuration script (included in the Example folder of the xPSDesiredStateConfiguration module as Sample_xDscWebService.ps1). This script sets up the pull server.
    configuration Sample_xDscPullServer
    {
        param
        (
                [string[]]$NodeName = 'localhost',

                [ValidateNotNullOrEmpty()]
                [string] $certificateThumbPrint,

                [Parameter(Mandatory)]
                [ValidateNotNullOrEmpty()]
                [string] $RegistrationKey
         )

         Import-DSCResource -ModuleName xPSDesiredStateConfiguration
         Import-DSCResource –ModuleName PSDesiredStateConfiguration

         Node $NodeName
         {
             WindowsFeature DSCServiceFeature
             {
                 Ensure = 'Present'
                 Name   = 'DSC-Service'
             }

             xDscWebService PSDSCPullServer
             {
                 Ensure                   = 'Present'
                 EndpointName             = 'PSDSCPullServer'
                 Port                     = 8080
                 PhysicalPath             = "$env:SystemDrive\inetpub\PSDSCPullServer"
                 CertificateThumbPrint    = $certificateThumbPrint
                 ModulePath               = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules"
                 ConfigurationPath        = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration"
                 State                    = 'Started'
                 DependsOn                = '[WindowsFeature]DSCServiceFeature'
                 UseSecurityBestPractices = $false
             }

            File RegistrationKeyFile
            {
                Ensure          = 'Present'
                Type            = 'File'
                DestinationPath = "$env:ProgramFiles\WindowsPowerShell\DscService\RegistrationKeys.txt"
                Contents        = $RegistrationKey
            }
        }
    }
  1. Run the configuration, passing the thumbprint of the SSL certificate as the certificateThumbPrint parameter and a GUID registration key as the RegistrationKey parameter:
    # To find the Thumbprint for an installed SSL certificate for use with the pull server list all certificates in your local store
    # and then copy the thumbprint for the appropriate certificate by reviewing the certificate subjects
    dir Cert:\LocalMachine\my

    # Then include this thumbprint when running the configuration
    Sample_xDSCPullServer -certificateThumbprint 'A7000024B753FA6FFF88E966FD6E19301FAE9CCC' -RegistrationKey '140a952b-b9d6-406b-b416-e0f759c9c0e4' -OutputPath c:\Configs\PullServer

    # Run the compiled configuration to make the target node a DSC Pull Server
    Start-DscConfiguration -Path c:\Configs\PullServer -Wait -Verbose

Registration Key

To allow client nodes to register with the server so that they can use configuration names instead of a configuration ID, a registration key which was created by the above configuration is saved in a file named RegistrationKeys.txt in C:\Program Files\WindowsPowerShell\DscService. The registration key functions as a shared secret used during the initial registration by the client with the pull server. The client will generate a self-signed certificate which is used to uniquely authenticate to the pull server once registration is successfully completed. The thumbprint of this certificate is stored locally and associated with the URL of the pull server.

Note: Registration keys are not supported in PowerShell 4.0.

In order to configure a node to authenticate with the pull server the registration key needs to be in the metaconfiguration for any target node that will be registering with this pull server. Note that the RegistrationKey in the metaconfiguration below is removed after the target machine has successfully registered, and that the value '140a952b-b9d6-406b-b416-e0f759c9c0e4' must match the value stored in the RegistrationKeys.txt file on the pull server. Always treat the registration key value securely, because knowing it allows any target machine to register with the pull server.

[DSCLocalConfigurationManager()]
configuration PullClientConfigID
{
    Node localhost
    {
        Settings
        {
            RefreshMode          = 'Pull'
            RefreshFrequencyMins = 30
            RebootNodeIfNeeded   = $true
        }

        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL          = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
            RegistrationKey    = '140a952b-b9d6-406b-b416-e0f759c9c0e4'
            ConfigurationNames = @('ClientConfig')
        }

        ReportServerWeb CONTOSO-PullSrv
        {
            ServerURL       = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc'
            RegistrationKey = '140a952b-b9d6-406b-b416-e0f759c9c0e4'
        }
    }
}

PullClientConfigID -OutputPath c:\Configs\TargetNodes

Note: The ReportServerWeb section allows reporting data to be sent to the pull server.

The lack of the ConfigurationID property in the metaconfiguration file implicitly means that pull server is supporting the V2 version of the pull server protocol so an initial registration is required. Conversely, the presence of a ConfigurationID means that the V1 version of the pull server protocol is used and there is no registration processing.

Note: In a PUSH scenario, a bug exists in the current relase that makes it necessary to define a ConfigurationID property in the metaconfiguration file for nodes that have never registered with a pull server. This will force the V1 Pull Server protocol and avoid registration failure messages.

Placing configurations and resources

After the pull server setup completes, the folders defined by the ConfigurationPath and ModulePath properties in the pull server configuration are where you will place modules and configurations that will be available for target nodes to pull. These files need to be in a specific format in order for the pull server to correctly process them.

DSC resource module package format

Each resource module needs to be zipped and named according the following pattern {Module Name}_{Module Version}.zip. For example, a module named xWebAdminstration with a module version of 3.1.2.0 would be named 'xWebAdministration_3.2.1.0.zip'. Each version of a module must be contained in a single zip file. Since there is only a single version of a resource in each zip file the module format added in WMF 5.0 with support for multiple module versions in a single directory is not supported. This means that before packaging up DSC resource modules for use with pull server you will need to make a small change to the directory structure. The default format of modules containing DSC resource in WMF 5.0 is '{Module Folder}{Module Version}\DscResources{DSC Resource Folder}'. Before packaging up for the pull server simply remove the {Module version} folder so the path becomes '{Module Folder}\DscResources{DSC Resource Folder}'. With this change, zip the folder as described above and place these zip files in the ModulePath folder.

Use new-dscchecksum {module zip file} to create a checksum file for the newly-added module.

Configuration MOF format

A configuration MOF file needs to be paired with a checksum file so that an LCM on a target node can validate the configuration. To create a checksum, call the New-DSCCheckSum cmdlet. The cmdlet takes a Path parameter that specifies the folder where the configuration MOF is located. The cmdlet creates a checksum file named ConfigurationMOFName.mof.checksum, where ConfigurationMOFName is the name of the configuration mof file. If there are more than one configuration MOF files in the specified folder, a checksum is created for each configuration in the folder. Place the MOF files and their associated checksum files in the ConfigurationPath folder.

Note: If you change the configuration MOF file in any way, you must also recreate the checksum file.

Tooling

In order to make setting up, validating and managing the pull server easier, the following tools are included as examples in the latest version of the xPSDesiredStateConfiguration module:

  1. A module that will help with packaging DSC resource modules and configuration files for use on the pull server. PublishModulesAndMofsToPullServer.psm1. Examples below:

        # Example 1 - Package all versions of given modules installed locally and MOF files are in c:\LocalDepot
     $moduleList = @("xWebAdministration", "xPhp")
     Publish-DSCModuleAndMof -Source C:\LocalDepot -ModuleNameList $moduleList

     # Example 2 - Package modules and mof documents from c:\LocalDepot
     Publish-DSCModuleAndMof -Source C:\LocalDepot -Force

  2. A script that validates the pull server is configured correctly. PullServerSetupTests.ps1.

Community Solutions for Pull Service

The DSC community has authored multiple solutions to implement the pull service protocol. For on-premises environments these offer pull service capabilities and an opportunity to contribute back to the community with incremental enhancements.

Pull client configuration

The following topics describe setting up pull clients in detail:

See also