How to Build a Secure PowerShell DSC Pull Server?

Posted by Charbel Nemnom on June 7, 2016
Share on Facebook0Share on Google+2Share on LinkedIn2Share on Reddit4Tweet about this on Twitter0
5/5 (1)


Windows PowerShell Desired State Configuration (DSC) is a technology introduced by Microsoft in Windows PowerShell v4.0.

At the time of writing, we are at PowerShell v5.0. If you are new to PowerShell DSC, I highly encourage you to start investing and learning this awesome technology today.

DSC is a big topic and can get complex, you should first start learning the basics before you move into advanced scenarios. A good source of reading is on MSDN Windows PowerShell Desired State Configuration Overview. This will give you a good start, but there is plenty of great information out there around this topic.

Desired State Configuration can be configured to deliver configurations in two different methods; push and pull.

PowerShell DSCPullServer

The push method is delivered from a server to a computer, thus “pushing” configurations. This method means you need to manage that and it’s not typically used in a production environment.

The pull method, on the other hand, is another way of delivering configurations to a computer. This method means you bring up a server that you can put all configurations on and all the nodes that are using DSC can pull their configurations from that server and get configured automatically.

There are three kinds of Pull Servers you are allowed to configure:

Configuring SMB Pull Server

  • SMB pull server is the simplest to configure, in other words, file server with SMB share.
  • Create and configure an SMB Share using New-SmbShare
  • Configure the clients Local Configuration Manager (LCM) to point to the SMB share configuration.
  • Not recommended because not all features are available in this mode.

Configuring HTTP Pull Server

  • Need resource module xPSDesiredStateConfiguration
  • Use xPsDesiredStateConfiguration DSC resource module to create an HTTP pull server configuration
  • Configure the clients for HTTP pull server
  • Not recommended in production, because all configurations will be sent in clear text.

Configuring HTTPS Pull Server

  • Need resource module xPSDesiredStateConfiguration
  • Install a certificate on the Pull server
  • Use xPsDesiredStateConfiguration DSC resource module to create an HTTPS pull server configuration
  • Configure the clients for HTTPS pull server
  • Recommended configuration mode

That being said, let’s get started on setting up Windows PowerShell DSC HTTPS pull server!

Infrastructure Overview

We have the following servers installed in our demo environment:

– Domain controller, DNS.

– Web Server, IIS (Pull Server running PowerShell v5.0).

– Test Server (Target server where we are applying the configuration to).

Step 1: Add a DNS Entry for the Pull Server

We need to add a DNS record for the pull server, this DNS record where we want to teach all the nodes on how to get to the pull server and find their configurations.

Open Windows PowerShell as an administration on the domain controller and run the following command:

Add-DnsServerResourceRecordA -ComputerName DC01 -name DSC -ZoneName virt.lab -IPv4Address

PowerShell command

Step 2: Download and Install xPsDesiredStateConfiguration DSC resource module

We need a DSC resource module of the PowerShell gallery. The DSC resource module that we will download called xPsDesiredStateConfiguration. This module gives us couple of capabilities and some documentation that will help to setup a DSC pull server and target server.

Open Windows PowerShell as an administration on the Pull Server and run the following commands:

Find-Module -name xPSDesired*

PowerShell command

At the time of writing, we are at version 3.10.

This module is getting updated regularly by the PowerShell team.

Please note that this module must be installed on the Pull Server and all target servers that will pull the configurations.

Install-Module -name xPSDesiredStateConfiguration, xWebAdministration -force

Installing module 'xWebAdministration'

If you noticed, I have installed the xWebAdministration DSC module as well. This module will help me to automate and setup the Web server in a further step.

Let’s check now the documentation that get installed with xPSDesiredStateConfiguration module.

Microsoft included a sample script called Sample_xDscWebService.ps1 to help you learn how to use the resource.

Please note the path of the sample script below:

C:\Program Files\WindowsPowerShell\Modules\xPSDesiredStateConfiguration\\Examples\Sample_xDscWebService.ps1

If you open Sample_xDscWebService.ps1, you can see we have couple of requirements:

xPSDesiredStateConfiguration module

The first requirement is; we need to install a special Windows feature called DSC-Service.

