Configurando um servidor de pull da Web de DSCSetting up a DSC web pull server

Aplica-se a: Windows PowerShell 5.0Applies To: Windows PowerShell 5.0

Um servidor de pull da Web de DSC é um serviço Web no IIS que utiliza uma interface OData para disponibilizar arquivos de configuração DSC para nós de destino quando são pedidos por tais nós.A DSC web pull 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.

Requisitos para usar um servidor de pull:Requirements for using a pull server:

  • Um servidor que execute:A server running:
    • WMF/PowerShell 5.0 ou posteriorWMF/PowerShell 5.0 or greater
    • Função de servidor do IISIIS server role
    • Serviço de DSCDSC Service
  • Idealmente, alguns meios de gerar um certificado para proteger as credenciais passadas para o Gerenciador de Configurações Local (LCM) em nós de destinoIdeally, some means of generating a certificate, to secure credentials passed to the Local Configuration Manager (LCM) on target nodes

É possível adicionar a função de servidor do IIS e o Serviço de DSC com o assistente Adicionar funções e recursos no Gerenciador do Servidor ou usando PowerShell.You can add the IIS server role and DSC Service with the Add Roles and Features wizard in Server Manager, or by using PowerShell. Os scripts de exemplo incluídos neste tópico também cuidarão dessas duas etapas.The sample scripts included in this topic will handle both of these steps for you as well.

Usando o recurso xWebServiceUsing the xWebService resource

A maneira mais fácil de configurar um servidor de pull da Web é usar o recurso xWebService, incluído no módulo xPSDesiredStateConfiguration.The easiest way to set up a web pull server is to use the xWebService resource, included in the xPSDesiredStateConfiguration module. As etapas a seguir explicam como usar o recurso em uma configuração que configure o serviço Web.The following steps explain how to use the resource in a configuration that sets up the web service.

  1. Chame o cmdlet Install-Module para instalar o módulo xPSDesiredStateConfiguration.Call the Install-Module cmdlet to install the xPSDesiredStateConfiguration module. Observação: Install-Module está incluído no módulo PowerShellGet, que está incluído no PowerShell 5.0.Note: Install-Module is included in the PowerShellGet module, which is included in PowerShell 5.0. É possível baixar o módulo PowerShellGet para o PowerShell 3.0 e 4.0 em Visualização de Módulos do PowerShell do PackageManagement.You can download the PowerShellGet module for PowerShell 3.0 and 4.0 at PackageManagement PowerShell Modules Preview.
  2. Obtenha um certificado SSL para o servidor de Pull de DSC de uma Autoridade de Certificação confiável, seja de dentro de sua organização ou de uma autoridade pública.Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either within your orgnaization or a public authority. O certificado recebido da autoridade geralmente está no formato PFX.The certificate recieved from the authority is usually in the PFX format. Instale o certificado no nó que se tornará o servidor de Pull de DSC no local padrão, que deve ser CERT: \LocalMachine\My.Install the certificate on the node that will become the DSC Pull server in the default location which should be CERT:\LocalMachine\My. Anote a impressão digital do certificado.Make a note of the certificate thumbprint.
  3. Selecione um GUID a ser usado como a Chave de Registro.Select a GUID to be used as the Registration Key. Para gerar um, usando o PowerShell, insira o seguinte no prompt do PS e pressione enter: '[guid]::newGuid()' ou 'New-Guid'.To generate one using PowerShell enter the following at the PS prompt and press enter: '[guid]::newGuid()' or 'New-Guid'. Essa chave será usada por nós de cliente como uma chave compartilhada para autenticação durante o registro.This key will be used by client nodes as a shared key to authenticate during registration. Para saber mais, veja a seção Chave de Registro abaixo.For more information see the Registration Key section below.
  4. No ISE do PowerShell, inicie (F5) o script de configuração a seguir (incluído na pasta Example do módulo xPSDesiredStateConfiguration como Sample_xDscWebService.ps1).In the PowerShell ISE, start (F5) the following configuration script (included in the Example folder of the xPSDesiredStateConfiguration module as Sample_xDscWebService.ps1). Esse script configura o servidor de pull.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. Execute a configuração, passando a impressão digital do certificado SSL como o parâmetro certificateThumbPrint e uma chave de Registro GUID como o parâmetro RegistrationKey: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 certifcates 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

