Practical usage in a Domain Environment (GPO-driven collection and conversion)

For AI agents: a documentation index is available at /llms.txt; a markdown version of this page is available at /v1.2.1.0/docs/examples/gpo-driven-collection/index.md.

This document outlines a practical, end-to-end example of running DNSServer.DebugLogParser in an Active Directory domain environment, focused on converting Windows DNS Server debug logs on domain controllers.

This example is accompanied by a ZIP archive, which provide the policy artifacts used to implement the workflow described here.
The most relevant artifacts are backup manifest, GPO report, Files.xml, Set-DNSServerDebugLogging.ps1, and ScheduledTasks.xml.

Scenario

• Multiple domain controllers (DCs) host the DNS Server role.
• DNS debug logging is enabled and configured consistently on each DC via a scheduled task (writing log files to C:\Administration\Logs\DNSServer).
• A centrally managed process converts logs into CSV for:
  • security analytics
  • operational reporting
  • troubleshooting
  • compliance/retention

Target outcomes

• Consistent conversion settings across all DCs
• Predictable output location and naming
• Optional compression to reduce storage footprint
• Optional statistics outputs for quick daily rollups
• Minimal host-side risk, with explicit rerun and cleanup considerations

Suggested architecture

Collection model: local convert + central pull

1. Each DC writes DNS debug logs to disk with rollover enabled.
2. Each DC converts rotated *.log files into a data CSV and statistics CSVs, then compresses the outputs into *.zip on a schedule (Task Scheduler).
3. Outputs are written next to the log files so the pipeline stays simple.
4. A central server collects the *.zip outputs, for example via file share ingestion, scheduled copy, SIEM forwarder, or an agent-based collector.

This model minimizes network reads of large raw log files and keeps parsing close to the data.

GPO workflow

The workflow is implemented through Group Policy (computer configuration) to ensure consistent settings across all domain controllers.

Reference implementation included in this repository (GPO report):

• Archive/report name: T0-C-Analytics-DNSDebugLogging
• Backup ID: {2B6F16BC-0E7C-4787-83D7-2854FED882EE}
• GPO link target: corp.company.com/Domain Controllers
• Item filter (used for both file deployment and scheduled tasks): only applies if C:\Windows\System32\dns.exe exists

1) Prerequisites (folders + module)

The provided backup assumes these folders already exist. Add separate GPP items if you want the deployment to create them automatically:

• C:\Administration\Scripts
• C:\Administration\Logs\DNSServer

The provided backup also assumes Convert-DNSDebugLogFile is already available on the DCs. The conversion task starts Windows PowerShell 5.1 with -NoProfile and does not import the module explicitly, so the module must be installed in a machine-wide Windows PowerShell module path that is visible to LocalSystem. Recommended approaches:

• Install DNSServer.DebugLogParser on the DCs. For example, from PowerShell Gallery (if policy allows).
• Deploy the module via internal repo / file share so it is discoverable in $env:PSModulePath
• Add an explicit Import-Module to the task action if you want deterministic loading behavior

2) Deploy the debug logging configuration script (GPP Files)

The GPO deploys the script:

• Source (in SYSVOL via GPP): %GptPath%\Preferences\Files\Set-DNSServerDebugLogging.ps1
• Target (on each DC): C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1

This is implemented in the GPP Files preference item in Files.xml.

3) Scheduled task: configure DNS debug logging

The GPO creates a scheduled task named Set-DNSServerDebugLogging.

• Security context in the supplied backup: SYSTEM with logon type S4U
• Trigger in the supplied backup: daily (start boundary 2025-03-01T00:00:01)
• Action in ScheduledTasks.xml:
  • powershell.exe -ExecutionPolicy RemoteSigned -command " & { C:\Administration\Scripts\Set-DNSServerDebugLogging.ps1 }"
  • Working directory: C:\Administration\Scripts

The linked Set-DNSServerDebugLogging.ps1 script configures DNS debug logging via Get-DnsServerDiagnostics / Set-DnsServerDiagnostics and (notably):