This feature must be installed first on the Pull server before we continue forward.

PowerShell command

After the service is installed, then we can start setup our Pull server.

Step 3: Install and Configure DSC Pull Server

If we look at the Web Service configuration, we can see the following configuration settings:

xDs cWeb Service PSDSC Pull Server

The EndpointName is the website name.

The Port is set to 8080. This is the port that the website will run on.

We need a secured website, so what port this should be? 443 right?

No, it doesn’t have to be 443, SSL works on any port, why do we usually set it for 443 though?

Because the browser makes it easier for us instead of adding the colon at the end of the website name.

As a best practice, do not set the Pull Server on port 443, because we can configure the nodes (LCMs) on how to get to the Pull server by giving them the port number.

The Pull web server will not be overloaded; you can put other things on it to use that resource a little bit more. In this way, you can set in the future other web services on port 443 that can be accessed by the users.

The PhysicalPath location is wrong, if you noticed in the screenshot above, the physical path for the website should be under C:\inetpub\wwwroot and not C:\inetpub\

The CertificateThumbPrint, we will create an SSL cert in the subsequent step.

I want to point out couple of other things, ModulePath and ConfigurationPath, this is the physical location on the Pull server where you will put your configurations and your DSC resource modules, we can change this path, but I do not recommend doing this.

In order to facilitate the pull server configuration and setup, Mr. Jason Helmick published an awesome script that will automate the whole process for you (end-to-end). Kudos to him.

I highly recommend you use it in your deployment.

You can download this script from here.

I will give you a summary about this script:

  • The script was designed to run on server Core in order to reduce the attack surface as much as possible, but it works on full server with desktop experience as well. I highly recommend server Core in production especially for Web Services, because web servers are under constant attack.
  • The script will configure a Pull web server with minimum components as possible.
  • The script will create an SSL certificate for you.
  • The script will install only the required IIS components for the pull server and then removing all the others.
  • Enable and configure the remote web management service for IIS.

Open the script with PowerShell ISE and update the Node name and FQDN to match your environment.

Next you want to run the script and look for the .mof file that get created.

Last but not least, we need to Push this configuration file to the Pull server.

Why we cannot pull it instead of push it, because we don’t have a pull server yet.

Now we are ready to start deploying the Pull server by running the following command:

Start-DscConfiguration -ComputerName <FQDN> -Path .\ -Verbose -Wait -Force

PowerShell ISE script

Step 4: Test DSC Pull Server

Let’s check if the pull server is installed correctly.

Open Windows PowerShell and running the following command:

Start-Process -FilePath iexplore.exe https://fsrv01-library.virt.lab:8080/PSDSCPullServer.svc

The result will look like as shown in the following screenshot:

xml code

If we launch the IIS management console, we can see the Pull server is configured on port 8080.

IIS management console

Congratulations! we have successfully deployed and configured a PowerShell DSC secure Pull server by completing the following steps:

  • Create DNS entry in Active Directory to be used in the next Post.
  • Download and Install xPsDesiredStateConfiguration DSC resource module.
  • Install and Configure DSC Pull Server.
  • Test DSC Pull Server.

Until next time…

Thanks for reading!


Related materials:

Views All Time
Views Today

Please rate this

Return to all posts

Microsoft has created its own FreeBSD image
How Transparent Page Sharing memory deduplication technology works in VMware vSphere 6.0
The following two tabs change content below.
Charbel Nemnom
Microsoft MVP Charbel Nemnom is an accomplished, hands-on technical professional with over 13 years of broad IT project management and infrastructure experience serving on and guiding technical teams to optimize performance of mission-critical enterprise systems. He is an excellent communicator, adept at identifying business needs and bridging the gap between functional groups and technology to foster targeted and innovative systems development. Charbel is well-respected by peers through demonstrating passion for technology and performance improvement. He has extensive practical knowledge of complex systems builds, network design and virtualization. Charbel has extensive experience in various systems, focusing on Microsoft Cloud Platform, Hyper-V, Datacenter Management, Cloud Computing, security, data protection, and many types of monitoring tools as well as a solid knowledge of technical reporting. Technical reviewer of the book Hyper-V Best Practices by Packt Publishing.