Domain Alerts
Administrator access required
This is a custom tool available in addition to the standard Watch My Domains SED interface.
To access custom tools, look for the custom tools icon in the main toolbar.
Domain Alerts is available in Watch My Domains SED 6.1.61 and later.
Domain Alerts watches the domains in the categories you choose and tells you when configured alert conditions are triggered. You pick which categories to watch, which columns matter to you, and how often to check. When an alert condition is triggered, the tool records the event in the WMD SED audit log and can email a combined digest to the people who need to know.
What Domain Alerts Does
Every domain in WMD SED has many fields, such as expiry dates, registrar, name servers, and status codes. Most of the time these stay the same. When one of them changes, it often matters, for example an expiry date moving, a status code appearing, or a name server being altered. Domain Alerts exists to catch those changes for the domains you care about most, without you having to watch the table yourself.
Domain Alerts performs no lookups of its own. It never contacts WHOIS, RDAP, DNS, or any registrar. It reads the data that WMD SED has already collected through its normal lookup process, takes a snapshot of the columns you are watching, and compares each new snapshot with the previous one. This means an alert is only as fresh as the underlying data that WMD SED itself maintains.
Because it compares snapshots rather than looking anything up, the tool is fast, puts no extra load on registrars, and works entirely from information already in your installation.
Using Domain Alerts
Who can use this tool, and how are alerts delivered? Domain Alerts is an administrator tool. Triggered alerts are written to the WMD SED audit log, where they become part of the standard audit history, and are also combined into an email digest sent to the recipients you configure. There is one alert configuration per installation.
The tool opens as a single configuration page with a category drawer on the left and the settings and domain views on the right.
Selecting Categories
The drawer on the left lists every category in your installation. Tick the categories whose domains you want to watch. The counters at the bottom of the drawer show how many categories are selected and how many domains currently match. Use All or None to select or clear every category at once.
All the domains that belong to the selected categories form the watched set. If a domain is added to one of those categories later, it is picked up automatically on the next run.
Choosing Alert Columns
Under Alert on Columns, use + Add an Alert Column to choose which domain columns should trigger an alert. You can watch built-in columns and any custom columns you have created. For each column you add, you can leave the condition blank or enter a condition that decides when the change counts as an alert.
| Condition | When an alert is raised |
|---|---|
| (blank) | Whenever the column's value changes in any way. This is value-change mode. |
available | When the value comes to contain the text available. The alert fires on the transition into that state, not on every run. |
expired|pendingdelete | When the value comes to contain expired or pendingdelete. Separate alternatives with a vertical bar. |
~clienthold | The ~ prefix means "must be absent". This raises an alert when clienthold is no longer present in the value. |
available|~clienthold | Terms can be combined. Plain terms are matched as alternatives, and any ~ term is a condition that must be absent. |
Conditions are matched as simple text, are not case-sensitive, and are evaluated on the transition from not-matching to matching, so a condition that stays true across runs does not re-alert every time.
Schedule and Recipients
Under Schedule, choose how often Domain Alerts should compare the watched domains:
| Option | Meaning |
|---|---|
| Hourly | Compare every hour |
| Every 2 hours | Compare every two hours |
| Every 6 hours | Compare every six hours |
| Daily | Compare once a day |
| Weekly | Compare once a week |
| Monthly | Compare once a month |
Enter one or more email addresses for the digest, separated by semicolons. The test-send button beside the field emails each recipient a sample message so you can confirm delivery works before relying on it. Each recipient is emailed separately, so recipients do not see one another's addresses.
Because the tool performs no lookups, the schedule controls how often it checks for changes, not how fresh the data is. Choosing a schedule more frequent than WMD SED's own lookup cycle simply means most runs will find no change.
The Domain Table
The domain panel lists the domains in the selected categories. Click a domain in the table to load its Saved Snapshot in the panel below, showing the stored value of each watched column, that is, the baseline the next comparison will be measured against.
Saved Snapshots
A snapshot is the stored baseline for a domain. The first time a domain is seen, its current values are saved as the baseline and no alert is raised. On later runs, the live value is compared with the saved baseline. A blank condition raises an alert whenever the value changes. A configured condition raises an alert only when it changes from not matching to matching. The baseline is then updated to the latest value.
Use Capture Missing Snapshots to create baselines for watched domains that do not have one yet. This is safe to use at any time; it only fills in missing baselines and never raises alerts on its own. It uses the last saved categories and alert columns, not unsaved changes currently shown on the page.
Saving
Click Save Settings to store the configuration. Settings are validated before saving, and any problems, such as an invalid email address or an unknown column, are shown next to the relevant field. After the settings are saved, Domain Alerts automatically creates any missing baselines for the saved categories and alert columns. Existing snapshots are not overwritten during this baseline capture.
How Alerting Works
Processing runs from a single scheduled task, typically once an hour. On each run the tool decides, from your saved schedule and when it last ran, whether a comparison is due. If it is not yet due, the run only creates any missing baselines and exits. If it is due, the tool compares every watched column against its saved snapshot.
A trigger occurs when a blank-condition value changes, or when a configured condition changes from not matching to matching. For each run containing one or more triggers, the tool:
- Combines the triggered alerts into one email digest and sends it separately to each configured recipient.
- After any required email delivery succeeds, records each trigger in the WMD SED audit log as part of the standard audit history.
- Updates the stored snapshots to the latest values so the same state is not reported again.
Newly added domains are given a baseline silently and do not raise an alert the first time they are seen. If a required notification email cannot be delivered, the audit and snapshot update stage is not completed, so the alert can be retried on the next run rather than being silently lost.
Processing Limit
A single alert configuration processes up to 1,000 domains. If the selected categories contain more than that, the tool watches a stable set of the first 1,000, keeping the same domains across runs rather than switching between them. It records the truncation transition in the audit log and includes it in the email digest when recipients are configured. The notification is produced when the limit is first reached, when the configuration or limit changes while still truncated, or when truncation returns after previously clearing; it is not repeated on every run.
Administrator and Setup Guide
The sections below cover installation, storage, configuration, and technical reference for administrators setting up or maintaining Domain Alerts.
Main Files in the Domain Alerts Tool
alerts.php- browser-based configuration pagealerts/run.php- command-line processing script run on a schedulealerts/install.php- command-line installer that creates and verifies the snapshot tablealerts/alerts-setup.sh- setup helper script for Linux environmentsalerts/lib/php/AlertsProcessor.php- shared processing engine used by the page and the scripts
Requirements
- WMD SED already installed, with shell access for the setup and processing scripts
- WMD administrator access for the browser configuration page
- A working outgoing email configuration in WMD SED if email digests are wanted
- The ability to run an hourly scheduled task: cron on Linux or Task Scheduler on Windows
Setup
Linux / Debian / Ubuntu
Run the setup helper as the wmdsed user from the tool folder:
bash alerts-setup.sh
For standard installations, no editing is normally required. To preview every action without changing the database, log directory, or crontab:
bash alerts-setup.sh --dry-run
The script verifies the environment, creates the snapshot table by running the installer, prepares the log directory, and adds one hourly cron entry that runs the processor. It manages only its own marked cron entry and leaves all other crontab lines untouched. It accepts install (the default), status, remove, and print, along with --php, --log, and --minute to override the PHP binary, log path, and the minute of the hour the entry runs.
Windows
The alerts-setup.sh helper is Linux-only. On Windows, complete the manual setup steps below, then schedule alerts/run.php to run once an hour with Windows Task Scheduler. See learn.domainpunch.com/wmdsed/install/wintask/ for the general Windows scheduled-task pattern used by WMD SED.
Manual Setup
Step 1 - Create the snapshot table
php alerts/install.php
This creates the single table Domain Alerts owns and verifies that the columns it needs to read are present. It is safe to run more than once; an existing, valid table is left unchanged. To verify without making any changes, use php alerts/install.php --check.
Step 2 - Configure the alert in the browser
Open the configuration page as a WMD administrator, select the categories to watch, add the alert columns and conditions, choose a schedule, enter the digest recipients, and save.
Optional - Verify or capture baselines
Saving the configuration automatically creates missing baselines for up to the 1,000-domain processing limit. You can later use Capture Missing Snapshots on the page, or run the processor once, to repeat the missing-baseline check. Existing snapshots are not overwritten and no alert is raised merely because a baseline is new.
php alerts/run.php
What Gets Stored
Domain Alerts stores as little as possible and owns only one database table.
| Data | Where it is stored |
|---|---|
| Alert configuration | WMD SED settings, under the key monitor_tool |
| Processing state, such as when it last ran | WMD SED settings, under the key monitor_tool_runtime |
| Snapshots, that is, the stored baselines | A dedicated table, mon_snapshots |
| Alerts, that is, detected changes | The WMD SED audit log, plus the email digest. No separate alert table is kept. |
The mon_snapshots table is the only table the tool creates. Alerts are not stored separately because the standard WMD SED audit log already provides the alert history.
CLI Reference - run.php
run.php is the processing script and is intended to be run on a schedule. On each run it creates any missing baselines, then performs a comparison only if the saved schedule is due.
| Argument | Type | Description |
|---|---|---|
--force | bare flag | Perform a comparison immediately, ignoring the saved schedule. Useful for testing. |
The script prints a JSON summary of the run, including how many alerts were raised, how many audit entries were written, how many emails were sent, and the next scheduled run time. It exits without processing if another run is already in progress.
Scheduling and the Saved Schedule
The scheduled task should run run.php once an hour. The chosen schedule, such as Daily or Weekly, is applied inside the tool: the hourly task fires every hour, but a comparison is only performed when the saved schedule says it is due. This means you never need to change the scheduled task when you change the schedule in the browser.
Concurrency Lock
Processing acquires a lock so that two runs cannot overlap. If a run starts while another is still in progress, the second run exits immediately without processing. The same lock covers baseline capture from the browser, so those cannot overlap with a scheduled run either.
CLI Reference - install.php
| Argument | Description |
|---|---|
--check | Verify dependencies and the snapshot table without creating anything. |
--json | Emit one machine-readable JSON result instead of human-readable output. |
--log-path | Print WMD SED's configured log folder and exit. |
--help | Show usage. |
Scheduled Processing
The lock prevents re-entry if a previous run is still in progress, so overlapping scheduled runs are not a concern on either Linux or Windows.
Linux / Debian / Ubuntu
The alerts-setup.sh script adds the cron entry automatically. To add or edit it manually:
crontab -e
Add a line in this form, running once an hour:
7 * * * * php /path/to/tools/alerts/run.php >> /path/to/alerts-cron.log 2>&1
Windows
Use Windows Task Scheduler to run the processor once an hour. Configure the task to start the PHP executable and pass the full path to alerts\run.php as its argument. Set the task's working directory to the WMD SED tools folder when your installation requires it.
Program/script: C:\path\to\php.exe Arguments: C:\path\to\wmdsed\tools\alerts\run.php Schedule: Hourly
The selected Hourly, Daily, Weekly, or Monthly schedule is still enforced inside Domain Alerts, so the Task Scheduler entry itself should always run once an hour.
See learn.domainpunch.com/wmdsed/install/wintask/ for the general WMD SED Task Scheduler pattern.
Browser Page - alerts.php
Access this as an authenticated WMD administrator through the Custom Built-in Tools page, or directly at https://yourserver/tools/alerts.php.
Features
- Category drawer for choosing which categories to watch, with select-all and select-none
- Alert columns with optional conditions, including value-change, alternatives with
|, and must-be-absent with~ - Schedule selector from hourly to monthly
- Digest recipients with a test-send button
- Domain table for the selected categories
- Saved-snapshot view per domain, with a control to capture any missing baselines
- Validation of settings before saving
- Session expiry handling with a clear prompt to log in again if the WMD session ends
If the snapshot table has not been created yet, run the installer before using the page for processing.
Security Notes
alerts.phprequires a valid WMD administrator session, and every action it performs is checked on the server before any data is accessed.run.phpandinstall.phpare command-line only and exit immediately if accessed through a browser.- The tool reads domain data directly and therefore operates with full access to that data. For this reason it is restricted to administrators.
- Domain Alerts performs no external lookups of any kind. It only reads data already held in WMD SED.
- The only table created by Domain Alerts is
mon_snapshots. The tool does not alter WMD SED domain or category data. It stores configuration and runtime state through WMD SED's settings system and writes triggered alerts through the standard audit log.
