Azure Policy Guest Configuration – Client

Michael Greene

This post builds upon the introduction published earlier to the PowerShell blog. In this post we are going to explore the Azure Policy Guest Configuration client and how configuration content is consumed. 

The full documentation for this service is available at the following short url. 

https://aka.ms/gcpol 

[Updated 9/9/2020 with changed file/folder names]

GC service/daemon 

Inside Azure Policy Guest Configuration, you will find the new DSC engine as part of the extension for virtual machines. You can see this using the “Run Command” feature in Azure for any virtual machine that is being audited by Azure Policy using one of the Guest Configuration initiatives. 

The structure of the agent folders is the same for both operating systems. You will find a folder that contains the binaries for the engine, a folder named “logs” containing logs generated by the engine, and a subfolder named “downloads” that is used to support additional requirements. 

Here are some example commands you can use to take a look at the new DSC engine yourself. 

Windows 

The Guest Configuration extension for Windows has not been published to GitHub yet.

List the binaries in Guest Configuration in Windows 

Command (note the version is current at this time but could change):

dir 'C:\Packages\Plugins\Microsoft.GuestConfiguration.ConfigurationforWindows\1.28.3.0\dsc\GC\'

Result: 

    Directory: C:\Packages\Plugins\Microsoft.GuestConfiguration.ConfigurationforWindows\1.28.3.0\dsc\GC


Mode                LastWriteTime         Length Name                                                                  
----                -------------         ------ ----                                                                  
-a----        7/20/2020   7:12 PM        1843712 gclib.dll                                                             
-a----        7/20/2020   7:16 PM         204800 gc_cache_operations.dll                                               
-a----        7/20/2020   7:03 PM         534528 gc_diagnostics.dll                                                    
-a----        7/20/2020   7:01 PM         572416 gc_infrastructure.dll                                                 
-a----        7/20/2020   7:05 PM          70144 gc_operations.dll                                                     
-a----        7/20/2020   7:07 PM        2157056 gc_pull_client.dll                                                    
-a----        7/20/2020   7:08 PM         463360 gc_reporting.dll                                                      
-a----        7/20/2020   7:04 PM         459776 gc_security_tools.dll                                                 
-a----        7/20/2020   7:18 PM         358400 gc_service.exe                                                        
-a----        7/20/2020   7:14 PM         618496 gc_timer.dll                                                          
-a----        7/20/2020   7:16 PM         213504 gc_timer_operations.dll                                               
-a----        7/20/2020   7:17 PM         268288 gc_worker.exe                                                         
-a----        7/20/2020   7:04 PM         398336 gc_worker_manager.dll  

You will also find an instance of pwsh.exe and supporting files in this same (version specific) folder. That is because Guest Configuration includes the portable installation of PowerShell Core so there is no need to manage PowerShell versions for the system. 

View the details of the DSC service in Guest Configuration in Windows 

Command: 

Get-Service GCService | fl * 

Result: 

Name                : GCService RequiredServices    : {} CanPauseAndContinue : False CanShutdown         : False CanStop             : True DisplayName         : Guest Configuration Service DependentServices   : {} MachineName         : . ServiceName         : GCService ServicesDependedOn  : {} ServiceHandle       : SafeServiceHandle Status              : Running ServiceType         : Win32OwnProcess StartType           : Automatic Site                : Container           : 

Linux 

The Guest Configuration extension for Linux is published in GitHub here. 

List the binaries in Guest Configuration in Linux 

Command (note the version is current at this time but could change): 

sudo ls /var/lib/waagent/Microsoft.GuestConfiguration.ConfigurationforLinux-1.25.5/GCAgent/GC/gc_* 

Result: 

[stdout] /var/lib/waagent/Microsoft.GuestConfiguration.ConfigurationforLinux-1.25.5/GCAgent/GC/gc_linux_service /var/lib/waagent/Microsoft.GuestConfiguration.ConfigurationforLinux-1.25.5/GCAgent/GC/gc_worker

Currently, Guest Configuration in Linux is only supporting content in the format of Chef InSpec profiles. We expect this to soon open to PowerShell-based resources and other tool formats. 

View the details of the GC service in Guest Configuration in Linux 

Command: 

systemctl status gcd.service 

Result: 

