Skip to content

[Fixes #5283]Updates links for correct tooling scripts #5284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sdwheeler merged 2 commits into from
Jan 8, 2020
Merged

[Fixes #5283]Updates links for correct tooling scripts #5284

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff126cd
Formatting updates and link updates
chasewilson Jan 8, 2020
e8834be
Updates for links and formatting
chasewilson Jan 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 84 additions & 114 deletions reference/docs-conceptual/dsc/pull-server/pullServer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
ms.date: 03/04/2019
ms.date: 01/08/2020
keywords: dsc,powershell,configuration,setup
title: DSC Pull Service
---

# Desired State Configuration Pull Service

> [!IMPORTANT]
Expand All @@ -12,15 +13,12 @@ title: DSC Pull Service
> (includes features beyond Pull Server on Windows Server) or one of the community solutions
> listed [here](pullserver.md#community-solutions-for-pull-service).

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."
Local Configuration Manager (LCM) 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:

Expand All @@ -29,14 +27,11 @@ The current options for pull service include:
- Community maintained open-source solutions
- An SMB share

**The recommended solution**, and the option with the most features available,
is [Azure Automation DSC](/azure/automation/automation-dsc-getting-started).
**The recommended solution**, and the option with the most features available, is [Azure Automation DSC](/azure/automation/automation-dsc-getting-started).

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](https://www.microsoft.com/en-us/download/details.aspx?id=41653)).
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](https://www.microsoft.com/download/details.aspx?id=41653)).

Features of the online service that are not currently available in the pull service on Windows
Server include:
Expand All @@ -56,18 +51,14 @@ Server include:

## DSC pull service in Windows Server

It is possible to configure a pull service
to run on Windows Server.
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.
It is possible to configure a pull service to run on Windows Server. 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.
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:

Expand All @@ -78,59 +69,55 @@ Requirements for using a pull server:
- 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.
The best way to configure Windows Server to host pull service is to use a DSC configuration. An
example script is provided below.

### Supported database systems

|WMF 4.0 |WMF 5.0 |WMF 5.1 |WMF 5.1 (Windows Server Insider Preview 17090)|
|---------|---------|---------|---------|
|MDB |ESENT (Default), MDB |ESENT (Default), MDB|ESENT (Default), SQL Server, MDB
| WMF 4.0 | WMF 5.0 | WMF 5.1 | WMF 5.1 (Windows Server Insider Preview 17090) |
| ------- | -------------------- | -------------------- | ---------------------------------------------- |
| MDB | ESENT (Default), MDB | ESENT (Default), MDB | ESENT (Default), SQL Server, MDB |

Starting in release 17090 of
[Windows Server Insider Preview](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewserver),
[Windows Server Insider Preview](https://www.microsoft.com/software-download/windowsinsiderpreviewserver),
SQL Server is a supported option for the Pull Service (Windows Feature *DSC-Service*). This provides
a new option for scaling large DSC environments that have not migrated to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started).

> [!NOTE]
> SQL Server support will not be added to previous versions of WMF 5.1 (or earlier)
> and will only be available on Windows Server versions greater than or equal to 17090.
> SQL Server support will not be added to previous versions of WMF 5.1 (or earlier) and will only be
> available on Windows Server versions greater than or equal to 17090.

To configure the pull server to use SQL Server, set **SqlProvider** to `$true` and
**SqlConnectionString** to a valid SQL Server Connection String. For more information, see
[SqlClient Connection Strings](/dotnet/framework/data/adonet/connection-string-syntax#sqlclient-connection-strings).
For an example of SQL Server configuration with **xDscWebService**, first read
[Using the xDscWebService resource](#using-the-xdscwebservice-resource) and then review
[Sample_xDscWebServiceRegistration_UseSQLProvider.ps1 on GitHub](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/Examples/Sample_xDscWebServiceRegistration_UseSQLProvider.ps1).
**SqlConnectionString** to a valid SQL Server Connection String. For more information, see [SqlClient Connection Strings](/dotnet/framework/data/adonet/connection-string-syntax#sqlclient-connection-strings).
For an example of SQL Server configuration with **xDscWebService**, first read [Using the xDscWebService resource](#using-the-xdscwebservice-resource)
and then review [Sample_xDscWebServiceRegistration_UseSQLProvider.ps1 on GitHub](https://github.com/dsccommunity/xPSDesiredStateConfiguration/blob/master/source/Examples/Sample_xDscWebServiceRegistration_UseSQLProvider.ps1).

### Using the xDscWebService resource

The easiest way to set up a web pull server is to use the **xDscWebService** resource,
included in the **xPSDesiredStateConfiguration** module.
The following steps explain how to use the resource
in a configuration that sets up the web service.
The easiest way to set up a web pull server is to use the **xDscWebService** 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](/powershell/module/PowershellGet/Install-Module) cmdlet to install the
1. Call the [Install-Module](/reference/6/PowerShellGet/Install-Module.md) 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](https://www.microsoft.com/en-us/download/details.aspx?id=49186).
2. Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either
> `Install-Module` is included in the **PowerShellGet** module, which is included in PowerShell
> 5.0 and higher.

1. 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.
3. Install the certificate on the node that will become the DSC Pull server in the default location,
1. 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.
4. Select a GUID to be used as the Registration Key. To generate one using PowerShell enter the
1. 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.
5. In the PowerShell ISE, start (F5) the following configuration script (included in the Examples
folder of the **xPSDesiredStateConfiguration** module as
`Sample_xDscWebServiceRegistration.ps1`). This script sets up the pull server.
1. In the PowerShell ISE, start (<kbd>F5</kbd>) the following configuration script (included in the
folder of the **xPSDesiredStateConfiguration** module as `Sample_xDscWebServiceRegistration.ps1`)
. This script sets up the pull server.

```powershell
configuration Sample_xDscWebServiceRegistration
Expand Down Expand Up @@ -186,7 +173,7 @@ in a configuration that sets up the web service.
}
```

6. Run the configuration, passing the thumbprint of the SSL certificate as the
1. Run the configuration, passing the thumbprint of the SSL certificate as the
**certificateThumbPrint** parameter and a GUID registration key as the **RegistrationKey**
parameter:

Expand Down Expand Up @@ -267,11 +254,10 @@ Sample_MetaConfigurationToRegisterWithLessSecurePullServer -RegistrationKey $Reg
> [!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.
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 release that makes it necessary to define
Expand All @@ -281,64 +267,50 @@ of the pull server protocol is used and there is no registration processing.

## 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.
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 to 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.1.2.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,
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.
Each resource module needs to be zipped and named according to 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.1.2.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, 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](/powershell/module/PSDesiredStateConfiguration/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.
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](/reference/6/PSDesiredStateConfiguration/New-DSCCheckSum.md)
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:
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](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/DSCPullServerSetup/PublishModulesAndMofsToPullServer.psm1).
[PublishModulesAndMofsToPullServer.psm1](https://github.com/dsccommunity/xPSDesiredStateConfiguration/blob/master/source/Modules/DscPullServerSetup/DscPullServerSetup.psm1).
Examples below:

```powershell
Expand All @@ -350,15 +322,13 @@ in the latest version of the xPSDesiredStateConfiguration module:
Publish-DSCModuleAndMof -Source C:\LocalDepot -Force
```

1. A script that validates the pull server is configured correctly. [PullServerSetupTests.ps1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/DSCPullServerSetup/PullServerDeploymentVerificationTest/PullServerSetupTests.ps1).
1. A script that validates the pull server is configured correctly. [PullServerSetupTests.ps1](https://github.com/dsccommunity/xPSDesiredStateConfiguration/blob/master/source/Modules/DscPullServerSetup/DscPullServerSetupTest/DscPullServerSetupTest.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.
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.

- [Tug](https://github.com/powershellorg/tug)
- [DSC-TRÆK](https://github.com/powershellorg/dsc-traek)
Expand All @@ -376,5 +346,5 @@ The following topics describe setting up pull clients in detail:
- [Windows PowerShell Desired State Configuration Overview](../overview/overview.md)
- [Enacting configurations](enactingConfigurations.md)
- [Using a DSC report server](reportServer.md)
- [[MS-DSCPM]: Desired State Configuration Pull Model Protocol](https://msdn.microsoft.com/library/dn393548.aspx)
- [[MS-DSCPM]: Desired State Configuration Pull Model Protocol Errata](https://msdn.microsoft.com/library/mt612824.aspx)
- [[MS-DSCPM]: Desired State Configuration Pull Model Protocol](https://docs.microsoft.com/openspecs/windows_protocols/ms-dscpm/ea744c01-51a2-4000-9ef2-312711dcc8c9)
- [[MS-DSCPM]: Desired State Configuration Pull Model Protocol Errata](https://docs.microsoft.com/openspecs/windows_protocols/ms-winerrata/f5fc7ae3-9172-41e8-ac6a-2a5a5b7bfaf5)