• Enables logging to file + rollover
• Writes to: C:\Administration\Logs\DNSServer\DnsDebugLog_<COMPUTERNAME>.<Domain>_.log
• Uses a 10 MB rollover size per file
• Captures primarily query-related activity (queries + notifications + updates + question transactions) and excludes full packet logging

4) Scheduled task: convert rotated debug logs to compressed CSV

The GPO creates a scheduled task named Convert-DNSDebugLogs.

• Security context in the supplied backup: SYSTEM with logon type InteractiveToken
• Trigger in the supplied backup: daily (start boundary 2026-01-01T00:30:00)
• Working directory: C:\Administration\Logs\DNSServer
• Action in ScheduledTasks.xml (formatted for readability):

Get-ChildItem .\*.log |
  Sort-Object lastwritetime, Name -Descending |
  Select-Object -Skip 1 |
  Convert-DNSDebugLogFile `
    -ComputerName $env:COMPUTERNAME `
    -Delimiter ';' `
    -OutputType Both `
    -ContextFilter Packet `
    -OutputCulture sv-SE `
    -CompressOutput

Design notes:

• Select-Object -Skip 1 intentionally avoids processing the newest (active) log file.
• That means current data is exported only after rollover; on low-volume DCs, the active log may stay unprocessed for more than a day.
• Because Convert-DNSDebugLogFile defaults -OutputFile to “same folder, same name, .csv”, outputs land next to the *.log inputs.
• With -CompressOutput, each processed log produces a *.zip and the intermediate CSVs are removed.
• Unless you archive or delete processed *.log files, later runs will reprocess every non-active log again.
• The task throws if $Error.Count -gt 0 to signal a failed run.

5) Central ingestion

Options (pick one):

• File share ingestion: DC writes (or copies) C:\Administration\Logs\DNSServer\*.zip to \\fileserver\share\dns\$env:COMPUTERNAME\... (grant share and NTFS rights to the DC computer accounts or the Domain Controllers group if the task runs as SYSTEM)
• Pull model: central job reads \\dc\C$\Administration\Logs\DNSServer\*.zip (least preferred; requires admin shares)
• Agent forwarder: SIEM / log pipeline that ships the *.zip outputs

Operational considerations

• Least privilege: tasks run as SYSTEM; ensure the local folders are writable and that any UNC targets grant access to the computer account if used.
• Signing policy: both tasks use -ExecutionPolicy RemoteSigned; sign or unblock the deployed script and module according to your policy.
• Disk usage: -CompressOutput helps significantly, but this workflow does not remove source logs; plan retention and cleanup.
• Re-processing behavior: unless you archive or delete processed logs, the conversion task will process every non-active *.log file again on later runs. This is simple and robust, but it can overwrite outputs and create duplicate downstream ingestion if your collector does not deduplicate.
• Multi-DC consolidation: -ComputerName $env:COMPUTERNAME is included so consolidated datasets remain traceable.
• Validation: header validation remains enabled because the task does not use -SkipHeaderValidation (recommended).

Validate and adapt (using the ZIP)

Use the ZIP archive as the reference implementation, then align the following aspects to your environment:

• Target scope: which DCs / OUs receive the policy
• Execution identity: confirm both scheduled tasks use the intended logon type (S4U vs InteractiveToken) or normalize them to your standard
• Folder creation: decide whether C:\Administration\Scripts and C:\Administration\Logs\DNSServer are pre-staged elsewhere or should be created by additional GPP items
• Paths: confirm C:\Administration\Scripts and C:\Administration\Logs\DNSServer match your standards
• Retention: decide whether to keep raw logs and for how long (especially if enabling cleanup options)
• Ingestion: confirm where CSV/ZIP outputs are written and how they are collected centrally

If you want to validate the exact GPO configuration without importing it, the authoritative sources in this repo are:

• manifest.xml for backup metadata
• gpreport.xml for the human-readable full report
• Files.xml for file deployment
• Set-DNSServerDebugLogging.ps1 for script content
• ScheduledTasks.xml for scheduled tasks