[stdout]
● gcd.service - DSC Service
   Loaded: loaded (/lib/systemd/system/gcd.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2020-09-09 16:43:12 UTC; 2h 38min ago
 Main PID: 4035 (gc_linux_servic)
    Tasks: 42 (limit: 4075)
   CGroup: /system.slice/gcd.service
           └─4035 /var/lib/waagent/Microsoft.GuestConfiguration.ConfigurationforLinux-1.25.5/GCAgent/GC/gc_linux_service

Sep 09 16:43:12 ub0 systemd[1]: gcd.service: Service hold-off time over, scheduling restart.
Sep 09 16:43:12 ub0 systemd[1]: gcd.service: Scheduled restart job, restart counter is at 4.
Sep 09 16:43:12 ub0 systemd[1]: Stopped DSC Service.
Sep 09 16:43:12 ub0 systemd[1]: Started DSC Service.
Sep 09 16:43:12 ub0 gc_linux_service[4035]: Running DSC rest server...

Configurations 

Configurations in Guest Configuration are managed in a whole new way. There is no longer a need for partial configurations because many configurations can be managed independently. 

Please keep in mind that currently, configurations are used only for auditing settings and not enforcing the configuration. 

The model for Guest Configuration takes lessons learned from both the DSC Extension and State Configuration service. The Guest Configuration service does not require or support uploading and storing assets in the service, or a compilation service. Configurations are packaged in .zip format as they were for DSC Extension. A Guest Assignment in the Guest Configuration resource provider includes a reference to the location of the package, a hash value of the package file, and a table of parameters to be passed to the engine when the configuration is executed. 

For content provided by Microsoft, the configuration content managed and replicated globally. When the package is downloaded to the machine, it is decompressed and extracted to a local folder. 

Each folder contains everything needed for DSC to manage the configuration including the mof, any resources required, and the metaconfiguration to use for that configuration. This means the mode, frequency, and other LCM settings can be unique per configuration. 

View configuration content in Windows 

In this test case, the server is in scope of multiple audit policies. 

Command: 

dir c:\programdata\GuestConfig\Configuration\ 

Result: 

 Directory: C:\programdata\GuestConfig\Configuration

Mode                LastWriteTime         Length Name                           ----                -------------         ------ ----                           d-----         6/5/2019   1:03 PM                WindowsDefenderExploitGuard    d-----         6/5/2019   1:03 PM                WindowsDscConfiguration        d-----         6/5/2019   1:03 PM                windowsfirewallenabled         d-----         6/5/2019   1:03 PM                WindowsLogAnalyticsAgentConnection                           d-----         6/5/2019   1:03 PM                WindowsPendingReboot           d-----         6/5/2019   1:04 PM                WindowsPowerShellModules       d-----         6/5/2019   1:04 PM                WindowsTimeZone                

View configuration content in Linux 

In this test case, the server is in scope of only one audit policy. 

Command: 

sudo ls /var/lib/GuestConfig/Configuration 

Result: 

[stdout] firewalldenabled 

Logs 

Log output is available on each node within the agent folder named “Logs”. This can also be returned using “Run Command”, however the output is limited to the last 4096 bytes so it is best to filter the logs to only what you are looking for. Examples approaches are given below. 

View error messages in Windows logs 

Command (note the version is current at this time but could change):

Select-String -Path 'C:\programdata\GuestConfig\gc_agent_logs\gc_agent.log' -pattern 'DSC*Engine' -CaseSensitive -Context 0,5

Result (this is a short snippet of the actual output): 

[INFO] [00000000-0000-0000-0000-000000000000] Job  3af0538a-35f4-415f-b5b8-70ae3099e6a2 : Operation Get-DscConfiguration  completed successfully. 

View error messages in Linux logs 

Command (note the version is current at this time but could change): 

grep -A 5 'DSC*Engine' /var/lib/GuestConfig/gc_agent_logs/gc_agent.log

Result (this is a short snippet of the actual output): 

[2019-06-05 18:14:22.772] [PID 30775] [TID 30824] [DSCEngine] [INFO] [00000000-0000-0000-0000-000000000000] Job 6ae51953-24aa-44e8-8abb-4ec522cc5b1f : Method CU_TestConfiguration ended successfully 

Thank you! Michael Greene Principal Program Manger Microsoft Azure @migreene 

Michael Greene Principal Group Program Manager, Command Line and PowerShell

Follow