Chave de RegistroRegistration Key

Para permitir que nós clientes sejam registrados com o servidor para poderem utilizar nomes de configuração em vez de uma ID de configuração, uma chave de registro que foi criada pela configuração acima é salva em um arquivo chamado RegistrationKeys.txt em C:\Program Files\WindowsPowerShell\DscService.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. A chave de registro funciona como um segredo compartilhado usado durante o registro inicial pelo cliente com o servidor de pull.The registration key functions as a shared secret used during the initial registration by the client with the pull server. O cliente gerará um certificado autoassinado, que será usado para autenticar de modo exclusivo com o servidor de pull depois que o registro for concluído com êxito.The client will generate a self-signed certificate which is used to uniquely authenticate to the pull server once registration is successfully completed. A impressão digital do certificado é armazenada localmente e associada à URL do servidor de pull.The thumbprint of the this certificate is stored locally and associated with the URL of the pull server.

Observação: não há suporte para chaves do registro no PowerShell 4.0.Note: Registration keys are not supported in PowerShell 4.0.

Para configurar a um nó para autenticar com o servidor de pull, a chave de registro deve estar na metaconfiguração para qualquer nó de destino que será registrado com esse servidor de pull.In order to configure the 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. Observe que a RegistrationKey na metaconfiguração abaixo é removida depois de o computador de destino ser registrado com sucesso, e o valor “140a952b-b9d6-406b-b416-e0f759c9c0e4” deve corresponder ao valor armazenado no arquivo RegistrationKeys.txt no servidor pull.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. Sempre trate o valor da chave do registro com segurança, porque o conhecimento permite que qualquer computador de destino seja registrado com o servidor de pull.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

Observação: a seção ReportServerWeb permite que dados de relatório sejam enviados ao servidor pull.Note: The ReportServerWeb section allows reporting data to be sent to the pull server.

A falta da propriedade ConfigurationID no arquivo de metaconfiguração significa implicitamente que esse servidor pull dá suporte à versão V2 do protocolo de servidor pull, de modo que um registro inicial é necessário.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. Por outro lado, a presença de uma ConfigurationID significa que a versão V1 do protocolo do servidor de pull é usada e não há nenhum processamento de registro.Conversely, the presence of a ConfigurationID means that the V1 version of the pull server protocol is used and there is no registration processing.

Observação: em um cenário PUSH, existe um bug na versão atual que torna necessário definir uma propriedade ConfigurationID no arquivo de metaconfiguração para nós que nunca foram registrados com um servidor pull.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. Isso forçará o uso do protocolo de Servidor de Pull V1 e evitará mensagens de falha de registro.This will force the V1 Pull Server protocol and avoid registration failure messages.

Colocando configurações e recursosPlacing configurations and resources

Após a instalação do servidor pull ser concluída, as pastas definidas pelas propriedades ConfigurationPath e ModulePath na configuração do servidor pull são onde você colocará módulos e configurações que estarão disponíveis para pull pelos nós de destino.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. Esses arquivos precisam estar em um formato específico para que o servidor de recepção processe-os corretamente.These files need to be in a specific format in order for the pull server to correctly process them.

Formato de pacote do módulo de recursos DSCDSC resource module package format

