As described in “Push vs. Pull Mode” blog, DSC configuration can be applied on target nodes using pull or push mechanism. In this blog I will talk about how to retrieve node information from DSC pull server. When the node pulls a configuration from the pull server and applies it locally, it can either succeed or fail. DSC compliance endpoint stores the configuration run status and node information in a database. Compliance endpoint can be used by admins to periodically check the status of the nodes to see if there are in sync with pull server or not (using tools like Excel or write their own client application).
In this post I will cover the following:
- Sending node’s status to pull server
- Query node information in json from pull server
Before configuring a node to pull a configuration from pull server, you will need to setup DSC pull server in your environment that is covered in “DSC Resource for configuring pull server environment” blog.
You will also need to setup a compliance endpoint that will record the node information that is covered in the same blog.
DSC Compliance endpoint stores the following information about the nodes in database:
- TargetName – Node name
ConfigurationId – Configuration ID associated with the node
StatusCode – Node status code.
Here is the list of status codes. Note that there might be additions or changes to the list in the future.
Status Code | Description |
0 | Configuration was applied successfully |
1 | Download Manager initialization failure |
2 | Get configuration command failure |
3 | Unexpected get configuration response from pull server |
4 | Configuration checksum file read failure |
5 | Configuration checksum validation failure |
6 | Invalid configuration file |
7 | Available modules check failure |
8 | Invalid configuration Id In meta-configuration |
9 | Invalid DownloadManager CustomData in meta-configuration |
10 | Get module command failure |
11 | Get Module Invalid Output |
12 | Module checksum file not found |
13 | Invalid module file |
14 | Module checksum validation failure |
15 | Module extraction failed |
16 | Module validation failed |
17 | Downloaded module is invalid |
18 | Configuration file not found |
19 | Multiple configuration files found |
20 | Configuration checksum file not found |
21 | Module not found |
22 | Invalid module version format |
23 | Invalid configuration Id format |
24 | Get Action command failed |
25 | Invalid checksum algorithm |
26 | Get Lcm Update command failed |
27 | Unexpected Get Lcm Update response from pull server |
28 | Invalid Refresh Mode in meta-configuration |
29 | Invalid Debug Mode in meta-configuration |
- NodeCompliant -Node is compliant with applied configuration or not.
- ServerCheckSum – Checksum of the configuration mof file stored on the pull server
- TargetCheckSum –Checksum of the configuration mof file that was applied on the node
- LastComplianceTime – Last time the node run the configuration successfully
- LastHeartbeatTime -Node’s last hearbeat time
- Dirty – True if node status was recorded in the database, and false if not.
Compliance endpoint database connection is defined through its web.config settings. If you did not define it for your environment, compliance endpoint would not be recording node information into the database. Below snippet shows how to define database connection:
Set-Webconfig-AppSettings ` |
-path$env:HOMEDRIVE\inetpub\wwwroot\$complianceSiteName ` |
-key"dbprovider" ` |
-value"ESENT" |
Set-Webconfig-AppSettings ` |
-path$env:HOMEDRIVE\inetpub\wwwroot\$complianceSiteName ` |
-key"dbconnectionstr" ` |
-value"$env:PROGRAMFILES\WindowsPowerShell\DscService\Devices.edb" |
|
Getting ready
First, we need to write a simple configuration that the node will be pulling from pull server, compile the configuration into mof, create it’s checksum file, deploy the mof and checksum files to the pull server. Then, configure the node to be in pull mode as by default LCM on the node is configured to be in push. For details please refer to “push vs. pull mode” blog.
Sending node’s status to pull server
When the node pulls a configuration from the pull server, the node includes the previous configuration run status with the new pull request which then gets recorded by compliance endpoint into the database.
Query node information in json from pull server
We will use the following function to query the node’s information from pull server.
<#
# DSC function to query node information from pull server.
#>
functionQueryNodeInformation
{
Param (
[string]$Uri="http://localhost:7070/PSDSCComplianceServer.svc/Status",
[string]$ContentType="application/json"
)
Write-Host"Querying node information from pull server URI = $Uri"-ForegroundColorGreen
Write-Host"Querying node status in content type = $ContentType "-ForegroundColorGreen
$response=Invoke-WebRequest -Uri$Uri-MethodGet-ContentType$ContentType -UseDefaultCredentials-Headers
@{Accept =$ContentType}
if($response.StatusCode -ne200)
{
Write-Host"node information was not retrieved."-ForegroundColorRed
}
$jsonResponse=ConvertFrom-Json$response.Content
return$jsonResponse
}
You need to replace Uri parameter with your_pull_ server_ URI. To retrieve the node information in xml format, you should set the ContentType to ”application/xml”.
Now, let us retrieve the node information in the parameter $json and format the output to be in a table:
$json=QueryNodeInformation–Urihttp://localhost:7070/PSDSCComplianceServer.svc/Status
$json.value |Format-TableTargetName,ConfigurationId,ServerChecksum,NodeCompliant,LastComplianceTime,StatusCode
In result you will see an output similar to:
TargetName ConfigurationId ServerCheckSum NodeCompliant LastComplianceTime StatusCode
---------- --------------- -------------- ------------- ----------------- ----------
Machine-975.. 1C707B86-EF8E…… AE467E88D512... True 1899-12-30T00:00:00 0
Hope this helps.
Thanks,
Narine Mossikyan
Software Engineer in Test