In this post of the Desired State Configuration series we will look at creating new custom DSC Resource. If you are reading this post and have not read the precious blog post titled “Anatomy of DSC Resource”, I would highly recommend to read that first. It will provide you enough insight on what DSC resources are and the things to be taken care off while creating custom DSC resources.
We will be creating a new custom DSC resource related to Windows Firewall. Firewall is a feature of Windows providing rules that can be enabled and disabled. This custom resource is called “CheckFirewall” and would be responsible for managing the firewall rules i.e. enabling and disabling firewall rules.
The DSC resource would perform the following actions
- Check the value within Configuration and call the function Test-TargetResource.
- If the value is ‘Absent’, then return ‘True’ if firewall is not already enabled else return ‘False’.
- If the value is ‘Present’, then return ‘True’, if the firewall is already enabled else return ‘False’.
- If the value returned by Test-TargetResource is “False”, DSC would call “Set-TargetResource” function of the Resource whereas if the Test-TargetResource function returns “True”, DSC would call “Get-TargetResource” function of the resource.
- The “Set-TargetResource” function of the resource is generally responsible for checking each property of the target resource and update it according to the provided configuration. However, in our case, we are either enabling or disabling a firewall rule and hence would not be checking any properties provided by Firewall rules.
Create a Resource Provider Folder
Create a Folder called “CheckFirewall” at “<<Your Drive>>\Windows\System32\WindowsPowershell\v1.0\Modules\PSDesiredStateConfiguration\PsProviders\”. In my case the drive is C:\
Create MOF file
The first step in creating the Resource is to create its MOF file. For more details about MOF files, refer to earlier post.
We have named the MOF file as CheckFirewall.Schema.mof and the name of the class is CheckFirewall. Its version number is “1.0.0” and friendly name is also “CheckFirewall”. Please note that it is this friendly name that is referred within the DSC configuration script. There are just 2 properties for this class
- DisplayName: referring to the display name of the firewall rule that needs to be enabled or disabled.
- Ensure: flag referring to whether the firewall rule should be enabled or disabled.
The MOF file can also be copied from some existing resource and modified as shown above and this is definitely more convenient and easier.
Create the Powershell Script Module file
In this step, we would create the script file that is the crux of creating the custom resource. The entire brains of the resource lies within this script file because it is here that all the DSC related mandatory functions are implemented namely Set-TargetResource, Get-TargetResource and Test-TargetResource.
Open Powershell ISE and implement the above mentioned three function and save it in CheckFirewall Directory created above as CheckFirewall.psm1 file.
We will use Windows Firewall Powershell cmdlets to determine the current state of the firewall rule and also for enabling and disabling it.
The Test-TargetResource function looks like below. We have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function.
The Get-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.
The Set-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.
Additionally, we also enable or disable the firewall rule using “Enable-NetFirewallRule” or “Disable-NetFirewallRule” depending upon the value of the configuration.
Above, notice that all the three functions defines parameters related to the properties available in the MOF file. Also, some can be mandatory while others could be optional.
Also, both Set-TargetResource and Get-TargetResource returns back a hashtable containing all the properties defined in the MOF file.
Generate the PSD1 file
We can either generate a new PSD1 file using “New-ModuleManifest” or copy some existing psd1 file for existing resource and modify accordingly. I recommend using the first approach of using the “New-ModuleManifest” since this would be less error prone provided you provide correct values. The details about generating this file is available in earlier blog post.
The name of the file should be “CheckFirewall” and should be generated within the above created folder. The sample content looks like below.
Now, this resource can be used in any DSC configuration script. An example is provided below. We have a Configuration node containing a Node for the Server name which in turn contains our new custom resource “CheckFirewall” and is named as “SQLFirewallPresent”. It is setting two available resource property i.e. DisplayName and Ensure. You would see that these are the two properties we have defined in our MOF file.
This concludes the creation of a custom resource for DSC. This is a simplified way of creating of DSC resource and many more aspects like localization and error handling should be part of the overall script.
Hope you liked this post.