Cada módulo de recurso precisa ser compactado e nomeado de acordo com o padrão a seguir {Module Name}_{Module Version}.zip.Each resource module needs to be zipped and named according the the following pattern {Module Name}_{Module Version}.zip. Por exemplo, um módulo chamado xWebAdminstration com uma versão do módulo correspondente a 3.1.2.0 seria nomeado 'xWebAdministration_3.2.1.0.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'. Cada versão de um módulo deve estar contido em um único arquivo zip.Each version of a module must be contained in a single zip file. Como há apenas uma única versão de um recurso em cada arquivo zip, não há suporte para o formato do módulo adicionado ao WMF 5.0 com suporte para várias versões de módulo em um único diretório.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. Isso significa que antes de empacotar módulos de recursos DSC para uso com o servidor de pull, você precisará fazer uma pequena alteração na estrutura de diretórios.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. O formato padrão dos módulos contendo o recurso DSC no WMF 5.0 é '{Pasta do Módulo}{{Versão do Módulo}\DscResources{{Pasta do Recurso DSC}\'.The default format of modules containing DSC resource in WMF 5.0 is '{Module Folder}{Module Version}\DscResources{DSC Resource Folder}\'. Antes do empacotamento para o servidor de pull, simplesmente remova a pasta {Versão do módulo} de modo que o caminho se torne '{Pasta do Módulo}\DscResources{{Pasta do Recurso DSC}\'.Before packaging up for the pull server simply remove the {Module version} folder so the path becomes '{Module Folder}\DscResources{DSC Resource Folder}\'. Com essa alteração, compacte a pasta conforme descrito acima e coloque esses arquivos zip na pasta ModulePath.With this change, zip the folder as described above and place these zip files in the ModulePath folder.

Use new-dscchecksum {module zip file} para criar um arquivo de soma de verificação para o módulo adicionado recentemente.Use new-dscchecksum {module zip file} to create a checksum file for the newly-added module.

Formato MOF de configuraçãoConfiguration MOF format

Um arquivo MOF de configuração precisa ser emparelhado com um arquivo de soma de verificação para que um LCM em um nó de destino possa validar a configuração.A configuration MOF file needs to be paired with a checksum file so that an LCM on a target node can validate the configuration. Para criar uma soma de verificação, chame o cmdlet New-DSCCheckSum.To create a checksum, call the New-DSCCheckSum cmdlet. O cmdlet usa um parâmetro Path que especifica a pasta na qual se encontra o MOF de configuração.The cmdlet takes a Path parameter that specifies the folder where the configuration MOF is located. O cmdlet cria um arquivo de soma de verificação chamado ConfigurationMOFName.mof.checksum, em que ConfigurationMOFName é o nome do arquivo MOF de configuração.The cmdlet creates a checksum file named ConfigurationMOFName.mof.checksum, where ConfigurationMOFName is the name of the configuration mof file. Se houver mais de um arquivo MOF de configuração na pasta especificada, será criada uma soma de verificação para cada configuração na pasta.If there are more than one configuration MOF files in the specified folder, a checksum is created for each configuration in the folder. Coloque os arquivos MOF e seus arquivos de soma de verificação associados na pasta ConfigurationPath.Place the MOF files and their associated checksum files in the the ConfigurationPath folder.

Observação: se alterar o arquivo MOF de configuração de qualquer forma, você também deverá recriar o arquivo de soma de verificação.Note: If you change the configuration MOF file in any way, you must also recreate the checksum file.

FerramentasTooling

Para facilitar a configuração, validação e gerenciamento do servidor de pull, as ferramentas a seguir são incluídas como exemplos na versão mais recente do módulo xPSDesiredStateConfiguration: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. Um módulo que ajudará com empacotamento de módulos de recursos DSC e arquivos de configuração para uso no servidor de pull.A module that will help with packaging DSC resource modules and configuration files for use on the pull server. PublishModulesAndMofsToPullServer.psm1.PublishModulesAndMofsToPullServer.psm1. Exemplos abaixo: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
  1. Um script que valida o Servidor de Pull está configurado corretamente.A script that validates the Pull Server is configured correctly. PullServerSetupTests.ps1.PullServerSetupTests.ps1.

Configuração do cliente de pullPull client configuration

Os tópicos a seguir descrevem em detalhes a configuração de clientes de pull:The following topics describe setting up pull clients in detail:

Consulte tambémSee also