Monitoring Active Directory with the PowerShell module PSADHealth

• Author
• Recent Posts

Mike Kanakos

Mike Kanakos is a Cloud and Datacenter Microsoft MVP, tech blogger and PowerShell community leader. He writes about infrastructure management and cloud automation. You can follow Mike on his blog https://www.commandline.ninja or on Twitter at @MikeKanakos.

Latest posts by Mike Kanakos (see all)

• Export and import to and from Excel with the PowerShell module ImportExcel - Thu, Apr 21 2022
• Getting started with the PSReadLine module for PowerShell - Thu, Feb 24 2022
• SecretsManagement module for PowerShell: Save passwords in PowerShell - Tue, Dec 22 2020

The toolkit is a collection of scripts and tools that check the internal pieces of Active Directory so you don't have to. It is not a replacement for tools already in place such as DCDiag. Instead, this toolkit comprises tools that my co-writers and I have found nowhere else. The goal of this module is to enable you to know when the core pieces of Active Directory aren't working as expected so you can take action.

What does this module do?

This module is a collaboration between myself, Greg Onstot, and Stephen Valdinger. Greg and I are Active Directory admins and we set out to fill the gap that existed in our current set of tools. We both had access to the big-name tools that others probably use every day, tools such as SolarWinds and Splunk. However, even with all the tools we had access to, it still felt like there were pieces of Active Directory that we had no insight into.

• We never knew in real time if replication was working as expected.
• We could never state with confidence whether there were missing DNS SRV records.
• We could never verify whether time was synced correctly with the outside world.
• We couldn't recall the last time anyone even looked at time-sync.

These were just a few of the ideas we thought we could solve by writing some code and building tools to fill the gaps. We built 11 tools that we believe provide insight into Active Directory in ways that most other tools don't or can't. Stevie built the Azure DevOps pipeline automation, improved our code, and built the structure and coding for the module itself.

Tools included in module

We designed the toolkit to be a standalone set of scripts to monitor core AD functions. The tools check and alert on the following areas of Active Directory:

• Active Directory database backup status
• Domain Controller disk space check
• Service status of core Active Directory services
• Are all DCs online and reachable?
• Are the external DNS servers for each DNS reachable?
• Are all core DNS records (SRV records) in place?
• Is time syncing with an external source?
• Are internal clocks on DCs starting to drift?
• Are there any replication failures?
• Can objects replicate through the domain?
• Are sysvols in sync?

How does the PSADHealth module work?

The tools included in this module require very little effort to make them work. You can download the module from your PowerShell command prompt.

Find-Module PSADHealth
  
Version    Name                                Repository           Description
-------    ----                                ----------           -----------
0.0.7      PSADHealth                          PSGallery            A module for testing and monitoring the core functions of Active Directory
.
  
Install-Module PSADHealth

The module works by running scheduled jobs that produce alerts when one of our tests detects a problem. You can find full instructions on the module and its required configuration at the GitHub Wiki.

The first thing to do after installation is configure the included JSON file. The JSON file is a collection of settings for the tests that will run in your environment. You set values for disk space thresholds and max days between backups, assign an email address to receive alerts, etc. The included sample JSON is below:

Get-ADConfig
 
{
  "SMTPServer": "smtp.foobar.com",
  "MailFrom": "ad_status_alert@foobar.com",
  "MailTo": [
    "ceo@foobar.com",
    "supreme_it_leader@foobar.com"
  ],
  "MaxDaysSinceBackup": "1",
  "MaxIntTimeDrift": "45",
  "MaxExtTimeDrift": "15",
  "ExternalTimeSvr": "time.google.com",
  "ExternalDNSServers": [
    "208.67.222.222",
    "208.67.220.220"
  ],
  "FreeDiskThreshold": "70",
  "MaxObjectReplCycles": "50",
  "MaxSysvolReplCycles": "50",
  "SupportArticle": "https://help.foobar.com/YourTroubleshootingArticles",
  "SlackToken": "2343-woeij2-jwoeij223-b2334322"

The scheduled jobs read the JSON and compare the values in the JSON to the values returned from the tests. If the values are above or below the thresholds, the jobs send alerts. The wiki explains each script and makes some recommendations for default values. We're still adding different alerts options such as Toast notifications.

After you set up your JSON file with the values you want, you then set up scheduled jobs on a central server to perform regular tests of your environment. We have included a script you can run to create the scheduled jobs automatically if you are not familiar with scheduled jobs. The scheduled jobs will look similar to this.

PSADHealth Scheduled Jobs

The initial installation and setup of the module takes less than 15 minutes. Once you create the scheduled jobs and set the thresholds, you're done! Here's a sample alert from a failed AD backup in my lab.

PSADHeath failed AD backup alert

What makes these tools unique?

I started off by saying we designed tests that we didn't see anyone else doing. Our sysvol and AD objection replication tests are unique and not found anywhere else. Our toolkit can test object and sysvol replication between every DC in your domain and track the progress along the way. The object replication test creates a disabled computer object and replicates the object to different DCs. The tool tracks and logs the progress as it gets to each DC.

PSADHealth AD object replication test on DC1

PSADHealth AD object replication test on DC2

PSADHealth AD object replication end of test

The event log contains every action the module performs, and alerts are sent if the computer object doesn't make it to a particular DC. It deletes the replicated test object at the end of a replication test cycle if it's successful. If not, we log and alert. In this example, the previous job did not complete and left an object behind.

PSADHealth AD object replication test warning

PSADHealth AD object replication test log entries

The same exists for our sysvol replication test.

PSADHealth AD sysvol replication test DC1

PSADHealth AD sysvol replication test DC3

PSADHealth AD Sysvol Replication test summary

PSADHealth AD Sysvol Replication test summary

Another unique test our toolkit performs is a check of the critical Active Directory services on each DC. Most tools perform a ping test. We go further and query each service necessary to run Active Directory and make sure we can interact with those services. That test runs on a regular cadence that you select in the JSON file; it runs locally on the DC in your environment.

The toolkit also verifies that each DC can reach its external DNS servers. The scheduled job uses PowerShell remoting to connect to each server and attempts a connection from the DC to the configured DNS servers on each DC.

Summary

We built this toolkit to help you have a better understanding of how well Active Directory is performing. It automates tests that need to run regularly and performs checks that other tools have ignored. Running this toolkit is a simple operation that requires very few resources. Once you set up the tool, it runs day in and day out in the background and you only hear from the tool when you need to take action.

This toolkit is an open-source project that my co-authors and I have built based on our knowledge and experiences; however, we're not done. Anyone can commit code to the project via GitHub. I invite you to download the tool, see how it works for you and provide feedback so we can continue to make tools better for everyone.

I'd like to finish by thanking my writing partners, Greg and Steve. Their knowledge and skills took this project farther than I could have on my own. Thank you, gentlemen! I appreciate your efforts.