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 on this topic.
Desired State Configuration can be configured to deliver configurations in two different methods; push and pull.
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, the file server with SMB share.
- Create and configure an SMB Share using New-SmbShare
- Configure the client’s 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!
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 too).
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 administrator on the domain controller and run the following command:
Add-DnsServerResourceRecordA -ComputerName DC01 -name DSC -ZoneName virt.lab -IPv4Address 172.16.20.21
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 a couple of capabilities and some documentation that will help to set up a DSC pull server and the target server.
Open Windows PowerShell as an administrator on the Pull Server and run the following commands:
Find-Module -name xPSDesired*
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
If you noticed, I have installed the xWebAdministration DSC module as well. This module will help me to automate and set up the Web server in a further step.
Let’s check now the documentation that gets 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:
If you open Sample_xDscWebService.ps1, you can see we have a couple of requirements:
The first requirement is; we need to install a special Windows feature called DSC-Service.
This feature must be installed first on the PullServer before we continue forward.
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:
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 secure 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 a 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.
I will give you a summary of the 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 a 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 remove 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 gets created.
Last but not least, we need to Push this configuration file to the Pull Server.
Why we cannot pull it instead of pushing 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
Step 4: Test DSC Pull Server
Let’s check if the pull server is installed correctly.
Open Windows PowerShell and run 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:
If we launch the IIS management console, we can see the Pull server is configured on port 8080.
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!