ReverseDSC for Files and Registry

As mentioned in multiple blog article I wrote in the past, ReverseDSC is technology agnostic, meaning that it can reverse engineer any component (Windows, Linux, MacOS, etc.) as long as there is a DSC module that exists for it. What we refer to as Orchestrator Scripts is what is technology specific and does specific operations for a specific component. You’ve seen me blog mainly about the SharePointDSC.Reverse Orchestrator Script lately, and show users how they can extract configuration of existing SharePoint Farms and replicate them elsewhere. There are however several other Orchestrator Scripts being developed at the moment including the SQLServer.Reverse one and the PSDesiredStateConfiguration.Reverse one that allows you to replicate file and registry structured on other machines using DSC.

In this article, I want to demo how the PSDesiredStateConfiguration.Reverse Orchestrator Script can be used to extract a DSC Configuration script. While the Orchestrator Script allows you to extract numerous components of an environment (Windows Features, Logs, Archives, Users, etc.) we will only focus on Files and Registry Entries within this article.

How to Install

Just like all other Orchestrator Scripts we are currently working on, the PSDesiredStateConfiguration.Reverse script is made available in the PowerShell Gallery. You can download and install it from any machine that has internet connectivity by executing the following lines of PowerShell (needs WMF 5.0).

Install-Script PSDesiredStateConfiguration.Reverse -Force

If you don’t have internet connectivity on your machine or if you don’t have access to a machine with WMF 5.0+ on it, then you will need to manually download the script for the GitHub Repository from a machine that has internet connectivity and copy it manually onto the machine. By default, the PowerShell code above downloads the script under c:\Program Files\WindowsPowerShell\Scripts. I would therefore recommend copying the script under that folder (create the Scripts folder if it doesn’t already exist).

ReverseDSC for Files

In this section we will cover the process of using the PSDesiredStateConfiguration.Reverse Orchestrator Script to extract a file structure from an existing environment as a DSC configuration script that we can use to recreate that exact file structure onto another environment. The challenge here is that in order for this file structure to be recreated on a new computer, we need to have access to the files from a central location. Let’s take the following example where I wish to extract the File structure in the path C:\MyCustomApplication from my machine.

MyCustomApplication file Structure

MyCustomApplication file Structure

The files are currently local to the machine. If we were to simply extract the file structure as a DSC Configuration Script, it would result in DSC Resources blocks similar to the following:

File 469e3fe0-b1c6-4b70-bc69-725dd2bc3739
{
    DestinationPath = 'C:\MyCustomApplication';
    Type = 'Directory';
    Recurse = $True;
    SourcePath = 'C:\MyCustomApplication';
    Ensure = 'Present';
}

This code tells DSC on the new machine to copy all files that exist under SourcePath (C:\MyCustomApplication) under the DestinationPath (C:\MyCustomApplication). Now, let’s forget that both paths are the same for one moment and try to understand the issue here. The new machine we are trying to configure with DSC knows nothing about the one we ran ReverseDSC on. It doesn’t have access to the original file repository where all the .dll, .chm, and .exe are located. Therefore we need to make sure these files we want to copy over our new machine are made available either on a network drive or with a Share from the machine we ran ReverseDSC on.

In order to solve this issue and to make it easy for users to extract a DSC Configuration script that can easily be leverage on other machines, the script accepts and array of HashTable values for the Folders parameter. The HashTable defines the following values:

Key Description
Source Root URL of the folder to scan on the local machine
SharedSource Root URL of the Shared folder or network location where the files to be copied are located.

To go back to our example above, I will be using the following values when calling the script:

Key Value
Source C:\MyCustomApplication
SharedSource \\NetworkShare\MyCustomApplication

I will then be calling the PSDesiredStateConfiguration.Reverse.ps1 script as follow:

.\PSDesiredStateConfiguration.Reverse.ps1 -Folders @{Source="C:\MyCustomApplication";SharedSource="\\NetworkShare\MyCustomApplication"}

Doing so will then result in the DSC Resource blocks having the DestinationPath match what was on the original server we ran ReverseDSC onto, and the SourcePath pointing to the shared location as follow:

File 617c1dc1-a7f6-48b6-bd69-24b4cefe2d21
{
    DestinationPath = 'C:\MyCustomApplication\Bin\Core.dll';
    Type = 'File';
    SourcePath = '\\NetworkShare\MyCustomApplication\Bin\Core.dll';
    Ensure = 'Present';
}

Upon compiling the DSC Configuration Script into a MOF file and initiating the DSC configuration on the new machine, the machine will automatically copy the files from the shared location to a local path matching the original machine on which we ran ReverseDSC onto.

It is also important to note that as mentioned above, the Folders parameter is actually an array of HashTable, meaning that multiple values could be passed to it. Assuming you had two folders you wanted to extract, you code do it as follow:

.\PSDesiredStateConfiguration.Reverse.ps1 -Folders @(@{Source="C:\Folder1";SharedSource="\\NetworkShare\Folder1"}, @{Source="C:\Folder2";SharedSource="\\NetworkShare\Folder2"})

ReverseDSC for Registry Keys

The process to use the PSDesiredStateConfiguration.Reverse Orchestrator Script against some Registry Keys is very similar to the Files process described above. The Script accepts a parameter named RegistryPaths that is an array of string that contains the paths to the Parent Registry key you wish to extract. The Registry Key paths can be entered either as the long or short form (e.g. HKLM:\System or HKEY_LOCAL_MACHINE\System).

Assuming I wanted to extract everything under the following Registry Paths:

  • HKLM:\System\CurrentControlSet\Control\Lsa
  • HKLM:\Software\dotnet

All I would need to do is call the script as follow:

.\PSDesiredStateConfiguration.Reverse.ps1 -RegistryPaths @("HKLM:\System\CurrentControlSet\Control\Lsa", "HKLM:\Software\dotnet")

That would then produce an output having DSC Resource Blocks similar to the following:

Registry 23e6bc1f-2f88-4b14-afbe-dddd8e3aa3e6
{
    ValueName = "NoLmHash";
    Key = "HKLM:\System\CurrentControlSet\Control\Lsa";
    Ensure = "Present";
    ValueType = "DWord";
    ValueData = @("1");
}

Reverse Engineer an Existing SharePoint Farm using PowerShell DSC

PowerShell Desired State Configuration (DSC) is a technology that allows you to define a configuration for an environment, and ensure it automatically gets configured tat way. It can also help you monitor the delta between the current state of the environment and what the defined configuration (a.k.a. Desired State) is. So as an example in the case of SharePoint, if you were to specify that you needed to register a Managed Account for user sp_services, and that someone was to delete that account, PowerShell DSC would automatically report the discrepancy in the logs or attempt to automatically recreated it based on how you configured your environment (Configuration Mode).

The SharePoint module for DSC is great to build new environments from the ground up. Simply specify what the Desired State should be (Web Applications, Site Collections, Service Applications, etc.) and let DSC do its job and automatically configure it. It acts as some kind of abstraction layer for the user, where they only need to define resources and their various settings for DSC to create and configure everything for them in the background. They don’t need to know the cmdlets to use, know what the objects’ properties are, and even less understand the object model behind it all. They only need to know what the DSC resource accepts.

Existing Environments

In many cases however, clients who want to get into DSC already have investments in SharePoint, where they have an existing SharePoint 2013 or 2016 farm that they would like to replicate somewhere else with DSC. Writing a DSC configuration script from scratch that represents their exact environment is a complex job and often results in the customer writing tens of thousands of lines of code. This is where the ReverseDSC orchestrator for SharePoint, called SharePointDSC.Reverse comes into play. SharePointDSC.Reverse is a PowerShell script (.ps1) that you execute against an existing SharePoint 2013 or 2016 farm to extract its PowerShell Desired State Configuration. The script will scan every component of the farm, down to the SPWeb level. This means that everything that can be defined in Central Administration, with the addition of Sites can be extracted with the SharePointDSC.Reverse. The output will be another .ps1 script that will contain the DSC configuration of your farm. That script can then be executed to compile a .MOF file that can be used to replicate your SharePoint environment elsewhere.

Other Scenarios

The ReverseDSC Orchestrator for SharePoint can also be used for several scenarios other than replicating a farm. It can be used to:

  • Extract a SharePoint 2013 Farm Configuration and replicate it as a SharePoint 2016 one;
  • Compare deltas between two extractions to see what changed between two point in time;
  • Create standalone copies of a Farm for developers;
  • Move an on-premises SharePoint Farm into Azure Infrastructure-as-a-Service;
  • On-board an existing farm onto PowerShell DSC to monitor it and ensure it remains in its desired state.

How to Use

The ReverseDSC Orchestrator for SharePoint is now officially available in the PowerShell Gallery. It can be installed, alongside all of its dependencies, by executing the following PowerShell one-liner from a machine that has internet connectivity:

Install-Script SharePointDSC.Reverse -Force 

Note that this has to be done on only one server in the farm; you don’t need to install it on all servers. If your SharePoint server doesn’t have internet connectivity, simply run the above line of PowerShell from a machine that does have internet connectivity, and manually copy the ReverseDSC, SharePointDSC from the PowerShell modules folder (C:\Program Files\WindowsPowerShell\Modules), and the SharePointDSC.Reverse.ps1 script from the PowerShell script folder (C:\Program Files\WindowsPowerShell\Scripts) onto the destination server.

Additional Resources

To learn more about the ReverseDSC Orchestrator for SharePoint, you can watch my Microsoft Virtual Academy session on the topic at the following URL: https://mva.microsoft.com/en-US/training-courses/sharepoint-automation-with-dsc-17843