Key takeaways
- Critical role of AD health: Active Directory’s health is vital for network stability and security.
- Comprehensive script functionality: The script offers a full suite of checks for AD replication health, including pre-checks, parameter handling, and detailed result analysis.
- Customizable parameters: Allows for environment-specific adjustments with parameters like ErrorCount and EventLogStart.
- Proactive problem identification: Aids in early detection of replication issues, preventing potential large-scale problems.
- Event log insights: Analyses event logs for specific replication-related events, providing deeper diagnostic information.
- SYSVOL verification: Checks the presence of the critical SYSVOL share, ensuring fundamental AD functionality.
- Exportable results: Offers options to export health reports in CSV or TXT formats, aiding in documentation and compliance.
- Automated and regular monitoring recommended: Regular, automated execution of the script is advised for continuous health assessment.
- Administrative privileges required: Needs to be run with administrative rights on a Domain Controller for full functionality.
- Enhancement with IT management tools: Can be effectively complemented by tools like NinjaOne for a more integrated IT management approach.
Introduction
Active Directory (AD) forms the backbone of identity and access management in most corporate IT environments. Ensuring its health and operational efficiency is not just a routine task; it’s a critical responsibility. This importance becomes even more apparent considering the complexity of modern networked environments and the dire consequences of any potential failure or breach.
Background
The PowerShell script in question is designed to monitor and report on the health of AD replication processes. For IT professionals and Managed Service Providers (MSPs), ensuring smooth AD replication is essential. Replication issues can lead to authentication problems, inconsistent data, and eventually, system-wide failures. This script stands as a crucial tool for preemptively identifying and addressing such issues.
The script:
#Requires -Version 5.1
<#
.SYNOPSIS
This will get the current status of AD Replication and alert if it's abnormal, as well as provide some diagnostic info.
.DESCRIPTION
This will get the current status of AD Replication and alert if it's abnormal, as well as provide some diagnostic info.
.EXAMPLE
(No Parameters)
WARNING: Replication has failed 100 or more times. See Diagnostic Info for more details
### Diagnostic Info ###
Repadmin: running command /showrepl against full DC localhost
Default-First-Site-Name\SRV19-TEST
DSA Options: IS_GC
Site Options: (none)
DSA object GUID: ffe29454-2a68-4ba8-a877-d5a49b382d16
DSA invocationID: ffe29454-2a68-4ba8-a877-d5a49b382d16
PARAMETER: -ErrorCount "99999999999999"
The number of errors until AD Replication is considered unhealthy.
.EXAMPLE
-ErrorCount "99999999999999"
AD Replication appears to be healthy. Please check below to confirm.
Destination DSA Last Success Time Failures Naming Context
--------------- ----------------- -------- --------------
SRV19-TEST 2023-04-17 17:12:45 179 DC=test,DC=lan
SRV19-TEST 2023-04-17 16:51:45 21 CN=Configuration,DC=test,DC=lan
SRV19-TEST 2023-04-17 16:51:45 21 CN=Schema,CN=Configuration,DC=test,DC=lan
SRV19-TEST 2023-04-17 17:06:18 22 DC=DomainDnsZones,DC=test,DC=lan
SRV19-TEST 2023-04-17 17:06:15 22 DC=ForestDnsZones,DC=test,DC=lan
PARAMETER: -EventLogStart "48"
Time in hours to search through event logs for possible issues.
.EXAMPLE
-EventLogStart "48"
DsBindWithCred to localhost failed with status 5
WARNING: Directory Service Log Event ID 1864 shows failure to replicate in > 1 week
TimeCreated Id LogName Level Message
----------- -- ------- ----- -------
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
PARAMETER: -ErrorCustomField "ReplaceMeWithAnyIntegerCustomField"
Name of an integer custom field that contains your desired ErrorCount threshold.
ex. "AllowedADerrors" where you have entered in your desired ErrorCount limit in the "AllowedADerrors" custom field rather than in a parameter.
PARAMETER: -EventLogCustomField "ReplaceMeWithAnyIntegerCustomField"
Name of an integer custom field that contains your desired EventLogStart threshold.
ex. "ADeventsAgeLimit" where you have entered in your desired EventLogStart limit in the "ADeventsAgeLimit" custom field rather than in a parameter.
.EXAMPLE
-ErrorCustomField "ReplaceMeWithAnyIntegerCustomField" -EventLogCustomField "ReplaceMeWithAnyIntegerCustomField"
DsBindWithCred to localhost failed with status 5
WARNING: Directory Service Log Event ID 1864 shows failure to replicate in > 1 week
TimeCreated Id LogName Level Message
----------- -- ------- ----- -------
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
PARAMETER: -ExportCSV "ReplaceMeWithAnyMultiLineCustomField"
Name of a multi-line customfield you'd like to export the results to (in csv format).
.EXAMPLE
-ExportCSV "ReplaceMeWithAnyMultiLineCustomField"
DsBindWithCred to localhost failed with status 5
WARNING: Directory Service Log Event ID 1864 shows failure to replicate in > 1 week
TimeCreated Id LogName Level Message
----------- -- ------- ----- -------
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
PARAMETER: -ExportTXT "ReplaceMeWithAnyMultiLineCustomField"
Name of a multiline customfield you'd like to export the results to.
.EXAMPLE
-ExportTXT "ReplaceMeWithAnyMultiLineCustomField"
DsBindWithCred to localhost failed with status 5
WARNING: Directory Service Log Event ID 1864 shows failure to replicate in > 1 week
TimeCreated Id LogName Level Message
----------- -- ------- ----- -------
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
7/2/2028 8:34:33 AM 1864 Directory Service Error This is the replication status for the following directo...
.OUTPUTS
.NOTES
Minimum OS Architecture Supported: Server 2016+
Release Notes: Renamed script and added Script Variable support
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms.
Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party.
Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider.
Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations.
Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks.
Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script.
EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#>
[CmdletBinding()]
param (
[Parameter()]
[int]$EventLogStart = "24",
[Parameter()]
[int]$ErrorCount = "100",
[Parameter()]
[String]$EventLogCustomField,
[Parameter()]
[String]$ErrorCustomField,
[Parameter()]
[String]$ExportCSV,
[Parameter()]
[String]$ExportTXT
)
begin {
function Test-IsElevated {
$id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
$p = New-Object System.Security.Principal.WindowsPrincipal($id)
$p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
}
function Test-IsSystem {
$id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
return $id.Name -like "NT AUTHORITY*" -or $id.IsSystem
}
function Test-IsDomainController {
$OS = Get-CimInstance -ClassName Win32_OperatingSystem
if ($OS.ProductType -eq "2") {
return $true
}
}
if (!(Test-IsElevated) -and !(Test-IsSystem)) {
Write-Error -Message "Access Denied. Please run with Administrator privileges."
exit 1
}
if (!(Test-IsDomainController)) {
Write-Error "This is not a domain controller. Please run this script on a DC."
exit 1
}
# If script variables are used grab that and replace the static ones.
if ($env:hoursBackToSearchEventLog -and $env:hoursBackToSearchEventLog -notlike "null") { $EventLogStart = $env:hoursBackToSearchEventLog }
if ($env:errorCountToAlertOn -and $env:errorCountToAlertOn -notlike "null") { $ErrorCount = $env:errorCountToAlertOn }
if ($env:retrieveHoursBackFromCustomFieldNamed -and $env:retrieveHoursBackFromCustomFieldNamed -notlike "null") { $EventLogCustomField = $env:retrieveHoursBackFromCustomFieldNamed }
if ($env:retrieveErrorCountFromCustomFieldNamed -and $env:retrieveErrorCountFromCustomFieldNamed -notlike "null") { $ErrorCustomField = $env:retrieveErrorCountFromCustomFieldNamed }
if ($env:exportCsvResultsToThisCustomField -and $env:exportCsvResultsToThisCustomField -notlike "null") { $ExportCSV = $env:exportCsvResultsToThisCustomField }
if ($env:exportTextResultsToThisCustomField -and $env:exportTextResultsToThisCustomField -notlike "null") { $ExportTXT = $env:exportTextResultsToThisCustomField }
# This function is to make it easier to set Ninja Custom Fields.
function Set-NinjaProperty {
[CmdletBinding()]
Param(
[Parameter(Mandatory = $True)]
[String]$Name,
[Parameter()]
[String]$Type,
[Parameter(Mandatory = $True, ValueFromPipeline = $True)]
$Value,
[Parameter()]
[String]$DocumentName
)
# If we're requested to set the field value for a Ninja document we'll specify it here.
$DocumentationParams = @{}
if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }
# This is a list of valid fields we can set. If no type is given we'll assume the input doesn't have to be changed in any way.
$ValidFields = "Attachment", "Checkbox", "Date", "Date or Date Time", "Decimal", "Dropdown", "Email", "Integer", "IP Address", "MultiLine", "MultiSelect", "Phone", "Secure", "Text", "Time", "URL"
if ($Type -and $ValidFields -notcontains $Type) { Write-Warning "$Type is an invalid type! Please check here for valid types. https://ninjarmm.zendesk.com/hc/en-us/articles/16973443979789-Command-Line-Interface-CLI-Supported-Fields-and-Functionality" }
# The below field requires additional information in order to set
$NeedsOptions = "Dropdown"
if ($DocumentName) {
if ($NeedsOptions -contains $Type) {
# We'll redirect the error output to the success stream to make it easier to error out if nothing was found or something else went wrong.
$NinjaPropertyOptions = Ninja-Property-Docs-Options -AttributeName $Name @DocumentationParams 2>&1
}
}
else {
if ($NeedsOptions -contains $Type) {
$NinjaPropertyOptions = Ninja-Property-Options -Name $Name 2>&1
}
}
# If we received some sort of error it should have an exception property and we'll exit the function with that error information.
if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }
# The below type's require values not typically given in order to be set. The below code will convert whatever we're given into a format ninjarmm-cli supports.
switch ($Type) {
"Checkbox" {
# While it's highly likely we were given a value like "True" or a boolean datatype it's better to be safe than sorry.
$NinjaValue = [System.Convert]::ToBoolean($Value)
}
"Date or Date Time" {
# Ninjarmm-cli is expecting the time to be representing as a Unix Epoch string. So we'll convert what we were given into that format.
$Date = (Get-Date $Value).ToUniversalTime()
$TimeSpan = New-TimeSpan (Get-Date "1970-01-01 00:00:00") $Date
$NinjaValue = $TimeSpan.TotalSeconds
}
"Dropdown" {
# Ninjarmm-cli is expecting the guid of the option we're trying to select. So we'll match up the value we were given with a guid.
$Options = $NinjaPropertyOptions -replace '=', ',' | ConvertFrom-Csv -Header "GUID", "Name"
$Selection = $Options | Where-Object { $_.Name -eq $Value } | Select-Object -ExpandProperty GUID
if (-not $Selection) {
throw "Value is not present in dropdown"
}
$NinjaValue = $Selection
}
default {
# All the other types shouldn't require additional work on the input.
$NinjaValue = $Value
}
}
# We'll need to set the field differently depending on if its a field in a Ninja Document or not.
if ($DocumentName) {
$CustomField = Ninja-Property-Docs-Set -AttributeName $Name -AttributeValue $NinjaValue @DocumentationParams 2>&1
}
else {
$CustomField = Ninja-Property-Set -Name $Name -Value $NinjaValue 2>&1
}
if ($CustomField.Exception) {
throw $CustomField
}
}
# Shortened Version from "Example - Get Ninja Property"
function Get-NinjaProperty {
[CmdletBinding()]
Param(
[Parameter(Mandatory = $True, ValueFromPipeline = $True)]
[String]$Name,
[Parameter()]
[String]$Type,
[Parameter()]
[String]$DocumentName
)
# If we're requested to get the field value from a Ninja document we'll specify it here.
$DocumentationParams = @{}
if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }
# These two types require more information to parse.
$NeedsOptions = "DropDown", "MultiSelect"
# Grabbing document values requires a slightly different command.
if ($DocumentName) {
# Secure fields are only readable when they're a device custom field
if ($Type -Like "Secure") { throw "$Type is an invalid type! Please check here for valid types. https://ninjarmm.zendesk.com/hc/en-us/articles/16973443979789-Command-Line-Interface-CLI-Supported-Fields-and-Functionality" }
# We'll redirect the error output to the success stream to make it easier to error out if nothing was found or something else went wrong.
Write-Host "Retrieving value from Ninja Document..."
$NinjaPropertyValue = Ninja-Property-Docs-Get -AttributeName $Name @DocumentationParams 2>&1
# Certain fields require more information to parse.
if ($NeedsOptions -contains $Type) {
$NinjaPropertyOptions = Ninja-Property-Docs-Options -AttributeName $Name @DocumentationParams 2>&1
}
}
else {
# We'll redirect error output to the success stream to make it easier to error out if nothing was found or something else went wrong.
$NinjaPropertyValue = Ninja-Property-Get -Name $Name 2>&1
# Certain fields require more information to parse.
if ($NeedsOptions -contains $Type) {
$NinjaPropertyOptions = Ninja-Property-Options -Name $Name 2>&1
}
}
# If we received some sort of error it should have an exception property and we'll exit the function with that error information.
if ($NinjaPropertyValue.Exception) { throw $NinjaPropertyValue }
if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }
# This switch will compare the type given with the quoted string. If it matches, it'll parse it further; otherwise, the default option will be selected.
switch ($Type) {
"Integer" {
# Cast's the Ninja provided string into an integer.
if (-not $NinjaPropertyValue) {
throw "CustomField $Name is empty!"
}
[int]$NinjaPropertyValue
}
default {
# If no type was given or not one that matches the above types just output what we retrieved.
$NinjaPropertyValue
}
}
}
$ExitCode = 0
}process {
# Grabbing the information from custom fields (if any)
if ($ErrorCustomField) {
try {
$FieldCount = Get-NinjaProperty -Name $ErrorCustomField -Type "Integer"
if ($FieldCount) { $ErrorCount = $FieldCount }
}
catch {
Write-Error -Message $_.ToString() -Category InvalidOperation -Exception (New-Object System.Exception)
exit 1
}
}
if ($EventLogCustomField) {
try {
$FieldStart = Get-NinjaProperty -Name $EventLogCustomField -Type "Integer"
if ($FieldStart) { $EventLogStart = $FieldStart }
}
catch {
Write-Error -Message $_.ToString() -Category InvalidOperation -Exception (New-Object System.Exception)
exit 1
}
}
$represult = (repadmin.exe /showrepl /csv | ConvertFrom-Csv)
if ($ExportCSV) {
try {
Set-NinjaProperty -Name $ExportCSV -Value (repadmin.exe /showrepl /csv)
}
catch {
Write-Error -Message $_.ToString() -Category InvalidOperation -Exception (New-Object System.Exception)
$ExitCode = 1
}
}
if ($ExportTXT) {
$String = $represult | Format-Table -Property "Destination DSA", "Last Success Time", "Last Failure Status", "Number of Failures", "Naming Context" | Out-String
try {
Set-NinjaProperty -Name $ExportTXT -Value $String
}
catch {
Write-Error -Message $_.ToString() -Category InvalidOperation -Exception (New-Object System.Exception)
$ExitCode = 1
}
}
if ($represult."Number of Failures" -ge $ErrorCount) {
Write-Warning "Replication has failed $ErrorCount or more times. See Diagnostic Info for more details"
# The Table version is a bit more to the point but the description gives you more of an idea of what's going wrong than in the non-table version.
Write-Host '### Diagnostic Info ###'
repadmin.exe /showrepl /errorsonly
$represult | Format-Table -Property "Destination DSA", "Last Success Time", @{Name = "Failures"; Expression = { $_."Number of Failures" } }, "Naming Context" | Out-String | Write-Host
Exit 1
}
else {
Write-Host "No errors found in repadmin /showrepl /csv"
}
# Check Event Log for replication failure
$Date = (Get-Date).AddHours(-$EventLogStart)
$Events = Get-WinEvent -FilterHashtable @{LogName = "Directory Service"; Id = 1864; StartTime = $Date } -ErrorAction SilentlyContinue |
Where-Object { ($_.Message -replace "`r`n", " ") -match "More than a week: [1-9]+.*" }
if ($Events) {
Write-Warning "Directory Service Log Event ID 1864 shows failure to replicate in > 1 week"
$Events | Format-Table -Property TimeCreated, Id, LogName, @{Name = "Level"; Expression = { $_.LevelDisplayName } }, Message -AutoSize | Out-String | Write-Host
Exit 1
}
else {
Write-Host "No bad event viewer events found since $Date."
}
# Check if Sysvol is present
$sysvol = (Get-CimInstance Win32_Share) | Where-Object { $_.name -eq "SYSVOL" }
if (!($sysvol.Path)) {
Write-Warning "SYSVOL is Missing!"
Get-CimInstance Win32_Share | Out-String | Write-Host
Exit 1
}
else {
Write-Host "SYSVOL appears to be present."
}
Write-Host "AD Replication appears to be healthy. Please check script output and other sources to confirm."
$Report = $represult | Format-Table -Property "Destination DSA", "Last Success Time", @{Name = "Failures"; Expression = { $_."Number of Failures" } }, "Naming Context" | Out-String
if ($Report) {
$Report | Write-Host
}
exit $ExitCode
}end {
}
Access over 300+ scripts in the NinjaOne Dojo
Detailed breakdown
The script performs several key functions:
- Pre-Checks: It starts by verifying if it’s running on a Domain Controller (DC) and has administrative privileges, ensuring it’s in the correct environment to perform its tasks.
- Parameter handling: The script accepts parameters like ErrorCount and EventLogStart, allowing customization based on different environments or requirements.
- Replication status check: Using repadmin.exe, it checks the current replication status. The script alerts if the number of replication failures exceeds a defined threshold.
- Event log analysis: It reviews the Directory Service event log for specific events (like ID 1864), which can indicate replication issues over a defined period.
- SYSVOL check: The script verifies the presence of the SYSVOL share, a critical component for AD functioning.
- Result handling: Depending on the results, it either outputs a health report or warnings about potential issues. There’s also functionality to export these results to CSV or TXT files.
Potential use cases
Imagine an IT admin, Alex, working in a company with a multi-site AD environment. Alex uses this script to regularly monitor AD health across all sites. By catching a replication issue early at one site, Alex is able to prevent a major authentication crisis, ensuring uninterrupted access to network resources for all users.
Comparisons
Traditionally, AD health checks are either done manually or using basic scripts that offer limited insights. This script’s comprehensive approach, including parameters for customization and export options, sets it apart. It’s more thorough than just using the Windows Server AD tools and less complex than implementing a full-fledged monitoring solution.
FAQs
- How often should I run this script?
Regular execution, such as weekly, is recommended, though this can vary based on your organization’s size and complexity. - What privileges are required to run this script?
Administrative privileges on a Domain Controller are necessary. - Can I customize the thresholds for alerts?
Yes, the ErrorCount and EventLogStart parameters allow customization.
Implications
Inconsistent AD replication can lead to serious security and operational risks. This script aids in preemptive detection, which is vital in maintaining the integrity and security of the IT environment. Its ability to export detailed reports is crucial for audits and compliance.
Recommendations
- Regular Scheduling: Automate the script to run at regular intervals.
- Customization: Adjust parameters like ErrorCount based on your specific environment.
- Review and Act: Regularly review the outputs and take proactive measures as needed.
Final thoughts
In the realm of IT management, tools like NinjaOne can enhance the utility of scripts like this by providing a unified platform for monitoring and managing network systems, including AD environments. This script complements such tools, offering targeted insights and diagnostics crucial for maintaining the health and security of Active Directory.