domain-monitor
Self-hosted server to monitor WHOIS records for specified domains, to help alert you of unwanted/unexpected changes to your domains and to help remind you when they need renewed.
If you use domain-monitor, make sure to abide by the terms of service of the TLD WHOIS server. Most forbid high-volume queries, marketing usage, and automated queries that are more than reasonably needed to register domain names.
To help you abide by WHOIS server TOS, domain-monitor barely queries the whois databases. domain-monitor acts in this way:
- Creates a reference whois file for the domain, including time queried
- Updates a whois reference if one of the following conditions is met:
- Reference file becomes 9 months old
- It's 3 months until the domain expiry date
- It's 2 months until the domain expiry date
- It's 1 month until the domain expiry date
- It's 2 weeks until the domain expiry date
- You tell domain-monitor you expect the WHOIS data to have changed (e.g. you renewed, transfered the domain, changed name servers)
- Checks periodically using DNS if the name servers match WHOIS reference file. If they don't, this triggers an alert (and a prompt to force update the WHOIS reference).
Installation
Docker
The docker image uses two volumes, be aware if you want to manually edit the configs or view the cached whois data.
| Image Mount | Contains |
|---|---|
| /app/config | config.yaml and domain.yaml |
| /app/whois-data | cached whois data in yaml files |
| Exposed Ports | Used for |
|---|---|
| 4201/tcp | WEB GUI |
Using Github Packages
docker run -p 127.0.0.1:4201:4201 ghcr.io/nwesterhausen/domain-monitor/server
Example docker-compose:
services:
dm:
image: ghcr.io/nwesterhausen/domain-monitor/server:latest
ports:
- 127.0.0.1:4201:4201/tcp
volumes:
- ./config:/app/config:rw
- ./whois:/app/whois-data:rw
version: '3.9'Using Docker Hub
Image is just nwesterhausen/domain-monitor, latest tag will be the most recent version, or pull by tagged version.
docker run -p 127.0.0.1:4201:4201 nwesterhausen/domain-monitor
Running with node
Should by OS agnostic. Requires nodejs >= 12
Simply clone this repository, install dependencies and node server/index.js. (Eleventy runs as a postinstall script.)
git clone https://github.com/nwesterhausen/domain-monitor.git
cd domain-monitor
yarn
node ./index.js
Configuration can be done via the configuration page of the web gui (default http://localhost:4201)
Config
There are two config files which you can edit yourself if you so choose.
config.yaml
A sample is provided as sample.config.yaml and on first run if you don't have
an existing config.yaml, domain-monitor copies the sample into config.yaml and
any changes you make on the webgui persist in config.yaml.
App Settings
Port
Set the port used by the http server (and WS)
app:
port: 4201
Alerts
admin
Set what email should receive alerts from domain-monitor
sendalerts
Boolean, if false prevents all alerts from being sent.
alerts:
admin: [email protected]
sendalerts: yes
SMTP
Set smtp settings for domain-monitor to use to send email alerts. Nodemailer is on the backend, so these options reflect the options needed to set up nodemailer smtp transport.
smtp:
host: localhost
port: 25
secure: false
auth:
user: [email protected]
pass: SECRET-PASS
domain.yaml
Contains a single object (domains) which is a list of domains to monitor. Each domain has the following properties:
| Property | Type | Description |
|---|---|---|
| name | string | Descriptive name for the domain entry |
| fqdn | string | FQDN for the domain in question. This is just host.tld |
| alerts | bool | If true, email alerts will be sent for this domain |
| enabled | bool | If true, whois lookups will be done (on the schedule described above) for this domain. |
| (todo) id | string | A generated ID string. If you are manually adding to domain.yaml do not add an ID, it will be generated by domain-monitor |