Working with Desired State Configuration

Desired State Configuration (DSC) was first introduced in PowerShell Version 4. With PowerShell Version 5, it has, of course, been developed a lot. Some of the new functions that would be interesting from an Exchange on-premise perspective are as follows:

• ThrottlingLimit (PSDesiredStateConfiguration) specifies the number of target computers or devices on which we want the command to run simultaneously
• Centralized DSC error reporting
• Improvements to DSC resourcing lists all DSC resources, automatic completion, the DependsOn property, and tab completion
• DSC can now be run with a specified user by adding the PSDscRunAsCredential cmdlet to the node block
• 32-bit support was added
• Partial configuration can now deliver configuration documents to a node in fragments
• New cmdlets such as Get-DscConfigurationStatus, Compare-DscConfiguration, Publish-DscConfiguration, Test-DscConfiguration, and Update-DscConfiguration were introduced

Now we have all the great functionality added into the last version of PowerShell for DSC.

Before we go deep into this recipe, we should be aware of what the purpose of DSC is and what DSC is all about.

DSC can in some way be compared to Active Directory Group Policies Objects (GPO). The main purpose of both of them is to make sure that settings are configured according to the configuration. In that sense, DSC can pretty much be compared to GPO, and DSC will make sure that the settings are equally the same over the specified nodes and that the settings will remain so.

The DSC system has two configuration modes: push or pull using HTTP(S) or SMB. A typical setup would be to have one server acting as the DSC server, where the configurations and modules are located.

In push mode, the MOF configuration is pushed to its intended targets, called nodes. The opposite is done in pull mode; the nodes then pull the configuration from the DSC server, which has to be configured, and get the required modules and resources. The pull nodes have a scheduled task that takes the actions.

In this recipe, we concentrate on pull mode, and the default setting for the pull interval is 15 minutes.

In this recipe, we will install and configure the DSC server. With the DSC server in place, we will take it to the next level and see how DSC can help us manage Exchange on-premises.

How to do it...

Our first example is an example of how to configure the DSC Pull Server. One thing to mention, as a prerequisite, is that winrm needs to be configured. This is done by running the following command winrm quickconfig.

So, let's install and configure the DSC Pull server using the following example. Save the following script as PullServerConfig.ps1 and run it:

configuration CreatePullServer
{
  param
    (
      [string[]]$ComputerName = 'localhost'
    )
  Import-DSCResource -ModuleName xPSDesiredStateConfiguration
  Node $ComputerName
    {
      WindowsFeature DSCServiceFeature
        {
          Ensure = "Present"
          Name   = "DSC-Service"
        }
      xDscWebService PSDSCPullServer
        {
            Ensure = "Present"
            EndpointName = "PSDSCPullServer"
            Port = 8080
            PhysicalPath = "$env:SystemDrive\inetpub\wwwroot\ `PSDSCPullServer"
            CertificateThumbPrint = "AllowUnencryptedTraffic"
            ModulePath = "$env:PROGRAMFILES\WindowsPowerShell\ `DscService\Modules"
            ConfigurationPath = "$env:PROGRAMFILES\ `WindowsPowerShell\DscService\Configuration"
            State = "Started"
            DependsOn = "[WindowsFeature]DSCServiceFeature"
          }
        xDscWebService PSDSCComplianceServer
          {
            Ensure = "Present"
            EndpointName = "PSDSCComplianceServer"
            Port = 9080
            PhysicalPath = "$env:SystemDrive\inetpub\wwwroot\ `PSDSCComplianceServer"
            CertificateThumbPrint = "AllowUnencryptedTraffic"
            State = "Started"
            IsComplianceServer = $true
            DependsOn = ("[WindowsFeature]DSCServiceFeature","[xDSCWebService]PSDSCPullServer")
          }
    }
}
CreatePullServer -ComputerName dscsrv.testlabs.se

This wasn't too hard. Was it? So, let's continue with the configuration for our Exchange server. In the following example, we are going to configure the execution policy to a value of RemoteSigned. We are also going to make sure that the MSExchangeFrontEndTransport service is running. So, let's create the script and finally one for pulling the configuration from the DSC server:

