Subnet Monitoring Events
To access subnet monitoring events:
On the Admin page, select Configuration in the upper-left corner.
Select Event Hooks in the filtering sidebar.
Enabling Subnet Monitoring
Subnet monitoring is enabled in the System Settings. Click the Settings button in the upper-right corner to go to the System Settings where you can enable subnet monitoring in the system and configure email notifications.
When enabled, the system monitors the free addresses in DHCP address pools and subnets and acts if the number of free addresses goes below a user-definable threshold.
When subnet monitoring is enabled, a new column, Monitoring, is added when viewing the subnet list. To filter the view by this column and quickly see all subnets that are monitored, you can enter “Monitor: Yes” in the Quick Filter search box.
SMTP Server
The mail server from which notification emails will be sent when the number of addresses goes below a certain threshold.
Mail from
The email address from which notification emails will be sent when the number of addresses goes below a certain threshold.
Subnet Monitoring Defaults
The Subnet monitoring events section lists the current defaults. To change the default values, click Set Defaults and make the desired changes in the dialog box.
- Enabled
When selected, all subnets are monitored by default. If you only want to monitor a subset of the subnets in the system, clear the checkbox and enable monitoring for the individual subnets instead by selecting the subnet on the IPAM page, and then selecting Set subnet monitoring on the Action menu.
- Script to invoke
Select the script to run when the number of free addresses goes below the set threshold.
- Email address
The email address that should be the recipient of notification when the number of free addresses goes below the set threshold.
- Dynamic threshold
Enter the threshold for the free addresses in a DHCP scope address pool.
Note
For split scopes and scopes in a superscope (on MS DHCP servers) and address pools using the shared-network feature on ISC DHCP servers, the total number of free addresses in all of the scope instances is used when calculating the number of free addresses.
- Static threshold
Enter the threshold for the free addresses in a subnet.
- Only perform action once (until resolved)
When selected, the action is performed only once when the number of free addresses goes below the threshold.
- Perform action when resolved
When selected, the action is performed when the number of free addresses is no longer below the threshold.
Note
The global subnet monitoring setting can be overridden for individual subnets by changing the setting explicitly for the subnet. For information on how to change monitoring settings for individual subnets, see IPAM, Set Subnet Monitoring.
Subnet Monitoring Script Interface
The XML schema for a subnet monitoring script is as follows:
<?xml version="1.0" encoding="ISO-8859-1"?>
<xs:schema targetNamespace="http://tempuri.org/XMLSchema.xsd" elementFormDefault="qualified" xmlns="http://tempuri.org/XMLSchema.xsd" xmlns:mstns="http://tempuri.org/XMLSchema.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="scopeMonitor">
<xs:complexType>
<xs:sequence>
<xs:element name="scope" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="server" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="superscope" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="threshold" type="xs:integer" minOccurs="1" maxOccurs="1" />
<xs:element name="available" type="xs:integer" minOccurs="1" maxOccurs="1" />
<xs:element name="fixed" type="xs:boolean" minOccurs="1" maxOccurs="1" />
<xs:element name="thresholdType" type="xs:string" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
The value of the thresholdType element will be either static or dynamic depending on whether the threshold being crossed is one of the dynamically allocatable addresses (that is, available addresses in address pools) or if it is a threshold set for static addresses (that is, available addresses outside of address pools).
Note
The global subnet monitor, set through the System Settings, is the only one that takes superscopes into account. When the global subnet monitor actions are performed, due to the conditions being met for a superscope, the XML generated will contain a <server> tag and a <superscope> tag.
An example XML structure for a subnet monitoring script might look as follows for scope:
<?xml version="1.0" encoding="ISO-8859-1"?>
<scopeMonitor>
<scope>123.45.67.0/24</scope>
<threshold>20</threshold>
<available>8</available>
<fixed>0</fixed>
<thresholdType>dynamic</thresholdType>
<customFields>
<customField customFieldID="1" customFieldName="Title" objectID="526" objectType="6" value="Your subnet title"></customField>
<customField customFieldID="2" customFieldName="Description" objectID="526" objectType="6" value="You subnet description"></customField>
<customFields>
</scopeMonitor>
The XML structure is slightly different if a superscope (MS DHCP) or a shared-network (ISC DHCP) configuration is used. An example XML structure for a scope monitoring script might look as follows for a superscope / shared-network configuration:
<?xml version="1.0" encoding="ISO-8859-1"?>
<scopeMonitor>
<server>dhcp1.corp.net.</server>
<superscope>office</superscope>
<threshold>20</threshold>
<available>22</available>
<fixed>1</fixed>
<thresholdType>dynamic</thresholdType>
</scopeMonitor>
A subnet monitoring script does not have any return value.
Example PowerShell Script
Note
Powershell scripts (.ps1
extension) are run natively by Men&Mice on Windows with powershell
. The script can then read the stdin with [Console]::In.ReadToEnd()
.
Instructions
Copy the
ScopeMonScript.ps1
toC:\\ProgramData\\Men and Mice\\Central\scripts
(the scripts folder).In Admin > Configuration > Event Hooks, under Subnet monitoring events, click Set Defaults.
Select
ScopeMonScript.ps1
in the Script to invoke field.Configure a dynamic threshold.
The monitor will be executed every 10 minutes during the DHCP synchronization interval.
param([Parameter(Mandatory=$false,ValueFromPipeLine=$false)]$UserName = "",
[Parameter(Mandatory=$false,ValueFromPipeLine=$false)]$Password = "",
[Parameter(Mandatory=$false,ValueFromPipeLine=$false)]$xmlFileName = "")
$strInput = get-content $xmlFileName
#$strInput = $args
# write output for troubleshooting in file:
#Add-Content -Path .\monitoroutput.xml $strInput
$strXML = [string]::Join(" ", $strInput)
$objXML = [xml]$strXML
$subnetMonitor = (Select-Xml -XML $objXML -XPath "/subnetMonitor").Node
# Check if it's an alert or fixed message
# The script only cares about alerts
if ($subnetMonitor.fixed -eq "0")
{
$strAlert = "Alert: The following scope or subnet has fewer IPs available than the configured threshold."
# We could send here an email or generate a trap or...
#Send-MailMessage -SmtpServer "smpt.example.com" -From "subnetmonitor@example.com" -To "alert1@example.com;alert2@example.net" -Subject "Subnet Monitor Message" -Body $strOutput
# First handle the superscopes
if ($subnetMonitor.superscope -ne $null -and $subnetMonitor.superscope -ne "")
{
$strOutput = @"
$strAlert
Superscope: $($subnetMonitor.superscope)
Alert Date: $(Get-Date -Format G)
Server: $($subnetMonitor.server)
Threshold: $($subnetMonitor.threshold)
IPs Available: $($subnetMonitor.available)
Subnet Type: $($subnetMonitor.thresholdType)
"@
New-EventLog -Source SubnetMonitor -LogName Application
Write-EventLog -LogName Application -Source SubnetMonitor -EventID 1063 -EntryType Warning -message "$strOutput"
#Add-Content -Path .\superscopemonitor_msg.txt $strOutput
}
else
{
# then in the else clause the normal scopes
$strOutput = @"
$strAlert
Alert Date: $(Get-Date -Format G)
Scope: $($subnetMonitor.subnet)
Threshold: $($subnetMonitor.threshold)
IPs Available: $($subnetMonitor.available)
Subnet Type: $($subnetMonitor.thresholdType)
"@
New-EventLog -Source SubnetMonitor -LogName Application
Write-EventLog -LogName Application -Source SubnetMonitor -EventID 1064 -EntryType Warning -message "$strOutput"
#Add-Content -Path .\scopemonitor_msg.txt $strOutput
}
}
else
{
# possible issue fixed message
}
Example Python Script
The following example script, written in Python, shows how a script could return different values depending on the input of custom fields. The script is called when an object property changes and it queries for country and city using a location code. The intended use here is to mark the locations of servers.
import sys
import xml.etree.ElementTree as ET
def get_custom_field_element(custom_fields, name):
element = custom_fields.find(f"./customField[@customFieldName='{name}']")
if element is None:
raise KeyError(f"Custom property '{name}' was not found.")
return element
def get_result(root):
# username variable is not used but this is how to get the username
username = root.get('userName')
custom_fields = root.find("./customFields")
result = ET.Element("result", {"success": "0"})
try:
location_element = get_custom_field_element(custom_fields, 'Location')
country_element = get_custom_field_element(custom_fields, 'Country')
city_element = get_custom_field_element(custom_fields, 'City')
except KeyError as e:
ET.SubElement(result, "error", {"code": "1", "message": str(e)})
return result
location = location_element.get('value')
# A database could be queried instead here
LOCATION_MAP = {
'l1': ('USA', 'Washington'),
'l2': ('UK', 'London')
}
if location not in LOCATION_MAP:
ET.SubElement(result, "error", {"code": "1", "message": "Unknown location."})
return result
result.set("success", "1")
country, city = LOCATION_MAP[location]
country_element.set('value', country)
city_element.set('value', city)
result.append(custom_fields)
return result
# Read all input and parse as XML
root = ET.fromstring(sys.stdin.read())
result = get_result(root)
print('<?xml version="1.0"?>')
# This will write the generated result xml to standard output
ET.dump(result)