Configuration CompliantExchange
{
  param ($MachineName)
  Import-DSCResource -ModuleNamePSDesiredStateConfiguration, ` xPowerShellExecutionPolicy
  Node $MachineName
  {
    xPowerShellExecutionPolicy SetPSExecutionPolicyToRemoteSigned
    {
      ExecutionPolicy = "RemoteSigned"
    }
  Service MSExchangeFrontEndTransport
    {
      Name = "MSExchangeFrontEndTransport"
      StartupType = "Automatic"
      State = "Running"
    }
  }
}
CompliantExchange –MachineName tlex01.testlabs.se
$guid = [guid]::NewGuid()
$source = "CompliantExchange\tlex01.testlabs.se.mof"
$dest = "\\dscsrv.testlabs.se\c`$\program files\windowspowershell\dscservice\configuration\$guid.mof"
copy $source $dest
New-DSCChecksum $dest

So, let's create the script to pull the configuration from the DSC server to our Exchange server. This should be executed on the Exchange on-premises server:

Configuration SetPullMode
{
  param([string]$guid)
  Node tlex01.testlabs.se
    {
      LocalConfigurationManager
       {
         ConfigurationMode = 'ApplyAndAutoCorrect'
         ConfigurationID = $guid
         RefreshMode = 'Pull'
         DownloadManagerName = 'WebDownloadManager'
         DownloadManagerCustomData = @{
           ServerUrl = 'http://dscsrv.testlabs.se:8080/PSDSCPullServer.svc';
           AllowUnsecureConnection = 'true' }
       }
    }
}
SetPullMode –guid $guid
Set-DSCLocalConfigurationManager -Computer tlex01.testlabs.se ` -Path ./SetPullMode –Verbose

How it works...

The first part in this recipe was the script to create the DSC Pull server, don't forget about the prerequisite (winrm quickconfig). To create the pull server in this example, we did import the DSC module named xPSDesiredStateConfiguration and use the resource named xDscWebService. Make sure to place the xPSDesiredStateConfiguration module into the $env:ProgramFiles\WindowsPowerShell\Modules folder.

We saved the script as PullServerConfig.ps1 and started it by running .\PullServerConfig.ps1. A folder will be created with the configuration name; in this case, it was called CreatePullServer. Inside the folder, we now have a file called nodename.domain.mod; in our example, it was named dscsrv.testlabs.se.mof.

Finally, to configure the server, we started the DSC configuration by running Start-DscConfiguration .\CreatePullServer -Wait. The reason we are using the Wait parameter is that it's easier for us to follow if everything runs as expected. The following screenshot shows you an ongoing configuration:

When our DSC server was created successfully, the second script that we used was made with the purpose to make sure that the execution policy was always set to RemoteSigned and that the Microsoft Exchange service named MSExchangeFrontEndTransport was always running. However, these two were just used to illustrate an example of what DSC could be used for.

First, we imported the DSC modules that are going to be used. One thing to mention here is that these modules need to be deployed to our pull clients/nodes, in the same folder as the DSC server. The modules should be placed in the $env:ProgramFiles\WindowsPowerShell\Modules folder.

In the second script, we specified which node we are going to configure with the resource and what setting.

Before deploying these scripts to the DSC server, we need to make sure to follow the third script, where we created a new guide and published the configuration/mof file in the $env:ProgramFiles\WindowsPowerShell\DscService\Configuration folder. This is basically done because the DSC server uses GUIDs and now node names.

With the MOF files in place, the last step for the configuration is to create a checksum for the MOF file. This is done using the New-DSCChecksum cmdlet.

The final step to allow the DSC server and its client/nodes to take the necessary actions, we need to configure the nodes. In our example, the Exchange server needs to pull the configuration from the DSC server. Once the pull mode has been configured, give the node 30 minutes to retrieve the configuration. The following screenshot shows you when to configure the Exchange server in order to use the pull method instead of the push method:

After applying the pull configuration settings, give the node at least 30 minutes, then you can go ahead and check whether the configuration has taken place by running the Get-DscConfigurationStatus cmdlet. This cmdlet will show you if the configuration was successfully deployed or if there were any issues. Also, the Get-DscConfiguration cmdlet can be helpful to see which configuration was deployed and its status.

See also

• Understanding the new execution policy
• Working with script repositories